From f510f385920b9a22bd1e68839cd4be3eea092e4d Mon Sep 17 00:00:00 2001 From: Paul Espinosa Date: Thu, 9 Jul 2020 18:38:02 +0700 Subject: [PATCH 1/6] 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 f64170817f3e46d7ba8d24ec6b1d0b0cd9f41301..cf9e485e8a3fb2f8ead41e7475780cfc212e5a0a 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#} -- 2.54.0 From 5afa7f2545a5f350bbac4c9d9349a7fbbd8f0977 Mon Sep 17 00:00:00 2001 From: Paul Date: Sat, 11 Jul 2020 09:09:07 +0700 Subject: [PATCH 2/6] Update doc/langref.html.in Co-authored-by: Joachim Schmidt --- doc/langref.html.in | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/langref.html.in b/doc/langref.html.in index cf9e485e8a3fb2f8ead41e7475780cfc212e5a0a..0f17f4c09668c439bdebdfb053207c14b87bc33b 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -273,8 +273,8 @@ pub fn main() !void {

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. + with the {#syntax#}!void{#endsyntax#} return type. This return type tells the Zig compiler + and other people reading the code that 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 -- 2.54.0 From 656b640e79e8cd391a046bb69713bffc3e0ff7b3 Mon Sep 17 00:00:00 2001 From: Paul Date: Sat, 11 Jul 2020 09:09:43 +0700 Subject: [PATCH 3/6] Update doc/langref.html.in Co-authored-by: Joachim Schmidt --- doc/langref.html.in | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/langref.html.in b/doc/langref.html.in index 0f17f4c09668c439bdebdfb053207c14b87bc33b..c84edbc6a22503072f90ab727324326dccd2c4b8 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -312,7 +312,7 @@ pub fn main() !void {

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, + represents writing data to a file. When 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. -- 2.54.0 From 50df1334f35411e0dbf12624dab68667a4e7a6ac Mon Sep 17 00:00:00 2001 From: Paul Date: Sat, 11 Jul 2020 09:09:57 +0700 Subject: [PATCH 4/6] Update doc/langref.html.in Co-authored-by: Joachim Schmidt --- doc/langref.html.in | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/langref.html.in b/doc/langref.html.in index c84edbc6a22503072f90ab727324326dccd2c4b8..6821dfd9f914a2d9e39c16173c7390ec7853cfd3 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -293,7 +293,7 @@ pub fn main() !void {

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 + the function's name. This information is also known as arguments. When there are multiple arguments passed to a function, they are separated by commas ,.

-- 2.54.0 From e57458a94f677c54ba3ff6698831312e622e8b2b Mon Sep 17 00:00:00 2001 From: Paul Date: Sat, 11 Jul 2020 09:10:08 +0700 Subject: [PATCH 5/6] Update doc/langref.html.in Co-authored-by: Joachim Schmidt --- doc/langref.html.in | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/langref.html.in b/doc/langref.html.in index 6821dfd9f914a2d9e39c16173c7390ec7853cfd3..d181844e90fc10f18444e8e9f461cd8c8131a1a0 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -263,7 +263,7 @@ pub fn main() !void { 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 + For more advanced 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.

-- 2.54.0 From b45a2d72c83ef383af24a7af03604292c7089dae Mon Sep 17 00:00:00 2001 From: Paul Espinosa Date: Sat, 11 Jul 2020 18:08:00 +0700 Subject: [PATCH 6/6] Introduce Error Union and Use Writer This commit edits the "Hello, World!" introduction. It introduces Error Union Types. Also, it changes `outStream` to `writer` in the code example and description. --- doc/langref.html.in | 45 +++++++++++++++++++++++++++------------------ 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/doc/langref.html.in b/doc/langref.html.in index d181844e90fc10f18444e8e9f461cd8c8131a1a0..51e7902c8cfdda640d59ed1184178afde91c5263 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -233,7 +233,7 @@ const std = @import("std"); pub fn main() !void { - const stdout = std.io.getStdOut().outStream(); + const stdout = std.io.getStdOut().writer(); try stdout.print("Hello, {}!\n", .{"world"}); } {#code_end#} @@ -269,16 +269,25 @@ pub fn main() !void {

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. + Functions may or may not return data after they are done performing their task. If a function + cannot perform its task, it might return an error. Zig makes all of this explicit.

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 that 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. + with the {#syntax#}!void{#endsyntax#} return type. This return type is known as an {#link|Error Union Type#}. + This syntax tells the Zig compiler that the function will either return an + error or a value. An error union type combines an {#link|Error Set Type#} and a {#link|Primitive Type|Primitive Types#}. + The full form of an error union type is + <error set type>{#syntax#}!{#endsyntax#}<primitive type>. In the code + sample, the error set type is not explicitly written on the left side of the {#syntax#}!{#endsyntax#} operator. + When written this way, the error set type is a special kind of error union type that has an + {#link|inferred error set type|Inferred Error Sets#}. The {#syntax#}void{#endsyntax#} after the {#syntax#}!{#endsyntax#} operator + tells the compiler that the function will not return a value under normal circumstances (i.e. no errors occur). +

+

+ Note to experienced programmers: Zig also has the boolean {#link|operator|Operators#} {#syntax#}!a{#endsyntax#} + where {#syntax#}a{#endsyntax#} is a value of type {#syntax#}bool{#endsyntax#}. Error union types contain the + name of the type in the syntax: {#syntax#}!{#endsyntax#}<primitive type>.

In Zig, a function's block of statements and expressions are surrounded by { and @@ -286,9 +295,9 @@ pub fn main() !void { 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. + First, a constant identifier, stdout, is initialized to represent standard output's + writer. Then, the program tries to print the Hello, world! + message to standard output.

Functions sometimes need information to perform their task. In Zig, information is passed @@ -310,14 +319,14 @@ pub fn main() !void { 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. When 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 + In Zig, the standard output writer's print function is allowed to fail because + it is actually a function defined as part of a generic Writer. Consider a generic Writer that + represents writing data to a file. When the disk is full, a write to the file will fail. + However, we typically do not expect writing text to the standard output to fail. To avoid having + to handle the failure case of printing to 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 + 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#} -- 2.54.0