diff --git a/doc/go_tutorial.txt b/doc/go_tutorial.txt index 500231eb73d..24ad5a6e654 100644 --- a/doc/go_tutorial.txt +++ b/doc/go_tutorial.txt @@ -8,14 +8,128 @@ Rob Pike This document is a tutorial introduction to the basics of the Go systems programming -language, intended for programmers familiar with C or C++. +language, intended for programmers familiar with C or C++. It is not a comprehensive +guide to the language; at the moment the closest to that is the draft specification: + + /doc/go_lang.html + +To check out the compiler and tools and be ready to run Go programs, see + + /doc/go_setup.html + +The presentation proceeds through a series of modest programs to illustrate +key features of the language. All the programs work (at time of writing) and are +checked in at + + /doc/progs + +Program snippets are annotated with the line number in the original file; for +cleanliness, blank lines remain blank. + +Hello, World +---- + +Let's start in the usual way: --PROG progs/helloworld.go ---PROG progs/helloworld.go /func.main/ END +Every Go source file declares which package it's part of using a "package" statement. +The "main" package's "main" function is where the program starts running (after +any initialization). ---PROG progs/helloworld.go /print/ +Function declarations are introduced with the "func" keyword. ---PROG progs/helloworld.go /func/ +Notice that string constants can contain Unicode characters, encoded in UTF-8. +Go is defined to accept UTF-8 input. Strings are arrays of bytes, usually used +to store Unicode strings represented in UTF-8. -Now is the time. +The built-in function "print()" has been used during the early stages of +development of the language but is not guaranteed to last. Here's a better version of the +program that doesn't depend on this "print()": + +--PROG progs/helloworld2.go + +This version imports the ''os'' package to acess its "Stdout" variable, of type +"*OS.FD"; given "OS.Stdout" we can use its "WriteString" method to print the string. + +The comment convention is the same as in C++: + + /* ... */ + // ... + +Echo +---- + +Next up, here's a version of the Unix utility "echo(1)": + +--PROG progs/echo.go + +It's still fairly small but it's doing a number of new things. In the last example, +we saw "func" introducing a function. The keywords "var", "const", and "type" +(not used yet) also introduce declarations, as does "import". +Notice that we can group declarations of the same sort into +parenthesized, semicolon-separated lists if we want, as on lines 3-6 and 10-13. +But it's not necessary to do so; we could have said + + const Space = " " + const Newline = "\n" + +Semicolons aren't needed here; in fact, semicolons are unnecessary after any +top-level declaration, even though they are needed as separators within +a parenthesized list of declarations. + +Having imported the "Flag" package, line 8 creates a global variable to hold +the value of echo's -n flag. (The nil indicates a nice feature not needed here; +see the source in "src/lib/flag.go" for details). + +In "main.main", we parse the arguments (line 16) and then create a local +string variable we will use to build the output. + +The declaration statement has the form + + var s string = ""; + +This is the "var" keyword, followed by the name of the variable, followed by +its type, followed by an equals sign and an initial value for the variable. + +Go tries to be terse, and this declaration could be shortened. Since the +string constant is of type string, we don't have to tell the compiler that. +We could write + + var s = ""; + +or we could go even shorter and write the idiom + + s := ""; + +The := operator is used a lot in Go to represent an initializing declaration. +(For those who know Limbo, it's the same, except notice that there is no +colon after the name in a full "var" declaration.) +And here's one in the "for" clause on the next line: + +--PROG progs/echo.go /for/ + +The "Flag" package has parsed the arguments and left the non-flags in +a list that can be iterated over in the obvious way. + +The Go "for" statement differs from that of C in a number of ways. First, +it's the only looping construct; there is no "while" or "do". Second, +there are no parentheses on the clause, but the braces on the body +are mandatory. Later examples will show some other ways "for" +can be written. + +The body of the loop builds up the string "s" by appending (using +=) +the flags and separating spaces. After the loop, if the "-n" flag is not +set, it appends a newline, and then writes the result. + +Notice that "main.main" is a niladic function with no return type. +It's defined that way. Falling off the end of "main.main" means +''success''; if you want to signal erroneous return, use + + sys.exit(1) + +The "sys" package is built in and contains some essentials for getting +started; for instance, "sys.argc()" and "sys.argv(int)" are used by the +"Flag" package to access the arguments. + +More to come. diff --git a/doc/progs/echo.go b/doc/progs/echo.go new file mode 100644 index 00000000000..9dc82856575 --- /dev/null +++ b/doc/progs/echo.go @@ -0,0 +1,32 @@ +// Copyright 2009 The Go Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +package main + +import ( + OS "os"; + Flag "flag"; +) + +var n_flag = Flag.Bool("n", false, nil, "don't print final newline") + +const ( + Space = " "; + Newline = "\n"; +) + +func main() { + Flag.Parse(); // Scans the arg list and sets up flags + var s string = ""; + for i := 0; i < Flag.NArg(); i++ { + if i > 0 { + s += Space + } + s += Flag.Arg(i) + } + if !n_flag.BVal() { + s += Newline + } + OS.Stdout.WriteString(s); +} diff --git a/doc/progs/helloworld.go b/doc/progs/helloworld.go new file mode 100644 index 00000000000..b77b7208817 --- /dev/null +++ b/doc/progs/helloworld.go @@ -0,0 +1,9 @@ +// Copyright 2009 The Go Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +package main + +func main() { + print("Hello, world; or Καλημέρα κόσμε; or こんにちは 世界\n"); +} diff --git a/doc/progs/helloworld2.go b/doc/progs/helloworld2.go new file mode 100644 index 00000000000..f2b4cae702d --- /dev/null +++ b/doc/progs/helloworld2.go @@ -0,0 +1,11 @@ +// Copyright 2009 The Go Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +package main + +import OS "os" // this package contains features for basic I/O + +func main() { + OS.Stdout.WriteString("Hello, world; or Καλημέρα κόσμε; or こんにちは 世界\n"); +}