From f510f385920b9a22bd1e68839cd4be3eea092e4d Mon Sep 17 00:00:00 2001 From: Paul Espinosa Date: Thu, 9 Jul 2020 18:38:02 +0700 Subject: [PATCH] Explain Language Ref's Hello World To introduce the Zig programming language, the "Hello, world!" code sample now has documentation to explain some of the features shown in the code sample and contains links to those features in the rest of the documentation. Writing style goals: * Balance writing style to keep beginner and experience programmers interested. * Be concise: allow the rest of the documentation to clarify language features. --- doc/langref.html.in | 91 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 86 insertions(+), 5 deletions(-) diff --git a/doc/langref.html.in b/doc/langref.html.in index f64170817f..cf9e485e8a 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -218,6 +218,8 @@

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!.

- {#code_begin|exe|hello#} +

+ 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. +

+ {#code_begin|exe|hello_again#} const print = @import("std").debug.print; pub fn main() void { @@ -247,9 +328,9 @@ pub fn main() void { } {#code_end#}

- 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.

- {#see_also|Values|@import|Errors|Root Source File#} + {#see_also|Values|@import|Errors|Root Source File|Source Encoding#} {#header_close#} {#header_open|Comments#} {#code_begin|test|comments#}