| ... | ... | @@ -410,109 +410,20 @@ pub fn main() !void { |
| 410 | 410 | } |
| 411 | 411 | {#code_end#} |
| 412 | 412 | <p> |
| 413 | | The Zig code sample above demonstrates one way to create a program that will output: <samp>Hello, world!</samp>. |
| 414 | | </p> |
| 415 | | <p> |
| 416 | | The code sample shows the contents of a file named <code class="file">hello.zig</code>. Files storing Zig |
| 417 | | source code are {#link|UTF-8 encoded|Source Encoding#} text files. The files storing |
| 418 | | Zig source code must be named with the <code class="file"><em>.zig</em></code> extension. |
| 419 | | </p> |
| 420 | | <p> |
| 421 | | Following the <code class="file">hello.zig</code> Zig code sample, the {#link|Zig Build System#} is used |
| 422 | | to build an executable program from the <code class="file">hello.zig</code> source code. Then, the |
| 423 | | <code class="file">hello</code> program is executed showing its output <samp>Hello, world!</samp>. The |
| 424 | | lines beginning with <samp>$</samp> represent command line prompts and a command. |
| 425 | | Everything else is program output. |
| 426 | | </p> |
| 427 | | <p> |
| 428 | | The code sample begins by adding the {#link|Zig Standard Library#} to the build using the {#link|@import#} builtin function. |
| 429 | | The {#syntax#}@import("std"){#endsyntax#} function call creates a structure that represents the Zig Standard Library. |
| 430 | | The code then {#link|declares|Container Level Variables#} a |
| 431 | | {#link|constant identifier|Assignment#}, named {#syntax#}std{#endsyntax#}, that gives access to the features of the Zig Standard Library. |
| 432 | | </p> |
| 433 | | <p> |
| 434 | | Next, a {#link|public function|Functions#}, {#syntax#}pub fn{#endsyntax#}, named {#syntax#}main{#endsyntax#} |
| 435 | | is declared. The {#syntax#}main{#endsyntax#} function is necessary because it tells the Zig compiler where the program starts. Programs |
| 436 | | designed to be executed will need a {#syntax#}pub fn main{#endsyntax#} function. |
| 437 | | </p> |
| 438 | | <aside role="note" aria-label="Note about main function"> |
| 439 | | <p> |
| 440 | | For more advanced use cases, Zig offers other features to inform the compiler where the program starts. Also, libraries do not need a |
| 441 | | {#syntax#}pub fn main{#endsyntax#} function because library code is called by other programs or libraries. |
| 442 | | </p> |
| 443 | | </aside> |
| 444 | | <p> |
| 445 | | A function is a block of any number of statements and expressions, that as a whole, perform a task. |
| 446 | | Functions may or may not return data after they are done performing their task. If a function |
| 447 | | cannot perform its task, it might return an error. Zig makes all of this explicit. |
| 448 | | </p> |
| 449 | | <p> |
| 450 | | In the <code class="file">hello.zig</code> code sample, the <code>main</code> function is declared |
| 451 | | with the {#syntax#}!void{#endsyntax#} return type. This return type is known as an {#link|Error Union Type#}. |
| 452 | | This syntax tells the Zig compiler that the function will either return an |
| 453 | | error or a value. An error union type combines an {#link|Error Set Type#} and any other data type |
| 454 | | (e.g. a {#link|Primitive Type|Primitive Types#} or a user-defined type such as a {#link|struct#}, {#link|enum#}, or {#link|union#}). |
| 455 | | The full form of an error union type is |
| 456 | | <code><error set type></code>{#syntax#}!{#endsyntax#}<code><any data type></code>. In the code |
| 457 | | sample, the error set type is not explicitly written on the left side of the {#syntax#}!{#endsyntax#} operator. |
| 458 | | When written this way, the error set type is an {#link|inferred error set type|Inferred Error Sets#}. The |
| 459 | | {#syntax#}void{#endsyntax#} after the {#syntax#}!{#endsyntax#} operator |
| 460 | | tells the compiler that the function will not return a value under normal circumstances (i.e. when no errors occur). |
| 461 | | </p> |
| 462 | | <aside role="note" aria-label="Note to disambiguate exclamation mark operator"> |
| 463 | | <p> |
| 464 | | Note to experienced programmers: Zig also has the boolean {#link|operator|Operators#} {#syntax#}!a{#endsyntax#} |
| 465 | | where {#syntax#}a{#endsyntax#} is a value of type {#syntax#}bool{#endsyntax#}. Error union types contain the |
| 466 | | name of the type in the syntax: {#syntax#}!{#endsyntax#}<code><any data type></code>. |
| 467 | | </p> |
| 468 | | </aside> |
| 469 | | <p> |
| 470 | | In Zig, a function's block of statements and expressions are surrounded by an open curly-brace <code>{</code> and |
| 471 | | close curly-brace <code>}</code>. In <code class="file">hello.zig</code>, the {#syntax#}main{#endsyntax#} function |
| 472 | | contains two statements. |
| 473 | | </p> |
| 474 | | <p> |
| 475 | | In the first statement, a constant identifier, {#syntax#}stdout{#endsyntax#}, is initialized to represent standard output's |
| 476 | | writer. In the second statement, the program tries to print the <samp>Hello, world!</samp> message to standard output. |
| 477 | | </p> |
| 478 | | <p> |
| 479 | | Functions sometimes need inputs to perform their task. Inputs are passed, in between parentheses, to functions. These |
| 480 | | inputs are also known as arguments. When multiple arguments are passed to a function, they are separated by commas. |
| 481 | | </p> |
| 482 | | <p> |
| 483 | | Two arguments are passed to the {#syntax#}stdout.print(){#endsyntax#} function: {#syntax#}"Hello, {s}!\n"{#endsyntax#} |
| 484 | | and {#syntax#}.{"world"}{#endsyntax#}. The first argument is called a format string, which is a string containing one or |
| 485 | | more placeholders. {#syntax#}"Hello, {s}!\n"{#endsyntax#} contains the placeholder {#syntax#}{s}{#endsyntax#}, which is |
| 486 | | replaced with {#syntax#}"world"{#endsyntax#} from the second argument. The file <code class="file">string_literals.zig</code> in |
| 487 | | {#link|String Literals and Unicode Code Point Literals|String Literals and Unicode Code Point Literals#} contains examples of format |
| 488 | | strings that can be used with the {#syntax#}stdout.print(){#endsyntax#} function. The <code>\n</code> inside of |
| 489 | | {#syntax#}"Hello, {s}!\n"{#endsyntax#} is the {#link|escape sequence|Escape Sequences#} for the newline character. |
| 490 | | </p> |
| 491 | | <p> |
| 492 | | The {#link|try#} expression evaluates the result of {#syntax#}stdout.print{#endsyntax#}. If the result is an error, then the |
| 493 | | {#syntax#}try{#endsyntax#} expression will return from {#syntax#}main{#endsyntax#} with the error. Otherwise, the program will continue. |
| 494 | | In this case, there are no more statements or expressions left to execute in the {#syntax#}main{#endsyntax#} function, so the program exits. |
| 495 | | </p> |
| 496 | | <p> |
| 497 | | In Zig, the standard output writer's {#syntax#}print{#endsyntax#} function is allowed to fail because |
| 498 | | it is actually a function defined as part of a generic Writer. Consider a generic Writer that |
| 499 | | represents writing data to a file. When the disk is full, a write to the file will fail. |
| 500 | | However, we typically do not expect writing text to the standard output to fail. To avoid having |
| 501 | | to handle the failure case of printing to standard output, you can use alternate functions: the |
| 502 | | functions in {#syntax#}std.log{#endsyntax#} for proper logging or the {#syntax#}std.debug.print{#endsyntax#} function. |
| 503 | | This documentation will use the latter option to print to standard error (stderr) and silently return |
| 504 | | on failure. The next code sample, <code class="file">hello_again.zig</code> demonstrates the use of |
| 505 | | {#syntax#}std.debug.print{#endsyntax#}. |
| 413 | Most of the time, it more appropriate to write to stderr rather than stdout, and |
| 414 | whether or not the message is successfully written to the stream is irrelevant. |
| 415 | For this common case, there is a simpler API: |
| 506 | 416 | </p> |
| 507 | 417 | {#code_begin|exe|hello_again#} |
| 508 | | const print = @import("std").debug.print; |
| 418 | const std = @import("std"); |
| 509 | 419 | |
| 510 | 420 | pub fn main() void { |
| 511 | | print("Hello, world!\n", .{}); |
| 421 | std.debug.print("Hello, world!\n", .{}); |
| 512 | 422 | } |
| 513 | 423 | {#code_end#} |
| 514 | 424 | <p> |
| 515 | | Note that you can leave off the {#syntax#}!{#endsyntax#} from the return type because {#syntax#}std.debug.print{#endsyntax#} cannot fail. |
| 425 | In this case, the {#syntax#}!{#endsyntax#} may be omitted from the return |
| 426 | type because no errors are returned from the function. |
| 516 | 427 | </p> |
| 517 | 428 | {#see_also|Values|@import|Errors|Root Source File|Source Encoding#} |
| 518 | 429 | {#header_close#} |
Andrew Kelley <andrew@ziglang.org> 2024-01-21 16:47:18-07:00