authorgravatar for manlio.perillo@gmail.comManlio Perillo <manlio.perillo@gmail.com> 2023-01-19 12:33:00+01:00
committergravatar for git@vexu.euVeikka Tuominen <git@vexu.eu> 2023-01-19 19:10:01+02:00
logefbb6128bbfdd0b731578dcc55d4a55732d20d8a
tree4b74df2eb8a75391e31e346a8dc6f5c8a8ff62cb
parentd87a58dfabc51a6b59a1d2f496f19e05586ce001

langref: always start code on a separate line in a syntax_block

In a syntax_block the code always start on a separate code, expect for C, JavaScript, Peg and with Zig inline assembly. Ensure that the code starts on a separate line, even in cases where there is only one line. Ensure that the end_syntax_block is always on a separate line and that the indentation is consistent.

1 files changed, 31 insertions(+), 16 deletions(-)

doc/langref.html.in+31-16
...@@ -6045,14 +6045,16 @@ const optional_int: ?i32 = 5678;...@@ -6045,14 +6045,16 @@ const optional_int: ?i32 = 5678;
6045 Task: call malloc, if the result is null, return null.6045 Task: call malloc, if the result is null, return null.
6046 </p>6046 </p>
6047 <p>C code</p>6047 <p>C code</p>
6048 {#syntax_block|c|call_malloc_in_c.c#}// malloc prototype included for reference6048 {#syntax_block|c|call_malloc_in_c.c#}
6049// malloc prototype included for reference
6049void *malloc(size_t size);6050void *malloc(size_t size);
60506051
6051struct Foo *do_a_thing(void) {6052struct Foo *do_a_thing(void) {
6052 char *ptr = malloc(1234);6053 char *ptr = malloc(1234);
6053 if (!ptr) return NULL;6054 if (!ptr) return NULL;
6054 // ...6055 // ...
6055}{#end_syntax_block#}6056}
6057 {#end_syntax_block#}
6056 <p>Zig code</p>6058 <p>Zig code</p>
6057 {#syntax_block|zig|call_malloc_from_zig.zig#}6059 {#syntax_block|zig|call_malloc_from_zig.zig#}
6058// malloc prototype included for reference6060// malloc prototype included for reference
...@@ -6072,7 +6074,8 @@ fn doAThing() ?*Foo {...@@ -6072,7 +6074,8 @@ fn doAThing() ?*Foo {
6072 <p>6074 <p>
6073 The other form of checking against NULL you might see looks like this:6075 The other form of checking against NULL you might see looks like this:
6074 </p>6076 </p>
6075 {#syntax_block|c|checking_null_in_c.c#}void do_a_thing(struct Foo *foo) {6077 {#syntax_block|c|checking_null_in_c.c#}
6078void do_a_thing(struct Foo *foo) {
6076 // do some stuff6079 // do some stuff
60776080
6078 if (foo) {6081 if (foo) {
...@@ -6080,7 +6083,8 @@ fn doAThing() ?*Foo {...@@ -6080,7 +6083,8 @@ fn doAThing() ?*Foo {
6080 }6083 }
60816084
6082 // do some stuff6085 // do some stuff
6083}{#end_syntax_block#}6086}
6087 {#end_syntax_block#}
6084 <p>6088 <p>
6085 In Zig you can accomplish the same thing:6089 In Zig you can accomplish the same thing:
6086 </p>6090 </p>
...@@ -7443,7 +7447,8 @@ pub fn syscall3(number: usize, arg1: usize, arg2: usize, arg3: usize) usize {...@@ -7443,7 +7447,8 @@ pub fn syscall3(number: usize, arg1: usize, arg2: usize, arg3: usize) usize {
7443 <p>7447 <p>
7444 Dissecting the syntax:7448 Dissecting the syntax:
7445 </p>7449 </p>
7446 {#syntax_block|zig|Assembly Syntax Explained#}// Inline assembly is an expression which returns a value.7450 {#syntax_block|zig|Assembly Syntax Explained#}
7451// Inline assembly is an expression which returns a value.
7447// the `asm` keyword begins the expression.7452// the `asm` keyword begins the expression.
7448_ = asm7453_ = asm
7449// `volatile` is an optional modifier that tells Zig this7454// `volatile` is an optional modifier that tells Zig this
...@@ -7498,7 +7503,8 @@ volatile (...@@ -7498,7 +7503,8 @@ volatile (
7498// output. In this example we list $rcx and $r11 because it is known the7503// output. In this example we list $rcx and $r11 because it is known the
7499// kernel syscall does not preserve these registers.7504// kernel syscall does not preserve these registers.
7500 : "rcx", "r11"7505 : "rcx", "r11"
7501);{#end_syntax_block#}7506);
7507 {#end_syntax_block#}
7502 <p>7508 <p>
7503 For x86 and x86_64 targets, the syntax is AT&amp;T syntax, rather than the more7509 For x86 and x86_64 targets, the syntax is AT&amp;T syntax, rather than the more
7504 popular Intel syntax. This is due to technical constraints; assembly parsing is7510 popular Intel syntax. This is due to technical constraints; assembly parsing is
...@@ -10688,12 +10694,15 @@ const c = @cImport({...@@ -10688,12 +10694,15 @@ const c = @cImport({
10688 or <kbd>-cflags</kbd> could result in clang or Zig parse failures, or subtle ABI incompatibilities10694 or <kbd>-cflags</kbd> could result in clang or Zig parse failures, or subtle ABI incompatibilities
10689 when linking with C code.10695 when linking with C code.
10690 </p>10696 </p>
10691 {#syntax_block|c|varytarget.h#}long FOO = __LONG_MAX__;{#end_syntax_block#}10697 {#syntax_block|c|varytarget.h#}
10698long FOO = __LONG_MAX__;
10699 {#end_syntax_block#}
10692 {#shell_samp#}$ zig translate-c -target thumb-freestanding-gnueabihf varytarget.h|grep FOO10700 {#shell_samp#}$ zig translate-c -target thumb-freestanding-gnueabihf varytarget.h|grep FOO
10693pub export var FOO: c_long = 2147483647;10701pub export var FOO: c_long = 2147483647;
10694$ zig translate-c -target x86_64-macos-gnu varytarget.h|grep FOO10702$ zig translate-c -target x86_64-macos-gnu varytarget.h|grep FOO
10695pub export var FOO: c_long = 9223372036854775807;{#end_shell_samp#}10703pub export var FOO: c_long = 9223372036854775807;{#end_shell_samp#}
10696 {#syntax_block|c|varycflags.h#}enum FOO { BAR };10704 {#syntax_block|c|varycflags.h#}
10705enum FOO { BAR };
10697int do_something(enum FOO foo);10706int do_something(enum FOO foo);
10698 {#end_syntax_block#}10707 {#end_syntax_block#}
10699 {#shell_samp#}$ zig translate-c varycflags.h|grep -B1 do_something10708 {#shell_samp#}$ zig translate-c varycflags.h|grep -B1 do_something
...@@ -10784,7 +10793,8 @@ pub fn main() void {...@@ -10784,7 +10793,8 @@ pub fn main() void {
10784 Zig.10793 Zig.
10785 </p>10794 </p>
10786 <p>Consider the following example:</p>10795 <p>Consider the following example:</p>
10787 {#syntax_block|c|macro.c#}#define MAKELOCAL(NAME, INIT) int NAME = INIT10796 {#syntax_block|c|macro.c#}
10797#define MAKELOCAL(NAME, INIT) int NAME = INIT
10788int foo(void) {10798int foo(void) {
10789 MAKELOCAL(a, 1);10799 MAKELOCAL(a, 1);
10790 MAKELOCAL(b, 2);10800 MAKELOCAL(b, 2);
...@@ -10905,7 +10915,8 @@ export fn add(a: i32, b: i32) i32 {...@@ -10905,7 +10915,8 @@ export fn add(a: i32, b: i32) i32 {
10905 <p>To make a shared library:</p>10915 <p>To make a shared library:</p>
10906 {#shell_samp#}$ zig build-lib mathtest.zig -dynamic{#end_shell_samp#}10916 {#shell_samp#}$ zig build-lib mathtest.zig -dynamic{#end_shell_samp#}
10907 <p>Here is an example with the {#link|Zig Build System#}:</p>10917 <p>Here is an example with the {#link|Zig Build System#}:</p>
10908 {#syntax_block|c|test.c#}// This header is generated by zig from mathtest.zig10918 {#syntax_block|c|test.c#}
10919// This header is generated by zig from mathtest.zig
10909#include "mathtest.h"10920#include "mathtest.h"
10910#include <stdio.h>10921#include <stdio.h>
1091110922
...@@ -10959,7 +10970,8 @@ export fn decode_base_64(...@@ -10959,7 +10970,8 @@ export fn decode_base_64(
10959 return decoded_size;10970 return decoded_size;
10960}10971}
10961 {#code_end#}10972 {#code_end#}
10962 {#syntax_block|c|test.c#}// This header is generated by zig from base64.zig10973 {#syntax_block|c|test.c#}
10974// This header is generated by zig from base64.zig
10963#include "base64.h"10975#include "base64.h"
1096410976
10965#include <string.h>10977#include <string.h>
...@@ -11009,7 +11021,8 @@ export fn add(a: i32, b: i32) void {...@@ -11009,7 +11021,8 @@ export fn add(a: i32, b: i32) void {
11009 print(a + b);11021 print(a + b);
11010}11022}
11011 {#code_end#}11023 {#code_end#}
11012 {#syntax_block|javascript|test.js#}const fs = require('fs');11024 {#syntax_block|javascript|test.js#}
11025const fs = require('fs');
11013const source = fs.readFileSync("./math.wasm");11026const source = fs.readFileSync("./math.wasm");
11014const typedArray = new Uint8Array(source);11027const typedArray = new Uint8Array(source);
1101511028
...@@ -11019,8 +11032,9 @@ WebAssembly.instantiate(typedArray, {...@@ -11019,8 +11032,9 @@ WebAssembly.instantiate(typedArray, {
11019 }}).then(result => {11032 }}).then(result => {
11020 const add = result.instance.exports.add;11033 const add = result.instance.exports.add;
11021 add(1, 2);11034 add(1, 2);
11022});{#end_syntax_block#}11035});
11023 {#shell_samp#}$ node test.js11036 {#end_syntax_block#}
11037 {#shell_samp#}$ node test.js
11024The result is 3{#end_shell_samp#}11038The result is 3{#end_shell_samp#}
11025 {#header_close#}11039 {#header_close#}
11026 {#header_open|WASI#}11040 {#header_open|WASI#}
...@@ -12065,7 +12079,8 @@ fn readU32Be() u32 {}...@@ -12065,7 +12079,8 @@ fn readU32Be() u32 {}
12065 {#header_close#}12079 {#header_close#}
1206612080
12067 {#header_open|Grammar#}12081 {#header_open|Grammar#}
12068 {#syntax_block|peg|grammar.y#}Root <- skip container_doc_comment? ContainerMembers eof12082 {#syntax_block|peg|grammar.y#}
12083Root <- skip container_doc_comment? ContainerMembers eof
1206912084
12070# *** Top level ***12085# *** Top level ***
12071ContainerMembers <- ContainerDeclarations (ContainerField COMMA)* (ContainerField / ContainerDeclarations)12086ContainerMembers <- ContainerDeclarations (ContainerField COMMA)* (ContainerField / ContainerDeclarations)
...@@ -12631,7 +12646,7 @@ keyword <- KEYWORD_addrspace / KEYWORD_align / KEYWORD_allowzero / KEYWORD_and...@@ -12631,7 +12646,7 @@ keyword <- KEYWORD_addrspace / KEYWORD_align / KEYWORD_allowzero / KEYWORD_and
12631 / KEYWORD_struct / KEYWORD_suspend / KEYWORD_switch / KEYWORD_test12646 / KEYWORD_struct / KEYWORD_suspend / KEYWORD_switch / KEYWORD_test
12632 / KEYWORD_threadlocal / KEYWORD_try / KEYWORD_union / KEYWORD_unreachable12647 / KEYWORD_threadlocal / KEYWORD_try / KEYWORD_union / KEYWORD_unreachable
12633 / KEYWORD_usingnamespace / KEYWORD_var / KEYWORD_volatile / KEYWORD_while12648 / KEYWORD_usingnamespace / KEYWORD_var / KEYWORD_volatile / KEYWORD_while
12634{#end_syntax_block#}12649 {#end_syntax_block#}
12635 {#header_close#}12650 {#header_close#}
12636 {#header_open|Zen#}12651 {#header_open|Zen#}
12637 <ul>12652 <ul>