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;
60456045 Task: call malloc, if the result is null, return null.
60466046 </p>
60476047 <p>C code</p>
6048 {#syntax_block|c|call_malloc_in_c.c#}// malloc prototype included for reference
6048 {#syntax_block|c|call_malloc_in_c.c#}
6049// malloc prototype included for reference
60496050void *malloc(size_t size);
60506051
60516052struct Foo *do_a_thing(void) {
60526053 char *ptr = malloc(1234);
60536054 if (!ptr) return NULL;
60546055 // ...
6055}{#end_syntax_block#}
6056}
6057 {#end_syntax_block#}
60566058 <p>Zig code</p>
60576059 {#syntax_block|zig|call_malloc_from_zig.zig#}
60586060// malloc prototype included for reference
......@@ -6072,7 +6074,8 @@ fn doAThing() ?*Foo {
60726074 <p>
60736075 The other form of checking against NULL you might see looks like this:
60746076 </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) {
60766079 // do some stuff
60776080
60786081 if (foo) {
......@@ -6080,7 +6083,8 @@ fn doAThing() ?*Foo {
60806083 }
60816084
60826085 // do some stuff
6083}{#end_syntax_block#}
6086}
6087 {#end_syntax_block#}
60846088 <p>
60856089 In Zig you can accomplish the same thing:
60866090 </p>
......@@ -7443,7 +7447,8 @@ pub fn syscall3(number: usize, arg1: usize, arg2: usize, arg3: usize) usize {
74437447 <p>
74447448 Dissecting the syntax:
74457449 </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.
74477452// the `asm` keyword begins the expression.
74487453_ = asm
74497454// `volatile` is an optional modifier that tells Zig this
......@@ -7498,7 +7503,8 @@ volatile (
74987503// output. In this example we list $rcx and $r11 because it is known the
74997504// kernel syscall does not preserve these registers.
75007505 : "rcx", "r11"
7501);{#end_syntax_block#}
7506);
7507 {#end_syntax_block#}
75027508 <p>
75037509 For x86 and x86_64 targets, the syntax is AT&amp;T syntax, rather than the more
75047510 popular Intel syntax. This is due to technical constraints; assembly parsing is
......@@ -10688,12 +10694,15 @@ const c = @cImport({
1068810694 or <kbd>-cflags</kbd> could result in clang or Zig parse failures, or subtle ABI incompatibilities
1068910695 when linking with C code.
1069010696 </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#}
1069210700 {#shell_samp#}$ zig translate-c -target thumb-freestanding-gnueabihf varytarget.h|grep FOO
1069310701pub export var FOO: c_long = 2147483647;
1069410702$ zig translate-c -target x86_64-macos-gnu varytarget.h|grep FOO
1069510703pub 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 };
1069710706int do_something(enum FOO foo);
1069810707 {#end_syntax_block#}
1069910708 {#shell_samp#}$ zig translate-c varycflags.h|grep -B1 do_something
......@@ -10784,7 +10793,8 @@ pub fn main() void {
1078410793 Zig.
1078510794 </p>
1078610795 <p>Consider the following example:</p>
10787 {#syntax_block|c|macro.c#}#define MAKELOCAL(NAME, INIT) int NAME = INIT
10796 {#syntax_block|c|macro.c#}
10797#define MAKELOCAL(NAME, INIT) int NAME = INIT
1078810798int foo(void) {
1078910799 MAKELOCAL(a, 1);
1079010800 MAKELOCAL(b, 2);
......@@ -10905,7 +10915,8 @@ export fn add(a: i32, b: i32) i32 {
1090510915 <p>To make a shared library:</p>
1090610916 {#shell_samp#}$ zig build-lib mathtest.zig -dynamic{#end_shell_samp#}
1090710917 <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.zig
10918 {#syntax_block|c|test.c#}
10919// This header is generated by zig from mathtest.zig
1090910920#include "mathtest.h"
1091010921#include <stdio.h>
1091110922
......@@ -10959,7 +10970,8 @@ export fn decode_base_64(
1095910970 return decoded_size;
1096010971}
1096110972 {#code_end#}
10962 {#syntax_block|c|test.c#}// This header is generated by zig from base64.zig
10973 {#syntax_block|c|test.c#}
10974// This header is generated by zig from base64.zig
1096310975#include "base64.h"
1096410976
1096510977#include <string.h>
......@@ -11009,7 +11021,8 @@ export fn add(a: i32, b: i32) void {
1100911021 print(a + b);
1101011022}
1101111023 {#code_end#}
11012 {#syntax_block|javascript|test.js#}const fs = require('fs');
11024 {#syntax_block|javascript|test.js#}
11025const fs = require('fs');
1101311026const source = fs.readFileSync("./math.wasm");
1101411027const typedArray = new Uint8Array(source);
1101511028
......@@ -11019,8 +11032,9 @@ WebAssembly.instantiate(typedArray, {
1101911032 }}).then(result => {
1102011033 const add = result.instance.exports.add;
1102111034 add(1, 2);
11022});{#end_syntax_block#}
11023 {#shell_samp#}$ node test.js
11035});
11036 {#end_syntax_block#}
11037 {#shell_samp#}$ node test.js
1102411038The result is 3{#end_shell_samp#}
1102511039 {#header_close#}
1102611040 {#header_open|WASI#}
......@@ -12065,7 +12079,8 @@ fn readU32Be() u32 {}
1206512079 {#header_close#}
1206612080
1206712081 {#header_open|Grammar#}
12068 {#syntax_block|peg|grammar.y#}Root <- skip container_doc_comment? ContainerMembers eof
12082 {#syntax_block|peg|grammar.y#}
12083Root <- skip container_doc_comment? ContainerMembers eof
1206912084
1207012085# *** Top level ***
1207112086ContainerMembers <- ContainerDeclarations (ContainerField COMMA)* (ContainerField / ContainerDeclarations)
......@@ -12631,7 +12646,7 @@ keyword <- KEYWORD_addrspace / KEYWORD_align / KEYWORD_allowzero / KEYWORD_and
1263112646 / KEYWORD_struct / KEYWORD_suspend / KEYWORD_switch / KEYWORD_test
1263212647 / KEYWORD_threadlocal / KEYWORD_try / KEYWORD_union / KEYWORD_unreachable
1263312648 / KEYWORD_usingnamespace / KEYWORD_var / KEYWORD_volatile / KEYWORD_while
12634{#end_syntax_block#}
12649 {#end_syntax_block#}
1263512650 {#header_close#}
1263612651 {#header_open|Zen#}
1263712652 <ul>