authorgravatar for manlio.perillo@gmail.comManlio Perillo <manlio.perillo@gmail.com> 2023-02-11 11:29:36+01:00
committergravatar for git@vexu.euVeikka Tuominen <git@vexu.eu> 2023-02-13 16:21:54+02:00
log5894be94c8326dc1c32fd528f002911c04af69c9
treea250a3d43b9ed2af0f9c7f79efd392d40e7f8fc9
parent25d6b8c1f1d5dc532c2bb68057d90751895aea68

langref: make more examples testable

Some examples using {#syntax_block|zig|...#} either have a valid syntax or it is easy to make the syntax valid. Update these example to use {#code_begin|syntax|...#}. Remove extra whitespace in the error_union_parsing_u64.zig example. Replace size_t with usize in the call_malloc_from_zig.zig example.

1 files changed, 62 insertions(+), 61 deletions(-)

doc/langref.html.in+62-61
...@@ -5393,7 +5393,6 @@ pub fn parseU64(buf: []const u8, radix: u8) !u64 {...@@ -5393,7 +5393,6 @@ pub fn parseU64(buf: []const u8, radix: u8) !u64 {
5393 // x *= radix5393 // x *= radix
5394 var ov = @mulWithOverflow(x, radix);5394 var ov = @mulWithOverflow(x, radix);
5395 if (ov[1] != 0) return error.OverFlow;5395 if (ov[1] != 0) return error.OverFlow;
5396
53975396
5398 // x += digit5397 // x += digit
5399 ov = @addWithOverflow(ov[0], digit);5398 ov = @addWithOverflow(ov[0], digit);
...@@ -6067,7 +6066,7 @@ struct Foo *do_a_thing(void) {...@@ -6067,7 +6066,7 @@ struct Foo *do_a_thing(void) {
6067 <p>Zig code</p>6066 <p>Zig code</p>
6068 {#syntax_block|zig|call_malloc_from_zig.zig#}6067 {#syntax_block|zig|call_malloc_from_zig.zig#}
6069// malloc prototype included for reference6068// malloc prototype included for reference
6070extern fn malloc(size: size_t) ?*u8;6069extern fn malloc(size: usize) ?*u8;
60716070
6072fn doAThing() ?*Foo {6071fn doAThing() ?*Foo {
6073 const ptr = malloc(1234) orelse return null;6072 const ptr = malloc(1234) orelse return null;
...@@ -7479,64 +7478,66 @@ pub fn syscall3(number: usize, arg1: usize, arg2: usize, arg3: usize) usize {...@@ -7479,64 +7478,66 @@ pub fn syscall3(number: usize, arg1: usize, arg2: usize, arg3: usize) usize {
7479 <p>7478 <p>
7480 Dissecting the syntax:7479 Dissecting the syntax:
7481 </p>7480 </p>
7482 {#syntax_block|zig|Assembly Syntax Explained#}7481 {#code_begin|syntax|Assembly Syntax Explained#}
7483// Inline assembly is an expression which returns a value.7482pub fn syscall1(number: usize, arg1: usize) usize {
7484// the `asm` keyword begins the expression.7483 // Inline assembly is an expression which returns a value.
7485_ = asm7484 // the `asm` keyword begins the expression.
7486// `volatile` is an optional modifier that tells Zig this7485 return asm
7487// inline assembly expression has side-effects. Without7486 // `volatile` is an optional modifier that tells Zig this
7488// `volatile`, Zig is allowed to delete the inline assembly7487 // inline assembly expression has side-effects. Without
7489// code if the result is unused.7488 // `volatile`, Zig is allowed to delete the inline assembly
7490volatile (7489 // code if the result is unused.
7491// Next is a comptime string which is the assembly code.7490 volatile (
7492// Inside this string one may use `%[ret]`, `%[number]`,7491 // Next is a comptime string which is the assembly code.
7493// or `%[arg1]` where a register is expected, to specify7492 // Inside this string one may use `%[ret]`, `%[number]`,
7494// the register that Zig uses for the argument or return value,7493 // or `%[arg1]` where a register is expected, to specify
7495// if the register constraint strings are used. However in7494 // the register that Zig uses for the argument or return value,
7496// the below code, this is not used. A literal `%` can be7495 // if the register constraint strings are used. However in
7497// obtained by escaping it with a double percent: `%%`.7496 // the below code, this is not used. A literal `%` can be
7498// Often multiline string syntax comes in handy here.7497 // obtained by escaping it with a double percent: `%%`.
7498 // Often multiline string syntax comes in handy here.
7499 \\syscall7499 \\syscall
7500// Next is the output. It is possible in the future Zig will7500 // Next is the output. It is possible in the future Zig will
7501// support multiple outputs, depending on how7501 // support multiple outputs, depending on how
7502// https://github.com/ziglang/zig/issues/215 is resolved.7502 // https://github.com/ziglang/zig/issues/215 is resolved.
7503// It is allowed for there to be no outputs, in which case7503 // It is allowed for there to be no outputs, in which case
7504// this colon would be directly followed by the colon for the inputs.7504 // this colon would be directly followed by the colon for the inputs.
7505 :7505 :
7506// This specifies the name to be used in `%[ret]` syntax in7506 // This specifies the name to be used in `%[ret]` syntax in
7507// the above assembly string. This example does not use it,7507 // the above assembly string. This example does not use it,
7508// but the syntax is mandatory.7508 // but the syntax is mandatory.
7509 [ret]7509 [ret]
7510// Next is the output constraint string. This feature is still7510 // Next is the output constraint string. This feature is still
7511// considered unstable in Zig, and so LLVM/GCC documentation7511 // considered unstable in Zig, and so LLVM/GCC documentation
7512// must be used to understand the semantics.7512 // must be used to understand the semantics.
7513// http://releases.llvm.org/10.0.0/docs/LangRef.html#inline-asm-constraint-string7513 // http://releases.llvm.org/10.0.0/docs/LangRef.html#inline-asm-constraint-string
7514// https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html7514 // https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html
7515// In this example, the constraint string means "the result value of7515 // In this example, the constraint string means "the result value of
7516// this inline assembly instruction is whatever is in $rax".7516 // this inline assembly instruction is whatever is in $rax".
7517 "={rax}"7517 "={rax}"
7518// Next is either a value binding, or `->` and then a type. The7518 // Next is either a value binding, or `->` and then a type. The
7519// type is the result type of the inline assembly expression.7519 // type is the result type of the inline assembly expression.
7520// If it is a value binding, then `%[ret]` syntax would be used7520 // If it is a value binding, then `%[ret]` syntax would be used
7521// to refer to the register bound to the value.7521 // to refer to the register bound to the value.
7522 (-> usize)7522 (-> usize)
7523// Next is the list of inputs.7523 // Next is the list of inputs.
7524// The constraint for these inputs means, "when the assembly code is7524 // The constraint for these inputs means, "when the assembly code is
7525// executed, $rax shall have the value of `number` and $rdi shall have7525 // executed, $rax shall have the value of `number` and $rdi shall have
7526// the value of `arg1`". Any number of input parameters is allowed,7526 // the value of `arg1`". Any number of input parameters is allowed,
7527// including none.7527 // including none.
7528 : [number] "{rax}" (number),7528 : [number] "{rax}" (number),
7529 [arg1] "{rdi}" (arg1)7529 [arg1] "{rdi}" (arg1)
7530// Next is the list of clobbers. These declare a set of registers whose7530 // Next is the list of clobbers. These declare a set of registers whose
7531// values will not be preserved by the execution of this assembly code.7531 // values will not be preserved by the execution of this assembly code.
7532// These do not include output or input registers. The special clobber7532 // These do not include output or input registers. The special clobber
7533// value of "memory" means that the assembly writes to arbitrary undeclared7533 // value of "memory" means that the assembly writes to arbitrary undeclared
7534// memory locations - not only the memory pointed to by a declared indirect7534 // memory locations - not only the memory pointed to by a declared indirect
7535// output. In this example we list $rcx and $r11 because it is known the7535 // output. In this example we list $rcx and $r11 because it is known the
7536// kernel syscall does not preserve these registers.7536 // kernel syscall does not preserve these registers.
7537 : "rcx", "r11"7537 : "rcx", "r11"
7538);7538 );
7539 {#end_syntax_block#}7539}
7540 {#code_end#}
7540 <p>7541 <p>
7541 For x86 and x86_64 targets, the syntax is AT&amp;T syntax, rather than the more7542 For x86 and x86_64 targets, the syntax is AT&amp;T syntax, rather than the more
7542 popular Intel syntax. This is due to technical constraints; assembly parsing is7543 popular Intel syntax. This is due to technical constraints; assembly parsing is
...@@ -7892,7 +7893,7 @@ fn add(a: i32, b: i32) i32 {...@@ -7892,7 +7893,7 @@ fn add(a: i32, b: i32) i32 {
7892 {#syntax#}@call{#endsyntax#} allows more flexibility than normal function call syntax does. The7893 {#syntax#}@call{#endsyntax#} allows more flexibility than normal function call syntax does. The
7893 {#syntax#}CallModifier{#endsyntax#} enum is reproduced here:7894 {#syntax#}CallModifier{#endsyntax#} enum is reproduced here:
7894 </p>7895 </p>
7895 {#syntax_block|zig|builtin.CallModifier struct#}7896 {#code_begin|syntax|builtin.CallModifier struct#}
7896pub const CallModifier = enum {7897pub const CallModifier = enum {
7897 /// Equivalent to function call syntax.7898 /// Equivalent to function call syntax.
7898 auto,7899 auto,
...@@ -7926,7 +7927,7 @@ pub const CallModifier = enum {...@@ -7926,7 +7927,7 @@ pub const CallModifier = enum {
7926 /// compile-time, a compile error is emitted instead.7927 /// compile-time, a compile error is emitted instead.
7927 compile_time,7928 compile_time,
7928};7929};
7929 {#end_syntax_block#}7930 {#code_end#}
7930 {#header_close#}7931 {#header_close#}
79317932
7932 {#header_open|@cDefine#}7933 {#header_open|@cDefine#}