Go first draft

1 files changed, 423 insertions, 0 deletions

diff --git a/go.html.markdown b/go.html.markdown
new file mode 100644
index 00000000..9888b37d
--- /dev/null
+++ b/go.html.markdown
@@ -0,0 +1,423 @@
+---
+name: Go
+category: language
+language: Go
+filename: learngo.go
+contributors:
+    - ["Sonia Keys", "https://github.com/soniakeys"]
+---
+
+Go was created out of the need to get work done.  It's not the latest trend
+in computer science, but it is the newest fastest way to solve real-world
+problems.
+
+It has familiar concepts of imperative languages with static typing.
+It's fast to compile and fast to execute, it adds easy-to-understand
+concurrency to leverage today's multi-core CPUs, and has features to
+help with large-scale programming.
+
+Go comes with a great standard library and an enthusiastic community.
+
+```Go
+// Single line comment
+/* Multi-
+   line comment */
+
+// A package clause starts every source file.
+// Main is a special name declaring an executable rather than a library.
+package main
+
+// An import declaration comes next.  It declares library packages referenced
+// in this file.  The list must be exactly correct!  Missing or unused packages
+// are errors, not warnings.
+import (
+	"fmt"      // A package in the Go standard library
+	"net/http" // Yes, a web server!
+	"strconv"  // String conversions
+)
+
+// A function definition.  Main is special.  It is the entry point for the
+// executable program.  Love it or hate it, Go uses brace brackets.
+func main() {
+	// Println is a function that outputs a line to stdout.  It can be
+	// called here because fmt has been imported and the function name
+	// "Println" is upper case.  Symbols starting with an upper case letter
+	// are publicly visible.  No other special syntax is needed to export
+	// something from a package.
+	// To call Println, qualify it with the package name, fmt.
+	fmt.Println("Hello world!")
+
+	// Call another function within this package.
+	beyondHello()
+}
+
+// Idiomatic Go uses camel case.  Functions have parameters in parentheses.
+// If there are no parameters, empty parens are still required.
+func beyondHello() {
+	var x int // Variable declaration.  Variables must be declared before use.
+	x = 3     // Variable assignment.
+	// "Short" declarations use := syntax to declare and assign, infering the
+	// type from the right hand side as much as possible and using some
+	// defaults where the rhs could be interpreted different ways.
+	// Idiomatic Go uses short declarations in preference to var keyword.
+	y := 4
+	sum, prod := learnMultiple(x, y)        // function returns two values
+	fmt.Println("sum:", sum, "prod:", prod) // simple output
+	learnTypes()                            // < y minutes, learn more!
+}
+
+// Functions can have parameters and (multiple!) return values.
+// In declarations, the symbol precedes the type, and the type does not have
+// to be repeated if it is the same for multiple symbols in a row.
+func learnMultiple(x, y int) (sum, prod int) {
+	return x + y, x * y // return two values
+}
+
+// Some built-in types and literals.
+func learnTypes() {
+	// Short declaration usually gives you what you want.
+	s := "Learn Go!" // string type
+
+	s2 := `A "raw" string literal
+can include line breaks.` // same string type
+
+	// non-ASCII literal.  Go source is UTF-8.
+	g := 'Σ' // rune type, an alias for uint32, holds a UTF-8 code point
+
+	f := 3.14195 // float64, an IEEE-754 64-bit floating point number
+	c := 3 + 4i  // complex128, represented internally with two float64s
+
+	// You can use var syntax with an initializer if you want
+	// something other than the default that a short declaration gives you.
+	var u uint = 7 // unsigned, but implementation dependent size as with int
+	var pi float32 = 22. / 7
+
+	// Or more idiomatically, use conversion syntax with a short declaration.
+	n := byte('\n') // byte is an alias for uint8
+
+	// Arrays have size fixed at compile time.
+	var a4 [4]int           // an array of 4 ints, initialized to all 0
+	a3 := [...]int{3, 1, 5} // an array of 3 ints, initialized as shown
+
+	// Slices have dynamic size.  Arrays and slices each have advantages
+	// but use cases for slices are much more common.
+	s3 := []int{4, 5, 9}    // compare to a3.  no ellipsis here
+	s4 := make([]int, 4)    // allocates slice of 4 ints, initialized to all 0
+	var d2 [][]float64      // declaration only, nothing allocated here
+	bs := []byte("a slice") // type conversion syntax
+
+	p, q := learnMemory() // A little side bar.
+	// Did you read it?  This short declaration declares p and q to be of
+	// type pointer to int.  P is now pointing into a block of of 20 ints, but
+	// the only one accessible is the one that p is pointing at.  There is
+	// no p++ to get at the next one.
+	fmt.Println(*p, *q) // * follows a pointer.  This prints two ints.
+
+	// Maps are a dynamically growable associative array type, like the
+	// hash or dictionary types of some other languages.
+	m := map[string]int{"three": 3, "four": 4}
+	m["one"] = 1
+
+	// Unused variables are an error in Go.
+	// The underbar lets you "use" a variable but discard its value.
+	_, _, _, _, _, _, _, _, _ = s2, g, f, u, pi, n, a3, s4, bs
+	// Output of course counts as using a variable.
+	fmt.Println(s, c, a4, s3, d2, m)
+
+	learnFlowControl() // back in the flow
+}
+
+// Go is fully garbage collected.  It has pointers but no pointer arithmetic.
+// You can make a mistake with a nil pointer, but not by incrementing a pointer.
+func learnMemory() (p, q *int) {
+	// Named return values p and q have type pointer to int.  They are
+	// initialized to nil at this point.  Evaluating *p or *q here would cause
+	// a panic--a run time error.
+	p = new(int) // built-in function new allocates memory.
+	// The allocated int is initialized to 0, p is no longer nil.
+	s := make([]int, 20) // allocate 20 ints as a single block of memory
+	s[3] = 7             // assign one of them
+	r := -2              // declare another local variable
+	return &s[3], &r     // Oh my.
+	// The line above returns two values, yes, and both of the expressions
+	// are valid.  & takes the address of an object.  Elements of a slice are
+	// addressable, and so are local variables.  Built-in functions new and
+	// make explicitly allocate memory, but local objects can be allocated
+	// as needed.  Here memory for r will be still be referenced after the
+	// function returns so it will be allocated as well.  The int allocated
+	// with new on the other hand will no longer be referenced and can be
+	// garbage collected as needed by the Go runtime.  The memory allocated
+	// with make will still be referenced at that one element, and so it
+	// cannot be garbage collected.  All 20 ints remain in memory because
+	// one of them is still referenced.
+}
+
+func expensiveComputation() int {
+	return 1e6
+}
+
+func learnFlowControl() {
+	// If statements require brace brackets, and do not require parens.
+	if true {
+		fmt.Println("told ya")
+	}
+	// This is how we format the brace brackets.  Formatting is standardized
+	// by the command line command "go fmt."  Everybody does it.  You will
+	// suffer endless disparaging remarks until you conform as well.
+	if false {
+		// pout
+	} else {
+		// gloat
+	}
+	// If statements can be chained of course, but it's idiomatic to use
+	// the handy switch statement instead.
+	x := 1
+	switch x {
+	case 0:
+	case 1:
+		// cases don't "fall through"
+	case 2:
+		// unreached
+	}
+	// Like if, for doesn't use parens either.  The scope of a variable
+	// declared in the first clause of the for statement is the statement
+	// and block.  This x shadows the x declared above, but goes out of
+	// scope after the for block.
+	for x := 0; x < 3; x++ { // ++ is a statement
+		fmt.Println("iteration", x)
+	}
+	// x == 1 here.
+
+	// For is the only loop statement in Go, but it has alternate forms.
+	for { // infinite loop
+		break    // just kidding
+		continue // unreached
+	}
+	// The initial assignment of the for statement is handy enough that Go
+	// if statements can have one as well.  Just like in the for statement,
+	// the := here means to declare and assign y first, then test y > x.
+	// The scope of y is limited to the if statement and block.
+	if y := expensiveComputation(); y > x {
+		x = y
+	}
+	// Functions are first class objects and function literals are handy.
+	// Function literals are closures.
+	xBig := func() bool {
+		return x > 100 // references x declared above switch statement.
+	}
+	fmt.Println("xBig:", xBig()) // true (we last assigned 1e6 to x)
+	x /= 1e5                     // this makes it == 10
+	fmt.Println("xBig:", xBig()) // false now
+
+	// When you need it, you'll love it.  Actually Go's goto has been reformed
+	// a bit to avoid indeterminate states.  You can't jump around variable
+	// declarations and you can't jump into blocks.
+	goto love
+love:
+
+	learnInterfaces() // Good stuff coming up!
+}
+
+// An interface is a list of functionality that a type supports.  Notably
+// missing from an interface definition is any declaration of which types
+// implement the interface.  Types simply implement an interface or they don't.
+//
+// An interface can have any number of methods, but it's actually common
+// for an interface to have only single method.  It is idiomatic in this
+// case for the single method to be named with some action, and for the
+// interface name to end in "er."
+//
+// An interface definition is one kind of a type definition.  Interface is
+// a built in type.  Stringer is defined here as an interface type with one
+// method, String.
+type Stringer interface {
+	String() string
+}
+
+// Struct is another built in type.  A struct aggregates "fields."
+// Pair here has two fields, ints named x and y.
+type pair struct {
+	x, y int
+}
+
+// User defined types can have "methods." These are functions that operate
+// in the context of an instance of the user defined type.  The instance
+// is called the "receiver" and is identified with a declaration just in front
+// of the method name.  The receiver here is "p." In most ways the receiver
+// works just like a function parameter.
+//
+// This String method has the same name and return value as the String method
+// of the Stringer interface.  Further, String is the only method of Stringer.
+// The pair type thus implements all methods of the Stringer interface and
+// we say simply that pair implements Stringer.  No other syntax is needed.
+func (p pair) String() string {
+	// Sprintf is another public function in package fmt.
+	// Dot syntax references fields of p.
+	return fmt.Sprintf("(%d, %d)", p.x, p.y)
+}
+
+func learnInterfaces() {
+	// Brace syntax is a "struct literal."  It evaluates to an initialized
+	// struct.  The := syntax declares and initializes p to this struct.
+	p := pair{3, 4}
+	fmt.Println(p.String()) // call String method of p, of type pair.
+	var i Stringer          // declare i of type Stringer.
+	i = p                   // valid because pair implements Stringer
+	// Call String method of i, of type Stringer.  Output same as above.
+	fmt.Println(i.String())
+	// It gets more interesting now.  We defined Stringer in this file,
+	// but the same interface happens to be defined in package fmt.
+	// Pair thus implements fmt.Stringer as well, and does so with no
+	// declaration of the fact.  The definition of pair doesn't mention
+	// any interfaces at all, and of course the authors of fmt.Stringer
+	// had no idea that we were going to define pair.
+	//
+	// Functions in the fmt package know how to print some standard built in
+	// types, and beyond that, they see if a type implements fmt.Stringer.
+	// If so, they simply call the String method to ask an object for a
+	// printable representation of itself.
+	fmt.Println(p) // output same as above. Println calls String method.
+	fmt.Println(i) // output same as above
+
+	learnErrorHandling()
+}
+
+func learnErrorHandling() {
+	// Sometimes you just need to know if something worked or not.  Go has
+	// a ", ok" idiom for that.  Something, a map expression here, but commonly
+	// a function, can return a boolean value of ok or not ok as a second
+	// return value.
+	m := map[int]string{3: "three", 4: "four"}
+	if x, ok := m[1]; !ok { // , ok is optional but see how useful it is.
+		fmt.Println("no one there")
+	} else {
+		fmt.Print(x)
+	}
+	// An error value communicates not just "ok" but more about the problem.
+	if _, err := strconv.Atoi("non-int"); err != nil { // _ discards value
+		// prints "strconv.ParseInt: parsing "non-int": invalid syntax"
+		fmt.Println(err)
+	}
+	// error is a built in type.  It is an interface with a single method,
+	// defined internally as,
+	//
+	// type error interface {
+	//     Error() string
+	// }
+	//
+	// The string returned by the Error method is conventionally a printable
+	// error message.  You can define your own error types by simply adding
+	// an Error method.  Your type then automatically implements the error
+	// interface.  We've seen two interfaces now, fmt.Stringer and error.
+
+	// We'll revisit interfaces a little later.  Meanwhile,
+	learnConcurrency()
+}
+
+// Go has concurrency support in the language definition.  The element of
+// concurrent execution is called a "goroutine" and is similar to a thread
+// but "lighter."  Goroutines are multiplexed to operating system threads
+// and a running Go program can have far more goroutines than available OS
+// threads.  If a machine has multiple CPU cores, goroutines can run in
+// parallel.
+//
+// Go "Channels" allow communication between goroutines in a way that is
+// both powerful and easy to understand.  Channel is a type in Go and objects
+// of type channel are first class objects--they can be assigned to variables,
+// passed around to functions, and so on.  A channel works conceptually much
+// like a Unix pipe.  You put data in at one end and it comes out the other.
+// Channel "send" and "receive" operations are goroutine-safe.  No locks
+// or additional synchronization is needed.
+
+// Inc increments a number, and sends the result on a channel.  The channel
+// operation makes this function useful to run concurrently with other
+// goroutines.  There is no special declaration though that says this function
+// is concurrent.  It is an ordinary function that happens to have a
+// parameter of channel type.
+func inc(i int, c chan int) {
+	c <- i + 1 // <- is the "send" operator when a channel appears on the left.
+}
+
+// We'll use inc to increment some numbers concurrently.
+func learnConcurrency() {
+	// Same make function used earlier to make a slice.  Make allocates and
+	// initializes slices, maps, and channels.
+	c := make(chan int)
+	// Start three concurrent goroutines.  Numbers will be incremented
+	// concurrently, perhaps in parallel if the machine is capable and
+	// properly configured.  All three send to the same channel.
+	go inc(0, c) // go is a statement that starts a new goroutine.
+	go inc(10, c)
+	go inc(-805, c)
+	// Read three results from the channel and print them out.
+	// There is no telling in what order the results will arrive!
+	fmt.Println(<-c, <-c, <-c) // channel on right, <- is "receive" operator.
+
+	cs := make(chan string)       // another channel, this one handles strings.
+	cc := make(chan chan string)  // a channel of channels.
+	go func() { c <- 84 }()       // start a new goroutine just to send a value
+	go func() { cs <- "wordy" }() // again, for cs this time
+	// Select has syntax like a switch statement but is doing something
+	// pretty different.  Each case involves a channel operation.  In rough
+	// terms, a case is selected at random out of the cases that are ready to
+	// communicate.  If none are ready, select waits for one to become ready.
+	select {
+	case i := <-c: // the value received can be assigned to a variable
+		fmt.Println("it's a", i)
+	case <-cs: // or the value received can be discarded
+		fmt.Println("it's a string")
+	case <-cc: // empty channel, not ready for communication.
+		fmt.Println("didn't happen.")
+	}
+	// At this point a value was taken from either c or cs.  One of the two
+	// goroutines started above has completed, the other will remain blocked.
+
+	learnWebProgramming() // Go does it.  You want to do it too.
+}
+
+// A simple web server can be created with a single function from the standard
+// library.  ListenAndServe, in package net/http, listens at the specified
+// TCP address and uses an object that knows how to serve data.  "Knows how"
+// means "satisfies an interface."  The second parameter is of type interface,
+// specifically http.Handler.  http.Handler has a single method, ServeHTTP.
+func learnWebProgramming() {
+	err := http.ListenAndServe(":8080", pair{})
+	// Error returns are ubiquitous in Go.  Always check error returns and
+	// do something with them.  Often it's enough to print it out as an
+	// indication of what failed.  Of course there are better things to do
+	// in production code: log it, try something else, shut everything down,
+	// and so on.
+	fmt.Println(err)
+}
+
+// You can make any type into an http.Hander by implementing ServeHTTP.
+// Lets use the pair type we defined earlier, just because we have it
+// sitting around.  ServeHTTP has two parameters.  The request parameter
+// is a struct that we'll ignore here.  http.ResponseWriter is yet another
+// interface!  Here it is an object supplied to us with the guarantee that
+// it implements its interface, which includes a method Write.
+// We call this Write method to serve data.
+func (p pair) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	w.Write([]byte("You learned Go in Y minutes!"))
+}
+
+// And that's it for a proof-of-concept web server!  If you run this program
+// it will print out all the lines from the earlier parts of the lesson, then
+// start this web server.  To hit the web server, just point a browser at
+// localhost:8080 and you'll see the message.  (Then you can probably press
+// ctrl-C to kill it.)
+```
+
+## Further Reading
+
+The root of all things Go is the [official Go web site](http://golang.org/).
+There you can follow the tutorial, play interactively, and read lots.
+
+The language definition itself is highly recommended.  It's easy to read
+and amazingly short (as language definitions go these days.)
+
+On the reading list for students of Go is the source code to the standard
+library.  Comprehensively documented, it demonstrates the best of readable
+and understandable Go, Go style, and Go idioms.  Click on a function name
+in the documentation and the source code comes up!
+