authorgravatar for mrpaul@aestheticwisdom.comPaul Espinosa <mrpaul@aestheticwisdom.com> 2020-07-09 18:38:02+07:00
committergravatar for mrpaul@aestheticwisdom.comPaul Espinosa <mrpaul@aestheticwisdom.com> 2020-07-09 21:32:51+07:00
logf510f385920b9a22bd1e68839cd4be3eea092e4d
tree2dfb2883ce38edcf6f9af13bd0278e119d630c78
parenta489ea0b2f38c67025c2b2424749a9a7320cdd5a

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.

1 files changed, 86 insertions(+), 5 deletions(-)

doc/langref.html.in+86-5
......@@ -218,6 +218,8 @@
218218 </p>
219219 <p>
220220 The code samples in this document are compiled and tested as part of the main test suite of Zig.
221 </p>
222 <p>
221223 This HTML document depends on no external files, so you can use it offline.
222224 </p>
223225 <p>
......@@ -236,10 +238,89 @@ pub fn main() !void {
236238}
237239 {#code_end#}
238240 <p>
239 Usually you don't want to write to stdout. You want to write to stderr, and you
240 don't care if it fails. For that you can use a simpler API:
241 The Zig code sample above demonstrates one way to create a program that will output <code>Hello, world!</code>.
241242 </p>
242 {#code_begin|exe|hello#}
243 <p>
244 The code sample shows the contents of a file named <code>hello.zig</code>. Files storing Zig
245 source code are {#link|UTF-8 encoded|Source Encoding#} text files. The files storing
246 Zig source code are usually named with the <code>.zig</code> extension.
247 </p>
248 <p>
249 Following the <code>hello.zig</code> Zig code sample, the {#link|Zig Build System#} is used
250 to build an executable program from the <code>hello.zig</code> source code. Then, the
251 <code>hello</code> program is executed showing its output <code>Hello, world!</code>. The
252 lines beginning with <code>$</code> represent command line prompts and a command.
253 Everything else is program output.
254 </p>
255 <p>
256 The code sample begins by adding Zig's Standard Library to the build using the {#link|@import#} builtin function.
257 The {#syntax#}@import("std"){#endsyntax#} function call creates a structure to represent the Standard Library.
258 The code then makes a {#link|top-level declaration|Global Variables#} of a
259 {#link|constant identifier|Assignment#}, named <code>std</code>, for easy access to
260 <a href="https://github.com/ziglang/zig/wiki/FAQ#where-is-the-documentation-for-the-zig-standard-library">Zig's standard library</a>.
261 </p>
262 <p>
263 Next, a {#link|public function|Functions#}, {#syntax#}pub fn{#endsyntax#}, named <code>main</code>
264 is declared. The <code>main</code> function is necessary because it tells the Zig compiler where the start of
265 the program exists. Programs designed to be executed will need a {#syntax#}pub fn main{#endsyntax#} function.
266 For more advanced Zig use cases, Zig offers other features to inform the compiler where the start of
267 the program exists. Libraries, on the other hand, do not need a <code>main</code> function because
268 library code is usually called by other programs.
269 </p>
270 <p>
271 A function is a block of any number of statements and expressions that, as a whole, perform a task.
272 Functions may or may not return data after they are done performing their task.
273 </p>
274 <p>
275 In the <code>hello.zig</code> code sample, the <code>main</code> function is declared
276 with the {#syntax#}!void{#endsyntax#} return type. This return type tells the Zig compiler,
277 and other people reading the code, the function will not return a value and it <i>might</i> fail.
278 The {#syntax#}!{#endsyntax#} (bang, exclamation mark) before the {#syntax#}void{#endsyntax#}
279 {#link|type|Primitive Types#} is what tells the Zig compiler an {#link|error|Errors#} <i>might</i>
280 occur. The {#syntax#}void{#endsyntax#} return type tells the Zig compiler the <code>main</code>
281 function will not return a value.
282 </p>
283 <p>
284 In Zig, a function's block of statements and expressions are surrounded by <code>{</code> and
285 <code>}</code> curly-braces. Inside of the <code>main</code> function are expressions that perform
286 the task of outputting <code>Hello, world!</code> to standard output.
287 </p>
288 <p>
289 First, a constant identifier, <code>stdout</code>, is initialized to represent the standard output
290 stream. Then, the program tries to print the <code>Hello, world!</code> message to the standard output
291 stream.
292 </p>
293 <p>
294 Functions sometimes need information to perform their task. In Zig, information is passed
295 to functions between open <code>(</code> and close <code>)</code> parenthesis placed after
296 the function's name. The information passed to functions are its arguments. When there are
297 multiple arguments passed to a function, they are separated by commas <code>,</code>.
298 </p>
299 <p>
300 The two arguments passed to the <code>stdout.print()</code> function, <code>"Hello, {}!\n"</code>
301 and <code>.{"world"}</code>, are evaluated at {#link|compile-time|comptime#}. The code sample is
302 purposely written to show how to perform {#link|string|String Literals and Character Literals#}
303 substitution in the <code>print</code> function. The curly-braces inside of the first argument
304 are substituted with the compile-time known value inside of the second argument
305 (known as an {#link|anonymous struct literal|Anonymous Struct Literals#}). The <code>\n</code>
306 inside of the double-quotes of the first argument is the {#link|escape sequence|Escape Sequences#} for the
307 newline character. The {#link|try#} expression evaluates the result of <code>stdout.print</code>.
308 If the result is an error, then the {#syntax#}try{#endsyntax#} expression will return from
309 <code>main</code> with the error. Otherwise, the program will continue. In this case, there are no
310 more statements or expressions left to execute in the <code>main</code> function, so the program exits.
311 </p>
312 <p>
313 In Zig, the standard output stream's <code>print</code> function is allowed to fail because
314 it is actually a function defined for a generic output stream. Consider a generic output stream that
315 represents writing data to a file and the disk is full; a write to the file will fail. However,
316 we typically do not expect writing text to the standard output stream to fail. To avoid having
317 to handle the failure case of printing to a standard output, you can use alternate functions: the
318 <code>std.log</code> function for proper logging or the <code>std.debug.print</code> function.
319 This documentation will use the latter option to print to standard error (stderr) and silently
320 return on failure. The next code sample, <code>hello_again.zig</code> demonstrates the use of
321 <code>std.debug.print</code>.
322 </p>
323 {#code_begin|exe|hello_again#}
243324const print = @import("std").debug.print;
244325
245326pub fn main() void {
......@@ -247,9 +328,9 @@ pub fn main() void {
247328}
248329 {#code_end#}
249330 <p>
250 Note that you can leave off the {#syntax#}!{#endsyntax#} from the return type because {#syntax#}print{#endsyntax#} cannot fail.
331 Note that you can leave off the {#syntax#}!{#endsyntax#} from the return type because <code>std.debug.print</code> cannot fail.
251332 </p>
252 {#see_also|Values|@import|Errors|Root Source File#}
333 {#see_also|Values|@import|Errors|Root Source File|Source Encoding#}
253334 {#header_close#}
254335 {#header_open|Comments#}
255336 {#code_begin|test|comments#}