The code samples in this document are compiled and tested as part of the main test suite of Zig. +
+This HTML document depends on no external files, so you can use it offline.
@@ -236,10 +238,89 @@ pub fn main() !void { } {#code_end#}
- Usually you don't want to write to stdout. You want to write to stderr, and you
- don't care if it fails. For that you can use a simpler API:
+ The Zig code sample above demonstrates one way to create a program that will output Hello, world!.
+ The code sample shows the contents of a file named hello.zig. Files storing Zig
+ source code are {#link|UTF-8 encoded|Source Encoding#} text files. The files storing
+ Zig source code are usually named with the .zig extension.
+
+ Following the hello.zig Zig code sample, the {#link|Zig Build System#} is used
+ to build an executable program from the hello.zig source code. Then, the
+ hello program is executed showing its output Hello, world!. The
+ lines beginning with $ represent command line prompts and a command.
+ Everything else is program output.
+
+ The code sample begins by adding Zig's Standard Library to the build using the {#link|@import#} builtin function.
+ The {#syntax#}@import("std"){#endsyntax#} function call creates a structure to represent the Standard Library.
+ The code then makes a {#link|top-level declaration|Global Variables#} of a
+ {#link|constant identifier|Assignment#}, named std, for easy access to
+ Zig's standard library.
+
+ Next, a {#link|public function|Functions#}, {#syntax#}pub fn{#endsyntax#}, named main
+ is declared. The main function is necessary because it tells the Zig compiler where the start of
+ the program exists. Programs designed to be executed will need a {#syntax#}pub fn main{#endsyntax#} function.
+ For more advanced Zig use cases, Zig offers other features to inform the compiler where the start of
+ the program exists. Libraries, on the other hand, do not need a main function because
+ library code is usually called by other programs.
+
+ A function is a block of any number of statements and expressions that, as a whole, perform a task. + Functions may or may not return data after they are done performing their task. +
+
+ In the hello.zig code sample, the main function is declared
+ with the {#syntax#}!void{#endsyntax#} return type. This return type tells the Zig compiler,
+ and other people reading the code, the function will not return a value and it might fail.
+ The {#syntax#}!{#endsyntax#} (bang, exclamation mark) before the {#syntax#}void{#endsyntax#}
+ {#link|type|Primitive Types#} is what tells the Zig compiler an {#link|error|Errors#} might
+ occur. The {#syntax#}void{#endsyntax#} return type tells the Zig compiler the main
+ function will not return a value.
+
+ In Zig, a function's block of statements and expressions are surrounded by { and
+ } curly-braces. Inside of the main function are expressions that perform
+ the task of outputting Hello, world! to standard output.
+
+ First, a constant identifier, stdout, is initialized to represent the standard output
+ stream. Then, the program tries to print the Hello, world! message to the standard output
+ stream.
+
+ Functions sometimes need information to perform their task. In Zig, information is passed
+ to functions between open ( and close ) parenthesis placed after
+ the function's name. The information passed to functions are its arguments. When there are
+ multiple arguments passed to a function, they are separated by commas ,.
+
+ The two arguments passed to the stdout.print() function, "Hello, {}!\n"
+ and .{"world"}, are evaluated at {#link|compile-time|comptime#}. The code sample is
+ purposely written to show how to perform {#link|string|String Literals and Character Literals#}
+ substitution in the print function. The curly-braces inside of the first argument
+ are substituted with the compile-time known value inside of the second argument
+ (known as an {#link|anonymous struct literal|Anonymous Struct Literals#}). The \n
+ inside of the double-quotes of the first argument is the {#link|escape sequence|Escape Sequences#} for the
+ newline character. The {#link|try#} expression evaluates the result of stdout.print.
+ If the result is an error, then the {#syntax#}try{#endsyntax#} expression will return from
+ main with the error. Otherwise, the program will continue. In this case, there are no
+ more statements or expressions left to execute in the main function, so the program exits.
+
+ In Zig, the standard output stream's print function is allowed to fail because
+ it is actually a function defined for a generic output stream. Consider a generic output stream that
+ represents writing data to a file and the disk is full; a write to the file will fail. However,
+ we typically do not expect writing text to the standard output stream to fail. To avoid having
+ to handle the failure case of printing to a standard output, you can use alternate functions: the
+ std.log function for proper logging or the std.debug.print function.
+ This documentation will use the latter option to print to standard error (stderr) and silently
+ return on failure. The next code sample, hello_again.zig demonstrates the use of
+ std.debug.print.
+
- Note that you can leave off the {#syntax#}!{#endsyntax#} from the return type because {#syntax#}print{#endsyntax#} cannot fail.
+ Note that you can leave off the {#syntax#}!{#endsyntax#} from the return type because std.debug.print cannot fail.