| ... | ... | @@ -218,6 +218,8 @@ |
| 218 | 218 | </p> |
| 219 | 219 | <p> |
| 220 | 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 | 223 | This HTML document depends on no external files, so you can use it offline. |
| 222 | 224 | </p> |
| 223 | 225 | <p> |
| ... | ... | @@ -236,10 +238,98 @@ pub fn main() !void { |
| 236 | 238 | } |
| 237 | 239 | {#code_end#} |
| 238 | 240 | <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>. |
| 241 | 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 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. If a function |
| 273 | cannot perform its task, it might return an error. Zig makes all of this explicit. |
| 274 | </p> |
| 275 | <p> |
| 276 | In the <code>hello.zig</code> code sample, the <code>main</code> function is declared |
| 277 | with the {#syntax#}!void{#endsyntax#} return type. This return type is known as an {#link|Error Union Type#}. |
| 278 | This syntax tells the Zig compiler that the function will either return an |
| 279 | error or a value. An error union type combines an {#link|Error Set Type#} and a {#link|Primitive Type|Primitive Types#}. |
| 280 | The full form of an error union type is |
| 281 | <code><error set type></code>{#syntax#}!{#endsyntax#}<code><primitive type></code>. In the code |
| 282 | sample, the error set type is not explicitly written on the left side of the {#syntax#}!{#endsyntax#} operator. |
| 283 | When written this way, the error set type is a special kind of error union type that has an |
| 284 | {#link|inferred error set type|Inferred Error Sets#}. The {#syntax#}void{#endsyntax#} after the {#syntax#}!{#endsyntax#} operator |
| 285 | tells the compiler that the function will not return a value under normal circumstances (i.e. no errors occur). |
| 286 | </p> |
| 287 | <p> |
| 288 | Note to experienced programmers: Zig also has the boolean {#link|operator|Operators#} {#syntax#}!a{#endsyntax#} |
| 289 | where {#syntax#}a{#endsyntax#} is a value of type {#syntax#}bool{#endsyntax#}. Error union types contain the |
| 290 | name of the type in the syntax: {#syntax#}!{#endsyntax#}<code><primitive type></code>. |
| 291 | </p> |
| 292 | <p> |
| 293 | In Zig, a function's block of statements and expressions are surrounded by <code>{</code> and |
| 294 | <code>}</code> curly-braces. Inside of the <code>main</code> function are expressions that perform |
| 295 | the task of outputting <code>Hello, world!</code> to standard output. |
| 296 | </p> |
| 297 | <p> |
| 298 | First, a constant identifier, <code>stdout</code>, is initialized to represent standard output's |
| 299 | writer. Then, the program tries to print the <code>Hello, world!</code> |
| 300 | message to standard output. |
| 301 | </p> |
| 302 | <p> |
| 303 | Functions sometimes need information to perform their task. In Zig, information is passed |
| 304 | to functions between open <code>(</code> and close <code>)</code> parenthesis placed after |
| 305 | the function's name. This information is also known as arguments. When there are |
| 306 | multiple arguments passed to a function, they are separated by commas <code>,</code>. |
| 307 | </p> |
| 308 | <p> |
| 309 | The two arguments passed to the <code>stdout.print()</code> function, <code>"Hello, {}!\n"</code> |
| 310 | and <code>.{"world"}</code>, are evaluated at {#link|compile-time|comptime#}. The code sample is |
| 311 | purposely written to show how to perform {#link|string|String Literals and Character Literals#} |
| 312 | substitution in the <code>print</code> function. The curly-braces inside of the first argument |
| 313 | are substituted with the compile-time known value inside of the second argument |
| 314 | (known as an {#link|anonymous struct literal|Anonymous Struct Literals#}). The <code>\n</code> |
| 315 | inside of the double-quotes of the first argument is the {#link|escape sequence|Escape Sequences#} for the |
| 316 | newline character. The {#link|try#} expression evaluates the result of <code>stdout.print</code>. |
| 317 | If the result is an error, then the {#syntax#}try{#endsyntax#} expression will return from |
| 318 | <code>main</code> with the error. Otherwise, the program will continue. In this case, there are no |
| 319 | more statements or expressions left to execute in the <code>main</code> function, so the program exits. |
| 320 | </p> |
| 321 | <p> |
| 322 | In Zig, the standard output writer's <code>print</code> function is allowed to fail because |
| 323 | it is actually a function defined as part of a generic Writer. Consider a generic Writer that |
| 324 | represents writing data to a file. When the disk is full, a write to the file will fail. |
| 325 | However, we typically do not expect writing text to the standard output to fail. To avoid having |
| 326 | to handle the failure case of printing to standard output, you can use alternate functions: the |
| 327 | <code>std.log</code> function for proper logging or the <code>std.debug.print</code> function. |
| 328 | This documentation will use the latter option to print to standard error (stderr) and silently return |
| 329 | on failure. The next code sample, <code>hello_again.zig</code> demonstrates the use of |
| 330 | <code>std.debug.print</code>. |
| 331 | </p> |
| 332 | {#code_begin|exe|hello_again#} |
| 243 | 333 | const print = @import("std").debug.print; |
| 244 | 334 | |
| 245 | 335 | pub fn main() void { |
| ... | ... | @@ -247,9 +337,9 @@ pub fn main() void { |
| 247 | 337 | } |
| 248 | 338 | {#code_end#} |
| 249 | 339 | <p> |
| 250 | | Note that you can leave off the {#syntax#}!{#endsyntax#} from the return type because {#syntax#}print{#endsyntax#} cannot fail. |
| 340 | Note that you can leave off the {#syntax#}!{#endsyntax#} from the return type because <code>std.debug.print</code> cannot fail. |
| 251 | 341 | </p> |
| 252 | | {#see_also|Values|@import|Errors|Root Source File#} |
| 342 | {#see_also|Values|@import|Errors|Root Source File|Source Encoding#} |
| 253 | 343 | {#header_close#} |
| 254 | 344 | {#header_open|Comments#} |
| 255 | 345 | {#code_begin|test|comments#} |
Andrew Kelley <andrew@ziglang.org> 2020-07-13 22:45:32+00:00
GitHub <noreply@github.com> 2020-07-13 22:45:32+00:00
Signed by PGP key 4AEE18F83AFDEB23