authorgravatar for git@vexu.euVeikka Tuominen <git@vexu.eu> 2020-08-27 16:12:18+03:00
committergravatar for noreply@github.comGitHub <noreply@github.com> 2020-08-27 16:12:18+03:00
logf6cedfaaca2a1ca22786b32aa76ef6348b74ac38
tree5476968b26013adc73cd0b8738eb40e0cf1a05a9
parentdc7608da973291aafb7a58f33eb65dc3389c123d
parentd4b1ed1bc96e2b93f7e972ddb274cdb35704a8d7
signature Signed by PGP key 4AEE18F83AFDEB23

Merge pull request #6160 from extrasharp/keyword-documentation

Add Keyword Reference section

1 files changed, 580 insertions(+), 8 deletions(-)

doc/langref.html.in+580-8
......@@ -10308,14 +10308,586 @@ fn readU32Be() u32 {}
1030810308 {#header_close#}
1030910309
1031010310 {#header_open|Keyword Reference#}
10311 <p>
10312 TODO the rest of the keywords. Most of these can just be links to the relevant section.
10313 </p>
10314 {#header_open|Keyword: pub#}
10315 <p>The {#syntax#}pub{#endsyntax#} in front of a top level declaration makes the
10316 declaration available to reference from a different file than the one it is declared in.</p>
10317 {#see_also|@import#}
10318 {#header_close#}
10311 <div class="table-wrapper">
10312 <table>
10313 <tr>
10314 <th>
10315 Keyword
10316 </th>
10317 <th>
10318 Description
10319 </th>
10320 </tr>
10321 <tr>
10322 <td>
10323 <pre>{#syntax#}align{#endsyntax#}</pre>
10324 </td>
10325 <td>
10326 {#syntax#}align{#endsyntax#} can be used to specify the alignment of a pointer.
10327 It can also be used after a variable or function declaration to specify the alignment of pointers to that variable or function.
10328 <ul>
10329 <li>See also {#link|Alignment#}</li>
10330 </ul>
10331 </td>
10332 </tr>
10333 <tr>
10334 <td>
10335 <pre>{#syntax#}allowzero{#endsyntax#}</pre>
10336 </td>
10337 <td>
10338 The pointer attribute {#syntax#}allowzero{#endsyntax#} allows a pointer to have address zero.
10339 <ul>
10340 <li>See also {#link|allowzero#}</li>
10341 </ul>
10342 </td>
10343 </tr>
10344 <tr>
10345 <td>
10346 <pre>{#syntax#}and{#endsyntax#}</pre>
10347 </td>
10348 <td>
10349 The boolean operator {#syntax#}and{#endsyntax#}.
10350 <ul>
10351 <li>See also {#link|Operators#}</li>
10352 </ul>
10353 </td>
10354 </tr>
10355 <tr>
10356 <td>
10357 <pre>{#syntax#}anyframe{#endsyntax#}</pre>
10358 </td>
10359 <td>
10360 {#syntax#}anyframe{#endsyntax#} can be used as a type for variables which hold pointers to function frames.
10361 <ul>
10362 <li>See also {#link|Async Functions#}</li>
10363 </ul>
10364 </td>
10365 </tr>
10366 <tr>
10367 <td>
10368 <pre>{#syntax#}anytype{#endsyntax#}</pre>
10369 </td>
10370 <td>
10371 Function parameters and struct fields can be declared with {#syntax#}anytype{#endsyntax#} in place of the type.
10372 The type will be inferred where the function is called or the struct is instantiated.
10373 <ul>
10374 <li>See also {#link|Function Parameter Type Inference#}</li>
10375 </ul>
10376 </td>
10377 </tr>
10378 <tr>
10379 <td>
10380 <pre>{#syntax#}asm{#endsyntax#}</pre>
10381 </td>
10382 <td>
10383 {#syntax#}asm{#endsyntax#} begins an inline assembly expression. This allows for directly controlling the machine code generated on compilation.
10384 <ul>
10385 <li>See also {#link|Assembly#}</li>
10386 </ul>
10387 </td>
10388 </tr>
10389 <tr>
10390 <td>
10391 <pre>{#syntax#}async{#endsyntax#}</pre>
10392 </td>
10393 <td>
10394 {#syntax#}async{#endsyntax#} can be used before a function call to get a pointer to the function's frame when it suspends.
10395 <ul>
10396 <li>See also {#link|Async Functions#}</li>
10397 </ul>
10398 </td>
10399 </tr>
10400 <tr>
10401 <td>
10402 <pre>{#syntax#}await{#endsyntax#}</pre>
10403 </td>
10404 <td>
10405 {#syntax#}await{#endsyntax#} can be used to suspend the current function until the frame provided after the {#syntax#}await{#endsyntax#} completes.
10406 {#syntax#}await{#endsyntax#} copies the value returned from the target function's frame to the caller.
10407 <ul>
10408 <li>See also {#link|Async Functions#}</li>
10409 </ul>
10410 </td>
10411 </tr>
10412 <tr>
10413 <td>
10414 <pre>{#syntax#}break{#endsyntax#}</pre>
10415 </td>
10416 <td>
10417 {#syntax#}break{#endsyntax#} can be used with a block label to return a value from the block.
10418 It can also be used to exit a loop before iteration completes naturally.
10419 <ul>
10420 <li>See also {#link|blocks#}, {#link|while#}, {#link|for#}</li>
10421 </ul>
10422 </td>
10423 </tr>
10424 <tr>
10425 <td>
10426 <pre>{#syntax#}catch{#endsyntax#}</pre>
10427 </td>
10428 <td>
10429 {#syntax#}catch{#endsyntax#} can be used to evaluate an expression if the expression before it evaluates to an error.
10430 The expression after the {#syntax#}catch{#endsyntax#} can optionally capture the error value.
10431 <ul>
10432 <li>See also {#link|catch#}, {#link|Operators#}</li>
10433 </ul>
10434 </td>
10435 </tr>
10436 <tr>
10437 <td>
10438 <pre>{#syntax#}comptime{#endsyntax#}</pre>
10439 </td>
10440 <td>
10441 {#syntax#}comptime{#endsyntax#} before a declaration can be used to label variables or function parameters as known at compile time.
10442 It can also be used to guarantee an expression is run at compile time.
10443 <ul>
10444 <li>See also {#link|comptime#}</li>
10445 </ul>
10446 </td>
10447 </tr>
10448 <tr>
10449 <td>
10450 <pre>{#syntax#}const{#endsyntax#}</pre>
10451 </td>
10452 <td>
10453 {#syntax#}const{#endsyntax#} declares a variable that can not be modified.
10454 Used as a pointer attribute, it denotes the value referenced by the pointer cannot be modified.
10455 <ul>
10456 <li>See also {#link|Variables#}</li>
10457 </ul>
10458 </td>
10459 </tr>
10460 <tr>
10461 <td>
10462 <pre>{#syntax#}continue{#endsyntax#}</pre>
10463 </td>
10464 <td>
10465 {#syntax#}continue{#endsyntax#} can be used in a loop to jump back to the beginning of the loop.
10466 <ul>
10467 <li>See also {#link|while#}, {#link|for#}</li>
10468 </ul>
10469 </td>
10470 </tr>
10471 <tr>
10472 <td>
10473 <pre>{#syntax#}defer{#endsyntax#}</pre>
10474 </td>
10475 <td>
10476 {#syntax#}defer{#endsyntax#} will execute an expression when control flow leaves the current block.
10477 <ul>
10478 <li>See also {#link|defer#}</li>
10479 </ul>
10480 </td>
10481 </tr>
10482 <tr>
10483 <td>
10484 <pre>{#syntax#}else{#endsyntax#}</pre>
10485 </td>
10486 <td>
10487 {#syntax#}else{#endsyntax#} can be used to provide an alternate branch for {#syntax#}if{#endsyntax#}, {#syntax#}switch{#endsyntax#},
10488 {#syntax#}while{#endsyntax#}, and {#syntax#}for{#endsyntax#} expressions.
10489 <ul>
10490 <li>If used after an if expression, the else branch will be executed if the test value returns false, null, or an error.</li>
10491 <li>If used within a switch expression, the else branch will be executed if the test value matches no other cases.</li>
10492 <li>If used after a loop expression, the else branch will be executed if the loop finishes without breaking.</li>
10493 <li>See also {#link|if#}, {#link|switch#}, {#link|while#}, {#link|for#}</li>
10494 </ul>
10495 </td>
10496 </tr>
10497 <tr>
10498 <td>
10499 <pre>{#syntax#}enum{#endsyntax#}</pre>
10500 </td>
10501 <td>
10502 {#syntax#}enum{#endsyntax#} defines an enum type.
10503 <ul>
10504 <li>See also {#link|enum#}</li>
10505 </ul>
10506 </td>
10507 </tr>
10508 <tr>
10509 <td>
10510 <pre>{#syntax#}errdefer{#endsyntax#}</pre>
10511 </td>
10512 <td>
10513 {#syntax#}errdefer{#endsyntax#} will execute an expression when control flow leaves the current block if the function returns an error.
10514 <ul>
10515 <li>See also {#link|errdefer#}</li>
10516 </ul>
10517 </td>
10518 </tr>
10519 <tr>
10520 <td>
10521 <pre>{#syntax#}error{#endsyntax#}</pre>
10522 </td>
10523 <td>
10524 {#syntax#}error{#endsyntax#} defines an error type.
10525 <ul>
10526 <li>See also {#link|Errors#}</li>
10527 </ul>
10528 </td>
10529 </tr>
10530 <tr>
10531 <td>
10532 <pre>{#syntax#}export{#endsyntax#}</pre>
10533 </td>
10534 <td>
10535 {#syntax#}export{#endsyntax#} makes a function or variable externally visible in the generated object file.
10536 Exported functions default to the C calling convention.
10537 <ul>
10538 <li>See also {#link|Functions#}</li>
10539 </ul>
10540 </td>
10541 </tr>
10542 <tr>
10543 <td>
10544 <pre>{#syntax#}extern{#endsyntax#}</pre>
10545 </td>
10546 <td>
10547 {#syntax#}extern{#endsyntax#} can be used to declare a function or variable that will be resolved at link time, when linking statically
10548 or at runtime, when linking dynamically.
10549 <ul>
10550 <li>See also {#link|Functions#}</li>
10551 </ul>
10552 </td>
10553 </tr>
10554 <tr>
10555 <td>
10556 <pre>{#syntax#}false{#endsyntax#}</pre>
10557 </td>
10558 <td>
10559 The boolean value {#syntax#}false{#endsyntax#}.
10560 <ul>
10561 <li>See also {#link|Primitive Values#}</li>
10562 </ul>
10563 </td>
10564 </tr>
10565 <tr>
10566 <td>
10567 <pre>{#syntax#}fn{#endsyntax#}</pre>
10568 </td>
10569 <td>
10570 {#syntax#}fn{#endsyntax#} declares a function.
10571 <ul>
10572 <li>See also {#link|Functions#}</li>
10573 </ul>
10574 </td>
10575 </tr>
10576 <tr>
10577 <td>
10578 <pre>{#syntax#}for{#endsyntax#}</pre>
10579 </td>
10580 <td>
10581 A {#syntax#}for{#endsyntax#} expression can be used to iterate over the elements of a slice, array, or tuple.
10582 <ul>
10583 <li>See also {#link|for#}</li>
10584 </ul>
10585 </td>
10586 </tr>
10587 <tr>
10588 <td>
10589 <pre>{#syntax#}if{#endsyntax#}</pre>
10590 </td>
10591 <td>
10592 An {#syntax#}if{#endsyntax#} expression can test boolean expressions, optional values, or error unions.
10593 For optional values or error unions, the if expression can capture the unwrapped value.
10594 <ul>
10595 <li>See also {#link|if#}</li>
10596 </ul>
10597 </td>
10598 </tr>
10599 <tr>
10600 <td>
10601 <pre>{#syntax#}inline{#endsyntax#}</pre>
10602 </td>
10603 <td>
10604 {#syntax#}inline{#endsyntax#} can be used to label a loop expression such that it will be unrolled at compile time.
10605 It can also be used to force a function to be inlined at all call sites.
10606 <ul>
10607 <li>See also {#link|inline while#}, {#link|inline for#}, {#link|Functions#}</li>
10608 </ul>
10609 </td>
10610 </tr>
10611 <tr>
10612 <td>
10613 <pre>{#syntax#}noalias{#endsyntax#}</pre>
10614 </td>
10615 <td>
10616 The {#syntax#}noalias{#endsyntax#} keyword.
10617 <ul>
10618 <li>TODO add documentation for noalias</li>
10619 </ul>
10620 </td>
10621 </tr>
10622 <tr>
10623 <td>
10624 <pre>{#syntax#}nosuspend{#endsyntax#}</pre>
10625 </td>
10626 <td>
10627 The {#syntax#}nosuspend{#endsyntax#} keyword.
10628 <ul>
10629 <li>TODO add documentation for nosuspend</li>
10630 </ul>
10631 </td>
10632 </tr>
10633 <tr>
10634 <td>
10635 <pre>{#syntax#}null{#endsyntax#}</pre>
10636 </td>
10637 <td>
10638 The optional value {#syntax#}null{#endsyntax#}.
10639 <ul>
10640 <li>See also {#link|null#}</li>
10641 </ul>
10642 </td>
10643 </tr>
10644 <tr>
10645 <td>
10646 <pre>{#syntax#}or{#endsyntax#}</pre>
10647 </td>
10648 <td>
10649 The boolean operator {#syntax#}or{#endsyntax#}.
10650 <ul>
10651 <li>See also {#link|Operators#}</li>
10652 </ul>
10653 </td>
10654 </tr>
10655 <tr>
10656 <td>
10657 <pre>{#syntax#}orelse{#endsyntax#}</pre>
10658 </td>
10659 <td>
10660 {#syntax#}orelse{#endsyntax#} can be used to evaluate an expression if the expression before it evaluates to null.
10661 <ul>
10662 <li>See also {#link|Optionals#}, {#link|Operators#}</li>
10663 </ul>
10664 </td>
10665 </tr>
10666 <tr>
10667 <td>
10668 <pre>{#syntax#}packed{#endsyntax#}</pre>
10669 </td>
10670 <td>
10671 The {#syntax#}packed{#endsyntax#} keyword before a struct definition changes the struct's in-memory layout
10672 to the guaranteed {#syntax#}packed{#endsyntax#} layout.
10673 <ul>
10674 <li>See also {#link|packed struct#}</li>
10675 </ul>
10676 </td>
10677 </tr>
10678 <tr>
10679 <td>
10680 <pre>{#syntax#}pub{#endsyntax#}</pre>
10681 </td>
10682 <td>
10683 The {#syntax#}pub{#endsyntax#} in front of a top level declaration makes the declaration available
10684 to reference from a different file than the one it is declared in.
10685 <ul>
10686 <li>See also {#link|import#}</li>
10687 </ul>
10688 </td>
10689 </tr>
10690 <tr>
10691 <td>
10692 <pre>{#syntax#}resume{#endsyntax#}</pre>
10693 </td>
10694 <td>
10695 {#syntax#}resume{#endsyntax#} will continue execution of a function frame after the point the function was suspended.
10696 <ul>
10697 <li>See also {#link|Suspend and Resume#}</li>
10698 </ul>
10699 </td>
10700 </tr>
10701 <tr>
10702 <td>
10703 <pre>{#syntax#}return{#endsyntax#}</pre>
10704 </td>
10705 <td>
10706 {#syntax#}return{#endsyntax#} exits a function with a value.
10707 <ul>
10708 <li>See also {#link|Functions#}</li>
10709 </ul>
10710 </td>
10711 </tr>
10712 <tr>
10713 <td>
10714 <pre>{#syntax#}linksection{#endsyntax#}</pre>
10715 </td>
10716 <td>
10717 The {#syntax#}linksection{#endsyntax#} keyword.
10718 <ul>
10719 <li>TODO add documentation for linksection</li>
10720 </ul>
10721 </td>
10722 </tr>
10723 <tr>
10724 <td>
10725 <pre>{#syntax#}struct{#endsyntax#}</pre>
10726 </td>
10727 <td>
10728 {#syntax#}struct{#endsyntax#} defines a struct.
10729 <ul>
10730 <li>See also {#link|struct#}</li>
10731 </ul>
10732 </td>
10733 </tr>
10734 <tr>
10735 <td>
10736 <pre>{#syntax#}suspend{#endsyntax#}</pre>
10737 </td>
10738 <td>
10739 {#syntax#}suspend{#endsyntax#} will cause control flow to return to the call site or resumer of the function.
10740 {#syntax#}suspend{#endsyntax#} can also be used before a block within a function,
10741 to allow the function access to its frame before control flow returns to the call site.
10742 <ul>
10743 <li>See also {#link|Suspend and Resume#}</li>
10744 </ul>
10745 </td>
10746 </tr>
10747 <tr>
10748 <td>
10749 <pre>{#syntax#}switch{#endsyntax#}</pre>
10750 </td>
10751 <td>
10752 A {#syntax#}switch{#endsyntax#} expression can be used to test values of a common type.
10753 {#syntax#}switch{#endsyntax#} cases can capture field values of a {#link|Tagged union#}.
10754 <ul>
10755 <li>See also {#link|switch#}</li>
10756 </ul>
10757 </td>
10758 </tr>
10759 <tr>
10760 <td>
10761 <pre>{#syntax#}test{#endsyntax#}</pre>
10762 </td>
10763 <td>
10764 The {#syntax#}test{#endsyntax#} keyword can be used to denote a top-level block of code
10765 used to make sure behavior meets expectations.
10766 <ul>
10767 <li>See also {#link|Zig Test#}</li>
10768 </ul>
10769 </td>
10770 </tr>
10771 <tr>
10772 <td>
10773 <pre>{#syntax#}threadlocal{#endsyntax#}</pre>
10774 </td>
10775 <td>
10776 {#syntax#}threadlocal{#endsyntax#} can be used to specify a variable as thread-local.
10777 <ul>
10778 <li>See also {#link|Thread Local Variables#}</li>
10779 </ul>
10780 </td>
10781 </tr>
10782 <tr>
10783 <td>
10784 <pre>{#syntax#}true{#endsyntax#}</pre>
10785 </td>
10786 <td>
10787 The boolean value {#syntax#}true{#endsyntax#}.
10788 <ul>
10789 <li>See also {#link|Primitive Values#}</li>
10790 </ul>
10791 </td>
10792 </tr>
10793 <tr>
10794 <td>
10795 <pre>{#syntax#}try{#endsyntax#}</pre>
10796 </td>
10797 <td>
10798 {#syntax#}try{#endsyntax#} evaluates an error union expression.
10799 If it is an error, it returns from the current function with the same error.
10800 Otherwise, the expression results in the unwrapped value.
10801 <ul>
10802 <li>See also {#link|try#}</li>
10803 </ul>
10804 </td>
10805 </tr>
10806 <tr>
10807 <td>
10808 <pre>{#syntax#}undefined{#endsyntax#}</pre>
10809 </td>
10810 <td>
10811 {#syntax#}undefined{#endsyntax#} can be used to leave a value uninitialized.
10812 <ul>
10813 <li>See also {#link|undefined#}</li>
10814 </ul>
10815 </td>
10816 </tr>
10817 <tr>
10818 <td>
10819 <pre>{#syntax#}union{#endsyntax#}</pre>
10820 </td>
10821 <td>
10822 {#syntax#}union{#endsyntax#} defines a union.
10823 <ul>
10824 <li>See also {#link|union#}</li>
10825 </ul>
10826 </td>
10827 </tr>
10828 <tr>
10829 <td>
10830 <pre>{#syntax#}unreachable{#endsyntax#}</pre>
10831 </td>
10832 <td>
10833 {#syntax#}unreachable{#endsyntax#} can be used to assert that control flow will never happen upon a particular location.
10834 Depending on the build mode, {#syntax#}unreachable{#endsyntax#} may emit a panic.
10835 <ul>
10836 <li>Emits a panic in {#syntax#}Debug{#endsyntax#} and {#syntax#}ReleaseSafe{#endsyntax#} mode, or when using <code>zig test</code>.</li>
10837 <li>Does not emit a panic in {#syntax#}ReleaseFast{#endsyntax#} mode, unless <code>zig test</code> is being used.</li>
10838 <li>See also {#link|unreachable#}</li>
10839 </ul>
10840 </td>
10841 </tr>
10842 <tr>
10843 <td>
10844 <pre>{#syntax#}usingnamespace{#endsyntax#}</pre>
10845 </td>
10846 <td>
10847 {#syntax#}usingnamespace{#endsyntax#} is a top-level declaration that imports all the public declarations of the operand,
10848 which must be a struct, union, or enum, into the current scope.
10849 <ul>
10850 <li>See also {#link|usingnamespace#}</li>
10851 </ul>
10852 </td>
10853 </tr>
10854 <tr>
10855 <td>
10856 <pre>{#syntax#}var{#endsyntax#}</pre>
10857 </td>
10858 <td>
10859 {#syntax#}var{#endsyntax#} declares a variable that may be modified.
10860 <ul>
10861 <li>See also {#link|Variables#}</li>
10862 </ul>
10863 </td>
10864 </tr>
10865 <tr>
10866 <td>
10867 <pre>{#syntax#}volatile{#endsyntax#}</pre>
10868 </td>
10869 <td>
10870 {#syntax#}volatile{#endsyntax#} can be used to denote loads or stores of a pointer have side effects.
10871 It can also modify an inline assembly expression to denote it has side effects.
10872 <ul>
10873 <li>See also {#link|volatile#}, {#link|Assembly#}</li>
10874 </ul>
10875 </td>
10876 </tr>
10877 <tr>
10878 <td>
10879 <pre>{#syntax#}while{#endsyntax#}</pre>
10880 </td>
10881 <td>
10882 A {#syntax#}while{#endsyntax#} expression can be used to repeatedly test a boolean, optional, or error union expression,
10883 and cease looping when that expression evaluates to false, null, or an error, respectively.
10884 <ul>
10885 <li>See also {#link|while#}</li>
10886 </ul>
10887 </td>
10888 </tr>
10889 </table>
10890 </div>
1031910891 {#header_close#}
1032010892
1032110893 {#header_open|Grammar#}