From efbb6128bbfdd0b731578dcc55d4a55732d20d8a Mon Sep 17 00:00:00 2001 From: Manlio Perillo Date: Thu, 19 Jan 2023 12:33:00 +0100 Subject: [PATCH] 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. --- doc/langref.html.in | 47 ++++++++++++++++++++++++++++++--------------- 1 file changed, 31 insertions(+), 16 deletions(-) diff --git a/doc/langref.html.in b/doc/langref.html.in index 30dbbb604e..ef2b6b9710 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -6045,14 +6045,16 @@ const optional_int: ?i32 = 5678; Task: call malloc, if the result is null, return null.

C code

- {#syntax_block|c|call_malloc_in_c.c#}// malloc prototype included for reference + {#syntax_block|c|call_malloc_in_c.c#} +// malloc prototype included for reference void *malloc(size_t size); struct Foo *do_a_thing(void) { char *ptr = malloc(1234); if (!ptr) return NULL; // ... -}{#end_syntax_block#} +} + {#end_syntax_block#}

Zig code

{#syntax_block|zig|call_malloc_from_zig.zig#} // malloc prototype included for reference @@ -6072,7 +6074,8 @@ fn doAThing() ?*Foo {

The other form of checking against NULL you might see looks like this:

- {#syntax_block|c|checking_null_in_c.c#}void do_a_thing(struct Foo *foo) { + {#syntax_block|c|checking_null_in_c.c#} +void do_a_thing(struct Foo *foo) { // do some stuff if (foo) { @@ -6080,7 +6083,8 @@ fn doAThing() ?*Foo { } // do some stuff -}{#end_syntax_block#} +} + {#end_syntax_block#}

In Zig you can accomplish the same thing:

@@ -7443,7 +7447,8 @@ pub fn syscall3(number: usize, arg1: usize, arg2: usize, arg3: usize) usize {

Dissecting the syntax:

- {#syntax_block|zig|Assembly Syntax Explained#}// Inline assembly is an expression which returns a value. + {#syntax_block|zig|Assembly Syntax Explained#} +// Inline assembly is an expression which returns a value. // the `asm` keyword begins the expression. _ = asm // `volatile` is an optional modifier that tells Zig this @@ -7498,7 +7503,8 @@ volatile ( // output. In this example we list $rcx and $r11 because it is known the // kernel syscall does not preserve these registers. : "rcx", "r11" -);{#end_syntax_block#} +); + {#end_syntax_block#}

For x86 and x86_64 targets, the syntax is AT&T syntax, rather than the more popular Intel syntax. This is due to technical constraints; assembly parsing is @@ -10688,12 +10694,15 @@ const c = @cImport({ or -cflags could result in clang or Zig parse failures, or subtle ABI incompatibilities when linking with C code.

- {#syntax_block|c|varytarget.h#}long FOO = __LONG_MAX__;{#end_syntax_block#} + {#syntax_block|c|varytarget.h#} +long FOO = __LONG_MAX__; + {#end_syntax_block#} {#shell_samp#}$ zig translate-c -target thumb-freestanding-gnueabihf varytarget.h|grep FOO pub export var FOO: c_long = 2147483647; $ zig translate-c -target x86_64-macos-gnu varytarget.h|grep FOO pub export var FOO: c_long = 9223372036854775807;{#end_shell_samp#} - {#syntax_block|c|varycflags.h#}enum FOO { BAR }; + {#syntax_block|c|varycflags.h#} +enum FOO { BAR }; int do_something(enum FOO foo); {#end_syntax_block#} {#shell_samp#}$ zig translate-c varycflags.h|grep -B1 do_something @@ -10784,7 +10793,8 @@ pub fn main() void { Zig.

Consider the following example:

- {#syntax_block|c|macro.c#}#define MAKELOCAL(NAME, INIT) int NAME = INIT + {#syntax_block|c|macro.c#} +#define MAKELOCAL(NAME, INIT) int NAME = INIT int foo(void) { MAKELOCAL(a, 1); MAKELOCAL(b, 2); @@ -10905,7 +10915,8 @@ export fn add(a: i32, b: i32) i32 {

To make a shared library:

{#shell_samp#}$ zig build-lib mathtest.zig -dynamic{#end_shell_samp#}

Here is an example with the {#link|Zig Build System#}:

- {#syntax_block|c|test.c#}// This header is generated by zig from mathtest.zig + {#syntax_block|c|test.c#} +// This header is generated by zig from mathtest.zig #include "mathtest.h" #include @@ -10959,7 +10970,8 @@ export fn decode_base_64( return decoded_size; } {#code_end#} - {#syntax_block|c|test.c#}// This header is generated by zig from base64.zig + {#syntax_block|c|test.c#} +// This header is generated by zig from base64.zig #include "base64.h" #include @@ -11009,7 +11021,8 @@ export fn add(a: i32, b: i32) void { print(a + b); } {#code_end#} - {#syntax_block|javascript|test.js#}const fs = require('fs'); + {#syntax_block|javascript|test.js#} +const fs = require('fs'); const source = fs.readFileSync("./math.wasm"); const typedArray = new Uint8Array(source); @@ -11019,8 +11032,9 @@ WebAssembly.instantiate(typedArray, { }}).then(result => { const add = result.instance.exports.add; add(1, 2); -});{#end_syntax_block#} - {#shell_samp#}$ node test.js +}); + {#end_syntax_block#} + {#shell_samp#}$ node test.js The result is 3{#end_shell_samp#} {#header_close#} {#header_open|WASI#} @@ -12065,7 +12079,8 @@ fn readU32Be() u32 {} {#header_close#} {#header_open|Grammar#} - {#syntax_block|peg|grammar.y#}Root <- skip container_doc_comment? ContainerMembers eof + {#syntax_block|peg|grammar.y#} +Root <- skip container_doc_comment? ContainerMembers eof # *** Top level *** ContainerMembers <- ContainerDeclarations (ContainerField COMMA)* (ContainerField / ContainerDeclarations) @@ -12631,7 +12646,7 @@ keyword <- KEYWORD_addrspace / KEYWORD_align / KEYWORD_allowzero / KEYWORD_and / KEYWORD_struct / KEYWORD_suspend / KEYWORD_switch / KEYWORD_test / KEYWORD_threadlocal / KEYWORD_try / KEYWORD_union / KEYWORD_unreachable / KEYWORD_usingnamespace / KEYWORD_var / KEYWORD_volatile / KEYWORD_while -{#end_syntax_block#} + {#end_syntax_block#} {#header_close#} {#header_open|Zen#}