Commit f510f385920b9a22bd1e68839cd4be3eea092e4d | zig

author	Paul Espinosa <mrpaul@aestheticwisdom.com> 2020-07-09 18:38:02+07:00
committer	Paul Espinosa <mrpaul@aestheticwisdom.com> 2020-07-09 21:32:51+07:00
log	f510f385920b9a22bd1e68839cd4be3eea092e4d
tree	2dfb2883ce38edcf6f9af13bd0278e119d630c78
parent	a489ea0b2f38c67025c2b2424749a9a7320cdd5a

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

doc/langref.html.in+86-5

...	@@ -218,6 +218,8 @@	...	@@ -218,6 +218,8 @@
218	</p>	218	</p>
219	<p>	219	<p>
220	The code samples in this document are compiled and tested as part of the main test suite of Zig.	220	The code samples in this document are compiled and tested as part of the main test suite of Zig.
		221	</p>
		222	<p>
221	This HTML document depends on no external files, so you can use it offline.	223	This HTML document depends on no external files, so you can use it offline.
222	</p>	224	</p>
223	<p>	225	<p>
...	@@ -236,10 +238,89 @@ pub fn main() !void {	...	@@ -236,10 +238,89 @@ pub fn main() !void {
236	}	238	}
237	{#code_end#}	239	{#code_end#}
238	<p>	240	<p>
239	Usually you don't want to write to stdout. You want to write to stderr, and you	241	The Zig code sample above demonstrates one way to create a program that will output <code>Hello, world!</code>.
240	don't care if it fails. For that you can use a simpler API:
241	</p>	242	</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#}
243	const print = @import("std").debug.print;	324	const print = @import("std").debug.print;
244		325
245	pub fn main() void {	326	pub fn main() void {
...	@@ -247,9 +328,9 @@ pub fn main() void {	...	@@ -247,9 +328,9 @@ pub fn main() void {
247	}	328	}
248	{#code_end#}	329	{#code_end#}
249	<p>	330	<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.
251	</p>	332	</p>
252	{#see_also\|Values\|@import\|Errors\|Root Source File#}	333	{#see_also\|Values\|@import\|Errors\|Root Source File\|Source Encoding#}
253	{#header_close#}	334	{#header_close#}
254	{#header_open\|Comments#}	335	{#header_open\|Comments#}
255	{#code_begin\|test\|comments#}	336	{#code_begin\|test\|comments#}