mirrors/zig
1
0
Fork 0
mirror of https://codeberg.org/ziglang/zig.git synced 2025-12-06 13:54:21 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Explain Language Ref's Hello World

Browse source 
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.
This commit is contained in:
Paul Espinosa 2020-07-09 18:38:02 +07:00
parent a489ea0b2f
commit f510f38592
1 changed files with 86 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

91
doc/langref.html.in
View file

@ -218,6 +218,8 @@
</p>
<p>
The code samples in this document are compiled and tested as part of the main test suite of Zig.
</p>
<p>
This HTML document depends on no external files, so you can use it offline.
</p>
<p>
@ -236,10 +238,89 @@ pub fn main() !void {
}
{#code_end#}
<p>
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 <code>Hello, world!</code>.
</p>
{#code_begin|exe|hello#}
<p>
The code sample shows the contents of a file named <code>hello.zig</code>. 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 <code>.zig</code> extension.
</p>
<p>
Following the <code>hello.zig</code> Zig code sample, the {#link|Zig Build System#} is used
to build an executable program from the <code>hello.zig</code> source code. Then, the
<code>hello</code> program is executed showing its output <code>Hello, world!</code>. The
lines beginning with <code>$</code> represent command line prompts and a command.
Everything else is program output.
</p>
<p>
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 <code>std</code>, for easy access to
<a href="https://github.com/ziglang/zig/wiki/FAQ#where-is-the-documentation-for-the-zig-standard-library">Zig's standard library</a>.
</p>
<p>
Next, a {#link|public function|Functions#}, {#syntax#}pub fn{#endsyntax#}, named <code>main</code>
is declared. The <code>main</code> 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 <code>main</code> function because
library code is usually called by other programs.
</p>
<p>
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.
</p>
<p>
In the <code>hello.zig</code> code sample, the <code>main</code> 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 <i>might</i> 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#} <i>might</i>
occur. The {#syntax#}void{#endsyntax#} return type tells the Zig compiler the <code>main</code>
function will not return a value.
</p>
<p>
In Zig, a function's block of statements and expressions are surrounded by <code>{</code> and
<code>}</code> curly-braces. Inside of the <code>main</code> function are expressions that perform
the task of outputting <code>Hello, world!</code> to standard output.
</p>
<p>
First, a constant identifier, <code>stdout</code>, is initialized to represent the standard output
stream. Then, the program tries to print the <code>Hello, world!</code> message to the standard output
stream.
</p>
<p>
Functions sometimes need information to perform their task. In Zig, information is passed
to functions between open <code>(</code> and close <code>)</code> 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 <code>,</code>.
</p>
<p>
The two arguments passed to the <code>stdout.print()</code> function, <code>"Hello, {}!\n"</code>
and <code>.{"world"}</code>, 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 <code>print</code> 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 <code>\n</code>
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 <code>stdout.print</code>.
If the result is an error, then the {#syntax#}try{#endsyntax#} expression will return from
<code>main</code> with the error. Otherwise, the program will continue. In this case, there are no
more statements or expressions left to execute in the <code>main</code> function, so the program exits.
</p>
<p>
In Zig, the standard output stream's <code>print</code> 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
<code>std.log</code> function for proper logging or the <code>std.debug.print</code> function.
This documentation will use the latter option to print to standard error (stderr) and silently
return on failure. The next code sample, <code>hello_again.zig</code> demonstrates the use of
<code>std.debug.print</code>.
</p>
{#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#}
<p>
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 <code>std.debug.print</code> cannot fail.
</p>
{#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#}