[ { "path": ".gitattributes", "content": "public/** linguist-generated\n\n" }, { "path": ".github/workflows/test.yml", "content": "name: test\n\non:\n push:\n branches: [ master ]\n pull_request:\n branches: [ master ]\n\njobs:\n\n build:\n strategy:\n matrix:\n os: [ubuntu-latest, macos-latest]\n go-version: [1.26.0]\n\n runs-on: ${{ matrix.os }}\n steps:\n - uses: actions/checkout@v2\n\n - name: Set up Go\n uses: actions/setup-go@v3\n with:\n go-version: ${{ matrix.go-version }}\n\n - name: Test\n run: tools/build\n env:\n VERBOSE: 1\n TESTING: 1\n" }, { "path": ".gitignore", "content": "*.pyc\n.idea\n.vscode\n" }, { "path": "CONTRIBUTING.md", "content": "## Contributing\n\nThanks for your interest in contributing to Go by Example!\n\n* When sending a PR that affects the displayed contents of the site, \n updating the HTML in the `public` directory by itself is insufficient, since\n the source of truth for the website is in the `examples` directory.\n \n Instead, update the proper source file(s) in the `examples` directory and\n run `tools/build` locally to regenerate the HTML; include both changes in\n your PR. \n \n If you don't want to deal with getting a proper PR in, feel free to just\n open an issue and point out the change you suggest.\n\n* We're open to adding more examples to the site. They should be on things\n used by many programmers and only require the standard library. If you're\n interested in adding an example, _please open an issue to discuss the topic\n first_.\n\n* We're not going to change the navigation of the site, in particular adding\n a \"previous section\" link or an \"index\" link other than the one on the title\n text.\n" }, { "path": "README.md", "content": "# Go by Example\n\nContent and build toolchain for [Go by Example](https://gobyexample.com),\na site that teaches Go via annotated example programs.\n\n### Overview\n\nThe Go by Example site is built by extracting code and\ncomments from source files in `examples` and rendering\nthem using `templates` into a static `public`\ndirectory. The programs implementing this build process\nare in `tools`, along with dependencies specified in\nthe `go.mod`file.\n\nThe built `public` directory can be served by any\nstatic content system. The production site uses S3 and\nCloudFront, for example.\n\n### Building\n\n[![test](https://github.com/mmcgrana/gobyexample/actions/workflows/test.yml/badge.svg)](https://github.com/mmcgrana/gobyexample/actions/workflows/test.yml)\n\nTo build the site you'll need Go installed. Run:\n\n```console\n$ tools/build\n```\n\nTo build continuously in a loop:\n\n```console\n$ tools/build-loop\n```\n\nTo see the site locally:\n\n```console\n$ tools/serve\n```\n\nand open `http://127.0.0.1:8000/` in your browser.\n\n### Publishing\n\nTo upload the site:\n\n```console\n$ export AWS_ACCESS_KEY_ID=...\n$ export AWS_SECRET_ACCESS_KEY=...\n$ tools/upload\n```\n\n### License\n\nThis work is copyright Mark McGranaghan and licensed under a\n[Creative Commons Attribution 3.0 Unported License](http://creativecommons.org/licenses/by/3.0/).\n\nThe Go Gopher is copyright [Renée French](https://reneefrench.blogspot.com/) and licensed under a\n[Creative Commons Attribution 3.0 Unported License](http://creativecommons.org/licenses/by/3.0/).\n\n\n### Translations\n\nContributor translations of the Go by Example site are available in:\n\n* [Chinese](https://gobyexample-cn.github.io/) by [gobyexample-cn](https://github.com/gobyexample-cn)\n* [French](http://le-go-par-l-exemple.keiruaprod.fr) by [keirua](https://github.com/keirua/gobyexample)\n* [Italian](https://gobyexampleit.andrearaponi.it/) by [andrearaponi](https://github.com/andrearaponi/gobyexample-it)\n* [Japanese](http://spinute.org/go-by-example) by [spinute](https://github.com/spinute)\n* [Korean](https://mingrammer.com/gobyexample/) by [mingrammer](https://github.com/mingrammer)\n* [Ukrainian](https://butuzov.github.io/gobyexample/) by [butuzov](https://github.com/butuzov/gobyexample)\n* [Brazilian Portuguese](https://lcslitx.github.io/GoEmExemplos/) by [lcslitx](https://github.com/LCSLITX)\n* [Burmese](https://setkyar.github.io/gobyexample) by [Set Kyar Wa Lar](https://github.com/setkyar/gobyexample)\n\n### Thanks\n\nThanks to [Jeremy Ashkenas](https://github.com/jashkenas)\nfor [Docco](http://jashkenas.github.io/docco/), which\ninspired this project.\n\n### FAQ\n\n#### I found a problem with the examples; what do I do?\n\nWe're very happy to fix problem reports and accept contributions! Please submit\n[an issue](https://github.com/mmcgrana/gobyexample/issues) or send a Pull Request.\nSee `CONTRIBUTING.md` for more details.\n\n#### What version of Go is required to run these examples?\n\nGiven Go's strong [backwards compatibility guarantees](https://go.dev/doc/go1compat),\nwe expect the vast majority of examples to work on the latest released version of Go\nas well as many older releases going back years.\n\nThat said, some examples show off new features added in recent releases; therefore,\nit's recommended to try running examples with the latest officially released Go version\n(see Go's [release history](https://go.dev/doc/devel/release) for details).\n\n#### I'm getting output in a different order from the example. Is the example wrong?\n\nSome of the examples demonstrate concurrent code which has a non-deterministic\nexecution order. It depends on how the Go runtime schedules its goroutines and\nmay vary by operating system, CPU architecture, or even Go version.\n\nSimilarly, examples that iterate over maps may produce items in a different order\nfrom what you're getting on your machine. This is because the order of iteration\nover maps in Go is [not specified and is not guaranteed to be the same from one\niteration to the next](https://go.dev/ref/spec#RangeClause).\n\nIt doesn't mean anything is wrong with the example. Typically the code in these\nexamples will be insensitive to the actual order of the output; if the code is\nsensitive to the order - that's probably a bug - so feel free to report it.\n\n\n\n\n" }, { "path": "examples/arrays/arrays.go", "content": "// In Go, an _array_ is a numbered sequence of elements of a\n// specific length. In typical Go code, [slices](slices) are\n// much more common; arrays are useful in some special\n// scenarios.\n\npackage main\n\nimport \"fmt\"\n\nfunc main() {\n\n\t// Here we create an array `a` that will hold exactly\n\t// 5 `int`s. The type of elements and length are both\n\t// part of the array's type. By default an array is\n\t// zero-valued, which for `int`s means `0`s.\n\tvar a [5]int\n\tfmt.Println(\"emp:\", a)\n\n\t// We can set a value at an index using the\n\t// `array[index] = value` syntax, and get a value with\n\t// `array[index]`.\n\ta[4] = 100\n\tfmt.Println(\"set:\", a)\n\tfmt.Println(\"get:\", a[4])\n\n\t// The builtin `len` returns the length of an array.\n\tfmt.Println(\"len:\", len(a))\n\n\t// Use this syntax to declare and initialize an array\n\t// in one line.\n\tb := [5]int{1, 2, 3, 4, 5}\n\tfmt.Println(\"dcl:\", b)\n\n\t// You can also have the compiler count the number of\n\t// elements for you with `...`\n\tb = [...]int{1, 2, 3, 4, 5}\n\tfmt.Println(\"dcl:\", b)\n\n\t// If you specify the index with `:`, the elements in\n\t// between will be zeroed.\n\tb = [...]int{100, 3: 400, 500}\n\tfmt.Println(\"idx:\", b)\n\n\t// Array types are one-dimensional, but you can\n\t// compose types to build multi-dimensional data\n\t// structures.\n\tvar twoD [2][3]int\n\tfor i := range 2 {\n\t\tfor j := range 3 {\n\t\t\ttwoD[i][j] = i + j\n\t\t}\n\t}\n\tfmt.Println(\"2d: \", twoD)\n\n\t// You can create and initialize multi-dimensional\n\t// arrays at once too.\n\ttwoD = [2][3]int{\n\t\t{1, 2, 3},\n\t\t{1, 2, 3},\n\t}\n\tfmt.Println(\"2d: \", twoD)\n}\n" }, { "path": "examples/arrays/arrays.hash", "content": "96cbe484a18a0dd8c1839a92963447bed94cc997\n-NFSggT7dFH\n" }, { "path": "examples/arrays/arrays.sh", "content": "# Note that arrays appear in the form `[v1 v2 v3 ...]`\n# when printed with `fmt.Println`.\n$ go run arrays.go\nemp: [0 0 0 0 0]\nset: [0 0 0 0 100]\nget: 100\nlen: 5\ndcl: [1 2 3 4 5]\ndcl: [1 2 3 4 5]\nidx: [100 0 0 400 500]\n2d: [[0 1 2] [1 2 3]]\n2d: [[1 2 3] [1 2 3]]\n" }, { "path": "examples/atomic-counters/atomic-counters.go", "content": "// The primary mechanism for managing state in Go is\n// communication over channels. We saw this for example\n// with [worker pools](worker-pools). There are a few other\n// options for managing state though. Here we'll\n// look at using the `sync/atomic` package for _atomic\n// counters_ accessed by multiple goroutines.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"sync\"\n\t\"sync/atomic\"\n)\n\nfunc main() {\n\n\t// We'll use an atomic integer type to represent our\n\t// (always-positive) counter.\n\tvar ops atomic.Uint64\n\n\t// A WaitGroup will help us wait for all goroutines\n\t// to finish their work.\n\tvar wg sync.WaitGroup\n\n\t// We'll start 50 goroutines that each increment the\n\t// counter exactly 1000 times.\n\tfor range 50 {\n\t\twg.Go(func() {\n\t\t\tfor range 1000 {\n\t\t\t\t// To atomically increment the counter we use `Add`.\n\t\t\t\tops.Add(1)\n\t\t\t}\n\t\t})\n\t}\n\n\t// Wait until all the goroutines are done.\n\twg.Wait()\n\n\t// Here no goroutines are writing to 'ops', but using\n\t// `Load` it's safe to atomically read a value even while\n\t// other goroutines are (atomically) updating it.\n\tfmt.Println(\"ops:\", ops.Load())\n}\n" }, { "path": "examples/atomic-counters/atomic-counters.hash", "content": "d898b7b79368f70c6f6d1c181575f7b83c592718\nyiGAVfTH49v\n" }, { "path": "examples/atomic-counters/atomic-counters.sh", "content": "# We expect to get exactly 50,000 operations. Had we\n# used a non-atomic integer and incremented it with\n# `ops++`, we'd likely get a different number,\n# changing between runs, because the goroutines\n# would interfere with each other. Moreover, we'd\n# get data race failures when running with the\n# `-race` flag.\n$ go run atomic-counters.go\nops: 50000\n\n# Next we'll look at mutexes, another tool for managing\n# state.\n" }, { "path": "examples/base64-encoding/base64-encoding.go", "content": "// Go provides built-in support for [base64\n// encoding/decoding](https://en.wikipedia.org/wiki/Base64).\n\npackage main\n\n// This syntax imports the `encoding/base64` package with\n// the `b64` name instead of the default `base64`. It'll\n// save us some space below.\nimport (\n\tb64 \"encoding/base64\"\n\t\"fmt\"\n)\n\nfunc main() {\n\n\t// Here's the `string` we'll encode/decode.\n\tdata := \"abc123!?$*&()'-=@~\"\n\n\t// Go supports both standard and URL-compatible\n\t// base64. Here's how to encode using the standard\n\t// encoder. The encoder requires a `[]byte` so we\n\t// convert our `string` to that type.\n\tsEnc := b64.StdEncoding.EncodeToString([]byte(data))\n\tfmt.Println(sEnc)\n\n\t// Decoding may return an error, which you can check\n\t// if you don't already know the input to be\n\t// well-formed.\n\tsDec, _ := b64.StdEncoding.DecodeString(sEnc)\n\tfmt.Println(string(sDec))\n\tfmt.Println()\n\n\t// This encodes/decodes using a URL-compatible base64\n\t// format.\n\tuEnc := b64.URLEncoding.EncodeToString([]byte(data))\n\tfmt.Println(uEnc)\n\tuDec, _ := b64.URLEncoding.DecodeString(uEnc)\n\tfmt.Println(string(uDec))\n}\n" }, { "path": "examples/base64-encoding/base64-encoding.hash", "content": "47f0317643bc5107af6fae64cb0fdad1260ead37\nyztzkirFEvv\n" }, { "path": "examples/base64-encoding/base64-encoding.sh", "content": "# The string encodes to slightly different values with the\n# standard and URL base64 encoders (trailing `+` vs `-`)\n# but they both decode to the original string as desired.\n$ go run base64-encoding.go\nYWJjMTIzIT8kKiYoKSctPUB+\nabc123!?$*&()'-=@~\n\nYWJjMTIzIT8kKiYoKSctPUB-\nabc123!?$*&()'-=@~\n" }, { "path": "examples/channel-buffering/channel-buffering.go", "content": "// By default channels are _unbuffered_, meaning that they\n// will only accept sends (`chan <-`) if there is a\n// corresponding receive (`<- chan`) ready to receive the\n// sent value. _Buffered channels_ accept a limited\n// number of values without a corresponding receiver for\n// those values.\n\npackage main\n\nimport \"fmt\"\n\nfunc main() {\n\n\t// Here we `make` a channel of strings buffering up to\n\t// 2 values.\n\tmessages := make(chan string, 2)\n\n\t// Because this channel is buffered, we can send these\n\t// values into the channel without a corresponding\n\t// concurrent receive.\n\tmessages <- \"buffered\"\n\tmessages <- \"channel\"\n\n\t// Later we can receive these two values as usual.\n\tfmt.Println(<-messages)\n\tfmt.Println(<-messages)\n}\n" }, { "path": "examples/channel-buffering/channel-buffering.hash", "content": "558f4f1140a52e1804636f5720a10de0b37ebddb\n3BRCdRnRszb\n" }, { "path": "examples/channel-buffering/channel-buffering.sh", "content": "$ go run channel-buffering.go \nbuffered\nchannel\n" }, { "path": "examples/channel-directions/channel-directions.go", "content": "// When using channels as function parameters, you can\n// specify if a channel is meant to only send or receive\n// values. This specificity increases the type-safety of\n// the program.\n\npackage main\n\nimport \"fmt\"\n\n// This `ping` function only accepts a channel for sending\n// values. It would be a compile-time error to try to\n// receive on this channel.\nfunc ping(pings chan<- string, msg string) {\n\tpings <- msg\n}\n\n// The `pong` function accepts one channel for receives\n// (`pings`) and a second for sends (`pongs`).\nfunc pong(pings <-chan string, pongs chan<- string) {\n\tmsg := <-pings\n\tpongs <- msg\n}\n\nfunc main() {\n\tpings := make(chan string, 1)\n\tpongs := make(chan string, 1)\n\tping(pings, \"passed message\")\n\tpong(pings, pongs)\n\tfmt.Println(<-pongs)\n}\n" }, { "path": "examples/channel-directions/channel-directions.hash", "content": "d1b1580f72c3c101ea46480e6c2361f4f96b049a\nmjNJDHwUH4R\n" }, { "path": "examples/channel-directions/channel-directions.sh", "content": "$ go run channel-directions.go\npassed message\n" }, { "path": "examples/channel-synchronization/channel-synchronization.go", "content": "// We can use channels to synchronize execution\n// across goroutines. Here's an example of using a\n// blocking receive to wait for a goroutine to finish.\n// When waiting for multiple goroutines to finish,\n// you may prefer to use a [WaitGroup](waitgroups).\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"time\"\n)\n\n// This is the function we'll run in a goroutine. The\n// `done` channel will be used to notify another\n// goroutine that this function's work is done.\nfunc worker(done chan bool) {\n\tfmt.Print(\"working...\")\n\ttime.Sleep(time.Second)\n\tfmt.Println(\"done\")\n\n\t// Send a value to notify that we're done.\n\tdone <- true\n}\n\nfunc main() {\n\n\t// Start a worker goroutine, giving it the channel to\n\t// notify on.\n\tdone := make(chan bool, 1)\n\tgo worker(done)\n\n\t// Block until we receive a notification from the\n\t// worker on the channel.\n\t<-done\n}\n" }, { "path": "examples/channel-synchronization/channel-synchronization.hash", "content": "aa83d53fdee417727ec9a7cd90172d34c15a28c2\nNw-1DzIGk5f\n" }, { "path": "examples/channel-synchronization/channel-synchronization.sh", "content": "$ go run channel-synchronization.go \nworking...done \n\n# If you removed the `<- done` line from this program,\n# the program could exit before the `worker` finished\n# its work, or in some cases even before it started.\n" }, { "path": "examples/channels/channels.go", "content": "// _Channels_ are the pipes that connect concurrent\n// goroutines. You can send values into channels from one\n// goroutine and receive those values into another\n// goroutine.\n\npackage main\n\nimport \"fmt\"\n\nfunc main() {\n\n\t// Create a new channel with `make(chan val-type)`.\n\t// Channels are typed by the values they convey.\n\tmessages := make(chan string)\n\n\t// _Send_ a value into a channel using the `channel <-`\n\t// syntax. Here we send `\"ping\"` to the `messages`\n\t// channel we made above, from a new goroutine.\n\tgo func() { messages <- \"ping\" }()\n\n\t// The `<-channel` syntax _receives_ a value from the\n\t// channel. Here we'll receive the `\"ping\"` message\n\t// we sent above and print it out.\n\tmsg := <-messages\n\tfmt.Println(msg)\n}\n" }, { "path": "examples/channels/channels.hash", "content": "4fa3a8956f7f1ded57e8dc72827329aef8497e18\nMaLY7AiAkHM\n" }, { "path": "examples/channels/channels.sh", "content": "# When we run the program the `\"ping\"` message is\n# successfully passed from one goroutine to another via\n# our channel.\n$ go run channels.go \nping\n\n# By default sends and receives block until both the\n# sender and receiver are ready. This property allowed\n# us to wait at the end of our program for the `\"ping\"`\n# message without having to use any other synchronization.\n" }, { "path": "examples/closing-channels/closing-channels.go", "content": "// _Closing_ a channel indicates that no more values\n// will be sent on it. This can be useful to communicate\n// completion to the channel's receivers.\n\npackage main\n\nimport \"fmt\"\n\n// In this example we'll use a `jobs` channel to\n// communicate work to be done from the `main()` goroutine\n// to a worker goroutine. When we have no more jobs for\n// the worker we'll `close` the `jobs` channel.\nfunc main() {\n\tjobs := make(chan int, 5)\n\tdone := make(chan bool)\n\n\t// Here's the worker goroutine. It repeatedly receives\n\t// from `jobs` with `j, more := <-jobs`. In this\n\t// special 2-value form of receive, the `more` value\n\t// will be `false` if `jobs` has been `close`d and all\n\t// values in the channel have already been received.\n\t// We use this to notify on `done` when we've worked\n\t// all our jobs.\n\tgo func() {\n\t\tfor {\n\t\t\tj, more := <-jobs\n\t\t\tif more {\n\t\t\t\tfmt.Println(\"received job\", j)\n\t\t\t} else {\n\t\t\t\tfmt.Println(\"received all jobs\")\n\t\t\t\tdone <- true\n\t\t\t\treturn\n\t\t\t}\n\t\t}\n\t}()\n\n\t// This sends 3 jobs to the worker over the `jobs`\n\t// channel, then closes it.\n\tfor j := 1; j <= 3; j++ {\n\t\tjobs <- j\n\t\tfmt.Println(\"sent job\", j)\n\t}\n\tclose(jobs)\n\tfmt.Println(\"sent all jobs\")\n\n\t// We await the worker using the\n\t// [synchronization](channel-synchronization) approach\n\t// we saw earlier.\n\t<-done\n\n\t// Reading from a closed channel succeeds immediately,\n\t// returning the zero value of the underlying type.\n\t// The optional second return value is `true` if the\n\t// value received was delivered by a successful send\n\t// operation to the channel, or `false` if it was a\n\t// zero value generated because the channel is closed\n\t// and empty.\n\t_, ok := <-jobs\n\tfmt.Println(\"received more jobs:\", ok)\n}\n" }, { "path": "examples/closing-channels/closing-channels.hash", "content": "13f0ccf3674db8e9631a424c4070f9d423f7dc11\nyZijZHYe22y\n" }, { "path": "examples/closing-channels/closing-channels.sh", "content": "$ go run closing-channels.go \nsent job 1\nreceived job 1\nsent job 2\nreceived job 2\nsent job 3\nreceived job 3\nsent all jobs\nreceived all jobs\nreceived more jobs: false\n\n# The idea of closed channels leads naturally to our next\n# example: `range` over channels.\n" }, { "path": "examples/closures/closures.go", "content": "// Go supports [_anonymous functions_](https://en.wikipedia.org/wiki/Anonymous_function),\n// which can form closures.\n// Anonymous functions are useful when you want to define\n// a function inline without having to name it.\n\npackage main\n\nimport \"fmt\"\n\n// This function `intSeq` returns another function, which\n// we define anonymously in the body of `intSeq`. The\n// returned function _closes over_ the variable `i` to\n// form a closure.\nfunc intSeq() func() int {\n\ti := 0\n\treturn func() int {\n\t\ti++\n\t\treturn i\n\t}\n}\n\nfunc main() {\n\n\t// We call `intSeq`, assigning the result (a function)\n\t// to `nextInt`. This function value captures its\n\t// own `i` value, which will be updated each time\n\t// we call `nextInt`.\n\tnextInt := intSeq()\n\n\t// See the effect of the closure by calling `nextInt`\n\t// a few times.\n\tfmt.Println(nextInt())\n\tfmt.Println(nextInt())\n\tfmt.Println(nextInt())\n\n\t// To confirm that the state is unique to that\n\t// particular function, create and test a new one.\n\tnewInts := intSeq()\n\tfmt.Println(newInts())\n}\n" }, { "path": "examples/closures/closures.hash", "content": "6514e124c8127250a2eecfadc9708181e51f9603\nNpgpzS8ZG8y\n" }, { "path": "examples/closures/closures.sh", "content": "$ go run closures.go\n1\n2\n3\n1\n\n# The last feature of functions we'll look at for now is\n# recursion.\n" }, { "path": "examples/command-line-arguments/command-line-arguments.go", "content": "// [_Command-line arguments_](https://en.wikipedia.org/wiki/Command-line_interface#Arguments)\n// are a common way to parameterize execution of programs.\n// For example, `go run hello.go` uses `run` and\n// `hello.go` arguments to the `go` program.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n)\n\nfunc main() {\n\n\t// `os.Args` provides access to raw command-line\n\t// arguments. Note that the first value in this slice\n\t// is the path to the program, and `os.Args[1:]`\n\t// holds the arguments to the program.\n\targsWithProg := os.Args\n\targsWithoutProg := os.Args[1:]\n\n\t// You can get individual args with normal indexing.\n\targ := os.Args[3]\n\n\tfmt.Println(argsWithProg)\n\tfmt.Println(argsWithoutProg)\n\tfmt.Println(arg)\n}\n" }, { "path": "examples/command-line-arguments/command-line-arguments.hash", "content": "ad871e829d1457d97d0f1c1af77e39f6942ac5a5\nUYCEvh9d2Zb\n" }, { "path": "examples/command-line-arguments/command-line-arguments.sh", "content": "# To experiment with command-line arguments it's best to\n# build a binary with `go build` first.\n$ go build command-line-arguments.go\n$ ./command-line-arguments a b c d\n[./command-line-arguments a b c d] \n[a b c d]\nc\n\n# Next we'll look at more advanced command-line processing\n# with flags.\n" }, { "path": "examples/command-line-flags/command-line-flags.go", "content": "// [_Command-line flags_](https://en.wikipedia.org/wiki/Command-line_interface#Command-line_option)\n// are a common way to specify options for command-line\n// programs. For example, in `wc -l` the `-l` is a\n// command-line flag.\n\npackage main\n\n// Go provides a `flag` package supporting basic\n// command-line flag parsing. We'll use this package to\n// implement our example command-line program.\nimport (\n\t\"flag\"\n\t\"fmt\"\n)\n\nfunc main() {\n\n\t// Basic flag declarations are available for string,\n\t// integer, and boolean options. Here we declare a\n\t// string flag `word` with a default value `\"foo\"`\n\t// and a short description. This `flag.String` function\n\t// returns a string pointer (not a string value);\n\t// we'll see how to use this pointer below.\n\twordPtr := flag.String(\"word\", \"foo\", \"a string\")\n\n\t// This declares `numb` and `fork` flags, using a\n\t// similar approach to the `word` flag.\n\tnumbPtr := flag.Int(\"numb\", 42, \"an int\")\n\tforkPtr := flag.Bool(\"fork\", false, \"a bool\")\n\n\t// It's also possible to declare an option that uses an\n\t// existing var declared elsewhere in the program.\n\t// Note that we need to pass in a pointer to the flag\n\t// declaration function.\n\tvar svar string\n\tflag.StringVar(&svar, \"svar\", \"bar\", \"a string var\")\n\n\t// Once all flags are declared, call `flag.Parse()`\n\t// to execute the command-line parsing.\n\tflag.Parse()\n\n\t// Here we'll just dump out the parsed options and\n\t// any trailing positional arguments. Note that we\n\t// need to dereference the pointers with e.g. `*wordPtr`\n\t// to get the actual option values.\n\tfmt.Println(\"word:\", *wordPtr)\n\tfmt.Println(\"numb:\", *numbPtr)\n\tfmt.Println(\"fork:\", *forkPtr)\n\tfmt.Println(\"svar:\", svar)\n\tfmt.Println(\"tail:\", flag.Args())\n}\n" }, { "path": "examples/command-line-flags/command-line-flags.hash", "content": "9cca50e58f488570cc8e92dde37582ea5ee04bf3\nIUPZlYSigc3\n" }, { "path": "examples/command-line-flags/command-line-flags.sh", "content": "# To experiment with the command-line flags program it's\n# best to first compile it and then run the resulting\n# binary directly.\n$ go build command-line-flags.go\n\n# Try out the built program by first giving it values for\n# all flags.\n$ ./command-line-flags -word=opt -numb=7 -fork -svar=flag\nword: opt\nnumb: 7\nfork: true\nsvar: flag\ntail: []\n\n# Note that if you omit flags they automatically take\n# their default values.\n$ ./command-line-flags -word=opt\nword: opt\nnumb: 42\nfork: false\nsvar: bar\ntail: []\n\n# Trailing positional arguments can be provided after\n# any flags.\n$ ./command-line-flags -word=opt a1 a2 a3\nword: opt\n...\ntail: [a1 a2 a3]\n\n# Note that the `flag` package requires all flags to\n# appear before positional arguments (otherwise the flags\n# will be interpreted as positional arguments).\n$ ./command-line-flags -word=opt a1 a2 a3 -numb=7\nword: opt\nnumb: 42\nfork: false\nsvar: bar\ntail: [a1 a2 a3 -numb=7]\n\n# Use `-h` or `--help` flags to get automatically\n# generated help text for the command-line program.\n$ ./command-line-flags -h\nUsage of ./command-line-flags:\n -fork=false: a bool\n -numb=42: an int\n -svar=\"bar\": a string var\n -word=\"foo\": a string\n\n# If you provide a flag that wasn't specified to the\n# `flag` package, the program will print an error message\n# and show the help text again.\n$ ./command-line-flags -wat\nflag provided but not defined: -wat\nUsage of ./command-line-flags:\n...\n" }, { "path": "examples/command-line-subcommands/command-line-subcommands.go", "content": "// Some command-line tools, like the `go` tool or `git`\n// have many *subcommands*, each with its own set of\n// flags. For example, `go build` and `go get` are two\n// different subcommands of the `go` tool.\n// The `flag` package lets us easily define simple\n// subcommands that have their own flags.\n\npackage main\n\nimport (\n\t\"flag\"\n\t\"fmt\"\n\t\"os\"\n)\n\nfunc main() {\n\n\t// We declare a subcommand using the `NewFlagSet`\n\t// function, and proceed to define new flags specific\n\t// for this subcommand.\n\tfooCmd := flag.NewFlagSet(\"foo\", flag.ExitOnError)\n\tfooEnable := fooCmd.Bool(\"enable\", false, \"enable\")\n\tfooName := fooCmd.String(\"name\", \"\", \"name\")\n\n\t// For a different subcommand we can define different\n\t// supported flags.\n\tbarCmd := flag.NewFlagSet(\"bar\", flag.ExitOnError)\n\tbarLevel := barCmd.Int(\"level\", 0, \"level\")\n\n\t// The subcommand is expected as the first argument\n\t// to the program.\n\tif len(os.Args) < 2 {\n\t\tfmt.Println(\"expected 'foo' or 'bar' subcommands\")\n\t\tos.Exit(1)\n\t}\n\n\t// Check which subcommand is invoked.\n\tswitch os.Args[1] {\n\n\t// For every subcommand, we parse its own flags and\n\t// have access to trailing positional arguments.\n\tcase \"foo\":\n\t\tfooCmd.Parse(os.Args[2:])\n\t\tfmt.Println(\"subcommand 'foo'\")\n\t\tfmt.Println(\" enable:\", *fooEnable)\n\t\tfmt.Println(\" name:\", *fooName)\n\t\tfmt.Println(\" tail:\", fooCmd.Args())\n\tcase \"bar\":\n\t\tbarCmd.Parse(os.Args[2:])\n\t\tfmt.Println(\"subcommand 'bar'\")\n\t\tfmt.Println(\" level:\", *barLevel)\n\t\tfmt.Println(\" tail:\", barCmd.Args())\n\tdefault:\n\t\tfmt.Println(\"expected 'foo' or 'bar' subcommands\")\n\t\tos.Exit(1)\n\t}\n}\n" }, { "path": "examples/command-line-subcommands/command-line-subcommands.hash", "content": "eed015f91ba8a8d5a667dfc4dde745e341fded6e\nDkvdHKK-XCv\n" }, { "path": "examples/command-line-subcommands/command-line-subcommands.sh", "content": "$ go build command-line-subcommands.go \n\n# First invoke the foo subcommand.\n$ ./command-line-subcommands foo -enable -name=joe a1 a2\nsubcommand 'foo'\n enable: true\n name: joe\n tail: [a1 a2]\n\n# Now try bar.\n$ ./command-line-subcommands bar -level 8 a1\nsubcommand 'bar'\n level: 8\n tail: [a1]\n\n# But bar won't accept foo's flags.\n$ ./command-line-subcommands bar -enable a1\nflag provided but not defined: -enable\nUsage of bar:\n -level int\n \tlevel\n\n# Next we'll look at environment variables, another common\n# way to parameterize programs.\n" }, { "path": "examples/constants/constants.go", "content": "// Go supports _constants_ of character, string, boolean,\n// and numeric values.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"math\"\n)\n\n// `const` declares a constant value.\nconst s string = \"constant\"\n\nfunc main() {\n\tfmt.Println(s)\n\n\t// A `const` statement can also appear inside a\n\t// function body.\n\tconst n = 500000000\n\n\t// Constant expressions perform arithmetic with\n\t// arbitrary precision.\n\tconst d = 3e20 / n\n\tfmt.Println(d)\n\n\t// A numeric constant has no type until it's given\n\t// one, such as by an explicit conversion.\n\tfmt.Println(int64(d))\n\n\t// A number can be given a type by using it in a\n\t// context that requires one, such as a variable\n\t// assignment or function call. For example, here\n\t// `math.Sin` expects a `float64`.\n\tfmt.Println(math.Sin(n))\n}\n" }, { "path": "examples/constants/constants.hash", "content": "96fb6ba58e0860f9f6ed3f26db2f1cbdd9a0dbd6\nLfvIxHlpomp\n" }, { "path": "examples/constants/constants.sh", "content": "$ go run constant.go \nconstant\n6e+11\n600000000000\n-0.28470407323754404\n" }, { "path": "examples/context/context.go", "content": "// In the previous example we looked at setting up a simple\n// [HTTP server](http-server). HTTP servers are useful for\n// demonstrating the usage of `context.Context` for\n// controlling cancellation. A `Context` carries deadlines,\n// cancellation signals, and other request-scoped values\n// across API boundaries and goroutines.\npackage main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"time\"\n)\n\nfunc hello(w http.ResponseWriter, req *http.Request) {\n\n\t// A `context.Context` is created for each request by\n\t// the `net/http` machinery, and is available with\n\t// the `Context()` method.\n\tctx := req.Context()\n\tfmt.Println(\"server: hello handler started\")\n\tdefer fmt.Println(\"server: hello handler ended\")\n\n\t// Wait for a few seconds before sending a reply to the\n\t// client. This could simulate some work the server is\n\t// doing. While working, keep an eye on the context's\n\t// `Done()` channel for a signal that we should cancel\n\t// the work and return as soon as possible.\n\tselect {\n\tcase <-time.After(10 * time.Second):\n\t\tfmt.Fprintf(w, \"hello\\n\")\n\tcase <-ctx.Done():\n\t\t// The context's `Err()` method returns an error\n\t\t// that explains why the `Done()` channel was\n\t\t// closed.\n\t\terr := ctx.Err()\n\t\tfmt.Println(\"server:\", err)\n\t\tinternalError := http.StatusInternalServerError\n\t\thttp.Error(w, err.Error(), internalError)\n\t}\n}\n\nfunc main() {\n\n\t// As before, we register our handler on the \"/hello\"\n\t// route, and start serving.\n\thttp.HandleFunc(\"/hello\", hello)\n\thttp.ListenAndServe(\":8090\", nil)\n}\n" }, { "path": "examples/context/context.hash", "content": "94a35a6172346b56737ed907a2320bd30f98995d\n7G1TlQrnbF1\n" }, { "path": "examples/context/context.sh", "content": "# Run the server in the background.\n$ go run context.go &\n\n# Simulate a client request to `/hello`, hitting\n# Ctrl+C shortly after starting to signal\n# cancellation.\n$ curl localhost:8090/hello\nserver: hello handler started\n^C\nserver: context canceled\nserver: hello handler ended\n" }, { "path": "examples/custom-errors/custom-errors.go", "content": "// It's possible to define custom error types by\n// implementing the `Error()` method on them. Here's a\n// variant on the example above that uses a custom type\n// to explicitly represent an argument error.\n\npackage main\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n)\n\n// A custom error type usually has the suffix \"Error\".\ntype argError struct {\n\targ int\n\tmessage string\n}\n\n// Adding this `Error` method makes `argError` implement\n// the `error` interface.\nfunc (e *argError) Error() string {\n\treturn fmt.Sprintf(\"%d - %s\", e.arg, e.message)\n}\n\nfunc f(arg int) (int, error) {\n\tif arg == 42 {\n\n\t\t// Return our custom error.\n\t\treturn -1, &argError{arg, \"can't work with it\"}\n\t}\n\treturn arg + 3, nil\n}\n\nfunc main() {\n\n\t// `errors.AsType` is a more advanced version of `errors.Is`.\n\t// It checks that a given error (or any error in its chain)\n\t// matches a specific error type and converts to a value\n\t// of that type, also returning `true`. If there's no match, the\n\t// second return value is `false`.\n\t_, err := f(42)\n\tif ae, ok := errors.AsType[*argError](err); ok {\n\t\tfmt.Println(ae.arg)\n\t\tfmt.Println(ae.message)\n\t} else {\n\t\tfmt.Println(\"err doesn't match argError\")\n\t}\n}\n" }, { "path": "examples/custom-errors/custom-errors.hash", "content": "fe71c150846bfa4d8dddfda4903fa8e30077a5b2\n0WHh8JFOjQq\n" }, { "path": "examples/custom-errors/custom-errors.sh", "content": "$ go run custom-errors.go\n42\ncan't work with it\n" }, { "path": "examples/defer/defer.go", "content": "// _Defer_ is used to ensure that a function call is\n// performed later in a program's execution, usually for\n// purposes of cleanup. `defer` is often used where e.g.\n// `ensure` and `finally` would be used in other languages.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\t\"path/filepath\"\n)\n\n// Suppose we wanted to create a file, write to it,\n// and then close when we're done. Here's how we could\n// do that with `defer`.\nfunc main() {\n\n\t// Immediately after getting a file object with\n\t// `createFile`, we defer the closing of that file\n\t// with `closeFile`. This will be executed at the end\n\t// of the enclosing function (`main`), after\n\t// `writeFile` has finished.\n\tpath := filepath.Join(os.TempDir(), \"defer.txt\")\n\tf := createFile(path)\n\tdefer closeFile(f)\n\twriteFile(f)\n}\n\nfunc createFile(p string) *os.File {\n\tfmt.Println(\"creating\")\n\tf, err := os.Create(p)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treturn f\n}\n\nfunc writeFile(f *os.File) {\n\tfmt.Println(\"writing\")\n\tfmt.Fprintln(f, \"data\")\n}\n\nfunc closeFile(f *os.File) {\n\tfmt.Println(\"closing\")\n\terr := f.Close()\n\t// It's important to check for errors when closing a\n\t// file, even in a deferred function.\n\tif err != nil {\n\t\tpanic(err)\n\t}\n}\n" }, { "path": "examples/defer/defer.hash", "content": "b3687ac676cbe21ebb53a8d864fc15649c27c4a8\n9_sJ5XnikSw\n" }, { "path": "examples/defer/defer.sh", "content": "# Running the program confirms that the file is closed\n# after being written.\n$ go run defer.go\ncreating\nwriting\nclosing\n" }, { "path": "examples/directories/directories.go", "content": "// Go has several useful functions for working with\n// *directories* in the file system.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"io/fs\"\n\t\"os\"\n\t\"path/filepath\"\n)\n\nfunc check(e error) {\n\tif e != nil {\n\t\tpanic(e)\n\t}\n}\n\nfunc main() {\n\n\t// Create a new sub-directory in the current working\n\t// directory.\n\terr := os.Mkdir(\"subdir\", 0755)\n\tcheck(err)\n\n\t// When creating temporary directories, it's good\n\t// practice to `defer` their removal. `os.RemoveAll`\n\t// will delete a whole directory tree (similarly to\n\t// `rm -rf`).\n\tdefer os.RemoveAll(\"subdir\")\n\n\t// Helper function to create a new empty file.\n\tcreateEmptyFile := func(name string) {\n\t\td := []byte(\"\")\n\t\tcheck(os.WriteFile(name, d, 0644))\n\t}\n\n\tcreateEmptyFile(\"subdir/file1\")\n\n\t// We can create a hierarchy of directories, including\n\t// parents with `MkdirAll`. This is similar to the\n\t// command-line `mkdir -p`.\n\terr = os.MkdirAll(\"subdir/parent/child\", 0755)\n\tcheck(err)\n\n\tcreateEmptyFile(\"subdir/parent/file2\")\n\tcreateEmptyFile(\"subdir/parent/file3\")\n\tcreateEmptyFile(\"subdir/parent/child/file4\")\n\n\t// `ReadDir` lists directory contents, returning a\n\t// slice of `os.DirEntry` objects.\n\tc, err := os.ReadDir(\"subdir/parent\")\n\tcheck(err)\n\n\tfmt.Println(\"Listing subdir/parent\")\n\tfor _, entry := range c {\n\t\tfmt.Println(\" \", entry.Name(), entry.IsDir())\n\t}\n\n\t// `Chdir` lets us change the current working directory,\n\t// similarly to `cd`.\n\terr = os.Chdir(\"subdir/parent/child\")\n\tcheck(err)\n\n\t// Now we'll see the contents of `subdir/parent/child`\n\t// when listing the *current* directory.\n\tc, err = os.ReadDir(\".\")\n\tcheck(err)\n\n\tfmt.Println(\"Listing subdir/parent/child\")\n\tfor _, entry := range c {\n\t\tfmt.Println(\" \", entry.Name(), entry.IsDir())\n\t}\n\n\t// `cd` back to where we started.\n\terr = os.Chdir(\"../../..\")\n\tcheck(err)\n\n\t// We can also visit a directory *recursively*,\n\t// including all its sub-directories. `WalkDir` accepts\n\t// a callback function to handle every file or\n\t// directory visited.\n\tfmt.Println(\"Visiting subdir\")\n\terr = filepath.WalkDir(\"subdir\", visit)\n}\n\n// `visit` is called for every file or directory found\n// recursively by `filepath.WalkDir`.\nfunc visit(path string, d fs.DirEntry, err error) error {\n\tif err != nil {\n\t\treturn err\n\t}\n\tfmt.Println(\" \", path, d.IsDir())\n\treturn nil\n}\n" }, { "path": "examples/directories/directories.hash", "content": "21e35905e45d7b391823ea761d69199e3712d92c\nORNj2BPrLQr\n" }, { "path": "examples/directories/directories.sh", "content": "$ go run directories.go\nListing subdir/parent\n child true\n file2 false\n file3 false\nListing subdir/parent/child\n file4 false\nVisiting subdir\n subdir true\n subdir/file1 false\n subdir/parent true\n subdir/parent/child true\n subdir/parent/child/file4 false\n subdir/parent/file2 false\n subdir/parent/file3 false\n" }, { "path": "examples/embed-directive/embed-directive.go", "content": "// `//go:embed` is a [compiler\n// directive](https://pkg.go.dev/cmd/compile#hdr-Compiler_Directives) that\n// allows programs to include arbitrary files and folders in the Go binary at\n// build time. Read more about the embed directive\n// [here](https://pkg.go.dev/embed).\npackage main\n\n// Import the `embed` package; if you don't use any exported\n// identifiers from this package, you can do a blank import with `_ \"embed\"`.\nimport (\n\t\"embed\"\n)\n\n// `embed` directives accept paths relative to the directory containing the\n// Go source file. This directive embeds the contents of the file into the\n// `string` variable immediately following it.\n//\n//go:embed folder/single_file.txt\nvar fileString string\n\n// Or embed the contents of the file into a `[]byte`.\n//\n//go:embed folder/single_file.txt\nvar fileByte []byte\n\n// We can also embed multiple files or even folders with wildcards. This uses\n// a variable of the [embed.FS type](https://pkg.go.dev/embed#FS), which\n// implements a simple virtual file system.\n//\n//go:embed folder/single_file.txt\n//go:embed folder/*.hash\nvar folder embed.FS\n\nfunc main() {\n\n\t// Print out the contents of `single_file.txt`.\n\tprint(fileString)\n\tprint(string(fileByte))\n\n\t// Retrieve some files from the embedded folder.\n\tcontent1, _ := folder.ReadFile(\"folder/file1.hash\")\n\tprint(string(content1))\n\n\tcontent2, _ := folder.ReadFile(\"folder/file2.hash\")\n\tprint(string(content2))\n}\n" }, { "path": "examples/embed-directive/embed-directive.hash", "content": "69526bd78ac861c85bb12b96e9f1273e8aecc5a6\n6m2ll-D52BB\n" }, { "path": "examples/embed-directive/embed-directive.sh", "content": "# Use these commands to run the example.\n# (Note: due to limitation on go playground,\n# this example can only be run on your local machine.)\n$ mkdir -p folder\n$ echo \"hello go\" > folder/single_file.txt\n$ echo \"123\" > folder/file1.hash\n$ echo \"456\" > folder/file2.hash\n\n$ go run embed-directive.go\nhello go\nhello go\n123\n456\n\n" }, { "path": "examples/embed-directive/folder/file1.hash", "content": "123\n" }, { "path": "examples/embed-directive/folder/file2.hash", "content": "456\n" }, { "path": "examples/embed-directive/folder/single_file.txt", "content": "hello go\n" }, { "path": "examples/enums/enums.go", "content": "// _Enumerated types_ (enums) are a special case of\n// [sum types](https://en.wikipedia.org/wiki/Algebraic_data_type).\n// An enum is a type that has a fixed number of possible\n// values, each with a distinct name. Go doesn't have an\n// enum type as a distinct language feature, but enums\n// are simple to implement using existing language idioms.\n\npackage main\n\nimport \"fmt\"\n\n// Our enum type `ServerState` has an underlying `int` type.\ntype ServerState int\n\n// The possible values for `ServerState` are defined as\n// constants. The special keyword [iota](https://go.dev/ref/spec#Iota)\n// generates successive constant values automatically; in this\n// case 0, 1, 2 and so on.\nconst (\n\tStateIdle ServerState = iota\n\tStateConnected\n\tStateError\n\tStateRetrying\n)\n\n// By implementing the [fmt.Stringer](https://pkg.go.dev/fmt#Stringer)\n// interface, values of `ServerState` can be printed out or converted\n// to strings.\n//\n// This can get cumbersome if there are many possible values. In such\n// cases the [stringer tool](https://pkg.go.dev/golang.org/x/tools/cmd/stringer)\n// can be used in conjunction with `go:generate` to automate the\n// process. See [this post](https://eli.thegreenplace.net/2021/a-comprehensive-guide-to-go-generate)\n// for a longer explanation.\nvar stateName = map[ServerState]string{\n\tStateIdle: \"idle\",\n\tStateConnected: \"connected\",\n\tStateError: \"error\",\n\tStateRetrying: \"retrying\",\n}\n\nfunc (ss ServerState) String() string {\n\treturn stateName[ss]\n}\n\nfunc main() {\n\tns := transition(StateIdle)\n\tfmt.Println(ns)\n\t// If we have a value of type `int`, we cannot pass it to `transition` - the\n\t// compiler will complain about type mismatch. This provides some degree of\n\t// compile-time type safety for enums.\n\n\tns2 := transition(ns)\n\tfmt.Println(ns2)\n}\n\n// transition emulates a state transition for a\n// server; it takes the existing state and returns\n// a new state.\nfunc transition(s ServerState) ServerState {\n\tswitch s {\n\tcase StateIdle:\n\t\treturn StateConnected\n\tcase StateConnected, StateRetrying:\n\t\t// Suppose we check some predicates here to\n\t\t// determine the next state...\n\t\treturn StateIdle\n\tcase StateError:\n\t\treturn StateError\n\tdefault:\n\t\tpanic(fmt.Errorf(\"unknown state: %s\", s))\n\t}\n}\n" }, { "path": "examples/enums/enums.hash", "content": "ee42927ee1c864794570e23e8dadb2d20d64a4fd\nprQMptP_p1s\n" }, { "path": "examples/enums/enums.sh", "content": "$ go run enums.go\nconnected\nidle\n" }, { "path": "examples/environment-variables/environment-variables.go", "content": "// [Environment variables](https://en.wikipedia.org/wiki/Environment_variable)\n// are a universal mechanism for [conveying configuration\n// information to Unix programs](https://www.12factor.net/config).\n// Let's look at how to set, get, and list environment variables.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\n\t// To set a key/value pair, use `os.Setenv`. To get a\n\t// value for a key, use `os.Getenv`. This will return\n\t// an empty string if the key isn't present in the\n\t// environment.\n\tos.Setenv(\"FOO\", \"1\")\n\tfmt.Println(\"FOO:\", os.Getenv(\"FOO\"))\n\tfmt.Println(\"BAR:\", os.Getenv(\"BAR\"))\n\n\t// Use `os.Environ` to list all key/value pairs in the\n\t// environment. This returns a slice of strings in the\n\t// form `KEY=value`. You can `strings.SplitN` them to\n\t// get the key and value. Here we print all the keys.\n\tfmt.Println()\n\tfor _, e := range os.Environ() {\n\t\tpair := strings.SplitN(e, \"=\", 2)\n\t\tfmt.Println(pair[0])\n\t}\n}\n" }, { "path": "examples/environment-variables/environment-variables.hash", "content": "f480d3803659977183a4bc5c14da26c80b1d31fe\n2jmwXM264NC\n" }, { "path": "examples/environment-variables/environment-variables.sh", "content": "# Running the program shows that we pick up the value\n# for `FOO` that we set in the program, but that\n# `BAR` is empty.\n$ go run environment-variables.go\nFOO: 1\nBAR: \n\n# The list of keys in the environment will depend on your\n# particular machine.\nTERM_PROGRAM\nPATH\nSHELL\n...\nFOO\n\n# If we set `BAR` in the environment first, the running\n# program picks that value up.\n$ BAR=2 go run environment-variables.go\nFOO: 1\nBAR: 2\n...\n" }, { "path": "examples/epoch/epoch.go", "content": "// A common requirement in programs is getting the number\n// of seconds, milliseconds, or nanoseconds since the\n// [Unix epoch](https://en.wikipedia.org/wiki/Unix_time).\n// Here's how to do it in Go.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"time\"\n)\n\nfunc main() {\n\n\t// Use `time.Now` with `Unix`, `UnixMilli` or `UnixNano`\n\t// to get elapsed time since the Unix epoch in seconds,\n\t// milliseconds or nanoseconds, respectively.\n\tnow := time.Now()\n\tfmt.Println(now)\n\n\tfmt.Println(now.Unix())\n\tfmt.Println(now.UnixMilli())\n\tfmt.Println(now.UnixNano())\n\n\t// You can also convert integer seconds or nanoseconds\n\t// since the epoch into the corresponding `time`.\n\tfmt.Println(time.Unix(now.Unix(), 0))\n\tfmt.Println(time.Unix(0, now.UnixNano()))\n}\n" }, { "path": "examples/epoch/epoch.hash", "content": "a67ae165a1f00c205a344327d9d638f4eb931b5c\nlRmD1EWHHPz\n" }, { "path": "examples/epoch/epoch.sh", "content": "$ go run epoch.go \n2012-10-31 16:13:58.292387 +0000 UTC\n1351700038\n1351700038292\n1351700038292387000\n2012-10-31 16:13:58 +0000 UTC\n2012-10-31 16:13:58.292387 +0000 UTC\n\n# Next we'll look at another time-related task: time\n# parsing and formatting.\n" }, { "path": "examples/errors/errors.go", "content": "// In Go it's idiomatic to communicate errors via an\n// explicit, separate return value. This contrasts with\n// the exceptions used in languages like Java, Python and\n// Ruby and the overloaded single result / error value\n// sometimes used in C. Go's approach makes it easy to\n// see which functions return errors and to handle them\n// using the same language constructs employed for other,\n// non-error tasks.\n//\n// See the documentation of the [errors package](https://pkg.go.dev/errors)\n// and [this blog post](https://go.dev/blog/go1.13-errors) for additional\n// details.\n\npackage main\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n)\n\n// By convention, errors are the last return value and\n// have type `error`, a built-in interface.\nfunc f(arg int) (int, error) {\n\tif arg == 42 {\n\t\t// `errors.New` constructs a basic `error` value\n\t\t// with the given error message.\n\t\treturn -1, errors.New(\"can't work with 42\")\n\t}\n\n\t// A `nil` value in the error position indicates that\n\t// there was no error.\n\treturn arg + 3, nil\n}\n\n// A sentinel error is a predeclared variable that is used to\n// signify a specific error condition.\nvar ErrOutOfTea = errors.New(\"no more tea available\")\nvar ErrPower = errors.New(\"can't boil water\")\n\nfunc makeTea(arg int) error {\n\tif arg == 2 {\n\t\treturn ErrOutOfTea\n\t} else if arg == 4 {\n\n\t\t// We can wrap errors with higher-level errors to add\n\t\t// context. The simplest way to do this is with the\n\t\t// `%w` verb in `fmt.Errorf`. Wrapped errors\n\t\t// create a logical chain (A wraps B, which wraps C, etc.)\n\t\t// that can be queried with functions like `errors.Is`\n\t\t// and `errors.AsType`.\n\t\treturn fmt.Errorf(\"making tea: %w\", ErrPower)\n\t}\n\treturn nil\n}\n\nfunc main() {\n\tfor _, i := range []int{7, 42} {\n\n\t\t// It's idiomatic to use an inline error check in the `if`\n\t\t// line.\n\t\tif r, e := f(i); e != nil {\n\t\t\tfmt.Println(\"f failed:\", e)\n\t\t} else {\n\t\t\tfmt.Println(\"f worked:\", r)\n\t\t}\n\t}\n\n\tfor i := range 5 {\n\t\tif err := makeTea(i); err != nil {\n\n\t\t\t// `errors.Is` checks that a given error (or any error in its chain)\n\t\t\t// matches a specific error value. This is especially useful with wrapped or\n\t\t\t// nested errors, allowing you to identify specific error types or sentinel\n\t\t\t// errors in a chain of errors.\n\t\t\tif errors.Is(err, ErrOutOfTea) {\n\t\t\t\tfmt.Println(\"We should buy new tea!\")\n\t\t\t} else if errors.Is(err, ErrPower) {\n\t\t\t\tfmt.Println(\"Now it is dark.\")\n\t\t\t} else {\n\t\t\t\tfmt.Printf(\"unknown error: %s\\n\", err)\n\t\t\t}\n\t\t\tcontinue\n\t\t}\n\n\t\tfmt.Println(\"Tea is ready!\")\n\t}\n}\n" }, { "path": "examples/errors/errors.hash", "content": "b426ab07abec1cf35659afaaa5a810e116d61e8e\nxWXAMmcrbTs\n" }, { "path": "examples/errors/errors.sh", "content": "$ go run errors.go\nf worked: 10\nf failed: can't work with 42\nTea is ready!\nTea is ready!\nWe should buy new tea!\nTea is ready!\nNow it is dark.\n" }, { "path": "examples/execing-processes/execing-processes.go", "content": "// In the previous example we looked at\n// [spawning external processes](spawning-processes). We\n// do this when we need an external process accessible to\n// a running Go process. Sometimes we just want to\n// completely replace the current Go process with another\n// (perhaps non-Go) one. To do this we'll use Go's\n// implementation of the classic\n// exec\n// function.\n\npackage main\n\nimport (\n\t\"os\"\n\t\"os/exec\"\n\t\"syscall\"\n)\n\nfunc main() {\n\n\t// For our example we'll exec `ls`. Go requires an\n\t// absolute path to the binary we want to execute, so\n\t// we'll use `exec.LookPath` to find it (probably\n\t// `/bin/ls`).\n\tbinary, lookErr := exec.LookPath(\"ls\")\n\tif lookErr != nil {\n\t\tpanic(lookErr)\n\t}\n\n\t// `Exec` requires arguments in slice form (as\n\t// opposed to one big string). We'll give `ls` a few\n\t// common arguments. Note that the first argument should\n\t// be the program name.\n\targs := []string{\"ls\", \"-a\", \"-l\", \"-h\"}\n\n\t// `Exec` also needs a set of [environment variables](environment-variables)\n\t// to use. Here we just provide our current\n\t// environment.\n\tenv := os.Environ()\n\n\t// Here's the actual `syscall.Exec` call. If this call is\n\t// successful, the execution of our process will end\n\t// here and be replaced by the `/bin/ls -a -l -h`\n\t// process. If there is an error we'll get a return\n\t// value.\n\texecErr := syscall.Exec(binary, args, env)\n\tif execErr != nil {\n\t\tpanic(execErr)\n\t}\n}\n" }, { "path": "examples/execing-processes/execing-processes.hash", "content": "568ae983493addff02d2ce8df57f41daf537f077\ns9qg7olf1dM\n" }, { "path": "examples/execing-processes/execing-processes.sh", "content": "# When we run our program it is replaced by `ls`.\n$ go run execing-processes.go\ntotal 16\ndrwxr-xr-x 4 mark 136B Oct 3 16:29 .\ndrwxr-xr-x 91 mark 3.0K Oct 3 12:50 ..\n-rw-r--r-- 1 mark 1.3K Oct 3 16:28 execing-processes.go\n\n# Note that Go does not offer a classic Unix `fork`\n# function. Usually this isn't an issue though, since\n# starting goroutines, spawning processes, and exec'ing\n# processes covers most use cases for `fork`.\n" }, { "path": "examples/exit/exit.go", "content": "// Use `os.Exit` to immediately exit with a given\n// status.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n)\n\nfunc main() {\n\n\t// `defer`s will _not_ be run when using `os.Exit`, so\n\t// this `fmt.Println` will never be called.\n\tdefer fmt.Println(\"!\")\n\n\t// Exit with status 3.\n\tos.Exit(3)\n}\n\n// Note that unlike e.g. C, Go does not use an integer\n// return value from `main` to indicate exit status. If\n// you'd like to exit with a non-zero status you should\n// use `os.Exit`.\n" }, { "path": "examples/exit/exit.hash", "content": "16f2c50f58d9d113f2cdd5367ddd95a220d89b19\nb9aYzlENkb__R\n" }, { "path": "examples/exit/exit.sh", "content": "# If you run `exit.go` using `go run`, the exit\n# will be picked up by `go` and printed.\n$ go run exit.go\nexit status 3\n\n# By building and executing a binary you can see\n# the status in the terminal.\n$ go build exit.go\n$ ./exit\n$ echo $?\n3\n\n# Note that the `!` from our program never got printed.\n" }, { "path": "examples/file-paths/file-paths.go", "content": "// The `filepath` package provides functions to parse\n// and construct *file paths* in a way that is portable\n// between operating systems; `dir/file` on Linux vs.\n// `dir\\file` on Windows, for example.\npackage main\n\nimport (\n\t\"fmt\"\n\t\"path/filepath\"\n\t\"strings\"\n)\n\nfunc main() {\n\n\t// `Join` should be used to construct paths in a\n\t// portable way. It takes any number of arguments\n\t// and constructs a hierarchical path from them.\n\tp := filepath.Join(\"dir1\", \"dir2\", \"filename\")\n\tfmt.Println(\"p:\", p)\n\n\t// You should always use `Join` instead of\n\t// concatenating `/`s or `\\`s manually. In addition\n\t// to providing portability, `Join` will also\n\t// normalize paths by removing superfluous separators\n\t// and directory changes.\n\tfmt.Println(filepath.Join(\"dir1//\", \"filename\"))\n\tfmt.Println(filepath.Join(\"dir1/../dir1\", \"filename\"))\n\n\t// `Dir` and `Base` can be used to split a path to the\n\t// directory and the file. Alternatively, `Split` will\n\t// return both in the same call.\n\tfmt.Println(\"Dir(p):\", filepath.Dir(p))\n\tfmt.Println(\"Base(p):\", filepath.Base(p))\n\n\t// We can check whether a path is absolute.\n\tfmt.Println(filepath.IsAbs(\"dir/file\"))\n\tfmt.Println(filepath.IsAbs(\"/dir/file\"))\n\n\tfilename := \"config.json\"\n\n\t// Some file names have extensions following a dot. We\n\t// can split the extension out of such names with `Ext`.\n\text := filepath.Ext(filename)\n\tfmt.Println(ext)\n\n\t// To find the file's name with the extension removed,\n\t// use `strings.TrimSuffix`.\n\tfmt.Println(strings.TrimSuffix(filename, ext))\n\n\t// `Rel` finds a relative path between a *base* and a\n\t// *target*. It returns an error if the target cannot\n\t// be made relative to base.\n\trel, err := filepath.Rel(\"a/b\", \"a/b/t/file\")\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Println(rel)\n\n\trel, err = filepath.Rel(\"a/b\", \"a/c/t/file\")\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Println(rel)\n}\n" }, { "path": "examples/file-paths/file-paths.hash", "content": "10823f6a3f4daea097a91374efa88c4361932488\n5h3lUytvmyO\n" }, { "path": "examples/file-paths/file-paths.sh", "content": "$ go run file-paths.go\np: dir1/dir2/filename\ndir1/filename\ndir1/filename\nDir(p): dir1/dir2\nBase(p): filename\nfalse\ntrue\n.json\nconfig\nt/file\n../c/t/file\n" }, { "path": "examples/for/for.go", "content": "// `for` is Go's only looping construct. Here are\n// some basic types of `for` loops.\n\npackage main\n\nimport \"fmt\"\n\nfunc main() {\n\n\t// The most basic type, with a single condition.\n\ti := 1\n\tfor i <= 3 {\n\t\tfmt.Println(i)\n\t\ti = i + 1\n\t}\n\n\t// A classic initial/condition/after `for` loop.\n\tfor j := 0; j < 3; j++ {\n\t\tfmt.Println(j)\n\t}\n\n\t// Another way of accomplishing the basic \"do this\n\t// N times\" iteration is `range` over an integer.\n\tfor i := range 3 {\n\t\tfmt.Println(\"range\", i)\n\t}\n\n\t// `for` without a condition will loop repeatedly\n\t// until you `break` out of the loop or `return` from\n\t// the enclosing function.\n\tfor {\n\t\tfmt.Println(\"loop\")\n\t\tbreak\n\t}\n\n\t// You can also `continue` to the next iteration of\n\t// the loop.\n\tfor n := range 6 {\n\t\tif n%2 == 0 {\n\t\t\tcontinue\n\t\t}\n\t\tfmt.Println(n)\n\t}\n}\n" }, { "path": "examples/for/for.hash", "content": "8eeb5be15c3c5fc3f9d0d8009dfcec771dc5e03d\n_F2rYHNilKa\n" }, { "path": "examples/for/for.sh", "content": "$ go run for.go\n1\n2\n3\n0\n1\n2\nrange 0\nrange 1\nrange 2\nloop\n1\n3\n5\n\n# We'll see some other `for` forms later when we look at\n# `range` statements, channels, and other data\n# structures.\n" }, { "path": "examples/functions/functions.go", "content": "// _Functions_ are central in Go. We'll learn about\n// functions with a few different examples.\n\npackage main\n\nimport \"fmt\"\n\n// Here's a function that takes two `int`s and returns\n// their sum as an `int`.\nfunc plus(a int, b int) int {\n\n\t// Go requires explicit returns, i.e. it won't\n\t// automatically return the value of the last\n\t// expression.\n\treturn a + b\n}\n\n// When you have multiple consecutive parameters of\n// the same type, you may omit the type name for the\n// like-typed parameters up to the final parameter that\n// declares the type.\nfunc plusPlus(a, b, c int) int {\n\treturn a + b + c\n}\n\nfunc main() {\n\n\t// Call a function just as you'd expect, with\n\t// `name(args)`.\n\tres := plus(1, 2)\n\tfmt.Println(\"1+2 =\", res)\n\n\tres = plusPlus(1, 2, 3)\n\tfmt.Println(\"1+2+3 =\", res)\n}\n" }, { "path": "examples/functions/functions.hash", "content": "94ade6d23721234a9612c9f77431106308b84953\n-o49-dQfGbK\n" }, { "path": "examples/functions/functions.sh", "content": "$ go run functions.go \n1+2 = 3\n1+2+3 = 6\n\n# There are several other features to Go functions. One is\n# multiple return values, which we'll look at next.\n" }, { "path": "examples/generics/generics.go", "content": "// Starting with version 1.18, Go has added support for\n// _generics_, also known as _type parameters_.\n\npackage main\n\nimport \"fmt\"\n\n// As an example of a generic function, `SlicesIndex` takes\n// a slice of any `comparable` type and an element of that\n// type and returns the index of the first occurrence of\n// v in s, or -1 if not present. The `comparable` constraint\n// means that we can compare values of this type with the\n// `==` and `!=` operators. For a more thorough explanation\n// of this type signature, see [this blog post](https://go.dev/blog/deconstructing-type-parameters).\n// Note that this function exists in the standard library\n// as [slices.Index](https://pkg.go.dev/slices#Index).\nfunc SlicesIndex[S ~[]E, E comparable](s S, v E) int {\n\tfor i := range s {\n\t\tif v == s[i] {\n\t\t\treturn i\n\t\t}\n\t}\n\treturn -1\n}\n\n// As an example of a generic type, `List` is a\n// singly-linked list with values of any type.\ntype List[T any] struct {\n\thead, tail *element[T]\n}\n\ntype element[T any] struct {\n\tnext *element[T]\n\tval T\n}\n\n// We can define methods on generic types just like we\n// do on regular types, but we have to keep the type\n// parameters in place. The type is `List[T]`, not `List`.\nfunc (lst *List[T]) Push(v T) {\n\tif lst.tail == nil {\n\t\tlst.head = &element[T]{val: v}\n\t\tlst.tail = lst.head\n\t} else {\n\t\tlst.tail.next = &element[T]{val: v}\n\t\tlst.tail = lst.tail.next\n\t}\n}\n\n// AllElements returns all the List elements as a slice.\n// In the next example we'll see a more idiomatic way\n// of iterating over all elements of custom types.\nfunc (lst *List[T]) AllElements() []T {\n\tvar elems []T\n\tfor e := lst.head; e != nil; e = e.next {\n\t\telems = append(elems, e.val)\n\t}\n\treturn elems\n}\n\nfunc main() {\n\tvar s = []string{\"foo\", \"bar\", \"zoo\"}\n\n\t// When invoking generic functions, we can often rely\n\t// on _type inference_. Note that we don't have to\n\t// specify the types for `S` and `E` when\n\t// calling `SlicesIndex` - the compiler infers them\n\t// automatically.\n\tfmt.Println(\"index of zoo:\", SlicesIndex(s, \"zoo\"))\n\n\t// ... though we could also specify them explicitly.\n\t_ = SlicesIndex[[]string, string](s, \"zoo\")\n\n\tlst := List[int]{}\n\tlst.Push(10)\n\tlst.Push(13)\n\tlst.Push(23)\n\tfmt.Println(\"list:\", lst.AllElements())\n}\n" }, { "path": "examples/generics/generics.hash", "content": "1ad71763360077271687c5e9d147c89c0b580b0a\n7v7vElzhAeO\n" }, { "path": "examples/generics/generics.sh", "content": "$ go run generics.go\nindex of zoo: 2\nlist: [10 13 23]\n" }, { "path": "examples/goroutines/goroutines.go", "content": "// A _goroutine_ is a lightweight thread of execution.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"time\"\n)\n\nfunc f(from string) {\n\tfor i := range 3 {\n\t\tfmt.Println(from, \":\", i)\n\t}\n}\n\nfunc main() {\n\n\t// Suppose we have a function call `f(s)`. Here's how\n\t// we'd call that in the usual way, running it\n\t// synchronously.\n\tf(\"direct\")\n\n\t// To invoke this function in a goroutine, use\n\t// `go f(s)`. This new goroutine will execute\n\t// concurrently with the calling one.\n\tgo f(\"goroutine\")\n\n\t// You can also start a goroutine for an anonymous\n\t// function call.\n\tgo func(msg string) {\n\t\tfmt.Println(msg)\n\t}(\"going\")\n\n\t// Our two function calls are running asynchronously in\n\t// separate goroutines now. Wait for them to finish\n\t// (for a more robust approach, use a [WaitGroup](waitgroups)).\n\ttime.Sleep(time.Second)\n\tfmt.Println(\"done\")\n}\n" }, { "path": "examples/goroutines/goroutines.hash", "content": "b7455068d7f944d7c1a2764e5ec05bee53296e62\n0fx_WokYVFO\n" }, { "path": "examples/goroutines/goroutines.sh", "content": "# When we run this program, we see the output of the\n# blocking call first, then the output of the two\n# goroutines. The goroutines' output may be interleaved,\n# because goroutines are being run concurrently by the\n# Go runtime.\n$ go run goroutines.go\ndirect : 0\ndirect : 1\ndirect : 2\ngoroutine : 0\ngoing\ngoroutine : 1\ngoroutine : 2\ndone\n\n# Next we'll look at a complement to goroutines in\n# concurrent Go programs: channels.\n" }, { "path": "examples/hello-world/hello-world.go", "content": "// Our first program will print the classic \"hello world\"\n// message. Here's the full source code.\npackage main\n\nimport \"fmt\"\n\nfunc main() {\n\tfmt.Println(\"hello world\")\n}\n" }, { "path": "examples/hello-world/hello-world.hash", "content": "3eb6e21f5f89b9a4bf64f267972a24211f0032e7\nNeviD0awXjt\n" }, { "path": "examples/hello-world/hello-world.sh", "content": "# To run the program, put the code in `hello-world.go` and\n# use `go run`.\n$ go run hello-world.go\nhello world\n\n# Sometimes we'll want to build our programs into\n# binaries. We can do this using `go build`.\n$ go build hello-world.go\n$ ls\nhello-world\thello-world.go\n\n# We can then execute the built binary directly.\n$ ./hello-world\nhello world\n\n# Now that we can run and build basic Go programs, let's\n# learn more about the language.\n" }, { "path": "examples/http-client/http-client.go", "content": "// The Go standard library comes with excellent support\n// for HTTP clients and servers in the `net/http`\n// package. In this example we'll use it to issue simple\n// HTTP requests.\npackage main\n\nimport (\n\t\"bufio\"\n\t\"fmt\"\n\t\"net/http\"\n)\n\nfunc main() {\n\n\t// Issue an HTTP GET request to a server. `http.Get` is a\n\t// convenient shortcut around creating an `http.Client`\n\t// object and calling its `Get` method; it uses the\n\t// `http.DefaultClient` object which has useful default\n\t// settings.\n\tresp, err := http.Get(\"https://gobyexample.com\")\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer resp.Body.Close()\n\n\t// Print the HTTP response status.\n\tfmt.Println(\"Response status:\", resp.Status)\n\n\t// Print the first 5 lines of the response body.\n\tscanner := bufio.NewScanner(resp.Body)\n\tfor i := 0; scanner.Scan() && i < 5; i++ {\n\t\tfmt.Println(scanner.Text())\n\t}\n\n\tif err := scanner.Err(); err != nil {\n\t\tpanic(err)\n\t}\n}\n" }, { "path": "examples/http-client/http-client.hash", "content": "1497e193431e4740f593039f613773daaf97772e\nvFW_el7oHMk\n" }, { "path": "examples/http-client/http-client.sh", "content": "$ go run http-clients.go\nResponse status: 200 OK\n\n\n \n \n Go by Example\n" }, { "path": "examples/http-server/http-server.go", "content": "// Writing a basic HTTP server is easy using the\n// `net/http` package.\npackage main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n)\n\n// A fundamental concept in `net/http` servers is\n// *handlers*. A handler is an object implementing the\n// `http.Handler` interface. A common way to write\n// a handler is by using the `http.HandlerFunc` adapter\n// on functions with the appropriate signature.\nfunc hello(w http.ResponseWriter, req *http.Request) {\n\n\t// Functions serving as handlers take a\n\t// `http.ResponseWriter` and a `http.Request` as\n\t// arguments. The response writer is used to fill in the\n\t// HTTP response. Here our simple response is just\n\t// \"hello\\n\".\n\tfmt.Fprintf(w, \"hello\\n\")\n}\n\nfunc headers(w http.ResponseWriter, req *http.Request) {\n\n\t// This handler does something a little more\n\t// sophisticated by reading all the HTTP request\n\t// headers and echoing them into the response body.\n\tfor name, headers := range req.Header {\n\t\tfor _, h := range headers {\n\t\t\tfmt.Fprintf(w, \"%v: %v\\n\", name, h)\n\t\t}\n\t}\n}\n\nfunc main() {\n\n\t// We register our handlers on server routes using the\n\t// `http.HandleFunc` convenience function. It sets up\n\t// the *default router* in the `net/http` package and\n\t// takes a function as an argument.\n\thttp.HandleFunc(\"/hello\", hello)\n\thttp.HandleFunc(\"/headers\", headers)\n\n\t// Finally, we call the `ListenAndServe` with the port\n\t// and a handler. `nil` tells it to use the default\n\t// router we've just set up.\n\thttp.ListenAndServe(\":8090\", nil)\n}\n" }, { "path": "examples/http-server/http-server.hash", "content": "7694e4f5c3907e999331bbab9ead9743b6e9c6b7\ns3xMMt9Ytry\n" }, { "path": "examples/http-server/http-server.sh", "content": "# Run the server in the background.\n$ go run http-server.go &\n\n# Access the `/hello` route.\n$ curl localhost:8090/hello\nhello\n" }, { "path": "examples/if-else/if-else.go", "content": "// Branching with `if` and `else` in Go is\n// straight-forward.\n\npackage main\n\nimport \"fmt\"\n\nfunc main() {\n\n\t// Here's a basic example.\n\tif 7%2 == 0 {\n\t\tfmt.Println(\"7 is even\")\n\t} else {\n\t\tfmt.Println(\"7 is odd\")\n\t}\n\n\t// You can have an `if` statement without an else.\n\tif 8%4 == 0 {\n\t\tfmt.Println(\"8 is divisible by 4\")\n\t}\n\n\t// Logical operators like `&&` and `||` are often\n\t// useful in conditions.\n\tif 8%2 == 0 || 7%2 == 0 {\n\t\tfmt.Println(\"either 8 or 7 are even\")\n\t}\n\n\t// A statement can precede conditionals; any variables\n\t// declared in this statement are available in the current\n\t// and all subsequent branches.\n\tif num := 9; num < 0 {\n\t\tfmt.Println(num, \"is negative\")\n\t} else if num < 10 {\n\t\tfmt.Println(num, \"has 1 digit\")\n\t} else {\n\t\tfmt.Println(num, \"has multiple digits\")\n\t}\n}\n\n// Note that you don't need parentheses around conditions\n// in Go, but that the braces are required.\n" }, { "path": "examples/if-else/if-else.hash", "content": "fd9e491f9891e6a9593c2c1d640c1df113ce3ccf\nRKgKzCe7qcF\n" }, { "path": "examples/if-else/if-else.sh", "content": "$ go run if-else.go\n7 is odd\n8 is divisible by 4\neither 8 or 7 are even\n9 has 1 digit\n\n# There is no [ternary if](https://en.wikipedia.org/wiki/%3F:)\n# in Go, so you'll need to use a full `if` statement even\n# for basic conditions.\n" }, { "path": "examples/interfaces/interfaces.go", "content": "// _Interfaces_ are named collections of method\n// signatures.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"math\"\n)\n\n// Here's a basic interface for geometric shapes.\ntype geometry interface {\n\tarea() float64\n\tperim() float64\n}\n\n// For our example we'll implement this interface on\n// `rect` and `circle` types.\ntype rect struct {\n\twidth, height float64\n}\ntype circle struct {\n\tradius float64\n}\n\n// To implement an interface in Go, we just need to\n// implement all the methods in the interface. Here we\n// implement `geometry` on `rect`s.\nfunc (r rect) area() float64 {\n\treturn r.width * r.height\n}\nfunc (r rect) perim() float64 {\n\treturn 2*r.width + 2*r.height\n}\n\n// The implementation for `circle`s.\nfunc (c circle) area() float64 {\n\treturn math.Pi * c.radius * c.radius\n}\nfunc (c circle) perim() float64 {\n\treturn 2 * math.Pi * c.radius\n}\n\n// If a variable has an interface type, then we can call\n// methods that are in the named interface. Here's a\n// generic `measure` function taking advantage of this\n// to work on any `geometry`.\nfunc measure(g geometry) {\n\tfmt.Println(g)\n\tfmt.Println(g.area())\n\tfmt.Println(g.perim())\n}\n\n// Sometimes it's useful to know the runtime type of an\n// interface value. One option is using a *type assertion*\n// as shown here; another is a [type `switch`](switch).\nfunc detectCircle(g geometry) {\n\tif c, ok := g.(circle); ok {\n\t\tfmt.Println(\"circle with radius\", c.radius)\n\t}\n}\n\nfunc main() {\n\tr := rect{width: 3, height: 4}\n\tc := circle{radius: 5}\n\n\t// The `circle` and `rect` struct types both\n\t// implement the `geometry` interface so we can use\n\t// instances of\n\t// these structs as arguments to `measure`.\n\tmeasure(r)\n\tmeasure(c)\n\n\tdetectCircle(r)\n\tdetectCircle(c)\n}\n" }, { "path": "examples/interfaces/interfaces.hash", "content": "6324a4bdb756a0ec2ccc60e13c97d2650e730ed6\nxAAbgd7GOKD\n" }, { "path": "examples/interfaces/interfaces.sh", "content": "$ go run interfaces.go\n{3 4}\n12\n14\n{5}\n78.53981633974483\n31.41592653589793\ncircle with radius 5\n\n# To understand how Go's interfaces work under the hood,\n# check out this [blog post](https://research.swtch.com/interfaces).\n" }, { "path": "examples/json/json.go", "content": "// Go offers built-in support for JSON encoding and\n// decoding, including to and from built-in and custom\n// data types.\n\npackage main\n\nimport (\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"os\"\n\t\"strings\"\n)\n\n// We'll use these two structs to demonstrate encoding and\n// decoding of custom types below.\ntype response1 struct {\n\tPage int\n\tFruits []string\n}\n\n// Only exported fields will be encoded/decoded in JSON.\n// Fields must start with capital letters to be exported.\ntype response2 struct {\n\tPage int `json:\"page\"`\n\tFruits []string `json:\"fruits\"`\n}\n\nfunc main() {\n\n\t// First we'll look at encoding basic data types to\n\t// JSON strings. Here are some examples for atomic\n\t// values.\n\tbolB, _ := json.Marshal(true)\n\tfmt.Println(string(bolB))\n\n\tintB, _ := json.Marshal(1)\n\tfmt.Println(string(intB))\n\n\tfltB, _ := json.Marshal(2.34)\n\tfmt.Println(string(fltB))\n\n\tstrB, _ := json.Marshal(\"gopher\")\n\tfmt.Println(string(strB))\n\n\t// And here are some for slices and maps, which encode\n\t// to JSON arrays and objects as you'd expect.\n\tslcD := []string{\"apple\", \"peach\", \"pear\"}\n\tslcB, _ := json.Marshal(slcD)\n\tfmt.Println(string(slcB))\n\n\tmapD := map[string]int{\"apple\": 5, \"lettuce\": 7}\n\tmapB, _ := json.Marshal(mapD)\n\tfmt.Println(string(mapB))\n\n\t// The JSON package can automatically encode your\n\t// custom data types. It will only include exported\n\t// fields in the encoded output and will by default\n\t// use those names as the JSON keys.\n\tres1D := &response1{\n\t\tPage: 1,\n\t\tFruits: []string{\"apple\", \"peach\", \"pear\"}}\n\tres1B, _ := json.Marshal(res1D)\n\tfmt.Println(string(res1B))\n\n\t// You can use tags on struct field declarations\n\t// to customize the encoded JSON key names. Check the\n\t// definition of `response2` above to see an example\n\t// of such tags.\n\tres2D := &response2{\n\t\tPage: 1,\n\t\tFruits: []string{\"apple\", \"peach\", \"pear\"}}\n\tres2B, _ := json.Marshal(res2D)\n\tfmt.Println(string(res2B))\n\n\t// Now let's look at decoding JSON data into Go\n\t// values. Here's an example for a generic data\n\t// structure.\n\tbyt := []byte(`{\"num\":6.13,\"strs\":[\"a\",\"b\"]}`)\n\n\t// We need to provide a variable where the JSON\n\t// package can put the decoded data. This\n\t// `map[string]interface{}` will hold a map of strings\n\t// to arbitrary data types.\n\tvar dat map[string]interface{}\n\n\t// Here's the actual decoding, and a check for\n\t// associated errors.\n\tif err := json.Unmarshal(byt, &dat); err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Println(dat)\n\n\t// In order to use the values in the decoded map,\n\t// we'll need to convert them to their appropriate type.\n\t// For example here we convert the value in `num` to\n\t// the expected `float64` type.\n\tnum := dat[\"num\"].(float64)\n\tfmt.Println(num)\n\n\t// Accessing nested data requires a series of\n\t// conversions.\n\tstrs := dat[\"strs\"].([]interface{})\n\tstr1 := strs[0].(string)\n\tfmt.Println(str1)\n\n\t// We can also decode JSON into custom data types.\n\t// This has the advantages of adding additional\n\t// type-safety to our programs and eliminating the\n\t// need for type assertions when accessing the decoded\n\t// data.\n\tstr := `{\"page\": 1, \"fruits\": [\"apple\", \"peach\"]}`\n\tres := response2{}\n\tjson.Unmarshal([]byte(str), &res)\n\tfmt.Println(res)\n\tfmt.Println(res.Fruits[0])\n\n\t// In the examples above we always used bytes and\n\t// strings as intermediates between the data and\n\t// JSON representation on standard out. We can also\n\t// stream JSON encodings directly to `os.Writer`s like\n\t// `os.Stdout` or even HTTP response bodies.\n\tenc := json.NewEncoder(os.Stdout)\n\td := map[string]int{\"apple\": 5, \"lettuce\": 7}\n\tenc.Encode(d)\n\n\t// Streaming reads from `os.Reader`s like `os.Stdin`\n\t// or HTTP request bodies is done with `json.Decoder`.\n\tdec := json.NewDecoder(strings.NewReader(str))\n\tres1 := response2{}\n\tdec.Decode(&res1)\n\tfmt.Println(res1)\n}\n" }, { "path": "examples/json/json.hash", "content": "db25fb3a8b52215441ebe0a5d6a4d4f1a8be5917\nzwf9dZ4pUPW\n" }, { "path": "examples/json/json.sh", "content": "$ go run json.go\ntrue\n1\n2.34\n\"gopher\"\n[\"apple\",\"peach\",\"pear\"]\n{\"apple\":5,\"lettuce\":7}\n{\"Page\":1,\"Fruits\":[\"apple\",\"peach\",\"pear\"]}\n{\"page\":1,\"fruits\":[\"apple\",\"peach\",\"pear\"]}\nmap[num:6.13 strs:[a b]]\n6.13\na\n{1 [apple peach]}\napple\n{\"apple\":5,\"lettuce\":7}\n{1 [apple peach]}\n\n\n# We've covered the basic of JSON in Go here, but check\n# out the [JSON and Go](https://go.dev/blog/json)\n# blog post and [JSON package docs](https://pkg.go.dev/encoding/json)\n# for more.\n" }, { "path": "examples/line-filters/line-filters.go", "content": "// A _line filter_ is a common type of program that reads\n// input on stdin, processes it, and then prints some\n// derived result to stdout. `grep` and `sed` are common\n// line filters.\n\n// Here's an example line filter in Go that writes a\n// capitalized version of all input text. You can use this\n// pattern to write your own Go line filters.\npackage main\n\nimport (\n\t\"bufio\"\n\t\"fmt\"\n\t\"os\"\n\t\"strings\"\n)\n\nfunc main() {\n\n\t// Wrapping the unbuffered `os.Stdin` with a buffered\n\t// scanner gives us a convenient `Scan` method that\n\t// advances the scanner to the next token; which is\n\t// the next line in the default scanner.\n\tscanner := bufio.NewScanner(os.Stdin)\n\n\tfor scanner.Scan() {\n\t\t// `Text` returns the current token, here the next line,\n\t\t// from the input.\n\t\tucl := strings.ToUpper(scanner.Text())\n\n\t\t// Write out the uppercased line.\n\t\tfmt.Println(ucl)\n\t}\n\n\t// Check for errors during `Scan`. End of file is\n\t// expected and not reported by `Scan` as an error.\n\tif err := scanner.Err(); err != nil {\n\t\tfmt.Fprintln(os.Stderr, \"error:\", err)\n\t\tos.Exit(1)\n\t}\n}\n" }, { "path": "examples/line-filters/line-filters.hash", "content": "42fd593180c40f71839f05447cc0a70d7cd213d1\nkNcupWRsYPP\n" }, { "path": "examples/line-filters/line-filters.sh", "content": "# To try out our line filter, first make a file with a few\n# lowercase lines.\n$ echo 'hello' > /tmp/lines\n$ echo 'filter' >> /tmp/lines\n\n# Then use the line filter to get uppercase lines.\n$ cat /tmp/lines | go run line-filters.go\nHELLO\nFILTER\n" }, { "path": "examples/logging/logging.go", "content": "// The Go standard library provides straightforward\n// tools for outputting logs from Go programs, with\n// the [log](https://pkg.go.dev/log) package for\n// free-form output and the\n// [log/slog](https://pkg.go.dev/log/slog) package for\n// structured output.\npackage main\n\nimport (\n\t\"bytes\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\n\t\"log/slog\"\n)\n\nfunc main() {\n\n\t// Simply invoking functions like `Println` from the\n\t// `log` package uses the _standard_ logger, which\n\t// is already pre-configured for reasonable logging\n\t// output to `os.Stderr`. Additional methods like\n\t// `Fatal*` or `Panic*` will exit the program after\n\t// logging.\n\tlog.Println(\"standard logger\")\n\n\t// Loggers can be configured with _flags_ to set\n\t// their output format. By default, the standard\n\t// logger has the `log.Ldate` and `log.Ltime` flags\n\t// set, and these are collected in `log.LstdFlags`.\n\t// We can change its flags to emit time with\n\t// microsecond accuracy, for example.\n\tlog.SetFlags(log.LstdFlags | log.Lmicroseconds)\n\tlog.Println(\"with micro\")\n\n\t// It also supports emitting the file name and\n\t// line from which the `log` function is called.\n\tlog.SetFlags(log.LstdFlags | log.Lshortfile)\n\tlog.Println(\"with file/line\")\n\n\t// It may be useful to create a custom logger and\n\t// pass it around. When creating a new logger, we\n\t// can set a _prefix_ to distinguish its output\n\t// from other loggers.\n\tmylog := log.New(os.Stdout, \"my:\", log.LstdFlags)\n\tmylog.Println(\"from mylog\")\n\n\t// We can set the prefix\n\t// on existing loggers (including the standard one)\n\t// with the `SetPrefix` method.\n\tmylog.SetPrefix(\"ohmy:\")\n\tmylog.Println(\"from mylog\")\n\n\t// Loggers can have custom output targets;\n\t// any `io.Writer` works.\n\tvar buf bytes.Buffer\n\tbuflog := log.New(&buf, \"buf:\", log.LstdFlags)\n\n\t// This call writes the log output into `buf`.\n\tbuflog.Println(\"hello\")\n\n\t// This will actually show it on standard output.\n\tfmt.Print(\"from buflog:\", buf.String())\n\n\t// The `slog` package provides\n\t// _structured_ log output. For example, logging\n\t// in JSON format is straightforward.\n\tjsonHandler := slog.NewJSONHandler(os.Stderr, nil)\n\tmyslog := slog.New(jsonHandler)\n\tmyslog.Info(\"hi there\")\n\n\t// In addition to the message, `slog` output can\n\t// contain an arbitrary number of key=value\n\t// pairs.\n\tmyslog.Info(\"hello again\", \"key\", \"val\", \"age\", 25)\n}\n" }, { "path": "examples/logging/logging.hash", "content": "38a7ef451859bb4c163df938b3a9d0e5ac293bef\nQd0uCqBlYUn\n" }, { "path": "examples/logging/logging.sh", "content": "# Sample output; the date and time\n# emitted will depend on when the example ran.\n$ go run logging.go\n2023/08/22 10:45:16 standard logger\n2023/08/22 10:45:16.904141 with micro\n2023/08/22 10:45:16 logging.go:40: with file/line\nmy:2023/08/22 10:45:16 from mylog\nohmy:2023/08/22 10:45:16 from mylog\nfrom buflog:buf:2023/08/22 10:45:16 hello\n\n# These are wrapped for clarity of presentation\n# on the website; in reality they are emitted\n# on a single line.\n{\"time\":\"2023-08-22T10:45:16.904166391-07:00\",\n \"level\":\"INFO\",\"msg\":\"hi there\"}\n{\"time\":\"2023-08-22T10:45:16.904178985-07:00\",\n\t\"level\":\"INFO\",\"msg\":\"hello again\",\n\t\"key\":\"val\",\"age\":25}\n" }, { "path": "examples/maps/maps.go", "content": "// _Maps_ are Go's built-in [associative data type](https://en.wikipedia.org/wiki/Associative_array)\n// (sometimes called _hashes_ or _dicts_ in other languages).\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"maps\"\n)\n\nfunc main() {\n\n\t// To create an empty map, use the builtin `make`:\n\t// `make(map[key-type]val-type)`.\n\tm := make(map[string]int)\n\n\t// Set key/value pairs using typical `name[key] = val`\n\t// syntax.\n\tm[\"k1\"] = 7\n\tm[\"k2\"] = 13\n\n\t// Printing a map with e.g. `fmt.Println` will show all of\n\t// its key/value pairs.\n\tfmt.Println(\"map:\", m)\n\n\t// Get a value for a key with `name[key]`.\n\tv1 := m[\"k1\"]\n\tfmt.Println(\"v1:\", v1)\n\n\t// If the key doesn't exist, the\n\t// [zero value](https://go.dev/ref/spec#The_zero_value) of the\n\t// value type is returned.\n\tv3 := m[\"k3\"]\n\tfmt.Println(\"v3:\", v3)\n\n\t// The builtin `len` returns the number of key/value\n\t// pairs when called on a map.\n\tfmt.Println(\"len:\", len(m))\n\n\t// The builtin `delete` removes key/value pairs from\n\t// a map.\n\tdelete(m, \"k2\")\n\tfmt.Println(\"map:\", m)\n\n\t// To remove *all* key/value pairs from a map, use\n\t// the `clear` builtin.\n\tclear(m)\n\tfmt.Println(\"map:\", m)\n\n\t// The optional second return value when getting a\n\t// value from a map indicates if the key was present\n\t// in the map. This can be used to disambiguate\n\t// between missing keys and keys with zero values\n\t// like `0` or `\"\"`. Here we didn't need the value\n\t// itself, so we ignored it with the _blank identifier_\n\t// `_`.\n\t_, prs := m[\"k2\"]\n\tfmt.Println(\"prs:\", prs)\n\n\t// You can also declare and initialize a new map in\n\t// the same line with this syntax.\n\tn := map[string]int{\"foo\": 1, \"bar\": 2}\n\tfmt.Println(\"map:\", n)\n\n\t// The `maps` package contains a number of useful\n\t// utility functions for maps.\n\tn2 := map[string]int{\"foo\": 1, \"bar\": 2}\n\tif maps.Equal(n, n2) {\n\t\tfmt.Println(\"n == n2\")\n\t}\n}\n" }, { "path": "examples/maps/maps.hash", "content": "c8435b8cc754213b70c58c9a51dfa824c6f70dd7\n5jpkxJ2T0Lv\n" }, { "path": "examples/maps/maps.sh", "content": "# Note that maps appear in the form `map[k:v k:v]` when\n# printed with `fmt.Println`.\n$ go run maps.go \nmap: map[k1:7 k2:13]\nv1: 7\nv3: 0\nlen: 2\nmap: map[k1:7]\nmap: map[]\nprs: false\nmap: map[bar:2 foo:1]\nn == n2\n" }, { "path": "examples/methods/methods.go", "content": "// Go supports _methods_ defined on struct types.\n\npackage main\n\nimport \"fmt\"\n\ntype rect struct {\n\twidth, height int\n}\n\n// This `area` method has a _receiver type_ of `*rect`.\nfunc (r *rect) area() int {\n\treturn r.width * r.height\n}\n\n// Methods can be defined for either pointer or value\n// receiver types. Here's an example of a value receiver.\nfunc (r rect) perim() int {\n\treturn 2*r.width + 2*r.height\n}\n\nfunc main() {\n\tr := rect{width: 10, height: 5}\n\n\t// Here we call the 2 methods defined for our struct.\n\tfmt.Println(\"area: \", r.area())\n\tfmt.Println(\"perim:\", r.perim())\n\n\t// Go automatically handles conversion between values\n\t// and pointers for method calls. You may want to use\n\t// a pointer receiver type to avoid copying on method\n\t// calls or to allow the method to mutate the\n\t// receiving struct.\n\trp := &r\n\tfmt.Println(\"area: \", rp.area())\n\tfmt.Println(\"perim:\", rp.perim())\n}\n" }, { "path": "examples/methods/methods.hash", "content": "8c5af60ad04b3e9baa62a85924f829711abe94d4\n4wmDCAydC1e\n" }, { "path": "examples/methods/methods.sh", "content": "$ go run methods.go \narea: 50\nperim: 30\narea: 50\nperim: 30\n\n# Next we'll look at Go's mechanism for grouping and\n# naming related sets of methods: interfaces.\n" }, { "path": "examples/multiple-return-values/multiple-return-values.go", "content": "// Go has built-in support for _multiple return values_.\n// This feature is used often in idiomatic Go, for example\n// to return both result and error values from a function.\n\npackage main\n\nimport \"fmt\"\n\n// The `(int, int)` in this function signature shows that\n// the function returns 2 `int`s.\nfunc vals() (int, int) {\n\treturn 3, 7\n}\n\nfunc main() {\n\n\t// Here we use the 2 different return values from the\n\t// call with _multiple assignment_.\n\ta, b := vals()\n\tfmt.Println(a)\n\tfmt.Println(b)\n\n\t// If you only want a subset of the returned values,\n\t// use the blank identifier `_`.\n\t_, c := vals()\n\tfmt.Println(c)\n}\n" }, { "path": "examples/multiple-return-values/multiple-return-values.hash", "content": "c6e4f5dd9c55b5d2aaeb7e939c216ec76f042501\nvZdUvLB1WbK\n" }, { "path": "examples/multiple-return-values/multiple-return-values.sh", "content": "$ go run multiple-return-values.go\n3\n7\n7\n\n# Accepting a variable number of arguments is another nice\n# feature of Go functions; we'll look at this next.\n" }, { "path": "examples/mutexes/mutexes.go", "content": "// In the previous example we saw how to manage simple\n// counter state using [atomic operations](atomic-counters).\n// For more complex state we can use a [_mutex_](https://en.wikipedia.org/wiki/Mutual_exclusion)\n// to safely access data across multiple goroutines.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"sync\"\n)\n\n// Container holds a map of counters; since we want to\n// update it concurrently from multiple goroutines, we\n// add a `Mutex` to synchronize access.\n// Note that mutexes must not be copied, so if this\n// `struct` is passed around, it should be done by\n// pointer.\ntype Container struct {\n\tmu sync.Mutex\n\tcounters map[string]int\n}\n\nfunc (c *Container) inc(name string) {\n\t// Lock the mutex before accessing `counters`; unlock\n\t// it at the end of the function using a [defer](defer)\n\t// statement.\n\tc.mu.Lock()\n\tdefer c.mu.Unlock()\n\tc.counters[name]++\n}\n\nfunc main() {\n\tc := Container{\n\t\t// Note that the zero value of a mutex is usable as-is, so no\n\t\t// initialization is required here.\n\t\tcounters: map[string]int{\"a\": 0, \"b\": 0},\n\t}\n\n\tvar wg sync.WaitGroup\n\n\t// This function increments a named counter\n\t// in a loop.\n\tdoIncrement := func(name string, n int) {\n\t\tfor range n {\n\t\t\tc.inc(name)\n\t\t}\n\t}\n\n\t// Run several goroutines concurrently; note\n\t// that they all access the same `Container`,\n\t// and two of them access the same counter.\n\twg.Go(func() {\n\t\tdoIncrement(\"a\", 10000)\n\t})\n\n\twg.Go(func() {\n\t\tdoIncrement(\"a\", 10000)\n\t})\n\n\twg.Go(func() {\n\t\tdoIncrement(\"b\", 10000)\n\t})\n\n\t// Wait for the goroutines to finish\n\twg.Wait()\n\tfmt.Println(c.counters)\n}\n" }, { "path": "examples/mutexes/mutexes.hash", "content": "5271a346794ed097df21fb0f2b2d3d01c9bb361c\nu0VAVSWRlU0\n" }, { "path": "examples/mutexes/mutexes.sh", "content": "# Running the program shows that the counters\n# updated as expected.\n$ go run mutexes.go\nmap[a:20000 b:10000]\n\n# Next we'll look at implementing this same state\n# management task using only goroutines and channels.\n" }, { "path": "examples/non-blocking-channel-operations/non-blocking-channel-operations.go", "content": "// Basic sends and receives on channels are blocking.\n// However, we can use `select` with a `default` clause to\n// implement _non-blocking_ sends, receives, and even\n// non-blocking multi-way `select`s.\n\npackage main\n\nimport \"fmt\"\n\nfunc main() {\n\tmessages := make(chan string)\n\tsignals := make(chan bool)\n\n\t// Here's a non-blocking receive. If a value is\n\t// available on `messages` then `select` will take\n\t// the `<-messages` `case` with that value. If not\n\t// it will immediately take the `default` case.\n\tselect {\n\tcase msg := <-messages:\n\t\tfmt.Println(\"received message\", msg)\n\tdefault:\n\t\tfmt.Println(\"no message received\")\n\t}\n\n\t// A non-blocking send works similarly. Here `msg`\n\t// cannot be sent to the `messages` channel, because\n\t// the channel has no buffer and there is no receiver.\n\t// Therefore the `default` case is selected.\n\tmsg := \"hi\"\n\tselect {\n\tcase messages <- msg:\n\t\tfmt.Println(\"sent message\", msg)\n\tdefault:\n\t\tfmt.Println(\"no message sent\")\n\t}\n\n\t// We can use multiple `case`s above the `default`\n\t// clause to implement a multi-way non-blocking\n\t// select. Here we attempt non-blocking receives\n\t// on both `messages` and `signals`.\n\tselect {\n\tcase msg := <-messages:\n\t\tfmt.Println(\"received message\", msg)\n\tcase sig := <-signals:\n\t\tfmt.Println(\"received signal\", sig)\n\tdefault:\n\t\tfmt.Println(\"no activity\")\n\t}\n}\n" }, { "path": "examples/non-blocking-channel-operations/non-blocking-channel-operations.hash", "content": "40588abf859a0280d8c71b79732e869eb2da9291\nTFv6-7OVNVq\n" }, { "path": "examples/non-blocking-channel-operations/non-blocking-channel-operations.sh", "content": "$ go run non-blocking-channel-operations.go \nno message received\nno message sent\nno activity\n" }, { "path": "examples/number-parsing/number-parsing.go", "content": "// Parsing numbers from strings is a basic but common task\n// in many programs; here's how to do it in Go.\n\npackage main\n\n// The built-in package `strconv` provides the number\n// parsing.\nimport (\n\t\"fmt\"\n\t\"strconv\"\n)\n\nfunc main() {\n\n\t// With `ParseFloat`, this `64` tells how many bits of\n\t// precision to parse.\n\tf, _ := strconv.ParseFloat(\"1.234\", 64)\n\tfmt.Println(f)\n\n\t// For `ParseInt`, the `0` means infer the base from\n\t// the string. `64` requires that the result fit in 64\n\t// bits.\n\ti, _ := strconv.ParseInt(\"123\", 0, 64)\n\tfmt.Println(i)\n\n\t// `ParseInt` will recognize hex-formatted numbers.\n\td, _ := strconv.ParseInt(\"0x1c8\", 0, 64)\n\tfmt.Println(d)\n\n\t// A `ParseUint` is also available.\n\tu, _ := strconv.ParseUint(\"789\", 0, 64)\n\tfmt.Println(u)\n\n\t// `Atoi` is a convenience function for basic base-10\n\t// `int` parsing.\n\tk, _ := strconv.Atoi(\"135\")\n\tfmt.Println(k)\n\n\t// Parse functions return an error on bad input.\n\t_, e := strconv.Atoi(\"wat\")\n\tfmt.Println(e)\n}\n" }, { "path": "examples/number-parsing/number-parsing.hash", "content": "146b42780ac43135d97f094c6d30db364882ea17\nZAMEid6Fpmu\n" }, { "path": "examples/number-parsing/number-parsing.sh", "content": "$ go run number-parsing.go \n1.234\n123\n456\n789\n135\nstrconv.ParseInt: parsing \"wat\": invalid syntax\n\n# Next we'll look at another common parsing task: URLs.\n" }, { "path": "examples/panic/panic.go", "content": "// A `panic` typically means something went unexpectedly\n// wrong. Mostly we use it to fail fast on errors that\n// shouldn't occur during normal operation, or that we\n// aren't prepared to handle gracefully.\n\npackage main\n\nimport (\n\t\"os\"\n\t\"path/filepath\"\n)\n\nfunc main() {\n\n\t// We'll use panic throughout this site to check for\n\t// unexpected errors. This is the only program on the\n\t// site designed to panic.\n\tpanic(\"a problem\")\n\n\t// A common use of panic is to abort if a function\n\t// returns an error value that we don't know how to\n\t// (or want to) handle. Here's an example of\n\t// `panic`king if we get an unexpected error when creating a new file.\n\tpath := filepath.Join(os.TempDir(), \"file\")\n\t_, err := os.Create(path)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n}\n" }, { "path": "examples/panic/panic.hash", "content": "39f5cb04eb753e4c35cfc6358f24d0b5985c8556\nZ57OSC0ASwn\n" }, { "path": "examples/panic/panic.sh", "content": "# Running this program will cause it to panic, print\n# an error message and goroutine traces, and exit with\n# a non-zero status.\n\n# When first panic in `main` fires, the program exits\n# without reaching the rest of the code. If you'd like\n# to see the program try to create a temp file, comment\n# the first panic out.\n$ go run panic.go\npanic: a problem\n\ngoroutine 1 [running]:\nmain.main()\n\t/.../panic.go:12 +0x47\n...\nexit status 2\n\n# Note that unlike some languages which use exceptions\n# for handling of many errors, in Go it is idiomatic\n# to use error-indicating return values wherever possible.\n" }, { "path": "examples/pointers/pointers.go", "content": "// Go supports pointers,\n// allowing you to pass references to values and records\n// within your program.\n\npackage main\n\nimport \"fmt\"\n\n// We'll show how pointers work in contrast to values with\n// 2 functions: `zeroval` and `zeroptr`. `zeroval` has an\n// `int` parameter, so arguments will be passed to it by\n// value. `zeroval` will get a copy of `ival` distinct\n// from the one in the calling function.\nfunc zeroval(ival int) {\n\tival = 0\n}\n\n// `zeroptr` in contrast has an `*int` parameter, meaning\n// that it takes an `int` pointer. The `*iptr` code in the\n// function body then _dereferences_ the pointer from its\n// memory address to the current value at that address.\n// Assigning a value to a dereferenced pointer changes the\n// value at the referenced address.\nfunc zeroptr(iptr *int) {\n\t*iptr = 0\n}\n\nfunc main() {\n\ti := 1\n\tfmt.Println(\"initial:\", i)\n\n\tzeroval(i)\n\tfmt.Println(\"zeroval:\", i)\n\n\t// The `&i` syntax gives the memory address of `i`,\n\t// i.e. a pointer to `i`.\n\tzeroptr(&i)\n\tfmt.Println(\"zeroptr:\", i)\n\n\t// Pointers can be printed too.\n\tfmt.Println(\"pointer:\", &i)\n}\n" }, { "path": "examples/pointers/pointers.hash", "content": "7f9855cfb983efc07415117e2be734f55a6bb64b\nOlWCLpxAyBz\n" }, { "path": "examples/pointers/pointers.sh", "content": "# `zeroval` doesn't change the `i` in `main`, but\n# `zeroptr` does because it has a reference to\n# the memory address for that variable.\n$ go run pointers.go\ninitial: 1\nzeroval: 1\nzeroptr: 0\npointer: 0x42131100\n" }, { "path": "examples/random-numbers/random-numbers.go", "content": "// Go's `math/rand/v2` package provides\n// [pseudorandom number](https://en.wikipedia.org/wiki/Pseudorandom_number_generator)\n// generation.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"math/rand/v2\"\n)\n\nfunc main() {\n\n\t// For example, `rand.IntN` returns a random `int` n,\n\t// `0 <= n < 100`.\n\tfmt.Print(rand.IntN(100), \",\")\n\tfmt.Print(rand.IntN(100))\n\tfmt.Println()\n\n\t// `rand.Float64` returns a `float64` `f`,\n\t// `0.0 <= f < 1.0`.\n\tfmt.Println(rand.Float64())\n\n\t// This can be used to generate random floats in\n\t// other ranges, for example `5.0 <= f' < 10.0`.\n\tfmt.Print((rand.Float64()*5)+5, \",\")\n\tfmt.Print((rand.Float64() * 5) + 5)\n\tfmt.Println()\n\n\t// If you want a known seed, create a new\n\t// `rand.Source` and pass it into the `New`\n\t// constructor. `NewPCG` creates a new\n\t// [PCG](https://en.wikipedia.org/wiki/Permuted_congruential_generator)\n\t// source that requires a seed of two `uint64`\n\t// numbers.\n\ts2 := rand.NewPCG(42, 1024)\n\tr2 := rand.New(s2)\n\tfmt.Print(r2.IntN(100), \",\")\n\tfmt.Print(r2.IntN(100))\n\tfmt.Println()\n\n\ts3 := rand.NewPCG(42, 1024)\n\tr3 := rand.New(s3)\n\tfmt.Print(r3.IntN(100), \",\")\n\tfmt.Print(r3.IntN(100))\n\tfmt.Println()\n}\n" }, { "path": "examples/random-numbers/random-numbers.hash", "content": "76b8f86171ffcf9e7d5781fdf50c050a824acd9b\nTkgmNAl8euK\n" }, { "path": "examples/random-numbers/random-numbers.sh", "content": "# Some of the generated numbers may be\n# different when you run the sample.\n$ go run random-numbers.go\n68,56\n0.8090228139659177\n5.840125017402497,6.937056298890035\n94,49\n94,49\n\n# See the [`math/rand/v2`](https://pkg.go.dev/math/rand/v2)\n# package docs for references on other random quantities\n# that Go can provide.\n" }, { "path": "examples/range-over-built-in-types/range-over-built-in-types.go", "content": "// _range_ iterates over elements in a variety of\n// built-in data structures. Let's see how to\n// use `range` with some of the data structures\n// we've already learned.\n\npackage main\n\nimport \"fmt\"\n\nfunc main() {\n\n\t// Here we use `range` to sum the numbers in a slice.\n\t// Arrays work like this too.\n\tnums := []int{2, 3, 4}\n\tsum := 0\n\tfor _, num := range nums {\n\t\tsum += num\n\t}\n\tfmt.Println(\"sum:\", sum)\n\n\t// `range` on arrays and slices provides both the\n\t// index and value for each entry. Above we didn't\n\t// need the index, so we ignored it with the\n\t// blank identifier `_`. Sometimes we actually want\n\t// the indexes though.\n\tfor i, num := range nums {\n\t\tif num == 3 {\n\t\t\tfmt.Println(\"index:\", i)\n\t\t}\n\t}\n\n\t// `range` on map iterates over key/value pairs.\n\tkvs := map[string]string{\"a\": \"apple\", \"b\": \"banana\"}\n\tfor k, v := range kvs {\n\t\tfmt.Printf(\"%s -> %s\\n\", k, v)\n\t}\n\n\t// `range` can also iterate over just the keys of a map.\n\tfor k := range kvs {\n\t\tfmt.Println(\"key:\", k)\n\t}\n\n\t// `range` on strings iterates over Unicode code\n\t// points. The first value is the starting byte index\n\t// of the `rune` and the second the `rune` itself.\n\t// See [Strings and Runes](strings-and-runes) for more\n\t// details.\n\tfor i, c := range \"go\" {\n\t\tfmt.Println(i, c)\n\t}\n}\n" }, { "path": "examples/range-over-built-in-types/range-over-built-in-types.hash", "content": "3d8c61f02f98892be9d3ff25d48da0bfb31bbd25\nS171w0PjgsD\n" }, { "path": "examples/range-over-built-in-types/range-over-built-in-types.sh", "content": "$ go run range-over-built-in-types.go\nsum: 9\nindex: 1\na -> apple\nb -> banana\nkey: a\nkey: b\n0 103\n1 111\n" }, { "path": "examples/range-over-channels/range-over-channels.go", "content": "// In a [previous](range-over-built-in-types) example we saw how `for` and\n// `range` provide iteration over basic data structures.\n// We can also use this syntax to iterate over\n// values received from a channel.\n\npackage main\n\nimport \"fmt\"\n\nfunc main() {\n\n\t// We'll iterate over 2 values in the `queue` channel.\n\tqueue := make(chan string, 2)\n\tqueue <- \"one\"\n\tqueue <- \"two\"\n\tclose(queue)\n\n\t// This `range` iterates over each element as it's\n\t// received from `queue`. Because we `close`d the\n\t// channel above, the iteration terminates after\n\t// receiving the 2 elements.\n\tfor elem := range queue {\n\t\tfmt.Println(elem)\n\t}\n}\n" }, { "path": "examples/range-over-channels/range-over-channels.hash", "content": "446dea3a7cb9e16ce3e17a6649c719e764936740\n8vAhX6eX1wy\n" }, { "path": "examples/range-over-channels/range-over-channels.sh", "content": "$ go run range-over-channels.go\none\ntwo\n\n# This example also showed that it's possible to close\n# a non-empty channel but still have the remaining\n# values be received.\n" }, { "path": "examples/range-over-iterators/range-over-iterators.go", "content": "// Starting with version 1.23, Go has added support for\n// [iterators](https://go.dev/blog/range-functions),\n// which lets us range over pretty much anything!\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"iter\"\n\t\"slices\"\n\t\"strings\"\n)\n\n// Let's look at the `List` type from the\n// [previous example](generics) again. In that example\n// we had an `AllElements` method that returned a slice\n// of all elements in the list. With Go iterators, we\n// can do it better - as shown below.\ntype List[T any] struct {\n\thead, tail *element[T]\n}\n\ntype element[T any] struct {\n\tnext *element[T]\n\tval T\n}\n\nfunc (lst *List[T]) Push(v T) {\n\tif lst.tail == nil {\n\t\tlst.head = &element[T]{val: v}\n\t\tlst.tail = lst.head\n\t} else {\n\t\tlst.tail.next = &element[T]{val: v}\n\t\tlst.tail = lst.tail.next\n\t}\n}\n\n// All returns an _iterator_, which in Go is a function\n// with a [special signature](https://pkg.go.dev/iter#Seq).\nfunc (lst *List[T]) All() iter.Seq[T] {\n\treturn func(yield func(T) bool) {\n\t\t// The iterator function takes another function as\n\t\t// a parameter, called `yield` by convention (but\n\t\t// the name can be arbitrary). It will call `yield` for\n\t\t// every element we want to iterate over, and note `yield`'s\n\t\t// return value for a potential early termination.\n\t\tfor e := lst.head; e != nil; e = e.next {\n\t\t\tif !yield(e.val) {\n\t\t\t\treturn\n\t\t\t}\n\t\t}\n\t}\n}\n\n// Iteration doesn't require an underlying data structure,\n// and doesn't even have to be finite! Here's a function\n// returning an iterator over Fibonacci numbers: it keeps\n// running as long as `yield` keeps returning `true`.\nfunc genFib() iter.Seq[int] {\n\treturn func(yield func(int) bool) {\n\t\ta, b := 0, 1\n\n\t\tfor {\n\t\t\tif !yield(a) {\n\t\t\t\treturn\n\t\t\t}\n\t\t\ta, b = b, a+b\n\t\t}\n\t}\n}\n\nfunc main() {\n\tlst := List[int]{}\n\tlst.Push(10)\n\tlst.Push(13)\n\tlst.Push(23)\n\n\t// Since `List.All` returns an iterator, we can use it\n\t// in a regular `range` loop.\n\tfor e := range lst.All() {\n\t\tfmt.Println(e)\n\t}\n\n\t// Packages like [slices](https://pkg.go.dev/slices) have\n\t// a number of useful functions to work with iterators.\n\t// For example, `Collect` takes any iterator and collects\n\t// all its values into a slice.\n\tall := slices.Collect(lst.All())\n\tfmt.Println(\"all:\", all)\n\n\t// Standard library packages now expose iterator helpers\n\t// too. For example, `strings.SplitSeq` iterates over parts\n\t// of a byte slice without first building a result slice.\n\tfor part := range strings.SplitSeq(\"go-by-example\", \"-\") {\n\t\tfmt.Printf(\"part: %s\\n\", part)\n\t}\n\n\tfor n := range genFib() {\n\n\t\t// Once the loop hits `break` or an early return, the `yield` function\n\t\t// passed to the iterator will return `false`.\n\t\tif n >= 10 {\n\t\t\tbreak\n\t\t}\n\t\tfmt.Println(n)\n\t}\n}\n" }, { "path": "examples/range-over-iterators/range-over-iterators.hash", "content": "d7e65d4e52957e845b0e2ca925af9ce5eff43148\nlHX3uDqdfUB\n" }, { "path": "examples/range-over-iterators/range-over-iterators.sh", "content": "$ go run range-over-iterators.go\n10\n13\n23\nall: [10 13 23]\npart: go\npart: by\npart: example\n0\n1\n1\n2\n3\n5\n8\n" }, { "path": "examples/rate-limiting/rate-limiting.go", "content": "// [_Rate limiting_](https://en.wikipedia.org/wiki/Rate_limiting)\n// is an important mechanism for controlling resource\n// utilization and maintaining quality of service. Go\n// elegantly supports rate limiting with goroutines,\n// channels, and [tickers](tickers).\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"time\"\n)\n\nfunc main() {\n\n\t// First we'll look at basic rate limiting. Suppose\n\t// we want to limit our handling of incoming requests.\n\t// We'll serve these requests off a channel of the\n\t// same name.\n\trequests := make(chan int, 5)\n\tfor i := 1; i <= 5; i++ {\n\t\trequests <- i\n\t}\n\tclose(requests)\n\n\t// This `limiter` channel will receive a value\n\t// every 200 milliseconds. This is the regulator in\n\t// our rate limiting scheme.\n\tlimiter := time.Tick(200 * time.Millisecond)\n\n\t// By blocking on a receive from the `limiter` channel\n\t// before serving each request, we limit ourselves to\n\t// 1 request every 200 milliseconds.\n\tfor req := range requests {\n\t\t<-limiter\n\t\tfmt.Println(\"request\", req, time.Now())\n\t}\n\n\t// We may want to allow short bursts of requests in\n\t// our rate limiting scheme while preserving the\n\t// overall rate limit. We can accomplish this by\n\t// buffering our limiter channel. This `burstyLimiter`\n\t// channel will allow bursts of up to 3 events.\n\tburstyLimiter := make(chan time.Time, 3)\n\n\t// Fill up the channel to represent allowed bursting.\n\tfor range 3 {\n\t\tburstyLimiter <- time.Now()\n\t}\n\n\t// Every 200 milliseconds we'll try to add a new\n\t// value to `burstyLimiter`, up to its limit of 3.\n\tgo func() {\n\t\tfor t := range time.Tick(200 * time.Millisecond) {\n\t\t\tburstyLimiter <- t\n\t\t}\n\t}()\n\n\t// Now simulate 5 more incoming requests. The first\n\t// 3 of these will benefit from the burst capability\n\t// of `burstyLimiter`.\n\tburstyRequests := make(chan int, 5)\n\tfor i := 1; i <= 5; i++ {\n\t\tburstyRequests <- i\n\t}\n\tclose(burstyRequests)\n\tfor req := range burstyRequests {\n\t\t<-burstyLimiter\n\t\tfmt.Println(\"request\", req, time.Now())\n\t}\n}\n" }, { "path": "examples/rate-limiting/rate-limiting.hash", "content": "c1eee474067ad718e57df5c55242ba4711e7bcb7\ny9V3goQfy5m\n" }, { "path": "examples/rate-limiting/rate-limiting.sh", "content": "# Running our program we see the first batch of requests\n# handled once every ~200 milliseconds as desired.\n$ go run rate-limiting.go\nrequest 1 2012-10-19 00:38:18.687438 +0000 UTC\nrequest 2 2012-10-19 00:38:18.887471 +0000 UTC\nrequest 3 2012-10-19 00:38:19.087238 +0000 UTC\nrequest 4 2012-10-19 00:38:19.287338 +0000 UTC\nrequest 5 2012-10-19 00:38:19.487331 +0000 UTC\n\n# For the second batch of requests we serve the first\n# 3 immediately because of the burstable rate limiting,\n# then serve the remaining 2 with ~200ms delays each.\nrequest 1 2012-10-19 00:38:20.487578 +0000 UTC\nrequest 2 2012-10-19 00:38:20.487645 +0000 UTC\nrequest 3 2012-10-19 00:38:20.487676 +0000 UTC\nrequest 4 2012-10-19 00:38:20.687483 +0000 UTC\nrequest 5 2012-10-19 00:38:20.887542 +0000 UTC\n" }, { "path": "examples/reading-files/reading-files.go", "content": "// Reading and writing files are basic tasks needed for\n// many Go programs. First we'll look at some examples of\n// reading files.\n\npackage main\n\nimport (\n\t\"bufio\"\n\t\"fmt\"\n\t\"io\"\n\t\"os\"\n\t\"path/filepath\"\n)\n\n// Reading files requires checking most calls for errors.\n// This helper will streamline our error checks below.\nfunc check(e error) {\n\tif e != nil {\n\t\tpanic(e)\n\t}\n}\n\nfunc main() {\n\n\t// Perhaps the most basic file reading task is\n\t// slurping a file's entire contents into memory.\n\tpath := filepath.Join(os.TempDir(), \"dat\")\n\tdat, err := os.ReadFile(path)\n\tcheck(err)\n\tfmt.Print(string(dat))\n\n\t// You'll often want more control over how and what\n\t// parts of a file are read. For these tasks, start\n\t// by `Open`ing a file to obtain an `os.File` value.\n\tf, err := os.Open(path)\n\tcheck(err)\n\n\t// Read some bytes from the beginning of the file.\n\t// Allow up to 5 to be read but also note how many\n\t// actually were read.\n\tb1 := make([]byte, 5)\n\tn1, err := f.Read(b1)\n\tcheck(err)\n\tfmt.Printf(\"%d bytes: %s\\n\", n1, string(b1[:n1]))\n\n\t// You can also `Seek` to a known location in the file\n\t// and `Read` from there.\n\to2, err := f.Seek(6, io.SeekStart)\n\tcheck(err)\n\tb2 := make([]byte, 2)\n\tn2, err := f.Read(b2)\n\tcheck(err)\n\tfmt.Printf(\"%d bytes @ %d: \", n2, o2)\n\tfmt.Printf(\"%v\\n\", string(b2[:n2]))\n\n\t// Other methods of seeking are relative to the\n\t// current cursor position,\n\t_, err = f.Seek(2, io.SeekCurrent)\n\tcheck(err)\n\n\t// and relative to the end of the file.\n\t_, err = f.Seek(-4, io.SeekEnd)\n\tcheck(err)\n\n\t// The `io` package provides some functions that may\n\t// be helpful for file reading. For example, reads\n\t// like the ones above can be more robustly\n\t// implemented with `ReadAtLeast`.\n\to3, err := f.Seek(6, io.SeekStart)\n\tcheck(err)\n\tb3 := make([]byte, 2)\n\tn3, err := io.ReadAtLeast(f, b3, 2)\n\tcheck(err)\n\tfmt.Printf(\"%d bytes @ %d: %s\\n\", n3, o3, string(b3))\n\n\t// There is no built-in rewind, but\n\t// `Seek(0, io.SeekStart)` accomplishes this.\n\t_, err = f.Seek(0, io.SeekStart)\n\tcheck(err)\n\n\t// The `bufio` package implements a buffered\n\t// reader that may be useful both for its efficiency\n\t// with many small reads and because of the additional\n\t// reading methods it provides.\n\tr4 := bufio.NewReader(f)\n\tb4, err := r4.Peek(5)\n\tcheck(err)\n\tfmt.Printf(\"5 bytes: %s\\n\", string(b4))\n\n\t// Close the file when you're done (usually this would\n\t// be scheduled immediately after `Open`ing with\n\t// `defer`).\n\tf.Close()\n}\n" }, { "path": "examples/reading-files/reading-files.hash", "content": "f4a5063dc6db22beac95c6b60a8a76e3422e8cf4\nJ710-KJyC8z\n" }, { "path": "examples/reading-files/reading-files.sh", "content": "$ echo \"hello\" > /tmp/dat\n$ echo \"go\" >> /tmp/dat\n$ go run reading-files.go\nhello\ngo\n5 bytes: hello\n2 bytes @ 6: go\n2 bytes @ 6: go\n5 bytes: hello\n\n# Next we'll look at writing files.\n" }, { "path": "examples/recover/recover.go", "content": "// Go makes it possible to _recover_ from a panic, by\n// using the `recover` built-in function. A `recover` can\n// stop a `panic` from aborting the program and let it\n// continue with execution instead.\n\n// An example of where this can be useful: a server\n// wouldn't want to crash if one of the client connections\n// exhibits a critical error. Instead, the server would\n// want to close that connection and continue serving\n// other clients. In fact, this is what Go's `net/http`\n// does by default for HTTP servers.\n\npackage main\n\nimport \"fmt\"\n\n// This function panics.\nfunc mayPanic() {\n\tpanic(\"a problem\")\n}\n\nfunc main() {\n\t// `recover` must be called within a deferred function.\n\t// When the enclosing function panics, the defer will\n\t// activate and a `recover` call within it will catch\n\t// the panic.\n\tdefer func() {\n\t\tif r := recover(); r != nil {\n\t\t\t// The return value of `recover` is the error raised in\n\t\t\t// the call to `panic`.\n\t\t\tfmt.Println(\"Recovered. Error:\\n\", r)\n\t\t}\n\t}()\n\n\tmayPanic()\n\n\t// This code will not run, because `mayPanic` panics.\n\t// The execution of `main` stops at the point of the\n\t// panic and resumes in the deferred closure.\n\tfmt.Println(\"After mayPanic()\")\n}\n" }, { "path": "examples/recover/recover.hash", "content": "053ecbddb4f4a1d881aa40086de99da4e78b9990\nSk-SVdofEIZ\n" }, { "path": "examples/recover/recover.sh", "content": "$ go run recover.go\nRecovered. Error:\n a problem\n" }, { "path": "examples/recursion/recursion.go", "content": "// Go supports\n// recursive functions.\n// Here's a classic example.\n\npackage main\n\nimport \"fmt\"\n\n// This `fact` function calls itself until it reaches the\n// base case of `fact(0)`.\nfunc fact(n int) int {\n\tif n == 0 {\n\t\treturn 1\n\t}\n\treturn n * fact(n-1)\n}\n\nfunc main() {\n\tfmt.Println(fact(7))\n\n\t// Anonymous functions can also be recursive, but this requires\n\t// explicitly declaring a variable with `var` to store\n\t// the function before it's defined.\n\tvar fib func(n int) int\n\n\tfib = func(n int) int {\n\t\tif n < 2 {\n\t\t\treturn n\n\t\t}\n\n\t\t// Since `fib` was previously declared in `main`, Go\n\t\t// knows which function to call with `fib` here.\n\t\treturn fib(n-1) + fib(n-2)\n\t}\n\n\tfmt.Println(fib(7))\n}\n" }, { "path": "examples/recursion/recursion.hash", "content": "5787b4a187dc208dcdae43c7fdc0ba19b821ed94\nk4IRATLn9cE\n" }, { "path": "examples/recursion/recursion.sh", "content": "$ go run recursion.go \n5040\n13\n" }, { "path": "examples/regular-expressions/regular-expressions.go", "content": "// Go offers built-in support for [regular expressions](https://en.wikipedia.org/wiki/Regular_expression).\n// Here are some examples of common regexp-related tasks\n// in Go.\n\npackage main\n\nimport (\n\t\"bytes\"\n\t\"fmt\"\n\t\"regexp\"\n)\n\nfunc main() {\n\n\t// This tests whether a pattern matches a string.\n\tmatch, _ := regexp.MatchString(\"p([a-z]+)ch\", \"peach\")\n\tfmt.Println(match)\n\n\t// Above we used a string pattern directly, but for\n\t// other regexp tasks you'll need to `Compile` an\n\t// optimized `Regexp` struct.\n\tr, _ := regexp.Compile(\"p([a-z]+)ch\")\n\n\t// Many methods are available on these structs. Here's\n\t// a match test like we saw earlier.\n\tfmt.Println(r.MatchString(\"peach\"))\n\n\t// This finds the match for the regexp.\n\tfmt.Println(r.FindString(\"peach punch\"))\n\n\t// This also finds the first match but returns the\n\t// start and end indexes for the match instead of the\n\t// matching text.\n\tfmt.Println(\"idx:\", r.FindStringIndex(\"peach punch\"))\n\n\t// The `Submatch` variants include information about\n\t// both the whole-pattern matches and the submatches\n\t// within those matches. For example this will return\n\t// information for both `p([a-z]+)ch` and `([a-z]+)`.\n\tfmt.Println(r.FindStringSubmatch(\"peach punch\"))\n\n\t// Similarly this will return information about the\n\t// indexes of matches and submatches.\n\tfmt.Println(r.FindStringSubmatchIndex(\"peach punch\"))\n\n\t// The `All` variants of these functions apply to all\n\t// matches in the input, not just the first. For\n\t// example to find all matches for a regexp.\n\tfmt.Println(r.FindAllString(\"peach punch pinch\", -1))\n\n\t// These `All` variants are available for the other\n\t// functions we saw above as well.\n\tfmt.Println(\"all:\", r.FindAllStringSubmatchIndex(\n\t\t\"peach punch pinch\", -1))\n\n\t// Providing a non-negative integer as the second\n\t// argument to these functions will limit the number\n\t// of matches.\n\tfmt.Println(r.FindAllString(\"peach punch pinch\", 2))\n\n\t// Our examples above had string arguments and used\n\t// names like `MatchString`. We can also provide\n\t// `[]byte` arguments and drop `String` from the\n\t// function name.\n\tfmt.Println(r.Match([]byte(\"peach\")))\n\n\t// When creating global variables with regular\n\t// expressions you can use the `MustCompile` variation\n\t// of `Compile`. `MustCompile` panics instead of\n\t// returning an error, which makes it safer to use for\n\t// global variables.\n\tr = regexp.MustCompile(\"p([a-z]+)ch\")\n\tfmt.Println(\"regexp:\", r)\n\n\t// The `regexp` package can also be used to replace\n\t// subsets of strings with other values.\n\tfmt.Println(r.ReplaceAllString(\"a peach\", \"\"))\n\n\t// The `Func` variant allows you to transform matched\n\t// text with a given function.\n\tin := []byte(\"a peach\")\n\tout := r.ReplaceAllFunc(in, bytes.ToUpper)\n\tfmt.Println(string(out))\n}\n" }, { "path": "examples/regular-expressions/regular-expressions.hash", "content": "7fd60a9497546cb5c84242276ed79aecbde7e950\nfI2YIfYsCaL\n" }, { "path": "examples/regular-expressions/regular-expressions.sh", "content": "$ go run regular-expressions.go\ntrue\ntrue\npeach\nidx: [0 5]\n[peach ea]\n[0 5 1 3]\n[peach punch pinch]\nall: [[0 5 1 3] [6 11 7 9] [12 17 13 15]]\n[peach punch]\ntrue\nregexp: p([a-z]+)ch\na \na PEACH\n\n# For a complete reference on Go regular expressions check\n# the [`regexp`](https://pkg.go.dev/regexp) package docs.\n" }, { "path": "examples/select/select.go", "content": "// Go's _select_ lets you wait on multiple channel\n// operations. Combining goroutines and channels with\n// select is a powerful feature of Go.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"time\"\n)\n\nfunc main() {\n\n\t// For our example we'll select across two channels.\n\tc1 := make(chan string)\n\tc2 := make(chan string)\n\n\t// Each channel will receive a value after some amount\n\t// of time, to simulate e.g. blocking RPC operations\n\t// executing in concurrent goroutines.\n\tgo func() {\n\t\ttime.Sleep(1 * time.Second)\n\t\tc1 <- \"one\"\n\t}()\n\tgo func() {\n\t\ttime.Sleep(2 * time.Second)\n\t\tc2 <- \"two\"\n\t}()\n\n\t// We'll use `select` to await both of these values\n\t// simultaneously, printing each one as it arrives.\n\tfor range 2 {\n\t\tselect {\n\t\tcase msg1 := <-c1:\n\t\t\tfmt.Println(\"received\", msg1)\n\t\tcase msg2 := <-c2:\n\t\t\tfmt.Println(\"received\", msg2)\n\t\t}\n\t}\n}\n" }, { "path": "examples/select/select.hash", "content": "b10a3f618c232683fba207e56e4b4cda812fd377\ndOrjUfgGwB2\n" }, { "path": "examples/select/select.sh", "content": "# We receive the values `\"one\"` and then `\"two\"` as\n# expected.\n$ time go run select.go \nreceived one\nreceived two\n\n# Note that the total execution time is only ~2 seconds\n# since both the 1 and 2 second `Sleeps` execute\n# concurrently.\nreal\t0m2.245s\n" }, { "path": "examples/sha256-hashes/sha256-hashes.go", "content": "// [_SHA256 hashes_](https://en.wikipedia.org/wiki/SHA-2) are\n// frequently used to compute short identities for binary\n// or text blobs. For example, TLS/SSL certificates use SHA256\n// to compute a certificate's signature. Here's how to compute\n// SHA256 hashes in Go.\n\npackage main\n\n// Go implements several hash functions in various\n// `crypto/*` packages.\nimport (\n\t\"crypto/sha256\"\n\t\"fmt\"\n)\n\nfunc main() {\n\ts := \"sha256 this string\"\n\n\t// Here we start with a new hash.\n\th := sha256.New()\n\n\t// `Write` expects bytes. If you have a string `s`,\n\t// use `[]byte(s)` to coerce it to bytes.\n\th.Write([]byte(s))\n\n\t// This gets the finalized hash result as a byte\n\t// slice. The argument to `Sum` can be used to append\n\t// to an existing byte slice: it usually isn't needed.\n\tbs := h.Sum(nil)\n\n\tfmt.Println(s)\n\tfmt.Printf(\"%x\\n\", bs)\n}\n" }, { "path": "examples/sha256-hashes/sha256-hashes.hash", "content": "66d0faf25cd171218b0fc0fc341836a4f0069932\nIHM1lZVm_Jm\n" }, { "path": "examples/sha256-hashes/sha256-hashes.sh", "content": "# Running the program computes the hash and prints it in\n# a human-readable hex format.\n$ go run sha256-hashes.go\nsha256 this string\n1af1dfa857bf1d8814fe1af8983c18080019922e557f15a8a...\n\n\n# You can compute other hashes using a similar pattern to\n# the one shown above. For example, to compute\n# SHA512 hashes import `crypto/sha512` and use\n# `sha512.New()`.\n\n# Note that if you need cryptographically secure hashes,\n# you should carefully research\n# [hash strength](https://en.wikipedia.org/wiki/Cryptographic_hash_function)!\n" }, { "path": "examples/signals/signals.go", "content": "// Sometimes we'd like our Go programs to intelligently\n// handle [Unix signals](https://en.wikipedia.org/wiki/Unix_signal).\n// For example, we might want a server to gracefully\n// shutdown when it receives a `SIGTERM`, or a command-line\n// tool to stop processing input if it receives a `SIGINT`.\n// Here's a modern way to handle signals using contexts.\n\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"os/signal\"\n\t\"syscall\"\n)\n\nfunc main() {\n\t// `signal.NotifyContext` returns a context that's canceled\n\t// when one of the listed signals arrives.\n\tctx, stop := signal.NotifyContext(\n\t\tcontext.Background(), syscall.SIGINT, syscall.SIGTERM)\n\tdefer stop()\n\n\t// The program will wait here until one of the\n\t// configured signals is received.\n\tfmt.Println(\"awaiting signal\")\n\t<-ctx.Done()\n\n\t// `context.Cause` reports why the context was canceled.\n\t// For a signal-triggered cancellation, this includes\n\t// the signal value.\n\tfmt.Println()\n\tfmt.Println(context.Cause(ctx))\n\tfmt.Println(\"exiting\")\n}\n" }, { "path": "examples/signals/signals.hash", "content": "f55b2c52d8888d110d5909023e1dd8bfdf0846a6\nF3Wm7JT8wgn\n" }, { "path": "examples/signals/signals.sh", "content": "# When we run this program it will block waiting for a\n# signal. By typing `ctrl-C` (which the\n# terminal shows as `^C`) we can send a `SIGINT` signal,\n# causing the program to print the cancellation cause and then exit.\n$ go run signals.go\nawaiting signal\n^C\ninterrupt signal received\nexiting\n" }, { "path": "examples/slices/slices.go", "content": "// _Slices_ are an important data type in Go, giving\n// a more powerful interface to sequences than arrays.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"slices\"\n)\n\nfunc main() {\n\n\t// Unlike arrays, slices are typed only by the\n\t// elements they contain (not the number of elements).\n\t// An uninitialized slice equals to nil and has\n\t// length 0.\n\tvar s []string\n\tfmt.Println(\"uninit:\", s, s == nil, len(s) == 0)\n\n\t// To create a slice with non-zero length, use\n\t// the builtin `make`. Here we make a slice of\n\t// `string`s of length `3` (initially zero-valued).\n\t// By default a new slice's capacity is equal to its\n\t// length; if we know the slice is going to grow ahead\n\t// of time, it's possible to pass a capacity explicitly\n\t// as an additional parameter to `make`.\n\ts = make([]string, 3)\n\tfmt.Println(\"emp:\", s, \"len:\", len(s), \"cap:\", cap(s))\n\n\t// We can set and get just like with arrays.\n\ts[0] = \"a\"\n\ts[1] = \"b\"\n\ts[2] = \"c\"\n\tfmt.Println(\"set:\", s)\n\tfmt.Println(\"get:\", s[2])\n\n\t// `len` returns the length of the slice as expected.\n\tfmt.Println(\"len:\", len(s))\n\n\t// In addition to these basic operations, slices\n\t// support several more that make them richer than\n\t// arrays. One is the builtin `append`, which\n\t// returns a slice containing one or more new values.\n\t// Note that we need to accept a return value from\n\t// `append` as we may get a new slice value.\n\ts = append(s, \"d\")\n\ts = append(s, \"e\", \"f\")\n\tfmt.Println(\"apd:\", s)\n\n\t// Slices can also be `copy`'d. Here we create an\n\t// empty slice `c` of the same length as `s` and copy\n\t// into `c` from `s`.\n\tc := make([]string, len(s))\n\tcopy(c, s)\n\tfmt.Println(\"cpy:\", c)\n\n\t// Slices support a \"slice\" operator with the syntax\n\t// `slice[low:high]`. For example, this gets a slice\n\t// of the elements `s[2]`, `s[3]`, and `s[4]`.\n\tl := s[2:5]\n\tfmt.Println(\"sl1:\", l)\n\n\t// This slices up to (but excluding) `s[5]`.\n\tl = s[:5]\n\tfmt.Println(\"sl2:\", l)\n\n\t// And this slices up from (and including) `s[2]`.\n\tl = s[2:]\n\tfmt.Println(\"sl3:\", l)\n\n\t// We can declare and initialize a variable for slice\n\t// in a single line as well.\n\tt := []string{\"g\", \"h\", \"i\"}\n\tfmt.Println(\"dcl:\", t)\n\n\t// The `slices` package contains a number of useful\n\t// utility functions for slices.\n\tt2 := []string{\"g\", \"h\", \"i\"}\n\tif slices.Equal(t, t2) {\n\t\tfmt.Println(\"t == t2\")\n\t}\n\n\t// Slices can be composed into multi-dimensional data\n\t// structures. The length of the inner slices can\n\t// vary, unlike with multi-dimensional arrays.\n\ttwoD := make([][]int, 3)\n\tfor i := range 3 {\n\t\tinnerLen := i + 1\n\t\ttwoD[i] = make([]int, innerLen)\n\t\tfor j := range innerLen {\n\t\t\ttwoD[i][j] = i + j\n\t\t}\n\t}\n\tfmt.Println(\"2d: \", twoD)\n}\n" }, { "path": "examples/slices/slices.hash", "content": "4db1907fd5137325a1e3c3fc50950d4250ed1a4b\n9-U3-8sKQun\n" }, { "path": "examples/slices/slices.sh", "content": "# Note that while slices are different types than arrays,\n# they are rendered similarly by `fmt.Println`.\n$ go run slices.go\nuninit: [] true true\nemp: [ ] len: 3 cap: 3\nset: [a b c]\nget: c\nlen: 3\napd: [a b c d e f]\ncpy: [a b c d e f]\nsl1: [c d e]\nsl2: [a b c d e]\nsl3: [c d e f]\ndcl: [g h i]\nt == t2\n2d: [[0] [1 2] [2 3 4]]\n\n# Check out this [great blog post](https://go.dev/blog/slices-intro)\n# by the Go team for more details on the design and\n# implementation of slices in Go.\n\n# Now that we've seen arrays and slices we'll look at\n# Go's other key builtin data structure: maps.\n" }, { "path": "examples/sorting/sorting.go", "content": "// Go's `slices` package implements sorting for builtins\n// and user-defined types. We'll look at sorting for\n// builtins first.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"slices\"\n)\n\nfunc main() {\n\n\t// Sorting functions are generic, and work for any\n\t// _ordered_ built-in type. For a list of ordered\n\t// types, see [cmp.Ordered](https://pkg.go.dev/cmp#Ordered).\n\tstrs := []string{\"c\", \"a\", \"b\"}\n\tslices.Sort(strs)\n\tfmt.Println(\"Strings:\", strs)\n\n\t// An example of sorting `int`s.\n\tints := []int{7, 2, 4}\n\tslices.Sort(ints)\n\tfmt.Println(\"Ints: \", ints)\n\n\t// We can also use the `slices` package to check if\n\t// a slice is already in sorted order.\n\ts := slices.IsSorted(ints)\n\tfmt.Println(\"Sorted: \", s)\n}\n" }, { "path": "examples/sorting/sorting.hash", "content": "2091224c8d8ac748883215c4dbe9611fb8afacc3\nX7iJcIua02T\n" }, { "path": "examples/sorting/sorting.sh", "content": "$ go run sorting.go\nStrings: [a b c]\nInts: [2 4 7]\nSorted: true\n" }, { "path": "examples/sorting-by-functions/sorting-by-functions.go", "content": "// Sometimes we'll want to sort a collection by something\n// other than its natural order. For example, suppose we\n// wanted to sort strings by their length instead of\n// alphabetically. Here's an example of custom sorts\n// in Go.\n\npackage main\n\nimport (\n\t\"cmp\"\n\t\"fmt\"\n\t\"slices\"\n)\n\nfunc main() {\n\tfruits := []string{\"peach\", \"banana\", \"kiwi\"}\n\n\t// We implement a comparison function for string\n\t// lengths. `cmp.Compare` is helpful for this.\n\tlenCmp := func(a, b string) int {\n\t\treturn cmp.Compare(len(a), len(b))\n\t}\n\n\t// Now we can call `slices.SortFunc` with this custom\n\t// comparison function to sort `fruits` by name length.\n\tslices.SortFunc(fruits, lenCmp)\n\tfmt.Println(fruits)\n\n\t// We can use the same technique to sort a slice of\n\t// values that aren't built-in types.\n\ttype Person struct {\n\t\tname string\n\t\tage int\n\t}\n\n\tpeople := []Person{\n\t\tPerson{name: \"Jax\", age: 37},\n\t\tPerson{name: \"TJ\", age: 25},\n\t\tPerson{name: \"Alex\", age: 72},\n\t}\n\n\t// Sort `people` by age using `slices.SortFunc`.\n\t//\n\t// Note: if the `Person` struct is large,\n\t// you may want the slice to contain `*Person` instead\n\t// and adjust the sorting function accordingly. If in\n\t// doubt, [benchmark](testing-and-benchmarking)!\n\tslices.SortFunc(people,\n\t\tfunc(a, b Person) int {\n\t\t\treturn cmp.Compare(a.age, b.age)\n\t\t})\n\tfmt.Println(people)\n}\n" }, { "path": "examples/sorting-by-functions/sorting-by-functions.hash", "content": "9902d1c5654b64d8b381ea7888c0793ac8ab4a97\n3EaTknAZHMu\n" }, { "path": "examples/sorting-by-functions/sorting-by-functions.sh", "content": "$ go run sorting-by-functions.go \n[kiwi peach banana]\n[{TJ 25} {Jax 37} {Alex 72}]\n" }, { "path": "examples/spawning-processes/spawning-processes.go", "content": "// Sometimes our Go programs need to spawn other\n// processes.\n\npackage main\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n\t\"io\"\n\t\"os/exec\"\n)\n\nfunc main() {\n\n\t// We'll start with a simple command that takes no\n\t// arguments or input and just prints something to\n\t// stdout. The `exec.Command` helper creates an object\n\t// to represent this external process.\n\tdateCmd := exec.Command(\"date\")\n\n\t// The `Output` method runs the command, waits for it\n\t// to finish and collects its standard output.\n\t// If there were no errors, `dateOut` will hold bytes\n\t// with the date info.\n\tdateOut, err := dateCmd.Output()\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Println(\"> date\")\n\tfmt.Println(string(dateOut))\n\n\t// `Output` and other methods of `Command` will return\n\t// `*exec.Error` if there was a problem executing the\n\t// command (e.g. wrong path), and `*exec.ExitError`\n\t// if the command ran but exited with a non-zero return\n\t// code.\n\t_, err = exec.Command(\"date\", \"-x\").Output()\n\tif err != nil {\n\t\tif e, ok := errors.AsType[*exec.Error](err); ok {\n\t\t\tfmt.Println(\"failed executing:\", e)\n\t\t} else if e, ok := errors.AsType[*exec.ExitError](err); ok {\n\t\t\texitCode := e.ExitCode()\n\t\t\tfmt.Println(\"command exit rc =\", exitCode)\n\t\t} else {\n\t\t\tpanic(err)\n\t\t}\n\t}\n\n\t// Next we'll look at a slightly more involved case\n\t// where we pipe data to the external process on its\n\t// `stdin` and collect the results from its `stdout`.\n\tgrepCmd := exec.Command(\"grep\", \"hello\")\n\n\t// Here we explicitly grab input/output pipes, start\n\t// the process, write some input to it, read the\n\t// resulting output, and finally wait for the process\n\t// to exit.\n\tgrepIn, _ := grepCmd.StdinPipe()\n\tgrepOut, _ := grepCmd.StdoutPipe()\n\tgrepCmd.Start()\n\tgrepIn.Write([]byte(\"hello grep\\ngoodbye grep\"))\n\tgrepIn.Close()\n\tgrepBytes, _ := io.ReadAll(grepOut)\n\tgrepCmd.Wait()\n\n\t// We omitted error checks in the above example, but\n\t// you could use the usual `if err != nil` pattern for\n\t// all of them. We also only collect the `StdoutPipe`\n\t// results, but you could collect the `StderrPipe` in\n\t// exactly the same way.\n\tfmt.Println(\"> grep hello\")\n\tfmt.Println(string(grepBytes))\n\n\t// Note that when spawning commands we need to\n\t// provide an explicitly delineated command and\n\t// argument array, vs. being able to just pass in one\n\t// command-line string. If you want to spawn a full\n\t// command with a string, you can use `bash`'s `-c`\n\t// option:\n\tlsCmd := exec.Command(\"bash\", \"-c\", \"ls -a -l -h\")\n\tlsOut, err := lsCmd.Output()\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Println(\"> ls -a -l -h\")\n\tfmt.Println(string(lsOut))\n}\n" }, { "path": "examples/spawning-processes/spawning-processes.hash", "content": "4eebcdac2df1c55c6264fe4422a8e6855bcbc2e6\nIxGAEXe0I7U\n" }, { "path": "examples/spawning-processes/spawning-processes.sh", "content": "# The spawned programs return output that is the same\n# as if we had run them directly from the command-line.\n$ go run spawning-processes.go \n> date\nThu 05 May 2022 10:10:12 PM PDT\n\n# date doesn't have a `-x` flag so it will exit with\n# an error message and non-zero return code.\ncommand exit rc = 1\n> grep hello\nhello grep\n\n> ls -a -l -h\ndrwxr-xr-x 4 mark 136B Oct 3 16:29 .\ndrwxr-xr-x 91 mark 3.0K Oct 3 12:50 ..\n-rw-r--r-- 1 mark 1.3K Oct 3 16:28 spawning-processes.go\n" }, { "path": "examples/stateful-goroutines/stateful-goroutines.go", "content": "// In the previous example we used explicit locking with\n// [mutexes](mutexes) to synchronize access to shared state\n// across multiple goroutines. Another option is to use the\n// built-in synchronization features of goroutines and\n// channels to achieve the same result. This channel-based\n// approach aligns with Go's ideas of sharing memory by\n// communicating and having each piece of data owned\n// by exactly one goroutine.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"math/rand\"\n\t\"sync/atomic\"\n\t\"time\"\n)\n\n// In this example our state will be owned by a single\n// goroutine. This will guarantee that the data is never\n// corrupted with concurrent access. In order to read or\n// write that state, other goroutines will send messages\n// to the owning goroutine and receive corresponding\n// replies. These `readOp` and `writeOp` `struct`s\n// encapsulate those requests and a way for the owning\n// goroutine to respond.\ntype readOp struct {\n\tkey int\n\tresp chan int\n}\ntype writeOp struct {\n\tkey int\n\tval int\n\tresp chan bool\n}\n\nfunc main() {\n\n\t// As before we'll count how many operations we perform.\n\tvar readOps uint64\n\tvar writeOps uint64\n\n\t// The `reads` and `writes` channels will be used by\n\t// other goroutines to issue read and write requests,\n\t// respectively.\n\treads := make(chan readOp)\n\twrites := make(chan writeOp)\n\n\t// Here is the goroutine that owns the `state`, which\n\t// is a map as in the previous example but now private\n\t// to the stateful goroutine. This goroutine repeatedly\n\t// selects on the `reads` and `writes` channels,\n\t// responding to requests as they arrive. A response\n\t// is executed by first performing the requested\n\t// operation and then sending a value on the response\n\t// channel `resp` to indicate success (and the desired\n\t// value in the case of `reads`).\n\tgo func() {\n\t\tvar state = make(map[int]int)\n\t\tfor {\n\t\t\tselect {\n\t\t\tcase read := <-reads:\n\t\t\t\tread.resp <- state[read.key]\n\t\t\tcase write := <-writes:\n\t\t\t\tstate[write.key] = write.val\n\t\t\t\twrite.resp <- true\n\t\t\t}\n\t\t}\n\t}()\n\n\t// This starts 100 goroutines to issue reads to the\n\t// state-owning goroutine via the `reads` channel.\n\t// Each read requires constructing a `readOp`, sending\n\t// it over the `reads` channel, and then receiving the\n\t// result over the provided `resp` channel.\n\tfor range 100 {\n\t\tgo func() {\n\t\t\tfor {\n\t\t\t\tread := readOp{\n\t\t\t\t\tkey: rand.Intn(5),\n\t\t\t\t\tresp: make(chan int)}\n\t\t\t\treads <- read\n\t\t\t\t<-read.resp\n\t\t\t\tatomic.AddUint64(&readOps, 1)\n\t\t\t\ttime.Sleep(time.Millisecond)\n\t\t\t}\n\t\t}()\n\t}\n\n\t// We start 10 writes as well, using a similar\n\t// approach.\n\tfor range 10 {\n\t\tgo func() {\n\t\t\tfor {\n\t\t\t\twrite := writeOp{\n\t\t\t\t\tkey: rand.Intn(5),\n\t\t\t\t\tval: rand.Intn(100),\n\t\t\t\t\tresp: make(chan bool)}\n\t\t\t\twrites <- write\n\t\t\t\t<-write.resp\n\t\t\t\tatomic.AddUint64(&writeOps, 1)\n\t\t\t\ttime.Sleep(time.Millisecond)\n\t\t\t}\n\t\t}()\n\t}\n\n\t// Let the goroutines work for a second.\n\ttime.Sleep(time.Second)\n\n\t// Finally, capture and report the op counts.\n\treadOpsFinal := atomic.LoadUint64(&readOps)\n\tfmt.Println(\"readOps:\", readOpsFinal)\n\twriteOpsFinal := atomic.LoadUint64(&writeOps)\n\tfmt.Println(\"writeOps:\", writeOpsFinal)\n}\n" }, { "path": "examples/stateful-goroutines/stateful-goroutines.hash", "content": "0436907e3df175590da08a697c204bc79054798f\nuwnybdsnOSa\n" }, { "path": "examples/stateful-goroutines/stateful-goroutines.sh", "content": "# Running our program shows that the goroutine-based\n# state management example completes about 80,000\n# total operations.\n$ go run stateful-goroutines.go\nreadOps: 71708\nwriteOps: 7177\n\n# For this particular case the goroutine-based approach\n# was a bit more involved than the mutex-based one. It\n# might be useful in certain cases though, for example\n# where you have other channels involved or when managing\n# multiple such mutexes would be error-prone. You should\n# use whichever approach feels most natural, especially\n# with respect to understanding the correctness of your\n# program.\n" }, { "path": "examples/string-formatting/string-formatting.go", "content": "// Go offers excellent support for string formatting in\n// the `printf` tradition. Here are some examples of\n// common string formatting tasks.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n)\n\ntype point struct {\n\tx, y int\n}\n\nfunc main() {\n\n\t// Go offers several printing \"verbs\" designed to\n\t// format general Go values. For example, this prints\n\t// an instance of our `point` struct.\n\tp := point{1, 2}\n\tfmt.Printf(\"struct1: %v\\n\", p)\n\n\t// If the value is a struct, the `%+v` variant will\n\t// include the struct's field names.\n\tfmt.Printf(\"struct2: %+v\\n\", p)\n\n\t// The `%#v` variant prints a Go syntax representation\n\t// of the value, i.e. the source code snippet that\n\t// would produce that value.\n\tfmt.Printf(\"struct3: %#v\\n\", p)\n\n\t// To print the type of a value, use `%T`.\n\tfmt.Printf(\"type: %T\\n\", p)\n\n\t// Formatting booleans is straight-forward.\n\tfmt.Printf(\"bool: %t\\n\", true)\n\n\t// There are many options for formatting integers.\n\t// Use `%d` for standard, base-10 formatting.\n\tfmt.Printf(\"int: %d\\n\", 123)\n\n\t// This prints a binary representation.\n\tfmt.Printf(\"bin: %b\\n\", 14)\n\n\t// This prints the character corresponding to the\n\t// given integer.\n\tfmt.Printf(\"char: %c\\n\", 33)\n\n\t// `%x` provides hex encoding.\n\tfmt.Printf(\"hex: %x\\n\", 456)\n\n\t// There are also several formatting options for\n\t// floats. For basic decimal formatting use `%f`.\n\tfmt.Printf(\"float1: %f\\n\", 78.9)\n\n\t// `%e` and `%E` format the float in (slightly\n\t// different versions of) scientific notation.\n\tfmt.Printf(\"float2: %e\\n\", 123400000.0)\n\tfmt.Printf(\"float3: %E\\n\", 123400000.0)\n\n\t// For basic string printing use `%s`.\n\tfmt.Printf(\"str1: %s\\n\", \"\\\"string\\\"\")\n\n\t// To double-quote strings as in Go source, use `%q`.\n\tfmt.Printf(\"str2: %q\\n\", \"\\\"string\\\"\")\n\n\t// As with integers seen earlier, `%x` renders\n\t// the string in base-16, with two output characters\n\t// per byte of input.\n\tfmt.Printf(\"str3: %x\\n\", \"hex this\")\n\n\t// To print a representation of a pointer, use `%p`.\n\tfmt.Printf(\"pointer: %p\\n\", &p)\n\n\t// When formatting numbers you will often want to\n\t// control the width and precision of the resulting\n\t// figure. To specify the width of an integer, use a\n\t// number after the `%` in the verb. By default the\n\t// result will be right-justified and padded with\n\t// spaces.\n\tfmt.Printf(\"width1: |%6d|%6d|\\n\", 12, 345)\n\n\t// You can also specify the width of printed floats,\n\t// though usually you'll also want to restrict the\n\t// decimal precision at the same time with the\n\t// width.precision syntax.\n\tfmt.Printf(\"width2: |%6.2f|%6.2f|\\n\", 1.2, 3.45)\n\n\t// To left-justify, use the `-` flag.\n\tfmt.Printf(\"width3: |%-6.2f|%-6.2f|\\n\", 1.2, 3.45)\n\n\t// You may also want to control width when formatting\n\t// strings, especially to ensure that they align in\n\t// table-like output. For basic right-justified width.\n\tfmt.Printf(\"width4: |%6s|%6s|\\n\", \"foo\", \"b\")\n\n\t// To left-justify use the `-` flag as with numbers.\n\tfmt.Printf(\"width5: |%-6s|%-6s|\\n\", \"foo\", \"b\")\n\n\t// So far we've seen `Printf`, which prints the\n\t// formatted string to `os.Stdout`. `Sprintf` formats\n\t// and returns a string without printing it anywhere.\n\ts := fmt.Sprintf(\"sprintf: a %s\", \"string\")\n\tfmt.Println(s)\n\n\t// You can format+print to `io.Writers` other than\n\t// `os.Stdout` using `Fprintf`.\n\tfmt.Fprintf(os.Stderr, \"io: an %s\\n\", \"error\")\n}\n" }, { "path": "examples/string-formatting/string-formatting.hash", "content": "2297335ea52cc0ed960153b891d35252636308b4\nEZCZX1Uwp6D\n" }, { "path": "examples/string-formatting/string-formatting.sh", "content": "$ go run string-formatting.go\nstruct1: {1 2}\nstruct2: {x:1 y:2}\nstruct3: main.point{x:1, y:2}\ntype: main.point\nbool: true\nint: 123\nbin: 1110\nchar: !\nhex: 1c8\nfloat1: 78.900000\nfloat2: 1.234000e+08\nfloat3: 1.234000E+08\nstr1: \"string\"\nstr2: \"\\\"string\\\"\"\nstr3: 6865782074686973\npointer: 0xc0000ba000\nwidth1: | 12| 345|\nwidth2: | 1.20| 3.45|\nwidth3: |1.20 |3.45 |\nwidth4: | foo| b|\nwidth5: |foo |b |\nsprintf: a string\nio: an error\n" }, { "path": "examples/string-functions/string-functions.go", "content": "// The standard library's `strings` package provides many\n// useful string-related functions. Here are some examples\n// to give you a sense of the package.\n\npackage main\n\nimport (\n\t\"fmt\"\n\ts \"strings\"\n)\n\n// We alias `fmt.Println` to a shorter name as we'll use\n// it a lot below.\nvar p = fmt.Println\n\nfunc main() {\n\n\t// Here's a sample of the functions available in\n\t// `strings`. Since these are functions from the\n\t// package, not methods on the string object itself,\n\t// we need to pass the string in question as the first\n\t// argument to the function. You can find more\n\t// functions in the [`strings`](https://pkg.go.dev/strings)\n\t// package docs.\n\tp(\"Contains: \", s.Contains(\"test\", \"es\"))\n\tp(\"Count: \", s.Count(\"test\", \"t\"))\n\tp(\"HasPrefix: \", s.HasPrefix(\"test\", \"te\"))\n\tp(\"HasSuffix: \", s.HasSuffix(\"test\", \"st\"))\n\tp(\"Index: \", s.Index(\"test\", \"e\"))\n\tp(\"Join: \", s.Join([]string{\"a\", \"b\"}, \"-\"))\n\tp(\"Repeat: \", s.Repeat(\"a\", 5))\n\tp(\"Replace: \", s.Replace(\"foo\", \"o\", \"0\", -1))\n\tp(\"Replace: \", s.Replace(\"foo\", \"o\", \"0\", 1))\n\tp(\"Split: \", s.Split(\"a-b-c-d-e\", \"-\"))\n\tp(\"ToLower: \", s.ToLower(\"TEST\"))\n\tp(\"ToUpper: \", s.ToUpper(\"test\"))\n}\n" }, { "path": "examples/string-functions/string-functions.hash", "content": "e1e2ea01b9c79fecebfece602915e9367b02a083\nwKSAzxfs96O\n" }, { "path": "examples/string-functions/string-functions.sh", "content": "$ go run string-functions.go\nContains: true\nCount: 2\nHasPrefix: true\nHasSuffix: true\nIndex: 1\nJoin: a-b\nRepeat: aaaaa\nReplace: f00\nReplace: f0o\nSplit: [a b c d e]\nToLower: test\nToUpper: TEST\n" }, { "path": "examples/strings-and-runes/strings-and-runes.go", "content": "// A Go string is a read-only slice of bytes. The language\n// and the standard library treat strings specially - as\n// containers of text encoded in [UTF-8](https://en.wikipedia.org/wiki/UTF-8).\n// In other languages, strings are made of \"characters\".\n// In Go, the concept of a character is called a `rune` - it's\n// an integer that represents a Unicode code point.\n// [This Go blog post](https://go.dev/blog/strings) is a good\n// introduction to the topic.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"unicode/utf8\"\n)\n\nfunc main() {\n\n\t// `s` is a `string` assigned a literal value\n\t// representing the word \"hello\" in the Thai\n\t// language. Go string literals are UTF-8\n\t// encoded text.\n\tconst s = \"สวัสดี\"\n\n\t// Since strings are equivalent to `[]byte`, this\n\t// will produce the length of the raw bytes stored within.\n\tfmt.Println(\"Len:\", len(s))\n\n\t// Indexing into a string produces the raw byte values at\n\t// each index. This loop generates the hex values of all\n\t// the bytes that constitute the code points in `s`.\n\tfor i := 0; i < len(s); i++ {\n\t\tfmt.Printf(\"%x \", s[i])\n\t}\n\tfmt.Println()\n\n\t// To count how many _runes_ are in a string, we can use\n\t// the `utf8` package. Note that the run-time of\n\t// `RuneCountInString` depends on the size of the string,\n\t// because it has to decode each UTF-8 rune sequentially.\n\t// Some Thai characters are represented by UTF-8 code points\n\t// that can span multiple bytes, so the result of this count\n\t// may be surprising.\n\tfmt.Println(\"Rune count:\", utf8.RuneCountInString(s))\n\n\t// A `range` loop handles strings specially and decodes\n\t// each `rune` along with its offset in the string.\n\tfor idx, runeValue := range s {\n\t\tfmt.Printf(\"%#U starts at %d\\n\", runeValue, idx)\n\t}\n\n\t// We can achieve the same iteration by using the\n\t// `utf8.DecodeRuneInString` function explicitly.\n\tfmt.Println(\"\\nUsing DecodeRuneInString\")\n\tfor i, w := 0, 0; i < len(s); i += w {\n\t\truneValue, width := utf8.DecodeRuneInString(s[i:])\n\t\tfmt.Printf(\"%#U starts at %d\\n\", runeValue, i)\n\t\tw = width\n\n\t\t// This demonstrates passing a `rune` value to a function.\n\t\texamineRune(runeValue)\n\t}\n}\n\nfunc examineRune(r rune) {\n\n\t// Values enclosed in single quotes are _rune literals_. We\n\t// can compare a `rune` value to a rune literal directly.\n\tif r == 't' {\n\t\tfmt.Println(\"found tee\")\n\t} else if r == 'ส' {\n\t\tfmt.Println(\"found so sua\")\n\t}\n}\n" }, { "path": "examples/strings-and-runes/strings-and-runes.hash", "content": "ffbc918567cea7cdadcaee87ffc404a1d4f5c62a\n-iNDXZ9IM3s\n" }, { "path": "examples/strings-and-runes/strings-and-runes.sh", "content": "$ go run strings-and-runes.go\nLen: 18\ne0 b8 aa e0 b8 a7 e0 b8 b1 e0 b8 aa e0 b8 94 e0 b8 b5 \nRune count: 6\nU+0E2A 'ส' starts at 0\nU+0E27 'ว' starts at 3\nU+0E31 'ั' starts at 6\nU+0E2A 'ส' starts at 9\nU+0E14 'ด' starts at 12\nU+0E35 'ี' starts at 15\n\nUsing DecodeRuneInString\nU+0E2A 'ส' starts at 0\nfound so sua\nU+0E27 'ว' starts at 3\nU+0E31 'ั' starts at 6\nU+0E2A 'ส' starts at 9\nfound so sua\nU+0E14 'ด' starts at 12\nU+0E35 'ี' starts at 15\n" }, { "path": "examples/struct-embedding/struct-embedding.go", "content": "// Go supports _embedding_ of structs and interfaces\n// to express a more seamless _composition_ of types.\n// This is not to be confused with [`//go:embed`](embed-directive) which is\n// a go directive introduced in Go version 1.16+ to embed\n// files and folders into the application binary.\n\npackage main\n\nimport \"fmt\"\n\ntype base struct {\n\tnum int\n}\n\nfunc (b base) describe() string {\n\treturn fmt.Sprintf(\"base with num=%v\", b.num)\n}\n\n// A `container` _embeds_ a `base`. An embedding looks\n// like a field without a name.\ntype container struct {\n\tbase\n\tstr string\n}\n\nfunc main() {\n\n\t// When creating structs with literals, we have to\n\t// initialize the embedding explicitly; here the\n\t// embedded type serves as the field name.\n\tco := container{\n\t\tbase: base{\n\t\t\tnum: 1,\n\t\t},\n\t\tstr: \"some name\",\n\t}\n\n\t// We can access the base's fields directly on `co`,\n\t// e.g. `co.num`.\n\tfmt.Printf(\"co={num: %v, str: %v}\\n\", co.num, co.str)\n\n\t// Alternatively, we can spell out the full path using\n\t// the embedded type name.\n\tfmt.Println(\"also num:\", co.base.num)\n\n\t// Since `container` embeds `base`, the methods of\n\t// `base` also become methods of a `container`. Here\n\t// we invoke a method that was embedded from `base`\n\t// directly on `co`.\n\tfmt.Println(\"describe:\", co.describe())\n\n\ttype describer interface {\n\t\tdescribe() string\n\t}\n\n\t// Embedding structs with methods may be used to bestow\n\t// interface implementations onto other structs. Here\n\t// we see that a `container` now implements the\n\t// `describer` interface because it embeds `base`.\n\tvar d describer = co\n\tfmt.Println(\"describer:\", d.describe())\n}\n" }, { "path": "examples/struct-embedding/struct-embedding.hash", "content": "7ac6d1889bfc68e8f3f931014c87e05db2ecda95\n-LOu1L0i2tR\n" }, { "path": "examples/struct-embedding/struct-embedding.sh", "content": "$ go run struct-embedding.go\nco={num: 1, str: some name}\nalso num: 1\ndescribe: base with num=1\ndescriber: base with num=1\n" }, { "path": "examples/structs/structs.go", "content": "// Go's _structs_ are typed collections of fields.\n// They're useful for grouping data together to form\n// records.\n\npackage main\n\nimport \"fmt\"\n\n// This `person` struct type has `name` and `age` fields.\ntype person struct {\n\tname string\n\tage int\n}\n\n// `newPerson` constructs a new person struct with the given name.\nfunc newPerson(name string) *person {\n\t// Go is a garbage collected language; you can safely\n\t// return a pointer to a local variable - it will only\n\t// be cleaned up by the garbage collector when there\n\t// are no active references to it.\n\tp := person{name: name}\n\tp.age = 42\n\treturn &p\n}\n\nfunc main() {\n\n\t// This syntax creates a new struct.\n\tfmt.Println(person{\"Bob\", 20})\n\n\t// You can name the fields when initializing a struct.\n\tfmt.Println(person{name: \"Alice\", age: 30})\n\n\t// Omitted fields will be zero-valued.\n\tfmt.Println(person{name: \"Fred\"})\n\n\t// An `&` prefix yields a pointer to the struct.\n\tfmt.Println(&person{name: \"Ann\", age: 40})\n\n\t// It's idiomatic to encapsulate new struct creation in constructor functions\n\tfmt.Println(newPerson(\"Jon\"))\n\n\t// Access struct fields with a dot.\n\ts := person{name: \"Sean\", age: 50}\n\tfmt.Println(s.name)\n\n\t// You can also use dots with struct pointers - the\n\t// pointers are automatically dereferenced.\n\tsp := &s\n\tfmt.Println(sp.age)\n\n\t// Structs are mutable.\n\tsp.age = 51\n\tfmt.Println(sp.age)\n\n\t// If a struct type is only used for a single value, we don't\n\t// have to give it a name. The value can have an anonymous\n\t// struct type. This technique is commonly used for\n\t// [table-driven tests](testing-and-benchmarking).\n\tdog := struct {\n\t\tname string\n\t\tisGood bool\n\t}{\n\t\t\"Rex\",\n\t\ttrue,\n\t}\n\tfmt.Println(dog)\n}\n" }, { "path": "examples/structs/structs.hash", "content": "b50c1756bf9a2ea7f8853f7f7cb7a61d5efebfc3\n56SPo-L2nMN\n" }, { "path": "examples/structs/structs.sh", "content": "$ go run structs.go\n{Bob 20}\n{Alice 30}\n{Fred 0}\n&{Ann 40}\n&{Jon 42}\nSean\n50\n51\n{Rex true}\n" }, { "path": "examples/switch/switch.go", "content": "// _Switch statements_ express conditionals across many\n// branches.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"time\"\n)\n\nfunc main() {\n\n\t// Here's a basic `switch`.\n\ti := 2\n\tfmt.Print(\"Write \", i, \" as \")\n\tswitch i {\n\tcase 1:\n\t\tfmt.Println(\"one\")\n\tcase 2:\n\t\tfmt.Println(\"two\")\n\tcase 3:\n\t\tfmt.Println(\"three\")\n\t}\n\n\t// You can use commas to separate multiple expressions\n\t// in the same `case` statement. We use the optional\n\t// `default` case in this example as well.\n\tswitch time.Now().Weekday() {\n\tcase time.Saturday, time.Sunday:\n\t\tfmt.Println(\"It's the weekend\")\n\tdefault:\n\t\tfmt.Println(\"It's a weekday\")\n\t}\n\n\t// `switch` without an expression is an alternate way\n\t// to express if/else logic. Here we also show how the\n\t// `case` expressions can be non-constants.\n\tt := time.Now()\n\tswitch {\n\tcase t.Hour() < 12:\n\t\tfmt.Println(\"It's before noon\")\n\tdefault:\n\t\tfmt.Println(\"It's after noon\")\n\t}\n\n\t// A type `switch` compares types instead of values. You\n\t// can use this to discover the type of an interface\n\t// value. In this example, the variable `t` will have the\n\t// type corresponding to its clause.\n\twhatAmI := func(i interface{}) {\n\t\tswitch t := i.(type) {\n\t\tcase bool:\n\t\t\tfmt.Println(\"I'm a bool\")\n\t\tcase int:\n\t\t\tfmt.Println(\"I'm an int\")\n\t\tdefault:\n\t\t\tfmt.Printf(\"Don't know type %T\\n\", t)\n\t\t}\n\t}\n\twhatAmI(true)\n\twhatAmI(1)\n\twhatAmI(\"hey\")\n}\n" }, { "path": "examples/switch/switch.hash", "content": "28a8909ee7963cb315f14a3be1607def1d91f3a3\nqVDqWoUQ6AI\n" }, { "path": "examples/switch/switch.sh", "content": "$ go run switch.go \nWrite 2 as two\nIt's a weekday\nIt's after noon\nI'm a bool\nI'm an int\nDon't know type string\n" }, { "path": "examples/tcp-server/tcp-server.go", "content": "// The `net` package provides the tools we need to easily build\n// TCP socket servers.\npackage main\n\nimport (\n\t\"bufio\"\n\t\"fmt\"\n\t\"log\"\n\t\"net\"\n\t\"strings\"\n)\n\nfunc main() {\n\n\t// `net.Listen` starts the server on the given network\n\t// (TCP) and address (port 8090 on all interfaces).\n\tlistener, err := net.Listen(\"tcp\", \":8090\")\n\tif err != nil {\n\t\tlog.Fatal(\"Error listening:\", err)\n\t}\n\n\t// Close the listener to free the port\n\t// when the application exits.\n\tdefer listener.Close()\n\n\t// Loop indefinitely to accept new client connections.\n\tfor {\n\t\t// Wait for a connection.\n\t\tconn, err := listener.Accept()\n\t\tif err != nil {\n\t\t\tlog.Println(\"Error accepting conn:\", err)\n\t\t\tcontinue\n\t\t}\n\n\t\t// We use a goroutine here to handle the connection\n\t\t// so that the main loop can continue accepting more\n\t\t// connections.\n\t\tgo handleConnection(conn)\n\t}\n}\n\n// `handleConnection` handles a single client connection,\n// reading one line of text from the client and returning a response.\nfunc handleConnection(conn net.Conn) {\n\t// Closing the connection releases resources when\n\t// we are finished interacting with the client.\n\tdefer conn.Close()\n\n\t// Use `bufio.NewReader` to read one line of data\n\t// from the client (terminated by a newline).\n\treader := bufio.NewReader(conn)\n\tmessage, err := reader.ReadString('\\n')\n\tif err != nil {\n\t\tlog.Printf(\"Read error: %v\", err)\n\t\treturn\n\t}\n\n\t// Create and send a response back to the client,\n\t// demonstrating two-way communication.\n\tackMsg := strings.ToUpper(strings.TrimSpace(message))\n\tresponse := fmt.Sprintf(\"ACK: %s\\n\", ackMsg)\n\t_, err = conn.Write([]byte(response))\n\tif err != nil {\n\t\tlog.Printf(\"Server write error: %v\", err)\n\t}\n}\n" }, { "path": "examples/tcp-server/tcp-server.hash", "content": "c356ece464b228046dc123501acc746ae63d58a8\nG0k2jHMA6ei\n" }, { "path": "examples/tcp-server/tcp-server.sh", "content": "# Run the TCP server in the background.\n$ go run tcp-server.go &\n\n# Send data and capture the response using netcat.\n$ echo \"Hello from netcat\" | nc localhost 8090\nACK: HELLO FROM NETCAT\n\n" }, { "path": "examples/temporary-files-and-directories/temporary-files-and-directories.go", "content": "// Throughout program execution, we often want to create\n// data that isn't needed after the program exits.\n// *Temporary files and directories* are useful for this\n// purpose since they don't pollute the file system over\n// time.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\t\"path/filepath\"\n)\n\nfunc check(e error) {\n\tif e != nil {\n\t\tpanic(e)\n\t}\n}\n\nfunc main() {\n\n\t// The easiest way to create a temporary file is by\n\t// calling `os.CreateTemp`. It creates a file *and*\n\t// opens it for reading and writing. We provide `\"\"`\n\t// as the first argument, so `os.CreateTemp` will\n\t// create the file in the default location for our OS.\n\tf, err := os.CreateTemp(\"\", \"sample\")\n\tcheck(err)\n\n\t// Display the name of the temporary file. On\n\t// Unix-based OSes the directory will likely be `/tmp`.\n\t// The file name starts with the prefix given as the\n\t// second argument to `os.CreateTemp` and the rest\n\t// is chosen automatically to ensure that concurrent\n\t// calls will always create different file names.\n\tfmt.Println(\"Temp file name:\", f.Name())\n\n\t// Clean up the file after we're done. The OS is\n\t// likely to clean up temporary files by itself after\n\t// some time, but it's good practice to do this\n\t// explicitly.\n\tdefer os.Remove(f.Name())\n\n\t// We can write some data to the file.\n\t_, err = f.Write([]byte{1, 2, 3, 4})\n\tcheck(err)\n\n\t// If we intend to write many temporary files, we may\n\t// prefer to create a temporary *directory*.\n\t// `os.MkdirTemp`'s arguments are the same as\n\t// `CreateTemp`'s, but it returns a directory *name*\n\t// rather than an open file.\n\tdname, err := os.MkdirTemp(\"\", \"sampledir\")\n\tcheck(err)\n\tfmt.Println(\"Temp dir name:\", dname)\n\n\tdefer os.RemoveAll(dname)\n\n\t// Now we can synthesize temporary file names by\n\t// prefixing them with our temporary directory.\n\tfname := filepath.Join(dname, \"file1\")\n\terr = os.WriteFile(fname, []byte{1, 2}, 0666)\n\tcheck(err)\n}\n" }, { "path": "examples/temporary-files-and-directories/temporary-files-and-directories.hash", "content": "d875fd8f061e895d72c48c360a8ad4b04e406dd4\nhVcPg9RH3_V\n" }, { "path": "examples/temporary-files-and-directories/temporary-files-and-directories.sh", "content": "$ go run temporary-files-and-directories.go\nTemp file name: /tmp/sample610887201\nTemp dir name: /tmp/sampledir898854668\n" }, { "path": "examples/testing-and-benchmarking/main_test.go", "content": "// Unit testing is an important part of writing\n// principled Go programs. The `testing` package\n// provides the tools we need to write unit tests\n// and the `go test` command runs tests.\n\n// For the sake of demonstration, this code is in package\n// `main`, but it could be any package. Testing code\n// typically lives in the same package as the code it tests.\npackage main\n\nimport (\n\t\"fmt\"\n\t\"testing\"\n)\n\n// We'll be testing this simple implementation of an\n// integer minimum. Typically, the code we're testing\n// would be in a source file named something like\n// `intutils.go`, and the test file for it would then\n// be named `intutils_test.go`.\nfunc IntMin(a, b int) int {\n\tif a < b {\n\t\treturn a\n\t}\n\treturn b\n}\n\n// A test is created by writing a function with a name\n// beginning with `Test`.\nfunc TestIntMinBasic(t *testing.T) {\n\tans := IntMin(2, -2)\n\tif ans != -2 {\n\t\t// `t.Error*` will report test failures but continue\n\t\t// executing the test. `t.Fatal*` will report test\n\t\t// failures and stop the test immediately.\n\t\tt.Errorf(\"IntMin(2, -2) = %d; want -2\", ans)\n\t}\n}\n\n// Writing tests can be repetitive, so it's idiomatic to\n// use a *table-driven style*, where test inputs and\n// expected outputs are listed in a table and a single loop\n// walks over them and performs the test logic.\nfunc TestIntMinTableDriven(t *testing.T) {\n\tvar tests = []struct {\n\t\ta, b int\n\t\twant int\n\t}{\n\t\t{0, 1, 0},\n\t\t{1, 0, 0},\n\t\t{2, -2, -2},\n\t\t{0, -1, -1},\n\t\t{-1, 0, -1},\n\t}\n\n\tfor _, tt := range tests {\n\t\t// `t.Run` enables running \"subtests\", one for each\n\t\t// table entry. These are shown separately\n\t\t// when executing `go test -v`.\n\t\ttestname := fmt.Sprintf(\"%d,%d\", tt.a, tt.b)\n\t\tt.Run(testname, func(t *testing.T) {\n\t\t\tans := IntMin(tt.a, tt.b)\n\t\t\tif ans != tt.want {\n\t\t\t\tt.Errorf(\"got %d, want %d\", ans, tt.want)\n\t\t\t}\n\t\t})\n\t}\n}\n\n// Benchmark tests typically go in `_test.go` files and are\n// named beginning with `Benchmark`.\n// Any code that's required for the benchmark to run but should\n// not be measured goes before this loop.\nfunc BenchmarkIntMin(b *testing.B) {\n\tfor b.Loop() {\n\t\t// The benchmark runner will automatically execute this loop\n\t\t// body many times to determine a reasonable estimate of the\n\t\t// run-time of a single iteration.\n\t\tIntMin(1, 2)\n\t}\n}\n" }, { "path": "examples/testing-and-benchmarking/main_test.sh", "content": "# Run all tests in the current project in verbose mode.\n$ go test -v\n== RUN TestIntMinBasic\n--- PASS: TestIntMinBasic (0.00s)\n=== RUN TestIntMinTableDriven\n=== RUN TestIntMinTableDriven/0,1\n=== RUN TestIntMinTableDriven/1,0\n=== RUN TestIntMinTableDriven/2,-2\n=== RUN TestIntMinTableDriven/0,-1\n=== RUN TestIntMinTableDriven/-1,0\n--- PASS: TestIntMinTableDriven (0.00s)\n --- PASS: TestIntMinTableDriven/0,1 (0.00s)\n --- PASS: TestIntMinTableDriven/1,0 (0.00s)\n --- PASS: TestIntMinTableDriven/2,-2 (0.00s)\n --- PASS: TestIntMinTableDriven/0,-1 (0.00s)\n --- PASS: TestIntMinTableDriven/-1,0 (0.00s)\nPASS\nok \texamples/testing-and-benchmarking\t0.023s\n\n# Run all benchmarks in the current project. All tests\n# are run prior to benchmarks. The `bench` flag filters\n# benchmark function names with a regexp.\n$ go test -bench=.\ngoos: darwin\ngoarch: arm64\npkg: examples/testing\nBenchmarkIntMin-8 1000000000 0.3136 ns/op\nPASS\nok \texamples/testing-and-benchmarking\t0.351s\n" }, { "path": "examples/testing-and-benchmarking/testing-and-benchmarking.hash", "content": "565e50f23b399cdbca4aedeb8b62b9f6ad097443\nosZckbKSkse\n" }, { "path": "examples/text-templates/text-templates.go", "content": "// Go offers built-in support for creating dynamic content or showing customized\n// output to the user with the `text/template` package. A sibling package\n// named `html/template` provides the same API but has additional security\n// features and should be used for generating HTML.\n\npackage main\n\nimport (\n\t\"os\"\n\t\"text/template\"\n)\n\nfunc main() {\n\n\t// We can create a new template and parse its body from\n\t// a string.\n\t// Templates are a mix of static text and \"actions\" enclosed in\n\t// `{{...}}` that are used to dynamically insert content.\n\tt1 := template.New(\"t1\")\n\tt1, err := t1.Parse(\"Value is {{.}}\\n\")\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\t// Alternatively, we can use the `template.Must` function to\n\t// panic in case `Parse` returns an error. This is especially\n\t// useful for templates initialized in the global scope.\n\tt1 = template.Must(t1.Parse(\"Value: {{.}}\\n\"))\n\n\t// By \"executing\" the template we generate its text with\n\t// specific values for its actions. The `{{.}}` action is\n\t// replaced by the value passed as a parameter to `Execute`.\n\tt1.Execute(os.Stdout, \"some text\")\n\tt1.Execute(os.Stdout, 5)\n\tt1.Execute(os.Stdout, []string{\n\t\t\"Go\",\n\t\t\"Rust\",\n\t\t\"C++\",\n\t\t\"C#\",\n\t})\n\n\t// Helper function we'll use below.\n\tCreate := func(name, t string) *template.Template {\n\t\treturn template.Must(template.New(name).Parse(t))\n\t}\n\n\t// If the data is a struct we can use the `{{.FieldName}}` action to access\n\t// its fields. The fields should be exported to be accessible when a\n\t// template is executing.\n\tt2 := Create(\"t2\", \"Name: {{.Name}}\\n\")\n\n\tt2.Execute(os.Stdout, struct {\n\t\tName string\n\t}{\"Jane Doe\"})\n\n\t// The same applies to maps; with maps there is no restriction on the\n\t// case of key names.\n\tt2.Execute(os.Stdout, map[string]string{\n\t\t\"Name\": \"Mickey Mouse\",\n\t})\n\n\t// if/else provide conditional execution for templates. A value is considered\n\t// false if it's the default value of a type, such as 0, an empty string,\n\t// nil pointer, etc.\n\t// This sample demonstrates another\n\t// feature of templates: using `-` in actions to trim whitespace.\n\tt3 := Create(\"t3\",\n\t\t\"{{if . -}} yes {{else -}} no {{end}}\\n\")\n\tt3.Execute(os.Stdout, \"not empty\")\n\tt3.Execute(os.Stdout, \"\")\n\n\t// range blocks let us loop through slices, arrays, maps or channels. Inside\n\t// the range block `{{.}}` is set to the current item of the iteration.\n\tt4 := Create(\"t4\",\n\t\t\"Range: {{range .}}{{.}} {{end}}\\n\")\n\tt4.Execute(os.Stdout,\n\t\t[]string{\n\t\t\t\"Go\",\n\t\t\t\"Rust\",\n\t\t\t\"C++\",\n\t\t\t\"C#\",\n\t\t})\n}\n" }, { "path": "examples/text-templates/text-templates.hash", "content": "c29676a83f4832a77b7a9e300d3fb5fe315de7b8\npDwkw1iMACF\n" }, { "path": "examples/text-templates/text-templates.sh", "content": "$ go run templates.go \nValue: some text\nValue: 5\nValue: [Go Rust C++ C#]\nName: Jane Doe\nName: Mickey Mouse\nyes \nno \nRange: Go Rust C++ C# \n" }, { "path": "examples/tickers/tickers.go", "content": "// [Timers](timers) are for when you want to do\n// something once in the future - _tickers_ are for when\n// you want to do something repeatedly at regular\n// intervals. Here's an example of a ticker that ticks\n// periodically until we stop it.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"time\"\n)\n\nfunc main() {\n\n\t// Tickers use a similar mechanism to timers: a\n\t// channel that is sent values. Here we'll use the\n\t// `select` builtin on the channel to await the\n\t// values as they arrive every 500ms.\n\tticker := time.NewTicker(500 * time.Millisecond)\n\tdone := make(chan bool)\n\n\tgo func() {\n\t\tfor {\n\t\t\tselect {\n\t\t\tcase <-done:\n\t\t\t\treturn\n\t\t\tcase t := <-ticker.C:\n\t\t\t\tfmt.Println(\"Tick at\", t)\n\t\t\t}\n\t\t}\n\t}()\n\n\t// Tickers can be stopped like timers. Once a ticker\n\t// is stopped it won't receive any more values on its\n\t// channel. We'll stop ours after 1600ms.\n\ttime.Sleep(1600 * time.Millisecond)\n\tticker.Stop()\n\tdone <- true\n\tfmt.Println(\"Ticker stopped\")\n}\n" }, { "path": "examples/tickers/tickers.hash", "content": "432b3be0884cead3f01b9cce0868ac6146e7864e\ngs6zoJP-Pl9\n" }, { "path": "examples/tickers/tickers.sh", "content": "# When we run this program the ticker should tick 3 times\n# before we stop it.\n$ go run tickers.go\nTick at 2012-09-23 11:29:56.487625 -0700 PDT\nTick at 2012-09-23 11:29:56.988063 -0700 PDT\nTick at 2012-09-23 11:29:57.488076 -0700 PDT\nTicker stopped\n" }, { "path": "examples/time/time.go", "content": "// Go offers extensive support for times and durations;\n// here are some examples.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"time\"\n)\n\nfunc main() {\n\tp := fmt.Println\n\n\t// We'll start by getting the current time.\n\tnow := time.Now()\n\tp(now)\n\n\t// You can build a `time` struct by providing the\n\t// year, month, day, etc. Times are always associated\n\t// with a `Location`, i.e. time zone.\n\tthen := time.Date(\n\t\t2009, 11, 17, 20, 34, 58, 651387237, time.UTC)\n\tp(then)\n\n\t// You can extract the various components of the time\n\t// value as expected.\n\tp(then.Year())\n\tp(then.Month())\n\tp(then.Day())\n\tp(then.Hour())\n\tp(then.Minute())\n\tp(then.Second())\n\tp(then.Nanosecond())\n\tp(then.Location())\n\n\t// The Monday-Sunday `Weekday` is also available.\n\tp(then.Weekday())\n\n\t// These methods compare two times, testing if the\n\t// first occurs before, after, or at the same time\n\t// as the second, respectively.\n\tp(then.Before(now))\n\tp(then.After(now))\n\tp(then.Equal(now))\n\n\t// The `Sub` methods returns a `Duration` representing\n\t// the interval between two times.\n\tdiff := now.Sub(then)\n\tp(diff)\n\n\t// We can compute the length of the duration in\n\t// various units.\n\tp(diff.Hours())\n\tp(diff.Minutes())\n\tp(diff.Seconds())\n\tp(diff.Nanoseconds())\n\n\t// You can use `Add` to advance a time by a given\n\t// duration, or with a `-` to move backwards by a\n\t// duration.\n\tp(then.Add(diff))\n\tp(then.Add(-diff))\n}\n" }, { "path": "examples/time/time.hash", "content": "24eefcc82ee0c70a4678a4952fe2b8c558c7419c\nYAM3s1KPc8c\n" }, { "path": "examples/time/time.sh", "content": "$ go run time.go\n2012-10-31 15:50:13.793654 +0000 UTC\n2009-11-17 20:34:58.651387237 +0000 UTC\n2009\nNovember\n17\n20\n34\n58\n651387237\nUTC\nTuesday\ntrue\nfalse\nfalse\n25891h15m15.142266763s\n25891.25420618521\n1.5534752523711128e+06\n9.320851514226677e+07\n93208515142266763\n2012-10-31 15:50:13.793654 +0000 UTC\n2006-12-05 01:19:43.509120474 +0000 UTC\n\n# Next we'll look at the related idea of time relative to\n# the Unix epoch.\n" }, { "path": "examples/time-formatting-parsing/time-formatting-parsing.go", "content": "// Go supports time formatting and parsing via\n// pattern-based layouts.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"time\"\n)\n\nfunc main() {\n\tp := fmt.Println\n\n\t// Here's a basic example of formatting a time\n\t// according to RFC3339, using the corresponding layout\n\t// constant.\n\tt := time.Now()\n\tp(t.Format(time.RFC3339))\n\n\t// Time parsing uses the same layout values as `Format`.\n\tt1, _ := time.Parse(time.RFC3339, \"2012-11-01T22:08:41+00:00\")\n\tp(t1)\n\n\t// `Format` and `Parse` use example-based layouts. Usually\n\t// you'll use a constant from `time` for these layouts, but\n\t// you can also supply custom layouts. Layouts must use the\n\t// reference time `Mon Jan 2 15:04:05 MST 2006` to show the\n\t// pattern with which to format/parse a given time/string.\n\t// The example time must be exactly as shown: the year 2006,\n\t// 15 for the hour, Monday for the day of the week, etc.\n\tp(t.Format(\"3:04PM\"))\n\tp(t.Format(\"Mon Jan _2 15:04:05 2006\"))\n\tp(t.Format(\"2006-01-02T15:04:05.999999-07:00\"))\n\tform := \"3 04 PM\"\n\tt2, _ := time.Parse(form, \"8 41 PM\")\n\tp(t2)\n\n\t// For purely numeric representations you can also\n\t// use standard string formatting with the extracted\n\t// components of the time value.\n\tfmt.Printf(\"%d-%02d-%02dT%02d:%02d:%02d-00:00\\n\",\n\t\tt.Year(), t.Month(), t.Day(),\n\t\tt.Hour(), t.Minute(), t.Second())\n\n\t// `Parse` will return an error on malformed input\n\t// explaining the parsing problem.\n\t_, err := time.Parse(\"Mon Jan _2 15:04:05 2006\", \"8:41PM\")\n\tp(err)\n}\n" }, { "path": "examples/time-formatting-parsing/time-formatting-parsing.hash", "content": "beec3e9eba00fffd88fd1f8b09fa9b38ed76974d\n0dgIUsTgEYs\n" }, { "path": "examples/time-formatting-parsing/time-formatting-parsing.sh", "content": "$ go run time-formatting-parsing.go \n2014-04-15T18:00:15-07:00\n2012-11-01 22:08:41 +0000 +0000\n6:00PM\nTue Apr 15 18:00:15 2014\n2014-04-15T18:00:15.161182-07:00\n0000-01-01 20:41:00 +0000 UTC\n2014-04-15T18:00:15-00:00\nparsing time \"8:41PM\" as \"Mon Jan _2 15:04:05 2006\": ...\n" }, { "path": "examples/timeouts/timeouts.go", "content": "// _Timeouts_ are important for programs that connect to\n// external resources or that otherwise need to bound\n// execution time. Implementing timeouts in Go is easy and\n// elegant thanks to channels and `select`.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"time\"\n)\n\nfunc main() {\n\n\t// For our example, suppose we're executing an external\n\t// call that returns its result on a channel `c1`\n\t// after 2s. Note that the channel is buffered, so the\n\t// send in the goroutine is nonblocking. This is a\n\t// common pattern to prevent goroutine leaks in case the\n\t// channel is never read.\n\tc1 := make(chan string, 1)\n\tgo func() {\n\t\ttime.Sleep(2 * time.Second)\n\t\tc1 <- \"result 1\"\n\t}()\n\n\t// Here's the `select` implementing a timeout.\n\t// `res := <-c1` awaits the result and `<-time.After`\n\t// awaits a value to be sent after the timeout of\n\t// 1s. Since `select` proceeds with the first\n\t// receive that's ready, we'll take the timeout case\n\t// if the operation takes more than the allowed 1s.\n\tselect {\n\tcase res := <-c1:\n\t\tfmt.Println(res)\n\tcase <-time.After(1 * time.Second):\n\t\tfmt.Println(\"timeout 1\")\n\t}\n\n\t// If we allow a longer timeout of 3s, then the receive\n\t// from `c2` will succeed and we'll print the result.\n\tc2 := make(chan string, 1)\n\tgo func() {\n\t\ttime.Sleep(2 * time.Second)\n\t\tc2 <- \"result 2\"\n\t}()\n\tselect {\n\tcase res := <-c2:\n\t\tfmt.Println(res)\n\tcase <-time.After(3 * time.Second):\n\t\tfmt.Println(\"timeout 2\")\n\t}\n}\n" }, { "path": "examples/timeouts/timeouts.hash", "content": "79963f30cb3ca93d559a409e3ded40c2bb64df66\ngyr0NbVKBVf\n" }, { "path": "examples/timeouts/timeouts.sh", "content": "# Running this program shows the first operation timing\n# out and the second succeeding.\n$ go run timeouts.go \ntimeout 1\nresult 2\n" }, { "path": "examples/timers/timers.go", "content": "// We often want to execute Go code at some point in the\n// future, or repeatedly at some interval. Go's built-in\n// _timer_ and _ticker_ features make both of these tasks\n// easy. We'll look first at timers and then\n// at [tickers](tickers).\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"time\"\n)\n\nfunc main() {\n\n\t// Timers represent a single event in the future. You\n\t// tell the timer how long you want to wait, and it\n\t// provides a channel that will be notified at that\n\t// time. This timer will wait 2 seconds.\n\ttimer1 := time.NewTimer(2 * time.Second)\n\n\t// The `<-timer1.C` blocks on the timer's channel `C`\n\t// until it sends a value indicating that the timer\n\t// fired.\n\t<-timer1.C\n\tfmt.Println(\"Timer 1 fired\")\n\n\t// If you just wanted to wait, you could have used\n\t// `time.Sleep`. One reason a timer may be useful is\n\t// that you can cancel the timer before it fires.\n\t// Here's an example of that.\n\ttimer2 := time.NewTimer(time.Second)\n\tgo func() {\n\t\t<-timer2.C\n\t\tfmt.Println(\"Timer 2 fired\")\n\t}()\n\tstop2 := timer2.Stop()\n\tif stop2 {\n\t\tfmt.Println(\"Timer 2 stopped\")\n\t}\n\n\t// Give the `timer2` enough time to fire, if it ever\n\t// was going to, to show it is in fact stopped.\n\ttime.Sleep(2 * time.Second)\n}\n" }, { "path": "examples/timers/timers.hash", "content": "36cae12a3ca529e473d7839e9573c3e0a202c2de\ngF7VLRz3URM\n" }, { "path": "examples/timers/timers.sh", "content": "# The first timer will fire ~2s after we start the\n# program, but the second should be stopped before it has\n# a chance to fire.\n$ go run timers.go\nTimer 1 fired\nTimer 2 stopped\n" }, { "path": "examples/url-parsing/url-parsing.go", "content": "// URLs provide a [uniform way to locate resources](https://adam.herokuapp.com/past/2010/3/30/urls_are_the_uniform_way_to_locate_resources/).\n// Here's how to parse URLs in Go.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"net\"\n\t\"net/url\"\n)\n\nfunc main() {\n\n\t// We'll parse this example URL, which includes a\n\t// scheme, authentication info, host, port, path,\n\t// query params, and query fragment.\n\ts := \"postgres://user:pass@host.com:5432/path?k=v#f\"\n\n\t// Parse the URL and ensure there are no errors.\n\tu, err := url.Parse(s)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\t// Accessing the scheme is straightforward.\n\tfmt.Println(u.Scheme)\n\n\t// `User` contains all authentication info; call\n\t// `Username` and `Password` on this for individual\n\t// values.\n\tfmt.Println(u.User)\n\tfmt.Println(u.User.Username())\n\tp, _ := u.User.Password()\n\tfmt.Println(p)\n\n\t// The `Host` contains both the hostname and the port,\n\t// if present. Use `SplitHostPort` to extract them.\n\tfmt.Println(u.Host)\n\thost, port, _ := net.SplitHostPort(u.Host)\n\tfmt.Println(host)\n\tfmt.Println(port)\n\n\t// Here we extract the `path` and the fragment after\n\t// the `#`.\n\tfmt.Println(u.Path)\n\tfmt.Println(u.Fragment)\n\n\t// To get query params in a string of `k=v` format,\n\t// use `RawQuery`. You can also parse query params\n\t// into a map. The parsed query param maps are from\n\t// strings to slices of strings, so index into `[0]`\n\t// if you only want the first value.\n\tfmt.Println(u.RawQuery)\n\tm, _ := url.ParseQuery(u.RawQuery)\n\tfmt.Println(m)\n\tfmt.Println(m[\"k\"][0])\n}\n" }, { "path": "examples/url-parsing/url-parsing.hash", "content": "7e77917c98bd88187b4fed2b8c988afdd0b0df7d\nfHTQn9X7l1B\n" }, { "path": "examples/url-parsing/url-parsing.sh", "content": "# Running our URL parsing program shows all the different\n# pieces that we extracted.\n$ go run url-parsing.go \npostgres\nuser:pass\nuser\npass\nhost.com:5432\nhost.com\n5432\n/path\nf\nk=v\nmap[k:[v]]\nv\n" }, { "path": "examples/values/values.go", "content": "// Go has various value types including strings,\n// integers, floats, booleans, etc. Here are a few\n// basic examples.\n\npackage main\n\nimport \"fmt\"\n\nfunc main() {\n\n\t// Strings, which can be added together with `+`.\n\tfmt.Println(\"go\" + \"lang\")\n\n\t// Integers and floats.\n\tfmt.Println(\"1+1 =\", 1+1)\n\tfmt.Println(\"7.0/3.0 =\", 7.0/3.0)\n\n\t// Booleans, with boolean operators as you'd expect.\n\tfmt.Println(true && false)\n\tfmt.Println(true || false)\n\tfmt.Println(!true)\n}\n" }, { "path": "examples/values/values.hash", "content": "476982956a689418d548148af5f17145de16f063\nYnVS3LZr8pk\n" }, { "path": "examples/values/values.sh", "content": "$ go run values.go\ngolang\n1+1 = 2\n7.0/3.0 = 2.3333333333333335\nfalse\ntrue\nfalse\n" }, { "path": "examples/variables/variables.go", "content": "// In Go, _variables_ are explicitly declared and used by\n// the compiler to e.g. check type-correctness of function\n// calls.\n\npackage main\n\nimport \"fmt\"\n\nfunc main() {\n\n\t// `var` declares 1 or more variables.\n\tvar a = \"initial\"\n\tfmt.Println(a)\n\n\t// You can declare multiple variables at once.\n\tvar b, c int = 1, 2\n\tfmt.Println(b, c)\n\n\t// Go will infer the type of initialized variables.\n\tvar d = true\n\tfmt.Println(d)\n\n\t// Variables declared without a corresponding\n\t// initialization are _zero-valued_. For example, the\n\t// zero value for an `int` is `0`.\n\tvar e int\n\tfmt.Println(e)\n\n\t// The `:=` syntax is shorthand for declaring and\n\t// initializing a variable, e.g. for\n\t// `var f string = \"apple\"` in this case.\n\t// This syntax is only available inside functions.\n\tf := \"apple\"\n\tfmt.Println(f)\n}\n" }, { "path": "examples/variables/variables.hash", "content": "9aeef52b289d7ad9b9ac79f129d4e49f956c60ef\nN5rWndIliJW\n" }, { "path": "examples/variables/variables.sh", "content": "$ go run variables.go\ninitial\n1 2\ntrue\n0\napple\n" }, { "path": "examples/variadic-functions/variadic-functions.go", "content": "// [_Variadic functions_](https://en.wikipedia.org/wiki/Variadic_function)\n// can be called with any number of trailing arguments.\n// For example, `fmt.Println` is a common variadic\n// function.\n\npackage main\n\nimport \"fmt\"\n\n// Here's a function that will take an arbitrary number\n// of `int`s as arguments.\nfunc sum(nums ...int) {\n\tfmt.Print(nums, \" \")\n\ttotal := 0\n\t// Within the function, the type of `nums` is\n\t// equivalent to `[]int`. We can call `len(nums)`,\n\t// iterate over it with `range`, etc.\n\tfor _, num := range nums {\n\t\ttotal += num\n\t}\n\tfmt.Println(total)\n}\n\nfunc main() {\n\n\t// Variadic functions can be called in the usual way\n\t// with individual arguments.\n\tsum(1, 2)\n\tsum(1, 2, 3)\n\n\t// If you already have multiple args in a slice,\n\t// apply them to a variadic function using\n\t// `func(slice...)` like this.\n\tnums := []int{1, 2, 3, 4}\n\tsum(nums...)\n}\n" }, { "path": "examples/variadic-functions/variadic-functions.hash", "content": "561184169a1b4c3d4970d496b282cc81016583d6\nglNdE8aKPNq\n" }, { "path": "examples/variadic-functions/variadic-functions.sh", "content": "$ go run variadic-functions.go \n[1 2] 3\n[1 2 3] 6\n[1 2 3 4] 10\n\n# Another key aspect of functions in Go is their ability\n# to form closures, which we'll look at next.\n" }, { "path": "examples/waitgroups/waitgroups.go", "content": "// To wait for multiple goroutines to finish, we can\n// use a *wait group*.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"sync\"\n\t\"time\"\n)\n\n// This is the function we'll run in every goroutine.\nfunc worker(id int) {\n\tfmt.Printf(\"Worker %d starting\\n\", id)\n\n\t// Sleep to simulate an expensive task.\n\ttime.Sleep(time.Second)\n\tfmt.Printf(\"Worker %d done\\n\", id)\n}\n\nfunc main() {\n\n\t// This WaitGroup is used to wait for all the\n\t// goroutines launched here to finish. Note: if a WaitGroup is\n\t// explicitly passed into functions, it should be done *by pointer*.\n\tvar wg sync.WaitGroup\n\n\t// Launch several goroutines using `WaitGroup.Go`\n\tfor i := 1; i <= 5; i++ {\n\t\twg.Go(func() {\n\t\t\tworker(i)\n\t\t})\n\t}\n\n\t// Block until all the goroutines started by `wg` are\n\t// done. A goroutine is done when the function it invokes\n\t// returns.\n\twg.Wait()\n\n\t// Note that this approach has no straightforward way\n\t// to propagate errors from workers. For more\n\t// advanced use cases, consider using the\n\t// [errgroup package](https://pkg.go.dev/golang.org/x/sync/errgroup).\n}\n" }, { "path": "examples/waitgroups/waitgroups.hash", "content": "97b564243e41a3a86f8c8417268fa942c05d881f\ncsaELahJTWt\n" }, { "path": "examples/waitgroups/waitgroups.sh", "content": "$ go run waitgroups.go\nWorker 5 starting\nWorker 3 starting\nWorker 4 starting\nWorker 1 starting\nWorker 2 starting\nWorker 4 done\nWorker 1 done\nWorker 2 done\nWorker 5 done\nWorker 3 done\n\n# The order of workers starting up and finishing\n# is likely to be different for each invocation.\n" }, { "path": "examples/worker-pools/worker-pools.go", "content": "// In this example we'll look at how to implement\n// a _worker pool_ using goroutines and channels.\n\npackage main\n\nimport (\n\t\"fmt\"\n\t\"time\"\n)\n\n// Here's the worker, of which we'll run several\n// concurrent instances. These workers will receive\n// work on the `jobs` channel and send the corresponding\n// results on `results`. We'll sleep a second per job to\n// simulate an expensive task.\nfunc worker(id int, jobs <-chan int, results chan<- int) {\n\tfor j := range jobs {\n\t\tfmt.Println(\"worker\", id, \"started job\", j)\n\t\ttime.Sleep(time.Second)\n\t\tfmt.Println(\"worker\", id, \"finished job\", j)\n\t\tresults <- j * 2\n\t}\n}\n\nfunc main() {\n\n\t// In order to use our pool of workers we need to send\n\t// them work and collect their results. We make 2\n\t// channels for this.\n\tconst numJobs = 5\n\tjobs := make(chan int, numJobs)\n\tresults := make(chan int, numJobs)\n\n\t// This starts up 3 workers, initially blocked\n\t// because there are no jobs yet.\n\tfor w := 1; w <= 3; w++ {\n\t\tgo worker(w, jobs, results)\n\t}\n\n\t// Here we send 5 `jobs` and then `close` that\n\t// channel to indicate that's all the work we have.\n\tfor j := 1; j <= numJobs; j++ {\n\t\tjobs <- j\n\t}\n\tclose(jobs)\n\n\t// Finally we collect all the results of the work.\n\t// This also ensures that the worker goroutines have\n\t// finished. An alternative way to wait for multiple\n\t// goroutines is to use a [WaitGroup](waitgroups).\n\tfor a := 1; a <= numJobs; a++ {\n\t\t<-results\n\t}\n}\n" }, { "path": "examples/worker-pools/worker-pools.hash", "content": "f6fd187061dfd0ae5ae8243efa3a6fcfa0777c84\nhiSJJsYZJKL\n" }, { "path": "examples/worker-pools/worker-pools.sh", "content": "# Our running program shows the 5 jobs being executed by\n# various workers. The program only takes about 2 seconds\n# despite doing about 5 seconds of total work because\n# there are 3 workers operating concurrently.\n$ time go run worker-pools.go \nworker 1 started job 1\nworker 2 started job 2\nworker 3 started job 3\nworker 1 finished job 1\nworker 1 started job 4\nworker 2 finished job 2\nworker 2 started job 5\nworker 3 finished job 3\nworker 1 finished job 4\nworker 2 finished job 5\n\nreal\t0m2.358s\n" }, { "path": "examples/writing-files/writing-files.go", "content": "// Writing files in Go follows similar patterns to the\n// ones we saw earlier for reading.\n\npackage main\n\nimport (\n\t\"bufio\"\n\t\"fmt\"\n\t\"os\"\n\t\"path/filepath\"\n)\n\nfunc check(e error) {\n\tif e != nil {\n\t\tpanic(e)\n\t}\n}\n\nfunc main() {\n\n\t// To start, here's how to dump a string (or just\n\t// bytes) into a file.\n\td1 := []byte(\"hello\\ngo\\n\")\n\tpath1 := filepath.Join(os.TempDir(), \"dat1\")\n\terr := os.WriteFile(path1, d1, 0644)\n\tcheck(err)\n\n\t// For more granular writes, open a file for writing.\n\tpath2 := filepath.Join(os.TempDir(), \"dat2\")\n\tf, err := os.Create(path2)\n\tcheck(err)\n\n\t// It's idiomatic to defer a `Close` immediately\n\t// after opening a file.\n\tdefer f.Close()\n\n\t// You can `Write` byte slices as you'd expect.\n\td2 := []byte{115, 111, 109, 101, 10}\n\tn2, err := f.Write(d2)\n\tcheck(err)\n\tfmt.Printf(\"wrote %d bytes\\n\", n2)\n\n\t// A `WriteString` is also available.\n\tn3, err := f.WriteString(\"writes\\n\")\n\tcheck(err)\n\tfmt.Printf(\"wrote %d bytes\\n\", n3)\n\n\t// Issue a `Sync` to flush writes to stable storage.\n\tf.Sync()\n\n\t// `bufio` provides buffered writers in addition\n\t// to the buffered readers we saw earlier.\n\tw := bufio.NewWriter(f)\n\tn4, err := w.WriteString(\"buffered\\n\")\n\tcheck(err)\n\tfmt.Printf(\"wrote %d bytes\\n\", n4)\n\n\t// Use `Flush` to ensure all buffered operations have\n\t// been applied to the underlying writer.\n\tw.Flush()\n\n}\n" }, { "path": "examples/writing-files/writing-files.hash", "content": "b93857561df33d0ed970d15e26f321627e770655\niuKQDnKfl2T\n" }, { "path": "examples/writing-files/writing-files.sh", "content": "# Try running the file-writing code.\n$ go run writing-files.go \nwrote 5 bytes\nwrote 7 bytes\nwrote 9 bytes\n\n# Then check the contents of the written files.\n$ cat /tmp/dat1\nhello\ngo\n$ cat /tmp/dat2\nsome\nwrites\nbuffered\n\n# Next we'll look at applying some of the file I/O ideas\n# we've just seen to the `stdin` and `stdout` streams.\n" }, { "path": "examples/xml/xml.go", "content": "// Go offers built-in support for XML and XML-like\n// formats with the `encoding/xml` package.\n\npackage main\n\nimport (\n\t\"encoding/xml\"\n\t\"fmt\"\n)\n\n// Plant will be mapped to XML. Similarly to the\n// JSON examples, field tags contain directives for the\n// encoder and decoder. Here we use some special features\n// of the XML package: the `XMLName` field name dictates\n// the name of the XML element representing this struct;\n// `id,attr` means that the `Id` field is an XML\n// _attribute_ rather than a nested element.\ntype Plant struct {\n\tXMLName xml.Name `xml:\"plant\"`\n\tId int `xml:\"id,attr\"`\n\tName string `xml:\"name\"`\n\tOrigin []string `xml:\"origin\"`\n}\n\nfunc (p Plant) String() string {\n\treturn fmt.Sprintf(\"Plant id=%v, name=%v, origin=%v\",\n\t\tp.Id, p.Name, p.Origin)\n}\n\nfunc main() {\n\tcoffee := &Plant{Id: 27, Name: \"Coffee\"}\n\tcoffee.Origin = []string{\"Ethiopia\", \"Brazil\"}\n\n\t// Emit XML representing our plant; using\n\t// `MarshalIndent` to produce a more\n\t// human-readable output.\n\tout, _ := xml.MarshalIndent(coffee, \" \", \" \")\n\tfmt.Println(string(out))\n\n\t// To add a generic XML header to the output, append\n\t// it explicitly.\n\tfmt.Println(xml.Header + string(out))\n\n\t// Use `Unmarshal` to parse a stream of bytes with XML\n\t// into a data structure. If the XML is malformed or\n\t// cannot be mapped onto Plant, a descriptive error\n\t// will be returned.\n\tvar p Plant\n\tif err := xml.Unmarshal(out, &p); err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Println(p)\n\n\ttomato := &Plant{Id: 81, Name: \"Tomato\"}\n\ttomato.Origin = []string{\"Mexico\", \"California\"}\n\n\t// The `parent>child>plant` field tag tells the encoder\n\t// to nest all `plant`s under `...`\n\ttype Nesting struct {\n\t\tXMLName xml.Name `xml:\"nesting\"`\n\t\tPlants []*Plant `xml:\"parent>child>plant\"`\n\t}\n\n\tnesting := &Nesting{}\n\tnesting.Plants = []*Plant{coffee, tomato}\n\n\tout, _ = xml.MarshalIndent(nesting, \" \", \" \")\n\tfmt.Println(string(out))\n}\n" }, { "path": "examples/xml/xml.hash", "content": "d64993474fdf0571436db63a82974d74932ba256\nvsP5mIrNJOG\n" }, { "path": "examples/xml/xml.sh", "content": "$ go run xml.go\n \n Coffee\n Ethiopia\n Brazil\n \n\n \n Coffee\n Ethiopia\n Brazil\n \nPlant id=27, name=Coffee, origin=[Ethiopia Brazil]\n \n \n \n \n Coffee\n Ethiopia\n Brazil\n \n \n Tomato\n Mexico\n California\n \n \n \n \n" }, { "path": "examples.txt", "content": "Hello World\nValues\nVariables\nConstants\nFor\nIf/Else\nSwitch\nArrays\nSlices\nMaps\nFunctions\nMultiple Return Values\nVariadic Functions\nClosures\nRecursion\nRange over Built-in Types\nPointers\nStrings and Runes\nStructs\nMethods\nInterfaces\nEnums\nStruct Embedding\nGenerics\nRange over Iterators\nErrors\nCustom Errors\nGoroutines\nChannels\nChannel Buffering\nChannel Synchronization\nChannel Directions\nSelect\nTimeouts\nNon-Blocking Channel Operations\nClosing Channels\nRange over Channels\nTimers\nTickers\nWorker Pools\nWaitGroups\nRate Limiting\nAtomic Counters\nMutexes\nStateful Goroutines\nSorting\nSorting by Functions\nPanic\nDefer\nRecover\nString Functions\nString Formatting\nText Templates\nRegular Expressions\nJSON\nXML\nTime\nEpoch\nTime Formatting / Parsing\nRandom Numbers\nNumber Parsing\nURL Parsing\nSHA256 Hashes\nBase64 Encoding\nReading Files\nWriting Files\nLine Filters\nFile Paths\nDirectories\nTemporary Files and Directories\nEmbed Directive\nTesting and Benchmarking\nCommand-Line Arguments\nCommand-Line Flags\nCommand-Line Subcommands\nEnvironment Variables\nLogging\nHTTP Client\nHTTP Server\nTCP Server\nContext\nSpawning Processes\nExec'ing Processes\nSignals\nExit\n" }, { "path": "go.mod", "content": "module github.com/mmcgrana/gobyexample\n\ngo 1.26.0\n\nrequire (\n\tgithub.com/alecthomas/chroma/v2 v2.10.0\n\tgithub.com/aws/aws-sdk-go-v2 v1.21.2\n\tgithub.com/aws/aws-sdk-go-v2/config v1.19.1\n\tgithub.com/aws/aws-sdk-go-v2/service/s3 v1.40.2\n\tgithub.com/russross/blackfriday/v2 v2.1.0\n)\n\nrequire (\n\tgithub.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.4.14 // indirect\n\tgithub.com/aws/aws-sdk-go-v2/credentials v1.13.43 // indirect\n\tgithub.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.13.13 // indirect\n\tgithub.com/aws/aws-sdk-go-v2/internal/configsources v1.1.43 // indirect\n\tgithub.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.4.37 // indirect\n\tgithub.com/aws/aws-sdk-go-v2/internal/ini v1.3.45 // indirect\n\tgithub.com/aws/aws-sdk-go-v2/internal/v4a v1.1.6 // indirect\n\tgithub.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.9.15 // indirect\n\tgithub.com/aws/aws-sdk-go-v2/service/internal/checksum v1.1.38 // indirect\n\tgithub.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.9.37 // indirect\n\tgithub.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.15.6 // indirect\n\tgithub.com/aws/aws-sdk-go-v2/service/sso v1.15.2 // indirect\n\tgithub.com/aws/aws-sdk-go-v2/service/ssooidc v1.17.3 // indirect\n\tgithub.com/aws/aws-sdk-go-v2/service/sts v1.23.2 // indirect\n\tgithub.com/aws/smithy-go v1.15.0 // indirect\n\tgithub.com/dlclark/regexp2 v1.10.0 // indirect\n)\n" }, { "path": "go.sum", "content": "github.com/alecthomas/assert/v2 v2.2.1 h1:XivOgYcduV98QCahG8T5XTezV5bylXe+lBxLG2K2ink=\ngithub.com/alecthomas/assert/v2 v2.2.1/go.mod h1:pXcQ2Asjp247dahGEmsZ6ru0UVwnkhktn7S0bBDLxvQ=\ngithub.com/alecthomas/chroma/v2 v2.10.0 h1:T2iQOCCt4pRmRMfL55gTodMtc7cU0y7lc1Jb8/mK/64=\ngithub.com/alecthomas/chroma/v2 v2.10.0/go.mod h1:4TQu7gdfuPjSh76j78ietmqh9LiurGF0EpseFXdKMBw=\ngithub.com/alecthomas/repr v0.2.0 h1:HAzS41CIzNW5syS8Mf9UwXhNH1J9aix/BvDRf1Ml2Yk=\ngithub.com/alecthomas/repr v0.2.0/go.mod h1:Fr0507jx4eOXV7AlPV6AVZLYrLIuIeSOWtW57eE/O/4=\ngithub.com/aws/aws-sdk-go-v2 v1.21.2 h1:+LXZ0sgo8quN9UOKXXzAWRT3FWd4NxeXWOZom9pE7GA=\ngithub.com/aws/aws-sdk-go-v2 v1.21.2/go.mod h1:ErQhvNuEMhJjweavOYhxVkn2RUx7kQXVATHrjKtxIpM=\ngithub.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.4.14 h1:Sc82v7tDQ/vdU1WtuSyzZ1I7y/68j//HJ6uozND1IDs=\ngithub.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.4.14/go.mod h1:9NCTOURS8OpxvoAVHq79LK81/zC78hfRWFn+aL0SPcY=\ngithub.com/aws/aws-sdk-go-v2/config v1.19.1 h1:oe3vqcGftyk40icfLymhhhNysAwk0NfiwkDi2GTPMXs=\ngithub.com/aws/aws-sdk-go-v2/config v1.19.1/go.mod h1:ZwDUgFnQgsazQTnWfeLWk5GjeqTQTL8lMkoE1UXzxdE=\ngithub.com/aws/aws-sdk-go-v2/credentials v1.13.43 h1:LU8vo40zBlo3R7bAvBVy/ku4nxGEyZe9N8MqAeFTzF8=\ngithub.com/aws/aws-sdk-go-v2/credentials v1.13.43/go.mod h1:zWJBz1Yf1ZtX5NGax9ZdNjhhI4rgjfgsyk6vTY1yfVg=\ngithub.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.13.13 h1:PIktER+hwIG286DqXyvVENjgLTAwGgoeriLDD5C+YlQ=\ngithub.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.13.13/go.mod h1:f/Ib/qYjhV2/qdsf79H3QP/eRE4AkVyEf6sk7XfZ1tg=\ngithub.com/aws/aws-sdk-go-v2/internal/configsources v1.1.43 h1:nFBQlGtkbPzp/NjZLuFxRqmT91rLJkgvsEQs68h962Y=\ngithub.com/aws/aws-sdk-go-v2/internal/configsources v1.1.43/go.mod h1:auo+PiyLl0n1l8A0e8RIeR8tOzYPfZZH/JNlrJ8igTQ=\ngithub.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.4.37 h1:JRVhO25+r3ar2mKGP7E0LDl8K9/G36gjlqca5iQbaqc=\ngithub.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.4.37/go.mod h1:Qe+2KtKml+FEsQF/DHmDV+xjtche/hwoF75EG4UlHW8=\ngithub.com/aws/aws-sdk-go-v2/internal/ini v1.3.45 h1:hze8YsjSh8Wl1rYa1CJpRmXP21BvOBuc76YhW0HsuQ4=\ngithub.com/aws/aws-sdk-go-v2/internal/ini v1.3.45/go.mod h1:lD5M20o09/LCuQ2mE62Mb/iSdSlCNuj6H5ci7tW7OsE=\ngithub.com/aws/aws-sdk-go-v2/internal/v4a v1.1.6 h1:wmGLw2i8ZTlHLw7a9ULGfQbuccw8uIiNr6sol5bFzc8=\ngithub.com/aws/aws-sdk-go-v2/internal/v4a v1.1.6/go.mod h1:Q0Hq2X/NuL7z8b1Dww8rmOFl+jzusKEcyvkKspwdpyc=\ngithub.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.9.15 h1:7R8uRYyXzdD71KWVCL78lJZltah6VVznXBazvKjfH58=\ngithub.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.9.15/go.mod h1:26SQUPcTNgV1Tapwdt4a1rOsYRsnBsJHLMPoxK2b0d8=\ngithub.com/aws/aws-sdk-go-v2/service/internal/checksum v1.1.38 h1:skaFGzv+3kA+v2BPKhuekeb1Hbb105+44r8ASC+q5SE=\ngithub.com/aws/aws-sdk-go-v2/service/internal/checksum v1.1.38/go.mod h1:epIZoRSSbRIwLPJU5F+OldHhwZPBdpDeQkRdCeY3+00=\ngithub.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.9.37 h1:WWZA/I2K4ptBS1kg0kV1JbBtG/umed0vwHRrmcr9z7k=\ngithub.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.9.37/go.mod h1:vBmDnwWXWxNPFRMmG2m/3MKOe+xEcMDo1tanpaWCcck=\ngithub.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.15.6 h1:9ulSU5ClouoPIYhDQdg9tpl83d5Yb91PXTKK+17q+ow=\ngithub.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.15.6/go.mod h1:lnc2taBsR9nTlz9meD+lhFZZ9EWY712QHrRflWpTcOA=\ngithub.com/aws/aws-sdk-go-v2/service/s3 v1.40.2 h1:Ll5/YVCOzRB+gxPqs2uD0R7/MyATC0w85626glSKmp4=\ngithub.com/aws/aws-sdk-go-v2/service/s3 v1.40.2/go.mod h1:Zjfqt7KhQK+PO1bbOsFNzKgaq7TcxzmEoDWN8lM0qzQ=\ngithub.com/aws/aws-sdk-go-v2/service/sso v1.15.2 h1:JuPGc7IkOP4AaqcZSIcyqLpFSqBWK32rM9+a1g6u73k=\ngithub.com/aws/aws-sdk-go-v2/service/sso v1.15.2/go.mod h1:gsL4keucRCgW+xA85ALBpRFfdSLH4kHOVSnLMSuBECo=\ngithub.com/aws/aws-sdk-go-v2/service/ssooidc v1.17.3 h1:HFiiRkf1SdaAmV3/BHOFZ9DjFynPHj8G/UIO1lQS+fk=\ngithub.com/aws/aws-sdk-go-v2/service/ssooidc v1.17.3/go.mod h1:a7bHA82fyUXOm+ZSWKU6PIoBxrjSprdLoM8xPYvzYVg=\ngithub.com/aws/aws-sdk-go-v2/service/sts v1.23.2 h1:0BkLfgeDjfZnZ+MhB3ONb01u9pwFYTCZVhlsSSBvlbU=\ngithub.com/aws/aws-sdk-go-v2/service/sts v1.23.2/go.mod h1:Eows6e1uQEsc4ZaHANmsPRzAKcVDrcmjjWiih2+HUUQ=\ngithub.com/aws/smithy-go v1.15.0 h1:PS/durmlzvAFpQHDs4wi4sNNP9ExsqZh6IlfdHXgKK8=\ngithub.com/aws/smithy-go v1.15.0/go.mod h1:Tg+OJXh4MB2R/uN61Ko2f6hTZwB/ZYGOtib8J3gBHzA=\ngithub.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=\ngithub.com/dlclark/regexp2 v1.10.0 h1:+/GIL799phkJqYW+3YbOd8LCcbHzT0Pbo8zl70MHsq0=\ngithub.com/dlclark/regexp2 v1.10.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=\ngithub.com/google/go-cmp v0.5.8 h1:e6P7q2lk1O+qJJb4BtCQXlK8vWEO8V1ZeuEdJNOqZyg=\ngithub.com/google/go-cmp v0.5.8/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=\ngithub.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUqJM=\ngithub.com/hexops/gotextdiff v1.0.3/go.mod h1:pSWU5MAI3yDq+fZBTazCSJysOMbxWL1BSow5/V2vxeg=\ngithub.com/jmespath/go-jmespath v0.4.0/go.mod h1:T8mJZnbsbmF+m6zOOFylbeCJqk5+pHWvzYPziyZiYoo=\ngithub.com/jmespath/go-jmespath/internal/testify v1.5.1/go.mod h1:L3OGu8Wl2/fWfCI6z80xFu9LTZmf1ZRjMHUOPmWr69U=\ngithub.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=\ngithub.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=\ngithub.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=\ngithub.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=\ngopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=\ngopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=\n" }, { "path": "public/404.html", "content": "\n\n \n \n Go by Example: Not Found\n \n \n \n
\n

Go by Example

\n

Sorry, we couldn't find that! Check out the home page?

\n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n\n" }, { "path": "public/arrays", "content": "\n\n \n \n Go by Example: Arrays\n \n \n \n \n
\n

Go by Example: Arrays

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

In Go, an array is a numbered sequence of elements of a\nspecific length. In typical Go code, slices are\nmuch more common; arrays are useful in some special\nscenarios.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n \n \n \n 
func main() {
\n
\n

Here we create an array a that will hold exactly\n5 ints. The type of elements and length are both\npart of the array’s type. By default an array is\nzero-valued, which for ints means 0s.

\n\n 		\n \n 
    var a [5]int\n    fmt.Println("emp:", a)
\n
\n

We can set a value at an index using the\narray[index] = value syntax, and get a value with\narray[index].

\n\n 		\n \n 
    a[4] = 100\n    fmt.Println("set:", a)\n    fmt.Println("get:", a[4])
\n
\n

The builtin len returns the length of an array.

\n\n 		\n \n 
    fmt.Println("len:", len(a))
\n
\n

Use this syntax to declare and initialize an array\nin one line.

\n\n 		\n \n 
    b := [5]int{1, 2, 3, 4, 5}\n    fmt.Println("dcl:", b)
\n
\n

You can also have the compiler count the number of\nelements for you with ...

\n\n 		\n \n 
    b = [...]int{1, 2, 3, 4, 5}\n    fmt.Println("dcl:", b)
\n
\n

If you specify the index with :, the elements in\nbetween will be zeroed.

\n\n 		\n \n 
    b = [...]int{100, 3: 400, 500}\n    fmt.Println("idx:", b)
\n
\n

Array types are one-dimensional, but you can\ncompose types to build multi-dimensional data\nstructures.

\n\n 		\n \n 
    var twoD [2][3]int\n    for i := range 2 {\n        for j := range 3 {\n            twoD[i][j] = i + j\n        }\n    }\n    fmt.Println("2d: ", twoD)
\n
\n

You can create and initialize multi-dimensional\narrays at once too.

\n\n 		\n \n 
    twoD = [2][3]int{\n        {1, 2, 3},\n        {1, 2, 3},\n    }\n    fmt.Println("2d: ", twoD)\n}
\n
\n \n \n \n \n \n \n \n \n
\n

Note that arrays appear in the form [v1 v2 v3 ...]\nwhen printed with fmt.Println.

\n\n 		\n \n 
$ go run arrays.go\nemp: [0 0 0 0 0]\nset: [0 0 0 0 100]\nget: 100\nlen: 5\ndcl: [1 2 3 4 5]\ndcl: [1 2 3 4 5]\nidx: [100 0 0 400 500]\n2d:  [[0 1 2] [1 2 3]]\n2d:  [[1 2 3] [1 2 3]]
\n
\n \n \n

\n Next example: Slices.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/atomic-counters", "content": "\n\n \n \n Go by Example: Atomic Counters\n \n \n \n \n
\n

Go by Example: Atomic Counters

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

The primary mechanism for managing state in Go is\ncommunication over channels. We saw this for example\nwith worker pools. There are a few other\noptions for managing state though. Here we’ll\nlook at using the sync/atomic package for atomic\ncounters accessed by multiple goroutines.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "sync"\n    "sync/atomic"\n)
\n
\n \n \n \n 
func main() {
\n
\n

We’ll use an atomic integer type to represent our\n(always-positive) counter.

\n\n 		\n \n 
    var ops atomic.Uint64
\n
\n

A WaitGroup will help us wait for all goroutines\nto finish their work.

\n\n 		\n \n 
    var wg sync.WaitGroup
\n
\n

We’ll start 50 goroutines that each increment the\ncounter exactly 1000 times.

\n\n 		\n \n 
    for range 50 {\n        wg.Go(func() {\n            for range 1000 {
\n
\n

To atomically increment the counter we use Add.

\n\n 		\n \n 
                ops.Add(1)\n            }\n        })\n    }
\n
\n

Wait until all the goroutines are done.

\n\n 		\n \n 
    wg.Wait()
\n
\n

Here no goroutines are writing to ‘ops’, but using\nLoad it’s safe to atomically read a value even while\nother goroutines are (atomically) updating it.

\n\n 		\n \n 
    fmt.Println("ops:", ops.Load())\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

We expect to get exactly 50,000 operations. Had we\nused a non-atomic integer and incremented it with\nops++, we’d likely get a different number,\nchanging between runs, because the goroutines\nwould interfere with each other. Moreover, we’d\nget data race failures when running with the\n-race flag.

\n\n 		\n \n 
$ go run atomic-counters.go\nops: 50000
\n
\n

Next we’ll look at mutexes, another tool for managing\nstate.

\n\n 		\n \n \n
\n \n \n

\n Next example: Mutexes.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/base64-encoding", "content": "\n\n \n \n Go by Example: Base64 Encoding\n \n \n \n \n
\n

Go by Example: Base64 Encoding

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go provides built-in support for base64\nencoding/decoding.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n

This syntax imports the encoding/base64 package with\nthe b64 name instead of the default base64. It’ll\nsave us some space below.

\n\n 		\n \n 
import (\n    b64 "encoding/base64"\n    "fmt"\n)
\n
\n \n \n \n 
func main() {
\n
\n

Here’s the string we’ll encode/decode.

\n\n 		\n \n 
    data := "abc123!?$*&()'-=@~"
\n
\n

Go supports both standard and URL-compatible\nbase64. Here’s how to encode using the standard\nencoder. The encoder requires a []byte so we\nconvert our string to that type.

\n\n 		\n \n 
    sEnc := b64.StdEncoding.EncodeToString([]byte(data))\n    fmt.Println(sEnc)
\n
\n

Decoding may return an error, which you can check\nif you don’t already know the input to be\nwell-formed.

\n\n 		\n \n 
    sDec, _ := b64.StdEncoding.DecodeString(sEnc)\n    fmt.Println(string(sDec))\n    fmt.Println()
\n
\n

This encodes/decodes using a URL-compatible base64\nformat.

\n\n 		\n \n 
    uEnc := b64.URLEncoding.EncodeToString([]byte(data))\n    fmt.Println(uEnc)\n    uDec, _ := b64.URLEncoding.DecodeString(uEnc)\n    fmt.Println(string(uDec))\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

The string encodes to slightly different values with the\nstandard and URL base64 encoders (trailing + vs -)\nbut they both decode to the original string as desired.

\n\n 		\n \n 
$ go run base64-encoding.go\nYWJjMTIzIT8kKiYoKSctPUB+\nabc123!?$*&()'-=@~
\n
\n \n \n \n 
YWJjMTIzIT8kKiYoKSctPUB-\nabc123!?$*&()'-=@~
\n
\n \n \n

\n Next example: Reading Files.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/channel-buffering", "content": "\n\n \n \n Go by Example: Channel Buffering\n \n \n \n \n
\n

Go by Example: Channel Buffering

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

By default channels are unbuffered, meaning that they\nwill only accept sends (chan <-) if there is a\ncorresponding receive (<- chan) ready to receive the\nsent value. Buffered channels accept a limited\nnumber of values without a corresponding receiver for\nthose values.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n \n \n \n 
func main() {
\n
\n

Here we make a channel of strings buffering up to\n2 values.

\n\n 		\n \n 
    messages := make(chan string, 2)
\n
\n

Because this channel is buffered, we can send these\nvalues into the channel without a corresponding\nconcurrent receive.

\n\n 		\n \n 
    messages <- "buffered"\n    messages <- "channel"
\n
\n

Later we can receive these two values as usual.

\n\n 		\n \n 
    fmt.Println(<-messages)\n    fmt.Println(<-messages)\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run channel-buffering.go \nbuffered\nchannel
\n
\n \n \n

\n Next example: Channel Synchronization.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/channel-directions", "content": "\n\n \n \n Go by Example: Channel Directions\n \n \n \n \n
\n

Go by Example: Channel Directions

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

When using channels as function parameters, you can\nspecify if a channel is meant to only send or receive\nvalues. This specificity increases the type-safety of\nthe program.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n

This ping function only accepts a channel for sending\nvalues. It would be a compile-time error to try to\nreceive on this channel.

\n\n 		\n \n 
func ping(pings chan<- string, msg string) {\n    pings <- msg\n}
\n
\n

The pong function accepts one channel for receives\n(pings) and a second for sends (pongs).

\n\n 		\n \n 
func pong(pings <-chan string, pongs chan<- string) {\n    msg := <-pings\n    pongs <- msg\n}
\n
\n \n \n \n 
func main() {\n    pings := make(chan string, 1)\n    pongs := make(chan string, 1)\n    ping(pings, "passed message")\n    pong(pings, pongs)\n    fmt.Println(<-pongs)\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run channel-directions.go\npassed message
\n
\n \n \n

\n Next example: Select.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/channel-synchronization", "content": "\n\n \n \n Go by Example: Channel Synchronization\n \n \n \n \n
\n

Go by Example: Channel Synchronization

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

We can use channels to synchronize execution\nacross goroutines. Here’s an example of using a\nblocking receive to wait for a goroutine to finish.\nWhen waiting for multiple goroutines to finish,\nyou may prefer to use a WaitGroup.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "time"\n)
\n
\n

This is the function we’ll run in a goroutine. The\ndone channel will be used to notify another\ngoroutine that this function’s work is done.

\n\n 		\n \n 
func worker(done chan bool) {\n    fmt.Print("working...")\n    time.Sleep(time.Second)\n    fmt.Println("done")
\n
\n

Send a value to notify that we’re done.

\n\n 		\n \n 
    done <- true\n}
\n
\n \n \n \n 
func main() {
\n
\n

Start a worker goroutine, giving it the channel to\nnotify on.

\n\n 		\n \n 
    done := make(chan bool, 1)\n    go worker(done)
\n
\n

Block until we receive a notification from the\nworker on the channel.

\n\n 		\n \n 
    <-done\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run channel-synchronization.go      \nworking...done
\n
\n

If you removed the <- done line from this program,\nthe program could exit before the worker finished\nits work, or in some cases even before it started.

\n\n 		\n \n \n
\n \n \n

\n Next example: Channel Directions.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/channels", "content": "\n\n \n \n Go by Example: Channels\n \n \n \n \n
\n

Go by Example: Channels

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Channels are the pipes that connect concurrent\ngoroutines. You can send values into channels from one\ngoroutine and receive those values into another\ngoroutine.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n \n \n \n 
func main() {
\n
\n

Create a new channel with make(chan val-type).\nChannels are typed by the values they convey.

\n\n 		\n \n 
    messages := make(chan string)
\n
\n

Send a value into a channel using the channel <-\nsyntax. Here we send "ping" to the messages\nchannel we made above, from a new goroutine.

\n\n 		\n \n 
    go func() { messages <- "ping" }()
\n
\n

The <-channel syntax receives a value from the\nchannel. Here we’ll receive the "ping" message\nwe sent above and print it out.

\n\n 		\n \n 
    msg := <-messages\n    fmt.Println(msg)\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

When we run the program the "ping" message is\nsuccessfully passed from one goroutine to another via\nour channel.

\n\n 		\n \n 
$ go run channels.go \nping
\n
\n

By default sends and receives block until both the\nsender and receiver are ready. This property allowed\nus to wait at the end of our program for the "ping"\nmessage without having to use any other synchronization.

\n\n 		\n \n \n
\n \n \n

\n Next example: Channel Buffering.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/closing-channels", "content": "\n\n \n \n Go by Example: Closing Channels\n \n \n \n \n
\n

Go by Example: Closing Channels

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Closing a channel indicates that no more values\nwill be sent on it. This can be useful to communicate\ncompletion to the channel’s receivers.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n

In this example we’ll use a jobs channel to\ncommunicate work to be done from the main() goroutine\nto a worker goroutine. When we have no more jobs for\nthe worker we’ll close the jobs channel.

\n\n 		\n \n 
func main() {\n    jobs := make(chan int, 5)\n    done := make(chan bool)
\n
\n

Here’s the worker goroutine. It repeatedly receives\nfrom jobs with j, more := <-jobs. In this\nspecial 2-value form of receive, the more value\nwill be false if jobs has been closed and all\nvalues in the channel have already been received.\nWe use this to notify on done when we’ve worked\nall our jobs.

\n\n 		\n \n 
    go func() {\n        for {\n            j, more := <-jobs\n            if more {\n                fmt.Println("received job", j)\n            } else {\n                fmt.Println("received all jobs")\n                done <- true\n                return\n            }\n        }\n    }()
\n
\n

This sends 3 jobs to the worker over the jobs\nchannel, then closes it.

\n\n 		\n \n 
    for j := 1; j <= 3; j++ {\n        jobs <- j\n        fmt.Println("sent job", j)\n    }\n    close(jobs)\n    fmt.Println("sent all jobs")
\n
\n

We await the worker using the\nsynchronization approach\nwe saw earlier.

\n\n 		\n \n 
    <-done
\n
\n

Reading from a closed channel succeeds immediately,\nreturning the zero value of the underlying type.\nThe optional second return value is true if the\nvalue received was delivered by a successful send\noperation to the channel, or false if it was a\nzero value generated because the channel is closed\nand empty.

\n\n 		\n \n 
    _, ok := <-jobs\n    fmt.Println("received more jobs:", ok)\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run closing-channels.go \nsent job 1\nreceived job 1\nsent job 2\nreceived job 2\nsent job 3\nreceived job 3\nsent all jobs\nreceived all jobs\nreceived more jobs: false
\n
\n

The idea of closed channels leads naturally to our next\nexample: range over channels.

\n\n 		\n \n \n
\n \n \n

\n Next example: Range over Channels.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/closures", "content": "\n\n \n \n Go by Example: Closures\n \n \n \n \n
\n

Go by Example: Closures

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go supports anonymous functions,\nwhich can form closures.\nAnonymous functions are useful when you want to define\na function inline without having to name it.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n

This function intSeq returns another function, which\nwe define anonymously in the body of intSeq. The\nreturned function closes over the variable i to\nform a closure.

\n\n 		\n \n 
func intSeq() func() int {\n    i := 0\n    return func() int {\n        i++\n        return i\n    }\n}
\n
\n \n \n \n 
func main() {
\n
\n

We call intSeq, assigning the result (a function)\nto nextInt. This function value captures its\nown i value, which will be updated each time\nwe call nextInt.

\n\n 		\n \n 
    nextInt := intSeq()
\n
\n

See the effect of the closure by calling nextInt\na few times.

\n\n 		\n \n 
    fmt.Println(nextInt())\n    fmt.Println(nextInt())\n    fmt.Println(nextInt())
\n
\n

To confirm that the state is unique to that\nparticular function, create and test a new one.

\n\n 		\n \n 
    newInts := intSeq()\n    fmt.Println(newInts())\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run closures.go\n1\n2\n3\n1
\n
\n

The last feature of functions we’ll look at for now is\nrecursion.

\n\n 		\n \n \n
\n \n \n

\n Next example: Recursion.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/command-line-arguments", "content": "\n\n \n \n Go by Example: Command-Line Arguments\n \n \n \n \n
\n

Go by Example: Command-Line Arguments

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Command-line arguments\nare a common way to parameterize execution of programs.\nFor example, go run hello.go uses run and\nhello.go arguments to the go program.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "os"\n)
\n
\n \n \n \n 
func main() {
\n
\n

os.Args provides access to raw command-line\narguments. Note that the first value in this slice\nis the path to the program, and os.Args[1:]\nholds the arguments to the program.

\n\n 		\n \n 
    argsWithProg := os.Args\n    argsWithoutProg := os.Args[1:]
\n
\n

You can get individual args with normal indexing.

\n\n 		\n \n 
    arg := os.Args[3]
\n
\n \n \n \n 
    fmt.Println(argsWithProg)\n    fmt.Println(argsWithoutProg)\n    fmt.Println(arg)\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

To experiment with command-line arguments it’s best to\nbuild a binary with go build first.

\n\n 		\n \n 
$ go build command-line-arguments.go\n$ ./command-line-arguments a b c d\n[./command-line-arguments a b c d]       \n[a b c d]\nc
\n
\n

Next we’ll look at more advanced command-line processing\nwith flags.

\n\n 		\n \n \n
\n \n \n

\n Next example: Command-Line Flags.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/command-line-flags", "content": "\n\n \n \n Go by Example: Command-Line Flags\n \n \n \n \n
\n

Go by Example: Command-Line Flags

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Command-line flags\nare a common way to specify options for command-line\nprograms. For example, in wc -l the -l is a\ncommand-line flag.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n

Go provides a flag package supporting basic\ncommand-line flag parsing. We’ll use this package to\nimplement our example command-line program.

\n\n 		\n \n 
import (\n    "flag"\n    "fmt"\n)
\n
\n \n \n \n 
func main() {
\n
\n

Basic flag declarations are available for string,\ninteger, and boolean options. Here we declare a\nstring flag word with a default value "foo"\nand a short description. This flag.String function\nreturns a string pointer (not a string value);\nwe’ll see how to use this pointer below.

\n\n 		\n \n 
    wordPtr := flag.String("word", "foo", "a string")
\n
\n

This declares numb and fork flags, using a\nsimilar approach to the word flag.

\n\n 		\n \n 
    numbPtr := flag.Int("numb", 42, "an int")\n    forkPtr := flag.Bool("fork", false, "a bool")
\n
\n

It’s also possible to declare an option that uses an\nexisting var declared elsewhere in the program.\nNote that we need to pass in a pointer to the flag\ndeclaration function.

\n\n 		\n \n 
    var svar string\n    flag.StringVar(&svar, "svar", "bar", "a string var")
\n
\n

Once all flags are declared, call flag.Parse()\nto execute the command-line parsing.

\n\n 		\n \n 
    flag.Parse()
\n
\n

Here we’ll just dump out the parsed options and\nany trailing positional arguments. Note that we\nneed to dereference the pointers with e.g. *wordPtr\nto get the actual option values.

\n\n 		\n \n 
    fmt.Println("word:", *wordPtr)\n    fmt.Println("numb:", *numbPtr)\n    fmt.Println("fork:", *forkPtr)\n    fmt.Println("svar:", svar)\n    fmt.Println("tail:", flag.Args())\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

To experiment with the command-line flags program it’s\nbest to first compile it and then run the resulting\nbinary directly.

\n\n 		\n \n 
$ go build command-line-flags.go
\n
\n

Try out the built program by first giving it values for\nall flags.

\n\n 		\n \n 
$ ./command-line-flags -word=opt -numb=7 -fork -svar=flag\nword: opt\nnumb: 7\nfork: true\nsvar: flag\ntail: []
\n
\n

Note that if you omit flags they automatically take\ntheir default values.

\n\n 		\n \n 
$ ./command-line-flags -word=opt\nword: opt\nnumb: 42\nfork: false\nsvar: bar\ntail: []
\n
\n

Trailing positional arguments can be provided after\nany flags.

\n\n 		\n \n 
$ ./command-line-flags -word=opt a1 a2 a3\nword: opt\n...\ntail: [a1 a2 a3]
\n
\n

Note that the flag package requires all flags to\nappear before positional arguments (otherwise the flags\nwill be interpreted as positional arguments).

\n\n 		\n \n 
$ ./command-line-flags -word=opt a1 a2 a3 -numb=7\nword: opt\nnumb: 42\nfork: false\nsvar: bar\ntail: [a1 a2 a3 -numb=7]
\n
\n

Use -h or --help flags to get automatically\ngenerated help text for the command-line program.

\n\n 		\n \n 
$ ./command-line-flags -h\nUsage of ./command-line-flags:\n  -fork=false: a bool\n  -numb=42: an int\n  -svar="bar": a string var\n  -word="foo": a string
\n
\n

If you provide a flag that wasn’t specified to the\nflag package, the program will print an error message\nand show the help text again.

\n\n 		\n \n 
$ ./command-line-flags -wat\nflag provided but not defined: -wat\nUsage of ./command-line-flags:\n...
\n
\n \n \n

\n Next example: Command-Line Subcommands.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/command-line-subcommands", "content": "\n\n \n \n Go by Example: Command-Line Subcommands\n \n \n \n \n
\n

Go by Example: Command-Line Subcommands

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Some command-line tools, like the go tool or git\nhave many subcommands, each with its own set of\nflags. For example, go build and go get are two\ndifferent subcommands of the go tool.\nThe flag package lets us easily define simple\nsubcommands that have their own flags.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "flag"\n    "fmt"\n    "os"\n)
\n
\n \n \n \n 
func main() {
\n
\n

We declare a subcommand using the NewFlagSet\nfunction, and proceed to define new flags specific\nfor this subcommand.

\n\n 		\n \n 
    fooCmd := flag.NewFlagSet("foo", flag.ExitOnError)\n    fooEnable := fooCmd.Bool("enable", false, "enable")\n    fooName := fooCmd.String("name", "", "name")
\n
\n

For a different subcommand we can define different\nsupported flags.

\n\n 		\n \n 
    barCmd := flag.NewFlagSet("bar", flag.ExitOnError)\n    barLevel := barCmd.Int("level", 0, "level")
\n
\n

The subcommand is expected as the first argument\nto the program.

\n\n 		\n \n 
    if len(os.Args) < 2 {\n        fmt.Println("expected 'foo' or 'bar' subcommands")\n        os.Exit(1)\n    }
\n
\n

Check which subcommand is invoked.

\n\n 		\n \n 
    switch os.Args[1] {
\n
\n

For every subcommand, we parse its own flags and\nhave access to trailing positional arguments.

\n\n 		\n \n 
    case "foo":\n        fooCmd.Parse(os.Args[2:])\n        fmt.Println("subcommand 'foo'")\n        fmt.Println("  enable:", *fooEnable)\n        fmt.Println("  name:", *fooName)\n        fmt.Println("  tail:", fooCmd.Args())\n    case "bar":\n        barCmd.Parse(os.Args[2:])\n        fmt.Println("subcommand 'bar'")\n        fmt.Println("  level:", *barLevel)\n        fmt.Println("  tail:", barCmd.Args())\n    default:\n        fmt.Println("expected 'foo' or 'bar' subcommands")\n        os.Exit(1)\n    }\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go build command-line-subcommands.go
\n
\n

First invoke the foo subcommand.

\n\n 		\n \n 
$ ./command-line-subcommands foo -enable -name=joe a1 a2\nsubcommand 'foo'\n  enable: true\n  name: joe\n  tail: [a1 a2]
\n
\n

Now try bar.

\n\n 		\n \n 
$ ./command-line-subcommands bar -level 8 a1\nsubcommand 'bar'\n  level: 8\n  tail: [a1]
\n
\n

But bar won’t accept foo’s flags.

\n\n 		\n \n 
$ ./command-line-subcommands bar -enable a1\nflag provided but not defined: -enable\nUsage of bar:\n  -level int\n        level
\n
\n

Next we’ll look at environment variables, another common\nway to parameterize programs.

\n\n 		\n \n \n
\n \n \n

\n Next example: Environment Variables.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/constants", "content": "\n\n \n \n Go by Example: Constants\n \n \n \n \n
\n

Go by Example: Constants

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go supports constants of character, string, boolean,\nand numeric values.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "math"\n)
\n
\n

const declares a constant value.

\n\n 		\n \n 
const s string = "constant"
\n
\n \n \n \n 
func main() {\n    fmt.Println(s)
\n
\n

A const statement can also appear inside a\nfunction body.

\n\n 		\n \n 
    const n = 500000000
\n
\n

Constant expressions perform arithmetic with\narbitrary precision.

\n\n 		\n \n 
    const d = 3e20 / n\n    fmt.Println(d)
\n
\n

A numeric constant has no type until it’s given\none, such as by an explicit conversion.

\n\n 		\n \n 
    fmt.Println(int64(d))
\n
\n

A number can be given a type by using it in a\ncontext that requires one, such as a variable\nassignment or function call. For example, here\nmath.Sin expects a float64.

\n\n 		\n \n 
    fmt.Println(math.Sin(n))\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run constant.go \nconstant\n6e+11\n600000000000\n-0.28470407323754404
\n
\n \n \n

\n Next example: For.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/context", "content": "\n\n \n \n Go by Example: Context\n \n \n \n \n
\n

Go by Example: Context

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

In the previous example we looked at setting up a simple\nHTTP server. HTTP servers are useful for\ndemonstrating the usage of context.Context for\ncontrolling cancellation. A Context carries deadlines,\ncancellation signals, and other request-scoped values\nacross API boundaries and goroutines.

\n\n 		\n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "net/http"\n    "time"\n)
\n
\n \n \n \n 
func hello(w http.ResponseWriter, req *http.Request) {
\n
\n

A context.Context is created for each request by\nthe net/http machinery, and is available with\nthe Context() method.

\n\n 		\n \n 
    ctx := req.Context()\n    fmt.Println("server: hello handler started")\n    defer fmt.Println("server: hello handler ended")
\n
\n

Wait for a few seconds before sending a reply to the\nclient. This could simulate some work the server is\ndoing. While working, keep an eye on the context’s\nDone() channel for a signal that we should cancel\nthe work and return as soon as possible.

\n\n 		\n \n 
    select {\n    case <-time.After(10 * time.Second):\n        fmt.Fprintf(w, "hello\\n")\n    case <-ctx.Done():
\n
\n

The context’s Err() method returns an error\nthat explains why the Done() channel was\nclosed.

\n\n 		\n \n 
        err := ctx.Err()\n        fmt.Println("server:", err)\n        internalError := http.StatusInternalServerError\n        http.Error(w, err.Error(), internalError)\n    }\n}
\n
\n \n \n \n 
func main() {
\n
\n

As before, we register our handler on the “/hello”\nroute, and start serving.

\n\n 		\n \n 
    http.HandleFunc("/hello", hello)\n    http.ListenAndServe(":8090", nil)\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Run the server in the background.

\n\n 		\n \n 
$ go run context.go &
\n
\n

Simulate a client request to /hello, hitting\nCtrl+C shortly after starting to signal\ncancellation.

\n\n 		\n \n 
$ curl localhost:8090/hello\nserver: hello handler started\n^C\nserver: context canceled\nserver: hello handler ended
\n
\n \n \n

\n Next example: Spawning Processes.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/custom-errors", "content": "\n\n \n \n Go by Example: Custom Errors\n \n \n \n \n
\n

Go by Example: Custom Errors

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

It’s possible to define custom error types by\nimplementing the Error() method on them. Here’s a\nvariant on the example above that uses a custom type\nto explicitly represent an argument error.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "errors"\n    "fmt"\n)
\n
\n

A custom error type usually has the suffix “Error”.

\n\n 		\n \n 
type argError struct {\n    arg     int\n    message string\n}
\n
\n

Adding this Error method makes argError implement\nthe error interface.

\n\n 		\n \n 
func (e *argError) Error() string {\n    return fmt.Sprintf("%d - %s", e.arg, e.message)\n}
\n
\n \n \n \n 
func f(arg int) (int, error) {\n    if arg == 42 {
\n
\n

Return our custom error.

\n\n 		\n \n 
        return -1, &argError{arg, "can't work with it"}\n    }\n    return arg + 3, nil\n}
\n
\n \n \n \n 
func main() {
\n
\n

errors.AsType is a more advanced version of errors.Is.\nIt checks that a given error (or any error in its chain)\nmatches a specific error type and converts to a value\nof that type, also returning true. If there’s no match, the\nsecond return value is false.

\n\n 		\n \n 
    _, err := f(42)\n    if ae, ok := errors.AsType[*argError](err); ok {\n        fmt.Println(ae.arg)\n        fmt.Println(ae.message)\n    } else {\n        fmt.Println("err doesn't match argError")\n    }\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run custom-errors.go\n42\ncan't work with it
\n
\n \n \n

\n Next example: Goroutines.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/defer", "content": "\n\n \n \n Go by Example: Defer\n \n \n \n \n
\n

Go by Example: Defer

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Defer is used to ensure that a function call is\nperformed later in a program’s execution, usually for\npurposes of cleanup. defer is often used where e.g.\nensure and finally would be used in other languages.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "os"\n    "path/filepath"\n)
\n
\n

Suppose we wanted to create a file, write to it,\nand then close when we’re done. Here’s how we could\ndo that with defer.

\n\n 		\n \n 
func main() {
\n
\n

Immediately after getting a file object with\ncreateFile, we defer the closing of that file\nwith closeFile. This will be executed at the end\nof the enclosing function (main), after\nwriteFile has finished.

\n\n 		\n \n 
    path := filepath.Join(os.TempDir(), "defer.txt")\n    f := createFile(path)\n    defer closeFile(f)\n    writeFile(f)\n}
\n
\n \n \n \n 
func createFile(p string) *os.File {\n    fmt.Println("creating")\n    f, err := os.Create(p)\n    if err != nil {\n        panic(err)\n    }\n    return f\n}
\n
\n \n \n \n 
func writeFile(f *os.File) {\n    fmt.Println("writing")\n    fmt.Fprintln(f, "data")\n}
\n
\n

It’s important to check for errors when closing a\nfile, even in a deferred function.

\n\n 		\n \n 
func closeFile(f *os.File) {\n    fmt.Println("closing")\n    err := f.Close()
\n
\n \n \n \n 
    if err != nil {\n        panic(err)\n    }\n}
\n
\n \n \n \n \n \n \n \n \n
\n

Running the program confirms that the file is closed\nafter being written.

\n\n 		\n \n 
$ go run defer.go\ncreating\nwriting\nclosing
\n
\n \n \n

\n Next example: Recover.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/directories", "content": "\n\n \n \n Go by Example: Directories\n \n \n \n \n
\n

Go by Example: Directories

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go has several useful functions for working with\ndirectories in the file system.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "io/fs"\n    "os"\n    "path/filepath"\n)
\n
\n \n \n \n 
func check(e error) {\n    if e != nil {\n        panic(e)\n    }\n}
\n
\n \n \n \n 
func main() {
\n
\n

Create a new sub-directory in the current working\ndirectory.

\n\n 		\n \n 
    err := os.Mkdir("subdir", 0755)\n    check(err)
\n
\n

When creating temporary directories, it’s good\npractice to defer their removal. os.RemoveAll\nwill delete a whole directory tree (similarly to\nrm -rf).

\n\n 		\n \n 
    defer os.RemoveAll("subdir")
\n
\n

Helper function to create a new empty file.

\n\n 		\n \n 
    createEmptyFile := func(name string) {\n        d := []byte("")\n        check(os.WriteFile(name, d, 0644))\n    }
\n
\n \n \n \n 
    createEmptyFile("subdir/file1")
\n
\n

We can create a hierarchy of directories, including\nparents with MkdirAll. This is similar to the\ncommand-line mkdir -p.

\n\n 		\n \n 
    err = os.MkdirAll("subdir/parent/child", 0755)\n    check(err)
\n
\n \n \n \n 
    createEmptyFile("subdir/parent/file2")\n    createEmptyFile("subdir/parent/file3")\n    createEmptyFile("subdir/parent/child/file4")
\n
\n

ReadDir lists directory contents, returning a\nslice of os.DirEntry objects.

\n\n 		\n \n 
    c, err := os.ReadDir("subdir/parent")\n    check(err)
\n
\n \n \n \n 
    fmt.Println("Listing subdir/parent")\n    for _, entry := range c {\n        fmt.Println(" ", entry.Name(), entry.IsDir())\n    }
\n
\n

Chdir lets us change the current working directory,\nsimilarly to cd.

\n\n 		\n \n 
    err = os.Chdir("subdir/parent/child")\n    check(err)
\n
\n

Now we’ll see the contents of subdir/parent/child\nwhen listing the current directory.

\n\n 		\n \n 
    c, err = os.ReadDir(".")\n    check(err)
\n
\n \n \n \n 
    fmt.Println("Listing subdir/parent/child")\n    for _, entry := range c {\n        fmt.Println(" ", entry.Name(), entry.IsDir())\n    }
\n
\n

cd back to where we started.

\n\n 		\n \n 
    err = os.Chdir("../../..")\n    check(err)
\n
\n

We can also visit a directory recursively,\nincluding all its sub-directories. WalkDir accepts\na callback function to handle every file or\ndirectory visited.

\n\n 		\n \n 
    fmt.Println("Visiting subdir")\n    err = filepath.WalkDir("subdir", visit)\n}
\n
\n

visit is called for every file or directory found\nrecursively by filepath.WalkDir.

\n\n 		\n \n 
func visit(path string, d fs.DirEntry, err error) error {\n    if err != nil {\n        return err\n    }\n    fmt.Println(" ", path, d.IsDir())\n    return nil\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run directories.go\nListing subdir/parent\n  child true\n  file2 false\n  file3 false\nListing subdir/parent/child\n  file4 false\nVisiting subdir\n  subdir true\n  subdir/file1 false\n  subdir/parent true\n  subdir/parent/child true\n  subdir/parent/child/file4 false\n  subdir/parent/file2 false\n  subdir/parent/file3 false
\n
\n \n \n

\n Next example: Temporary Files and Directories.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/embed-directive", "content": "\n\n \n \n Go by Example: Embed Directive\n \n \n \n \n
\n

Go by Example: Embed Directive

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

//go:embed is a compiler\ndirective that\nallows programs to include arbitrary files and folders in the Go binary at\nbuild time. Read more about the embed directive\nhere.

\n\n 		\n \n 
package main
\n
\n

Import the embed package; if you don’t use any exported\nidentifiers from this package, you can do a blank import with _ "embed".

\n\n 		\n \n 
import (\n    "embed"\n)
\n
\n

embed directives accept paths relative to the directory containing the\nGo source file. This directive embeds the contents of the file into the\nstring variable immediately following it.

\n\n 		\n \n 
//go:embed folder/single_file.txt\nvar fileString string
\n
\n

Or embed the contents of the file into a []byte.

\n\n 		\n \n 
//go:embed folder/single_file.txt\nvar fileByte []byte
\n
\n

We can also embed multiple files or even folders with wildcards. This uses\na variable of the embed.FS type, which\nimplements a simple virtual file system.

\n\n 		\n \n 
//go:embed folder/single_file.txt\n//go:embed folder/*.hash\nvar folder embed.FS
\n
\n \n \n \n 
func main() {
\n
\n

Print out the contents of single_file.txt.

\n\n 		\n \n 
    print(fileString)\n    print(string(fileByte))
\n
\n

Retrieve some files from the embedded folder.

\n\n 		\n \n 
    content1, _ := folder.ReadFile("folder/file1.hash")\n    print(string(content1))
\n
\n \n \n \n 
    content2, _ := folder.ReadFile("folder/file2.hash")\n    print(string(content2))\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Use these commands to run the example.\n(Note: due to limitation on go playground,\nthis example can only be run on your local machine.)

\n\n 		\n \n 
$ mkdir -p folder\n$ echo "hello go" > folder/single_file.txt\n$ echo "123" > folder/file1.hash\n$ echo "456" > folder/file2.hash
\n
\n \n \n \n 
$ go run embed-directive.go\nhello go\nhello go\n123\n456
\n
\n \n \n

\n Next example: Testing and Benchmarking.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/enums", "content": "\n\n \n \n Go by Example: Enums\n \n \n \n \n
\n

Go by Example: Enums

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Enumerated types (enums) are a special case of\nsum types.\nAn enum is a type that has a fixed number of possible\nvalues, each with a distinct name. Go doesn’t have an\nenum type as a distinct language feature, but enums\nare simple to implement using existing language idioms.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n

Our enum type ServerState has an underlying int type.

\n\n 		\n \n 
type ServerState int
\n
\n

The possible values for ServerState are defined as\nconstants. The special keyword iota\ngenerates successive constant values automatically; in this\ncase 0, 1, 2 and so on.

\n\n 		\n \n 
const (\n    StateIdle ServerState = iota\n    StateConnected\n    StateError\n    StateRetrying\n)
\n
\n

By implementing the fmt.Stringer\ninterface, values of ServerState can be printed out or converted\nto strings.

\n\n

This can get cumbersome if there are many possible values. In such\ncases the stringer tool\ncan be used in conjunction with go:generate to automate the\nprocess. See this post\nfor a longer explanation.

\n\n 		\n \n 
var stateName = map[ServerState]string{\n    StateIdle:      "idle",\n    StateConnected: "connected",\n    StateError:     "error",\n    StateRetrying:  "retrying",\n}
\n
\n \n \n \n 
func (ss ServerState) String() string {\n    return stateName[ss]\n}
\n
\n

If we have a value of type int, we cannot pass it to transition - the\ncompiler will complain about type mismatch. This provides some degree of\ncompile-time type safety for enums.

\n\n 		\n \n 
func main() {\n    ns := transition(StateIdle)\n    fmt.Println(ns)
\n
\n \n \n \n 
    ns2 := transition(ns)\n    fmt.Println(ns2)\n}
\n
\n

transition emulates a state transition for a\nserver; it takes the existing state and returns\na new state.

\n\n 		\n \n 
func transition(s ServerState) ServerState {\n    switch s {\n    case StateIdle:\n        return StateConnected\n    case StateConnected, StateRetrying:
\n
\n

Suppose we check some predicates here to\ndetermine the next state…

\n\n 		\n \n 
        return StateIdle\n    case StateError:\n        return StateError\n    default:\n        panic(fmt.Errorf("unknown state: %s", s))\n    }\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run enums.go\nconnected\nidle
\n
\n \n \n

\n Next example: Struct Embedding.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/environment-variables", "content": "\n\n \n \n Go by Example: Environment Variables\n \n \n \n \n
\n

Go by Example: Environment Variables

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Environment variables\nare a universal mechanism for conveying configuration\ninformation to Unix programs.\nLet’s look at how to set, get, and list environment variables.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "os"\n    "strings"\n)
\n
\n \n \n \n 
func main() {
\n
\n

To set a key/value pair, use os.Setenv. To get a\nvalue for a key, use os.Getenv. This will return\nan empty string if the key isn’t present in the\nenvironment.

\n\n 		\n \n 
    os.Setenv("FOO", "1")\n    fmt.Println("FOO:", os.Getenv("FOO"))\n    fmt.Println("BAR:", os.Getenv("BAR"))
\n
\n

Use os.Environ to list all key/value pairs in the\nenvironment. This returns a slice of strings in the\nform KEY=value. You can strings.SplitN them to\nget the key and value. Here we print all the keys.

\n\n 		\n \n 
    fmt.Println()\n    for _, e := range os.Environ() {\n        pair := strings.SplitN(e, "=", 2)\n        fmt.Println(pair[0])\n    }\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Running the program shows that we pick up the value\nfor FOO that we set in the program, but that\nBAR is empty.

\n\n 		\n \n 
$ go run environment-variables.go\nFOO: 1\nBAR:
\n
\n

The list of keys in the environment will depend on your\nparticular machine.

\n\n 		\n \n 
TERM_PROGRAM\nPATH\nSHELL\n...\nFOO
\n
\n

If we set BAR in the environment first, the running\nprogram picks that value up.

\n\n 		\n \n 
$ BAR=2 go run environment-variables.go\nFOO: 1\nBAR: 2\n...
\n
\n \n \n

\n Next example: Logging.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/epoch", "content": "\n\n \n \n Go by Example: Epoch\n \n \n \n \n
\n

Go by Example: Epoch

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

A common requirement in programs is getting the number\nof seconds, milliseconds, or nanoseconds since the\nUnix epoch.\nHere’s how to do it in Go.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "time"\n)
\n
\n \n \n \n 
func main() {
\n
\n

Use time.Now with Unix, UnixMilli or UnixNano\nto get elapsed time since the Unix epoch in seconds,\nmilliseconds or nanoseconds, respectively.

\n\n 		\n \n 
    now := time.Now()\n    fmt.Println(now)
\n
\n \n \n \n 
    fmt.Println(now.Unix())\n    fmt.Println(now.UnixMilli())\n    fmt.Println(now.UnixNano())
\n
\n

You can also convert integer seconds or nanoseconds\nsince the epoch into the corresponding time.

\n\n 		\n \n 
    fmt.Println(time.Unix(now.Unix(), 0))\n    fmt.Println(time.Unix(0, now.UnixNano()))\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run epoch.go \n2012-10-31 16:13:58.292387 +0000 UTC\n1351700038\n1351700038292\n1351700038292387000\n2012-10-31 16:13:58 +0000 UTC\n2012-10-31 16:13:58.292387 +0000 UTC
\n
\n

Next we’ll look at another time-related task: time\nparsing and formatting.

\n\n 		\n \n \n
\n \n \n

\n Next example: Time Formatting / Parsing.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/errors", "content": "\n\n \n \n Go by Example: Errors\n \n \n \n \n
\n

Go by Example: Errors

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

In Go it’s idiomatic to communicate errors via an\nexplicit, separate return value. This contrasts with\nthe exceptions used in languages like Java, Python and\nRuby and the overloaded single result / error value\nsometimes used in C. Go’s approach makes it easy to\nsee which functions return errors and to handle them\nusing the same language constructs employed for other,\nnon-error tasks.

\n\n

See the documentation of the errors package\nand this blog post for additional\ndetails.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "errors"\n    "fmt"\n)
\n
\n

By convention, errors are the last return value and\nhave type error, a built-in interface.

\n\n 		\n \n 
func f(arg int) (int, error) {\n    if arg == 42 {
\n
\n

errors.New constructs a basic error value\nwith the given error message.

\n\n 		\n \n 
        return -1, errors.New("can't work with 42")\n    }
\n
\n

A nil value in the error position indicates that\nthere was no error.

\n\n 		\n \n 
    return arg + 3, nil\n}
\n
\n

A sentinel error is a predeclared variable that is used to\nsignify a specific error condition.

\n\n 		\n \n 
var ErrOutOfTea = errors.New("no more tea available")\nvar ErrPower = errors.New("can't boil water")
\n
\n \n \n \n 
func makeTea(arg int) error {\n    if arg == 2 {\n        return ErrOutOfTea\n    } else if arg == 4 {
\n
\n

We can wrap errors with higher-level errors to add\ncontext. The simplest way to do this is with the\n%w verb in fmt.Errorf. Wrapped errors\ncreate a logical chain (A wraps B, which wraps C, etc.)\nthat can be queried with functions like errors.Is\nand errors.AsType.

\n\n 		\n \n 
        return fmt.Errorf("making tea: %w", ErrPower)\n    }\n    return nil\n}
\n
\n \n \n \n 
func main() {\n    for _, i := range []int{7, 42} {
\n
\n

It’s idiomatic to use an inline error check in the if\nline.

\n\n 		\n \n 
        if r, e := f(i); e != nil {\n            fmt.Println("f failed:", e)\n        } else {\n            fmt.Println("f worked:", r)\n        }\n    }
\n
\n \n \n \n 
    for i := range 5 {\n        if err := makeTea(i); err != nil {
\n
\n

errors.Is checks that a given error (or any error in its chain)\nmatches a specific error value. This is especially useful with wrapped or\nnested errors, allowing you to identify specific error types or sentinel\nerrors in a chain of errors.

\n\n 		\n \n 
            if errors.Is(err, ErrOutOfTea) {\n                fmt.Println("We should buy new tea!")\n            } else if errors.Is(err, ErrPower) {\n                fmt.Println("Now it is dark.")\n            } else {\n                fmt.Printf("unknown error: %s\\n", err)\n            }\n            continue\n        }
\n
\n \n \n \n 
        fmt.Println("Tea is ready!")\n    }\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run errors.go\nf worked: 10\nf failed: can't work with 42\nTea is ready!\nTea is ready!\nWe should buy new tea!\nTea is ready!\nNow it is dark.
\n
\n \n \n

\n Next example: Custom Errors.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/execing-processes", "content": "\n\n \n \n Go by Example: Exec'ing Processes\n \n \n \n \n
\n

Go by Example: Exec'ing Processes

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

In the previous example we looked at\nspawning external processes. We\ndo this when we need an external process accessible to\na running Go process. Sometimes we just want to\ncompletely replace the current Go process with another\n(perhaps non-Go) one. To do this we’ll use Go’s\nimplementation of the classic\nexec\nfunction.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "os"\n    "os/exec"\n    "syscall"\n)
\n
\n \n \n \n 
func main() {
\n
\n

For our example we’ll exec ls. Go requires an\nabsolute path to the binary we want to execute, so\nwe’ll use exec.LookPath to find it (probably\n/bin/ls).

\n\n 		\n \n 
    binary, lookErr := exec.LookPath("ls")\n    if lookErr != nil {\n        panic(lookErr)\n    }
\n
\n

Exec requires arguments in slice form (as\nopposed to one big string). We’ll give ls a few\ncommon arguments. Note that the first argument should\nbe the program name.

\n\n 		\n \n 
    args := []string{"ls", "-a", "-l", "-h"}
\n
\n

Exec also needs a set of environment variables\nto use. Here we just provide our current\nenvironment.

\n\n 		\n \n 
    env := os.Environ()
\n
\n

Here’s the actual syscall.Exec call. If this call is\nsuccessful, the execution of our process will end\nhere and be replaced by the /bin/ls -a -l -h\nprocess. If there is an error we’ll get a return\nvalue.

\n\n 		\n \n 
    execErr := syscall.Exec(binary, args, env)\n    if execErr != nil {\n        panic(execErr)\n    }\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

When we run our program it is replaced by ls.

\n\n 		\n \n 
$ go run execing-processes.go\ntotal 16\ndrwxr-xr-x  4 mark 136B Oct 3 16:29 .\ndrwxr-xr-x 91 mark 3.0K Oct 3 12:50 ..\n-rw-r--r--  1 mark 1.3K Oct 3 16:28 execing-processes.go
\n
\n

Note that Go does not offer a classic Unix fork\nfunction. Usually this isn’t an issue though, since\nstarting goroutines, spawning processes, and exec’ing\nprocesses covers most use cases for fork.

\n\n 		\n \n \n
\n \n \n

\n Next example: Signals.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/exit", "content": "\n\n \n \n Go by Example: Exit\n \n \n \n \n
\n

Go by Example: Exit

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Use os.Exit to immediately exit with a given\nstatus.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "os"\n)
\n
\n \n \n \n 
func main() {
\n
\n

defers will not be run when using os.Exit, so\nthis fmt.Println will never be called.

\n\n 		\n \n 
    defer fmt.Println("!")
\n
\n

Exit with status 3.

\n\n 		\n \n 
    os.Exit(3)\n}
\n
\n

Note that unlike e.g. C, Go does not use an integer\nreturn value from main to indicate exit status. If\nyou’d like to exit with a non-zero status you should\nuse os.Exit.

\n\n 		\n \n \n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

If you run exit.go using go run, the exit\nwill be picked up by go and printed.

\n\n 		\n \n 
$ go run exit.go\nexit status 3
\n
\n

By building and executing a binary you can see\nthe status in the terminal.

\n\n 		\n \n 
$ go build exit.go\n$ ./exit\n$ echo $?\n3
\n
\n

Note that the ! from our program never got printed.

\n\n 		\n \n \n
\n \n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/file-paths", "content": "\n\n \n \n Go by Example: File Paths\n \n \n \n \n
\n

Go by Example: File Paths

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

The filepath package provides functions to parse\nand construct file paths in a way that is portable\nbetween operating systems; dir/file on Linux vs.\ndir\\file on Windows, for example.

\n\n 		\n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "path/filepath"\n    "strings"\n)
\n
\n \n \n \n 
func main() {
\n
\n

Join should be used to construct paths in a\nportable way. It takes any number of arguments\nand constructs a hierarchical path from them.

\n\n 		\n \n 
    p := filepath.Join("dir1", "dir2", "filename")\n    fmt.Println("p:", p)
\n
\n

You should always use Join instead of\nconcatenating /s or \\s manually. In addition\nto providing portability, Join will also\nnormalize paths by removing superfluous separators\nand directory changes.

\n\n 		\n \n 
    fmt.Println(filepath.Join("dir1//", "filename"))\n    fmt.Println(filepath.Join("dir1/../dir1", "filename"))
\n
\n

Dir and Base can be used to split a path to the\ndirectory and the file. Alternatively, Split will\nreturn both in the same call.

\n\n 		\n \n 
    fmt.Println("Dir(p):", filepath.Dir(p))\n    fmt.Println("Base(p):", filepath.Base(p))
\n
\n

We can check whether a path is absolute.

\n\n 		\n \n 
    fmt.Println(filepath.IsAbs("dir/file"))\n    fmt.Println(filepath.IsAbs("/dir/file"))
\n
\n \n \n \n 
    filename := "config.json"
\n
\n

Some file names have extensions following a dot. We\ncan split the extension out of such names with Ext.

\n\n 		\n \n 
    ext := filepath.Ext(filename)\n    fmt.Println(ext)
\n
\n

To find the file’s name with the extension removed,\nuse strings.TrimSuffix.

\n\n 		\n \n 
    fmt.Println(strings.TrimSuffix(filename, ext))
\n
\n

Rel finds a relative path between a base and a\ntarget. It returns an error if the target cannot\nbe made relative to base.

\n\n 		\n \n 
    rel, err := filepath.Rel("a/b", "a/b/t/file")\n    if err != nil {\n        panic(err)\n    }\n    fmt.Println(rel)
\n
\n \n \n \n 
    rel, err = filepath.Rel("a/b", "a/c/t/file")\n    if err != nil {\n        panic(err)\n    }\n    fmt.Println(rel)\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run file-paths.go\np: dir1/dir2/filename\ndir1/filename\ndir1/filename\nDir(p): dir1/dir2\nBase(p): filename\nfalse\ntrue\n.json\nconfig\nt/file\n../c/t/file
\n
\n \n \n

\n Next example: Directories.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/for", "content": "\n\n \n \n Go by Example: For\n \n \n \n \n
\n

Go by Example: For

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

for is Go’s only looping construct. Here are\nsome basic types of for loops.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n \n \n \n 
func main() {
\n
\n

The most basic type, with a single condition.

\n\n 		\n \n 
    i := 1\n    for i <= 3 {\n        fmt.Println(i)\n        i = i + 1\n    }
\n
\n

A classic initial/condition/after for loop.

\n\n 		\n \n 
    for j := 0; j < 3; j++ {\n        fmt.Println(j)\n    }
\n
\n

Another way of accomplishing the basic “do this\nN times” iteration is range over an integer.

\n\n 		\n \n 
    for i := range 3 {\n        fmt.Println("range", i)\n    }
\n
\n

for without a condition will loop repeatedly\nuntil you break out of the loop or return from\nthe enclosing function.

\n\n 		\n \n 
    for {\n        fmt.Println("loop")\n        break\n    }
\n
\n

You can also continue to the next iteration of\nthe loop.

\n\n 		\n \n 
    for n := range 6 {\n        if n%2 == 0 {\n            continue\n        }\n        fmt.Println(n)\n    }\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run for.go\n1\n2\n3\n0\n1\n2\nrange 0\nrange 1\nrange 2\nloop\n1\n3\n5
\n
\n

We’ll see some other for forms later when we look at\nrange statements, channels, and other data\nstructures.

\n\n 		\n \n \n
\n \n \n

\n Next example: If/Else.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/functions", "content": "\n\n \n \n Go by Example: Functions\n \n \n \n \n
\n

Go by Example: Functions

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Functions are central in Go. We’ll learn about\nfunctions with a few different examples.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n

Here’s a function that takes two ints and returns\ntheir sum as an int.

\n\n 		\n \n 
func plus(a int, b int) int {
\n
\n

Go requires explicit returns, i.e. it won’t\nautomatically return the value of the last\nexpression.

\n\n 		\n \n 
    return a + b\n}
\n
\n

When you have multiple consecutive parameters of\nthe same type, you may omit the type name for the\nlike-typed parameters up to the final parameter that\ndeclares the type.

\n\n 		\n \n 
func plusPlus(a, b, c int) int {\n    return a + b + c\n}
\n
\n \n \n \n 
func main() {
\n
\n

Call a function just as you’d expect, with\nname(args).

\n\n 		\n \n 
    res := plus(1, 2)\n    fmt.Println("1+2 =", res)
\n
\n \n \n \n 
    res = plusPlus(1, 2, 3)\n    fmt.Println("1+2+3 =", res)\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run functions.go \n1+2 = 3\n1+2+3 = 6
\n
\n

There are several other features to Go functions. One is\nmultiple return values, which we’ll look at next.

\n\n 		\n \n \n
\n \n \n

\n Next example: Multiple Return Values.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/generics", "content": "\n\n \n \n Go by Example: Generics\n \n \n \n \n
\n

Go by Example: Generics

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Starting with version 1.18, Go has added support for\ngenerics, also known as type parameters.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n

As an example of a generic function, SlicesIndex takes\na slice of any comparable type and an element of that\ntype and returns the index of the first occurrence of\nv in s, or -1 if not present. The comparable constraint\nmeans that we can compare values of this type with the\n== and != operators. For a more thorough explanation\nof this type signature, see this blog post.\nNote that this function exists in the standard library\nas slices.Index.

\n\n 		\n \n 
func SlicesIndex[S ~[]E, E comparable](s S, v E) int {\n    for i := range s {\n        if v == s[i] {\n            return i\n        }\n    }\n    return -1\n}
\n
\n

As an example of a generic type, List is a\nsingly-linked list with values of any type.

\n\n 		\n \n 
type List[T any] struct {\n    head, tail *element[T]\n}
\n
\n \n \n \n 
type element[T any] struct {\n    next *element[T]\n    val  T\n}
\n
\n

We can define methods on generic types just like we\ndo on regular types, but we have to keep the type\nparameters in place. The type is List[T], not List.

\n\n 		\n \n 
func (lst *List[T]) Push(v T) {\n    if lst.tail == nil {\n        lst.head = &element[T]{val: v}\n        lst.tail = lst.head\n    } else {\n        lst.tail.next = &element[T]{val: v}\n        lst.tail = lst.tail.next\n    }\n}
\n
\n

AllElements returns all the List elements as a slice.\nIn the next example we’ll see a more idiomatic way\nof iterating over all elements of custom types.

\n\n 		\n \n 
func (lst *List[T]) AllElements() []T {\n    var elems []T\n    for e := lst.head; e != nil; e = e.next {\n        elems = append(elems, e.val)\n    }\n    return elems\n}
\n
\n \n \n \n 
func main() {\n    var s = []string{"foo", "bar", "zoo"}
\n
\n

When invoking generic functions, we can often rely\non type inference. Note that we don’t have to\nspecify the types for S and E when\ncalling SlicesIndex - the compiler infers them\nautomatically.

\n\n 		\n \n 
    fmt.Println("index of zoo:", SlicesIndex(s, "zoo"))
\n
\n

… though we could also specify them explicitly.

\n\n 		\n \n 
    _ = SlicesIndex[[]string, string](s, "zoo")
\n
\n \n \n \n 
    lst := List[int]{}\n    lst.Push(10)\n    lst.Push(13)\n    lst.Push(23)\n    fmt.Println("list:", lst.AllElements())\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run generics.go\nindex of zoo: 2\nlist: [10 13 23]
\n
\n \n \n

\n Next example: Range over Iterators.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/goroutines", "content": "\n\n \n \n Go by Example: Goroutines\n \n \n \n \n
\n

Go by Example: Goroutines

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

A goroutine is a lightweight thread of execution.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "time"\n)
\n
\n \n \n \n 
func f(from string) {\n    for i := range 3 {\n        fmt.Println(from, ":", i)\n    }\n}
\n
\n \n \n \n 
func main() {
\n
\n

Suppose we have a function call f(s). Here’s how\nwe’d call that in the usual way, running it\nsynchronously.

\n\n 		\n \n 
    f("direct")
\n
\n

To invoke this function in a goroutine, use\ngo f(s). This new goroutine will execute\nconcurrently with the calling one.

\n\n 		\n \n 
    go f("goroutine")
\n
\n

You can also start a goroutine for an anonymous\nfunction call.

\n\n 		\n \n 
    go func(msg string) {\n        fmt.Println(msg)\n    }("going")
\n
\n

Our two function calls are running asynchronously in\nseparate goroutines now. Wait for them to finish\n(for a more robust approach, use a WaitGroup).

\n\n 		\n \n 
    time.Sleep(time.Second)\n    fmt.Println("done")\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

When we run this program, we see the output of the\nblocking call first, then the output of the two\ngoroutines. The goroutines’ output may be interleaved,\nbecause goroutines are being run concurrently by the\nGo runtime.

\n\n 		\n \n 
$ go run goroutines.go\ndirect : 0\ndirect : 1\ndirect : 2\ngoroutine : 0\ngoing\ngoroutine : 1\ngoroutine : 2\ndone
\n
\n

Next we’ll look at a complement to goroutines in\nconcurrent Go programs: channels.

\n\n 		\n \n \n
\n \n \n

\n Next example: Channels.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/hello-world", "content": "\n\n \n \n Go by Example: Hello World\n \n \n \n \n
\n

Go by Example: Hello World

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Our first program will print the classic “hello world”\nmessage. Here’s the full source code.

\n\n 		\n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n \n \n \n 
func main() {\n    fmt.Println("hello world")\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

To run the program, put the code in hello-world.go and\nuse go run.

\n\n 		\n \n 
$ go run hello-world.go\nhello world
\n
\n

Sometimes we’ll want to build our programs into\nbinaries. We can do this using go build.

\n\n 		\n \n 
$ go build hello-world.go\n$ ls\nhello-world    hello-world.go
\n
\n

We can then execute the built binary directly.

\n\n 		\n \n 
$ ./hello-world\nhello world
\n
\n

Now that we can run and build basic Go programs, let’s\nlearn more about the language.

\n\n 		\n \n \n
\n \n \n

\n Next example: Values.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/http-client", "content": "\n\n \n \n Go by Example: HTTP Client\n \n \n \n \n
\n

Go by Example: HTTP Client

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

The Go standard library comes with excellent support\nfor HTTP clients and servers in the net/http\npackage. In this example we’ll use it to issue simple\nHTTP requests.

\n\n 		\n \n 
package main
\n
\n \n \n \n 
import (\n    "bufio"\n    "fmt"\n    "net/http"\n)
\n
\n \n \n \n 
func main() {
\n
\n

Issue an HTTP GET request to a server. http.Get is a\nconvenient shortcut around creating an http.Client\nobject and calling its Get method; it uses the\nhttp.DefaultClient object which has useful default\nsettings.

\n\n 		\n \n 
    resp, err := http.Get("https://gobyexample.com")\n    if err != nil {\n        panic(err)\n    }\n    defer resp.Body.Close()
\n
\n

Print the HTTP response status.

\n\n 		\n \n 
    fmt.Println("Response status:", resp.Status)
\n
\n

Print the first 5 lines of the response body.

\n\n 		\n \n 
    scanner := bufio.NewScanner(resp.Body)\n    for i := 0; scanner.Scan() && i < 5; i++ {\n        fmt.Println(scanner.Text())\n    }
\n
\n \n \n \n 
    if err := scanner.Err(); err != nil {\n        panic(err)\n    }\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run http-clients.go\nResponse status: 200 OK\n<!DOCTYPE html>\n<html>\n  <head>\n    <meta charset="utf-8">\n    <title>Go by Example</title>
\n
\n \n \n

\n Next example: HTTP Server.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/http-server", "content": "\n\n \n \n Go by Example: HTTP Server\n \n \n \n \n
\n

Go by Example: HTTP Server

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Writing a basic HTTP server is easy using the\nnet/http package.

\n\n 		\n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "net/http"\n)
\n
\n

A fundamental concept in net/http servers is\nhandlers. A handler is an object implementing the\nhttp.Handler interface. A common way to write\na handler is by using the http.HandlerFunc adapter\non functions with the appropriate signature.

\n\n 		\n \n 
func hello(w http.ResponseWriter, req *http.Request) {
\n
\n

Functions serving as handlers take a\nhttp.ResponseWriter and a http.Request as\narguments. The response writer is used to fill in the\nHTTP response. Here our simple response is just\n“hello\\n”.

\n\n 		\n \n 
    fmt.Fprintf(w, "hello\\n")\n}
\n
\n \n \n \n 
func headers(w http.ResponseWriter, req *http.Request) {
\n
\n

This handler does something a little more\nsophisticated by reading all the HTTP request\nheaders and echoing them into the response body.

\n\n 		\n \n 
    for name, headers := range req.Header {\n        for _, h := range headers {\n            fmt.Fprintf(w, "%v: %v\\n", name, h)\n        }\n    }\n}
\n
\n \n \n \n 
func main() {
\n
\n

We register our handlers on server routes using the\nhttp.HandleFunc convenience function. It sets up\nthe default router in the net/http package and\ntakes a function as an argument.

\n\n 		\n \n 
    http.HandleFunc("/hello", hello)\n    http.HandleFunc("/headers", headers)
\n
\n

Finally, we call the ListenAndServe with the port\nand a handler. nil tells it to use the default\nrouter we’ve just set up.

\n\n 		\n \n 
    http.ListenAndServe(":8090", nil)\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Run the server in the background.

\n\n 		\n \n 
$ go run http-server.go &
\n
\n

Access the /hello route.

\n\n 		\n \n 
$ curl localhost:8090/hello\nhello
\n
\n \n \n

\n Next example: TCP Server.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/if-else", "content": "\n\n \n \n Go by Example: If/Else\n \n \n \n \n
\n

Go by Example: If/Else

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Branching with if and else in Go is\nstraight-forward.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n \n \n \n 
func main() {
\n
\n

Here’s a basic example.

\n\n 		\n \n 
    if 7%2 == 0 {\n        fmt.Println("7 is even")\n    } else {\n        fmt.Println("7 is odd")\n    }
\n
\n

You can have an if statement without an else.

\n\n 		\n \n 
    if 8%4 == 0 {\n        fmt.Println("8 is divisible by 4")\n    }
\n
\n

Logical operators like && and || are often\nuseful in conditions.

\n\n 		\n \n 
    if 8%2 == 0 || 7%2 == 0 {\n        fmt.Println("either 8 or 7 are even")\n    }
\n
\n

A statement can precede conditionals; any variables\ndeclared in this statement are available in the current\nand all subsequent branches.

\n\n 		\n \n 
    if num := 9; num < 0 {\n        fmt.Println(num, "is negative")\n    } else if num < 10 {\n        fmt.Println(num, "has 1 digit")\n    } else {\n        fmt.Println(num, "has multiple digits")\n    }\n}
\n
\n

Note that you don’t need parentheses around conditions\nin Go, but that the braces are required.

\n\n 		\n \n \n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run if-else.go\n7 is odd\n8 is divisible by 4\neither 8 or 7 are even\n9 has 1 digit
\n
\n

There is no ternary if\nin Go, so you’ll need to use a full if statement even\nfor basic conditions.

\n\n 		\n \n \n
\n \n \n

\n Next example: Switch.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/index.html", "content": "\n\n \n \n Go by Example\n \n \n \n
\n

Go by Example

\n

\n Go is an\n open source programming language designed for\n building scalable, secure and reliable software.\n Please read the\n official documentation\n to learn more.\n

\n\n

\n Go by Example is a hands-on introduction\n to Go using annotated example programs. Check out\n the first example or\n browse the full list below.\n

\n\n

\n Unless stated otherwise, examples here assume the\n latest major release Go\n and may use new language features. Try to upgrade to the latest\n version if something isn't working.\n

\n\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n\n" }, { "path": "public/interfaces", "content": "\n\n \n \n Go by Example: Interfaces\n \n \n \n \n
\n

Go by Example: Interfaces

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Interfaces are named collections of method\nsignatures.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "math"\n)
\n
\n

Here’s a basic interface for geometric shapes.

\n\n 		\n \n 
type geometry interface {\n    area() float64\n    perim() float64\n}
\n
\n

For our example we’ll implement this interface on\nrect and circle types.

\n\n 		\n \n 
type rect struct {\n    width, height float64\n}\ntype circle struct {\n    radius float64\n}
\n
\n

To implement an interface in Go, we just need to\nimplement all the methods in the interface. Here we\nimplement geometry on rects.

\n\n 		\n \n 
func (r rect) area() float64 {\n    return r.width * r.height\n}\nfunc (r rect) perim() float64 {\n    return 2*r.width + 2*r.height\n}
\n
\n

The implementation for circles.

\n\n 		\n \n 
func (c circle) area() float64 {\n    return math.Pi * c.radius * c.radius\n}\nfunc (c circle) perim() float64 {\n    return 2 * math.Pi * c.radius\n}
\n
\n

If a variable has an interface type, then we can call\nmethods that are in the named interface. Here’s a\ngeneric measure function taking advantage of this\nto work on any geometry.

\n\n 		\n \n 
func measure(g geometry) {\n    fmt.Println(g)\n    fmt.Println(g.area())\n    fmt.Println(g.perim())\n}
\n
\n

Sometimes it’s useful to know the runtime type of an\ninterface value. One option is using a type assertion\nas shown here; another is a type switch.

\n\n 		\n \n 
func detectCircle(g geometry) {\n    if c, ok := g.(circle); ok {\n        fmt.Println("circle with radius", c.radius)\n    }\n}
\n
\n \n \n \n 
func main() {\n    r := rect{width: 3, height: 4}\n    c := circle{radius: 5}
\n
\n

The circle and rect struct types both\nimplement the geometry interface so we can use\ninstances of\nthese structs as arguments to measure.

\n\n 		\n \n 
    measure(r)\n    measure(c)
\n
\n \n \n \n 
    detectCircle(r)\n    detectCircle(c)\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run interfaces.go\n{3 4}\n12\n14\n{5}\n78.53981633974483\n31.41592653589793\ncircle with radius 5
\n
\n

To understand how Go’s interfaces work under the hood,\ncheck out this blog post.

\n\n 		\n \n \n
\n \n \n

\n Next example: Enums.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/json", "content": "\n\n \n \n Go by Example: JSON\n \n \n \n \n
\n

Go by Example: JSON

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go offers built-in support for JSON encoding and\ndecoding, including to and from built-in and custom\ndata types.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "encoding/json"\n    "fmt"\n    "os"\n    "strings"\n)
\n
\n

We’ll use these two structs to demonstrate encoding and\ndecoding of custom types below.

\n\n 		\n \n 
type response1 struct {\n    Page   int\n    Fruits []string\n}
\n
\n

Only exported fields will be encoded/decoded in JSON.\nFields must start with capital letters to be exported.

\n\n 		\n \n 
type response2 struct {\n    Page   int      `json:"page"`\n    Fruits []string `json:"fruits"`\n}
\n
\n \n \n \n 
func main() {
\n
\n

First we’ll look at encoding basic data types to\nJSON strings. Here are some examples for atomic\nvalues.

\n\n 		\n \n 
    bolB, _ := json.Marshal(true)\n    fmt.Println(string(bolB))
\n
\n \n \n \n 
    intB, _ := json.Marshal(1)\n    fmt.Println(string(intB))
\n
\n \n \n \n 
    fltB, _ := json.Marshal(2.34)\n    fmt.Println(string(fltB))
\n
\n \n \n \n 
    strB, _ := json.Marshal("gopher")\n    fmt.Println(string(strB))
\n
\n

And here are some for slices and maps, which encode\nto JSON arrays and objects as you’d expect.

\n\n 		\n \n 
    slcD := []string{"apple", "peach", "pear"}\n    slcB, _ := json.Marshal(slcD)\n    fmt.Println(string(slcB))
\n
\n \n \n \n 
    mapD := map[string]int{"apple": 5, "lettuce": 7}\n    mapB, _ := json.Marshal(mapD)\n    fmt.Println(string(mapB))
\n
\n

The JSON package can automatically encode your\ncustom data types. It will only include exported\nfields in the encoded output and will by default\nuse those names as the JSON keys.

\n\n 		\n \n 
    res1D := &response1{\n        Page:   1,\n        Fruits: []string{"apple", "peach", "pear"}}\n    res1B, _ := json.Marshal(res1D)\n    fmt.Println(string(res1B))
\n
\n

You can use tags on struct field declarations\nto customize the encoded JSON key names. Check the\ndefinition of response2 above to see an example\nof such tags.

\n\n 		\n \n 
    res2D := &response2{\n        Page:   1,\n        Fruits: []string{"apple", "peach", "pear"}}\n    res2B, _ := json.Marshal(res2D)\n    fmt.Println(string(res2B))
\n
\n

Now let’s look at decoding JSON data into Go\nvalues. Here’s an example for a generic data\nstructure.

\n\n 		\n \n 
    byt := []byte(`{"num":6.13,"strs":["a","b"]}`)
\n
\n

We need to provide a variable where the JSON\npackage can put the decoded data. This\nmap[string]interface{} will hold a map of strings\nto arbitrary data types.

\n\n 		\n \n 
    var dat map[string]interface{}
\n
\n

Here’s the actual decoding, and a check for\nassociated errors.

\n\n 		\n \n 
    if err := json.Unmarshal(byt, &dat); err != nil {\n        panic(err)\n    }\n    fmt.Println(dat)
\n
\n

In order to use the values in the decoded map,\nwe’ll need to convert them to their appropriate type.\nFor example here we convert the value in num to\nthe expected float64 type.

\n\n 		\n \n 
    num := dat["num"].(float64)\n    fmt.Println(num)
\n
\n

Accessing nested data requires a series of\nconversions.

\n\n 		\n \n 
    strs := dat["strs"].([]interface{})\n    str1 := strs[0].(string)\n    fmt.Println(str1)
\n
\n

We can also decode JSON into custom data types.\nThis has the advantages of adding additional\ntype-safety to our programs and eliminating the\nneed for type assertions when accessing the decoded\ndata.

\n\n 		\n \n 
    str := `{"page": 1, "fruits": ["apple", "peach"]}`\n    res := response2{}\n    json.Unmarshal([]byte(str), &res)\n    fmt.Println(res)\n    fmt.Println(res.Fruits[0])
\n
\n

In the examples above we always used bytes and\nstrings as intermediates between the data and\nJSON representation on standard out. We can also\nstream JSON encodings directly to os.Writers like\nos.Stdout or even HTTP response bodies.

\n\n 		\n \n 
    enc := json.NewEncoder(os.Stdout)\n    d := map[string]int{"apple": 5, "lettuce": 7}\n    enc.Encode(d)
\n
\n

Streaming reads from os.Readers like os.Stdin\nor HTTP request bodies is done with json.Decoder.

\n\n 		\n \n 
    dec := json.NewDecoder(strings.NewReader(str))\n    res1 := response2{}\n    dec.Decode(&res1)\n    fmt.Println(res1)\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run json.go\ntrue\n1\n2.34\n"gopher"\n["apple","peach","pear"]\n{"apple":5,"lettuce":7}\n{"Page":1,"Fruits":["apple","peach","pear"]}\n{"page":1,"fruits":["apple","peach","pear"]}\nmap[num:6.13 strs:[a b]]\n6.13\na\n{1 [apple peach]}\napple\n{"apple":5,"lettuce":7}\n{1 [apple peach]}
\n
\n

We’ve covered the basic of JSON in Go here, but check\nout the JSON and Go\nblog post and JSON package docs\nfor more.

\n\n 		\n \n \n
\n \n \n

\n Next example: XML.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/line-filters", "content": "\n\n \n \n Go by Example: Line Filters\n \n \n \n \n
\n

Go by Example: Line Filters

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

A line filter is a common type of program that reads\ninput on stdin, processes it, and then prints some\nderived result to stdout. grep and sed are common\nline filters.

\n\n 		\n \n \n
\n

Here’s an example line filter in Go that writes a\ncapitalized version of all input text. You can use this\npattern to write your own Go line filters.

\n\n 		\n \n 
package main
\n
\n \n \n \n 
import (\n    "bufio"\n    "fmt"\n    "os"\n    "strings"\n)
\n
\n \n \n \n 
func main() {
\n
\n

Wrapping the unbuffered os.Stdin with a buffered\nscanner gives us a convenient Scan method that\nadvances the scanner to the next token; which is\nthe next line in the default scanner.

\n\n 		\n \n 
    scanner := bufio.NewScanner(os.Stdin)
\n
\n

Text returns the current token, here the next line,\nfrom the input.

\n\n 		\n \n 
    for scanner.Scan() {
\n
\n \n \n \n 
        ucl := strings.ToUpper(scanner.Text())
\n
\n

Write out the uppercased line.

\n\n 		\n \n 
        fmt.Println(ucl)\n    }
\n
\n

Check for errors during Scan. End of file is\nexpected and not reported by Scan as an error.

\n\n 		\n \n 
    if err := scanner.Err(); err != nil {\n        fmt.Fprintln(os.Stderr, "error:", err)\n        os.Exit(1)\n    }\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

To try out our line filter, first make a file with a few\nlowercase lines.

\n\n 		\n \n 
$ echo 'hello'   > /tmp/lines\n$ echo 'filter' >> /tmp/lines
\n
\n

Then use the line filter to get uppercase lines.

\n\n 		\n \n 
$ cat /tmp/lines | go run line-filters.go\nHELLO\nFILTER
\n
\n \n \n

\n Next example: File Paths.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/logging", "content": "\n\n \n \n Go by Example: Logging\n \n \n \n \n
\n

Go by Example: Logging

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

The Go standard library provides straightforward\ntools for outputting logs from Go programs, with\nthe log package for\nfree-form output and the\nlog/slog package for\nstructured output.

\n\n 		\n \n 
package main
\n
\n \n \n \n 
import (\n    "bytes"\n    "fmt"\n    "log"\n    "os"
\n
\n \n \n \n 
    "log/slog"\n)
\n
\n \n \n \n 
func main() {
\n
\n

Simply invoking functions like Println from the\nlog package uses the standard logger, which\nis already pre-configured for reasonable logging\noutput to os.Stderr. Additional methods like\nFatal* or Panic* will exit the program after\nlogging.

\n\n 		\n \n 
    log.Println("standard logger")
\n
\n

Loggers can be configured with flags to set\ntheir output format. By default, the standard\nlogger has the log.Ldate and log.Ltime flags\nset, and these are collected in log.LstdFlags.\nWe can change its flags to emit time with\nmicrosecond accuracy, for example.

\n\n 		\n \n 
    log.SetFlags(log.LstdFlags | log.Lmicroseconds)\n    log.Println("with micro")
\n
\n

It also supports emitting the file name and\nline from which the log function is called.

\n\n 		\n \n 
    log.SetFlags(log.LstdFlags | log.Lshortfile)\n    log.Println("with file/line")
\n
\n

It may be useful to create a custom logger and\npass it around. When creating a new logger, we\ncan set a prefix to distinguish its output\nfrom other loggers.

\n\n 		\n \n 
    mylog := log.New(os.Stdout, "my:", log.LstdFlags)\n    mylog.Println("from mylog")
\n
\n

We can set the prefix\non existing loggers (including the standard one)\nwith the SetPrefix method.

\n\n 		\n \n 
    mylog.SetPrefix("ohmy:")\n    mylog.Println("from mylog")
\n
\n

Loggers can have custom output targets;\nany io.Writer works.

\n\n 		\n \n 
    var buf bytes.Buffer\n    buflog := log.New(&buf, "buf:", log.LstdFlags)
\n
\n

This call writes the log output into buf.

\n\n 		\n \n 
    buflog.Println("hello")
\n
\n

This will actually show it on standard output.

\n\n 		\n \n 
    fmt.Print("from buflog:", buf.String())
\n
\n

The slog package provides\nstructured log output. For example, logging\nin JSON format is straightforward.

\n\n 		\n \n 
    jsonHandler := slog.NewJSONHandler(os.Stderr, nil)\n    myslog := slog.New(jsonHandler)\n    myslog.Info("hi there")
\n
\n

In addition to the message, slog output can\ncontain an arbitrary number of key=value\npairs.

\n\n 		\n \n 
    myslog.Info("hello again", "key", "val", "age", 25)\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Sample output; the date and time\nemitted will depend on when the example ran.

\n\n 		\n \n 
$ go run logging.go\n2023/08/22 10:45:16 standard logger\n2023/08/22 10:45:16.904141 with micro\n2023/08/22 10:45:16 logging.go:40: with file/line\nmy:2023/08/22 10:45:16 from mylog\nohmy:2023/08/22 10:45:16 from mylog\nfrom buflog:buf:2023/08/22 10:45:16 hello
\n
\n

These are wrapped for clarity of presentation\non the website; in reality they are emitted\non a single line.

\n\n 		\n \n 
{"time":"2023-08-22T10:45:16.904166391-07:00",\n "level":"INFO","msg":"hi there"}\n{"time":"2023-08-22T10:45:16.904178985-07:00",\n    "level":"INFO","msg":"hello again",\n    "key":"val","age":25}
\n
\n \n \n

\n Next example: HTTP Client.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/maps", "content": "\n\n \n \n Go by Example: Maps\n \n \n \n \n
\n

Go by Example: Maps

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Maps are Go’s built-in associative data type\n(sometimes called hashes or dicts in other languages).

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "maps"\n)
\n
\n \n \n \n 
func main() {
\n
\n

To create an empty map, use the builtin make:\nmake(map[key-type]val-type).

\n\n 		\n \n 
    m := make(map[string]int)
\n
\n

Set key/value pairs using typical name[key] = val\nsyntax.

\n\n 		\n \n 
    m["k1"] = 7\n    m["k2"] = 13
\n
\n

Printing a map with e.g. fmt.Println will show all of\nits key/value pairs.

\n\n 		\n \n 
    fmt.Println("map:", m)
\n
\n

Get a value for a key with name[key].

\n\n 		\n \n 
    v1 := m["k1"]\n    fmt.Println("v1:", v1)
\n
\n

If the key doesn’t exist, the\nzero value of the\nvalue type is returned.

\n\n 		\n \n 
    v3 := m["k3"]\n    fmt.Println("v3:", v3)
\n
\n

The builtin len returns the number of key/value\npairs when called on a map.

\n\n 		\n \n 
    fmt.Println("len:", len(m))
\n
\n

The builtin delete removes key/value pairs from\na map.

\n\n 		\n \n 
    delete(m, "k2")\n    fmt.Println("map:", m)
\n
\n

To remove all key/value pairs from a map, use\nthe clear builtin.

\n\n 		\n \n 
    clear(m)\n    fmt.Println("map:", m)
\n
\n

The optional second return value when getting a\nvalue from a map indicates if the key was present\nin the map. This can be used to disambiguate\nbetween missing keys and keys with zero values\nlike 0 or "". Here we didn’t need the value\nitself, so we ignored it with the blank identifier\n_.

\n\n 		\n \n 
    _, prs := m["k2"]\n    fmt.Println("prs:", prs)
\n
\n

You can also declare and initialize a new map in\nthe same line with this syntax.

\n\n 		\n \n 
    n := map[string]int{"foo": 1, "bar": 2}\n    fmt.Println("map:", n)
\n
\n

The maps package contains a number of useful\nutility functions for maps.

\n\n 		\n \n 
    n2 := map[string]int{"foo": 1, "bar": 2}\n    if maps.Equal(n, n2) {\n        fmt.Println("n == n2")\n    }\n}
\n
\n \n \n \n \n \n \n \n \n
\n

Note that maps appear in the form map[k:v k:v] when\nprinted with fmt.Println.

\n\n 		\n \n 
$ go run maps.go \nmap: map[k1:7 k2:13]\nv1: 7\nv3: 0\nlen: 2\nmap: map[k1:7]\nmap: map[]\nprs: false\nmap: map[bar:2 foo:1]\nn == n2
\n
\n \n \n

\n Next example: Functions.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/methods", "content": "\n\n \n \n Go by Example: Methods\n \n \n \n \n
\n

Go by Example: Methods

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go supports methods defined on struct types.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n \n \n \n 
type rect struct {\n    width, height int\n}
\n
\n

This area method has a receiver type of *rect.

\n\n 		\n \n 
func (r *rect) area() int {\n    return r.width * r.height\n}
\n
\n

Methods can be defined for either pointer or value\nreceiver types. Here’s an example of a value receiver.

\n\n 		\n \n 
func (r rect) perim() int {\n    return 2*r.width + 2*r.height\n}
\n
\n \n \n \n 
func main() {\n    r := rect{width: 10, height: 5}
\n
\n

Here we call the 2 methods defined for our struct.

\n\n 		\n \n 
    fmt.Println("area: ", r.area())\n    fmt.Println("perim:", r.perim())
\n
\n

Go automatically handles conversion between values\nand pointers for method calls. You may want to use\na pointer receiver type to avoid copying on method\ncalls or to allow the method to mutate the\nreceiving struct.

\n\n 		\n \n 
    rp := &r\n    fmt.Println("area: ", rp.area())\n    fmt.Println("perim:", rp.perim())\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run methods.go \narea:  50\nperim: 30\narea:  50\nperim: 30
\n
\n

Next we’ll look at Go’s mechanism for grouping and\nnaming related sets of methods: interfaces.

\n\n 		\n \n \n
\n \n \n

\n Next example: Interfaces.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/multiple-return-values", "content": "\n\n \n \n Go by Example: Multiple Return Values\n \n \n \n \n
\n

Go by Example: Multiple Return Values

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go has built-in support for multiple return values.\nThis feature is used often in idiomatic Go, for example\nto return both result and error values from a function.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n

The (int, int) in this function signature shows that\nthe function returns 2 ints.

\n\n 		\n \n 
func vals() (int, int) {\n    return 3, 7\n}
\n
\n \n \n \n 
func main() {
\n
\n

Here we use the 2 different return values from the\ncall with multiple assignment.

\n\n 		\n \n 
    a, b := vals()\n    fmt.Println(a)\n    fmt.Println(b)
\n
\n

If you only want a subset of the returned values,\nuse the blank identifier _.

\n\n 		\n \n 
    _, c := vals()\n    fmt.Println(c)\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run multiple-return-values.go\n3\n7\n7
\n
\n

Accepting a variable number of arguments is another nice\nfeature of Go functions; we’ll look at this next.

\n\n 		\n \n \n
\n \n \n

\n Next example: Variadic Functions.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/mutexes", "content": "\n\n \n \n Go by Example: Mutexes\n \n \n \n \n
\n

Go by Example: Mutexes

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

In the previous example we saw how to manage simple\ncounter state using atomic operations.\nFor more complex state we can use a mutex\nto safely access data across multiple goroutines.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "sync"\n)
\n
\n

Container holds a map of counters; since we want to\nupdate it concurrently from multiple goroutines, we\nadd a Mutex to synchronize access.\nNote that mutexes must not be copied, so if this\nstruct is passed around, it should be done by\npointer.

\n\n 		\n \n 
type Container struct {\n    mu       sync.Mutex\n    counters map[string]int\n}
\n
\n

Lock the mutex before accessing counters; unlock\nit at the end of the function using a defer\nstatement.

\n\n 		\n \n 
func (c *Container) inc(name string) {
\n
\n \n \n \n 
    c.mu.Lock()\n    defer c.mu.Unlock()\n    c.counters[name]++\n}
\n
\n

Note that the zero value of a mutex is usable as-is, so no\ninitialization is required here.

\n\n 		\n \n 
func main() {\n    c := Container{
\n
\n \n \n \n 
        counters: map[string]int{"a": 0, "b": 0},\n    }
\n
\n \n \n \n 
    var wg sync.WaitGroup
\n
\n

This function increments a named counter\nin a loop.

\n\n 		\n \n 
    doIncrement := func(name string, n int) {\n        for range n {\n            c.inc(name)\n        }\n    }
\n
\n

Run several goroutines concurrently; note\nthat they all access the same Container,\nand two of them access the same counter.

\n\n 		\n \n 
    wg.Go(func() {\n        doIncrement("a", 10000)\n    })
\n
\n \n \n \n 
    wg.Go(func() {\n        doIncrement("a", 10000)\n    })
\n
\n \n \n \n 
    wg.Go(func() {\n        doIncrement("b", 10000)\n    })
\n
\n

Wait for the goroutines to finish

\n\n 		\n \n 
    wg.Wait()\n    fmt.Println(c.counters)\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Running the program shows that the counters\nupdated as expected.

\n\n 		\n \n 
$ go run mutexes.go\nmap[a:20000 b:10000]
\n
\n

Next we’ll look at implementing this same state\nmanagement task using only goroutines and channels.

\n\n 		\n \n \n
\n \n \n

\n Next example: Stateful Goroutines.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/non-blocking-channel-operations", "content": "\n\n \n \n Go by Example: Non-Blocking Channel Operations\n \n \n \n \n
\n

Go by Example: Non-Blocking Channel Operations

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Basic sends and receives on channels are blocking.\nHowever, we can use select with a default clause to\nimplement non-blocking sends, receives, and even\nnon-blocking multi-way selects.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n \n \n \n 
func main() {\n    messages := make(chan string)\n    signals := make(chan bool)
\n
\n

Here’s a non-blocking receive. If a value is\navailable on messages then select will take\nthe <-messages case with that value. If not\nit will immediately take the default case.

\n\n 		\n \n 
    select {\n    case msg := <-messages:\n        fmt.Println("received message", msg)\n    default:\n        fmt.Println("no message received")\n    }
\n
\n

A non-blocking send works similarly. Here msg\ncannot be sent to the messages channel, because\nthe channel has no buffer and there is no receiver.\nTherefore the default case is selected.

\n\n 		\n \n 
    msg := "hi"\n    select {\n    case messages <- msg:\n        fmt.Println("sent message", msg)\n    default:\n        fmt.Println("no message sent")\n    }
\n
\n

We can use multiple cases above the default\nclause to implement a multi-way non-blocking\nselect. Here we attempt non-blocking receives\non both messages and signals.

\n\n 		\n \n 
    select {\n    case msg := <-messages:\n        fmt.Println("received message", msg)\n    case sig := <-signals:\n        fmt.Println("received signal", sig)\n    default:\n        fmt.Println("no activity")\n    }\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run non-blocking-channel-operations.go \nno message received\nno message sent\nno activity
\n
\n \n \n

\n Next example: Closing Channels.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/number-parsing", "content": "\n\n \n \n Go by Example: Number Parsing\n \n \n \n \n
\n

Go by Example: Number Parsing

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Parsing numbers from strings is a basic but common task\nin many programs; here’s how to do it in Go.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n

The built-in package strconv provides the number\nparsing.

\n\n 		\n \n 
import (\n    "fmt"\n    "strconv"\n)
\n
\n \n \n \n 
func main() {
\n
\n

With ParseFloat, this 64 tells how many bits of\nprecision to parse.

\n\n 		\n \n 
    f, _ := strconv.ParseFloat("1.234", 64)\n    fmt.Println(f)
\n
\n

For ParseInt, the 0 means infer the base from\nthe string. 64 requires that the result fit in 64\nbits.

\n\n 		\n \n 
    i, _ := strconv.ParseInt("123", 0, 64)\n    fmt.Println(i)
\n
\n

ParseInt will recognize hex-formatted numbers.

\n\n 		\n \n 
    d, _ := strconv.ParseInt("0x1c8", 0, 64)\n    fmt.Println(d)
\n
\n

A ParseUint is also available.

\n\n 		\n \n 
    u, _ := strconv.ParseUint("789", 0, 64)\n    fmt.Println(u)
\n
\n

Atoi is a convenience function for basic base-10\nint parsing.

\n\n 		\n \n 
    k, _ := strconv.Atoi("135")\n    fmt.Println(k)
\n
\n

Parse functions return an error on bad input.

\n\n 		\n \n 
    _, e := strconv.Atoi("wat")\n    fmt.Println(e)\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run number-parsing.go \n1.234\n123\n456\n789\n135\nstrconv.ParseInt: parsing "wat": invalid syntax
\n
\n

Next we’ll look at another common parsing task: URLs.

\n\n 		\n \n \n
\n \n \n

\n Next example: URL Parsing.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/panic", "content": "\n\n \n \n Go by Example: Panic\n \n \n \n \n
\n

Go by Example: Panic

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

A panic typically means something went unexpectedly\nwrong. Mostly we use it to fail fast on errors that\nshouldn’t occur during normal operation, or that we\naren’t prepared to handle gracefully.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "os"\n    "path/filepath"\n)
\n
\n \n \n \n 
func main() {
\n
\n

We’ll use panic throughout this site to check for\nunexpected errors. This is the only program on the\nsite designed to panic.

\n\n 		\n \n 
    panic("a problem")
\n
\n

A common use of panic is to abort if a function\nreturns an error value that we don’t know how to\n(or want to) handle. Here’s an example of\npanicking if we get an unexpected error when creating a new file.

\n\n 		\n \n 
    path := filepath.Join(os.TempDir(), "file")\n    _, err := os.Create(path)\n    if err != nil {\n        panic(err)\n    }\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Running this program will cause it to panic, print\nan error message and goroutine traces, and exit with\na non-zero status.

\n\n 		\n \n \n
\n

When first panic in main fires, the program exits\nwithout reaching the rest of the code. If you’d like\nto see the program try to create a temp file, comment\nthe first panic out.

\n\n 		\n \n 
$ go run panic.go\npanic: a problem
\n
\n \n \n \n 
goroutine 1 [running]:\nmain.main()\n    /.../panic.go:12 +0x47\n...\nexit status 2
\n
\n

Note that unlike some languages which use exceptions\nfor handling of many errors, in Go it is idiomatic\nto use error-indicating return values wherever possible.

\n\n 		\n \n \n
\n \n \n

\n Next example: Defer.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/pointers", "content": "\n\n \n \n Go by Example: Pointers\n \n \n \n \n
\n

Go by Example: Pointers

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go supports pointers,\nallowing you to pass references to values and records\nwithin your program.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n

We’ll show how pointers work in contrast to values with\n2 functions: zeroval and zeroptr. zeroval has an\nint parameter, so arguments will be passed to it by\nvalue. zeroval will get a copy of ival distinct\nfrom the one in the calling function.

\n\n 		\n \n 
func zeroval(ival int) {\n    ival = 0\n}
\n
\n

zeroptr in contrast has an *int parameter, meaning\nthat it takes an int pointer. The *iptr code in the\nfunction body then dereferences the pointer from its\nmemory address to the current value at that address.\nAssigning a value to a dereferenced pointer changes the\nvalue at the referenced address.

\n\n 		\n \n 
func zeroptr(iptr *int) {\n    *iptr = 0\n}
\n
\n \n \n \n 
func main() {\n    i := 1\n    fmt.Println("initial:", i)
\n
\n \n \n \n 
    zeroval(i)\n    fmt.Println("zeroval:", i)
\n
\n

The &i syntax gives the memory address of i,\ni.e. a pointer to i.

\n\n 		\n \n 
    zeroptr(&i)\n    fmt.Println("zeroptr:", i)
\n
\n

Pointers can be printed too.

\n\n 		\n \n 
    fmt.Println("pointer:", &i)\n}
\n
\n \n \n \n \n \n \n \n \n
\n

zeroval doesn’t change the i in main, but\nzeroptr does because it has a reference to\nthe memory address for that variable.

\n\n 		\n \n 
$ go run pointers.go\ninitial: 1\nzeroval: 1\nzeroptr: 0\npointer: 0x42131100
\n
\n \n \n

\n Next example: Strings and Runes.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/random-numbers", "content": "\n\n \n \n Go by Example: Random Numbers\n \n \n \n \n
\n

Go by Example: Random Numbers

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go’s math/rand/v2 package provides\npseudorandom number\ngeneration.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "math/rand/v2"\n)
\n
\n \n \n \n 
func main() {
\n
\n

For example, rand.IntN returns a random int n,\n0 <= n < 100.

\n\n 		\n \n 
    fmt.Print(rand.IntN(100), ",")\n    fmt.Print(rand.IntN(100))\n    fmt.Println()
\n
\n

rand.Float64 returns a float64 f,\n0.0 <= f < 1.0.

\n\n 		\n \n 
    fmt.Println(rand.Float64())
\n
\n

This can be used to generate random floats in\nother ranges, for example 5.0 <= f' < 10.0.

\n\n 		\n \n 
    fmt.Print((rand.Float64()*5)+5, ",")\n    fmt.Print((rand.Float64() * 5) + 5)\n    fmt.Println()
\n
\n

If you want a known seed, create a new\nrand.Source and pass it into the New\nconstructor. NewPCG creates a new\nPCG\nsource that requires a seed of two uint64\nnumbers.

\n\n 		\n \n 
    s2 := rand.NewPCG(42, 1024)\n    r2 := rand.New(s2)\n    fmt.Print(r2.IntN(100), ",")\n    fmt.Print(r2.IntN(100))\n    fmt.Println()
\n
\n \n \n \n 
    s3 := rand.NewPCG(42, 1024)\n    r3 := rand.New(s3)\n    fmt.Print(r3.IntN(100), ",")\n    fmt.Print(r3.IntN(100))\n    fmt.Println()\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Some of the generated numbers may be\ndifferent when you run the sample.

\n\n 		\n \n 
$ go run random-numbers.go\n68,56\n0.8090228139659177\n5.840125017402497,6.937056298890035\n94,49\n94,49
\n
\n

See the math/rand/v2\npackage docs for references on other random quantities\nthat Go can provide.

\n\n 		\n \n \n
\n \n \n

\n Next example: Number Parsing.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/range-over-built-in-types", "content": "\n\n \n \n Go by Example: Range over Built-in Types\n \n \n \n \n
\n

Go by Example: Range over Built-in Types

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

range iterates over elements in a variety of\nbuilt-in data structures. Let’s see how to\nuse range with some of the data structures\nwe’ve already learned.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n \n \n \n 
func main() {
\n
\n

Here we use range to sum the numbers in a slice.\nArrays work like this too.

\n\n 		\n \n 
    nums := []int{2, 3, 4}\n    sum := 0\n    for _, num := range nums {\n        sum += num\n    }\n    fmt.Println("sum:", sum)
\n
\n

range on arrays and slices provides both the\nindex and value for each entry. Above we didn’t\nneed the index, so we ignored it with the\nblank identifier _. Sometimes we actually want\nthe indexes though.

\n\n 		\n \n 
    for i, num := range nums {\n        if num == 3 {\n            fmt.Println("index:", i)\n        }\n    }
\n
\n

range on map iterates over key/value pairs.

\n\n 		\n \n 
    kvs := map[string]string{"a": "apple", "b": "banana"}\n    for k, v := range kvs {\n        fmt.Printf("%s -> %s\\n", k, v)\n    }
\n
\n

range can also iterate over just the keys of a map.

\n\n 		\n \n 
    for k := range kvs {\n        fmt.Println("key:", k)\n    }
\n
\n

range on strings iterates over Unicode code\npoints. The first value is the starting byte index\nof the rune and the second the rune itself.\nSee Strings and Runes for more\ndetails.

\n\n 		\n \n 
    for i, c := range "go" {\n        fmt.Println(i, c)\n    }\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run range-over-built-in-types.go\nsum: 9\nindex: 1\na -> apple\nb -> banana\nkey: a\nkey: b\n0 103\n1 111
\n
\n \n \n

\n Next example: Pointers.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/range-over-channels", "content": "\n\n \n \n Go by Example: Range over Channels\n \n \n \n \n
\n

Go by Example: Range over Channels

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

In a previous example we saw how for and\nrange provide iteration over basic data structures.\nWe can also use this syntax to iterate over\nvalues received from a channel.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n \n \n \n 
func main() {
\n
\n

We’ll iterate over 2 values in the queue channel.

\n\n 		\n \n 
    queue := make(chan string, 2)\n    queue <- "one"\n    queue <- "two"\n    close(queue)
\n
\n

This range iterates over each element as it’s\nreceived from queue. Because we closed the\nchannel above, the iteration terminates after\nreceiving the 2 elements.

\n\n 		\n \n 
    for elem := range queue {\n        fmt.Println(elem)\n    }\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run range-over-channels.go\none\ntwo
\n
\n

This example also showed that it’s possible to close\na non-empty channel but still have the remaining\nvalues be received.

\n\n 		\n \n \n
\n \n \n

\n Next example: Timers.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/range-over-iterators", "content": "\n\n \n \n Go by Example: Range over Iterators\n \n \n \n \n
\n

Go by Example: Range over Iterators

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Starting with version 1.23, Go has added support for\niterators,\nwhich lets us range over pretty much anything!

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "iter"\n    "slices"\n    "strings"\n)
\n
\n

Let’s look at the List type from the\nprevious example again. In that example\nwe had an AllElements method that returned a slice\nof all elements in the list. With Go iterators, we\ncan do it better - as shown below.

\n\n 		\n \n 
type List[T any] struct {\n    head, tail *element[T]\n}
\n
\n \n \n \n 
type element[T any] struct {\n    next *element[T]\n    val  T\n}
\n
\n \n \n \n 
func (lst *List[T]) Push(v T) {\n    if lst.tail == nil {\n        lst.head = &element[T]{val: v}\n        lst.tail = lst.head\n    } else {\n        lst.tail.next = &element[T]{val: v}\n        lst.tail = lst.tail.next\n    }\n}
\n
\n

All returns an iterator, which in Go is a function\nwith a special signature.

\n\n 		\n \n 
func (lst *List[T]) All() iter.Seq[T] {\n    return func(yield func(T) bool) {
\n
\n

The iterator function takes another function as\na parameter, called yield by convention (but\nthe name can be arbitrary). It will call yield for\nevery element we want to iterate over, and note yield’s\nreturn value for a potential early termination.

\n\n 		\n \n 
        for e := lst.head; e != nil; e = e.next {\n            if !yield(e.val) {\n                return\n            }\n        }\n    }\n}
\n
\n

Iteration doesn’t require an underlying data structure,\nand doesn’t even have to be finite! Here’s a function\nreturning an iterator over Fibonacci numbers: it keeps\nrunning as long as yield keeps returning true.

\n\n 		\n \n 
func genFib() iter.Seq[int] {\n    return func(yield func(int) bool) {\n        a, b := 0, 1
\n
\n \n \n \n 
        for {\n            if !yield(a) {\n                return\n            }\n            a, b = b, a+b\n        }\n    }\n}
\n
\n \n \n \n 
func main() {\n    lst := List[int]{}\n    lst.Push(10)\n    lst.Push(13)\n    lst.Push(23)
\n
\n

Since List.All returns an iterator, we can use it\nin a regular range loop.

\n\n 		\n \n 
    for e := range lst.All() {\n        fmt.Println(e)\n    }
\n
\n

Packages like slices have\na number of useful functions to work with iterators.\nFor example, Collect takes any iterator and collects\nall its values into a slice.

\n\n 		\n \n 
    all := slices.Collect(lst.All())\n    fmt.Println("all:", all)
\n
\n

Standard library packages now expose iterator helpers\ntoo. For example, strings.SplitSeq iterates over parts\nof a byte slice without first building a result slice.

\n\n 		\n \n 
    for part := range strings.SplitSeq("go-by-example", "-") {\n        fmt.Printf("part: %s\\n", part)\n    }
\n
\n \n \n \n 
    for n := range genFib() {
\n
\n

Once the loop hits break or an early return, the yield function\npassed to the iterator will return false.

\n\n 		\n \n 
        if n >= 10 {\n            break\n        }\n        fmt.Println(n)\n    }\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run range-over-iterators.go\n10\n13\n23\nall: [10 13 23]\npart: go\npart: by\npart: example\n0\n1\n1\n2\n3\n5\n8
\n
\n \n \n

\n Next example: Errors.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/rate-limiting", "content": "\n\n \n \n Go by Example: Rate Limiting\n \n \n \n \n
\n

Go by Example: Rate Limiting

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Rate limiting\nis an important mechanism for controlling resource\nutilization and maintaining quality of service. Go\nelegantly supports rate limiting with goroutines,\nchannels, and tickers.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "time"\n)
\n
\n \n \n \n 
func main() {
\n
\n

First we’ll look at basic rate limiting. Suppose\nwe want to limit our handling of incoming requests.\nWe’ll serve these requests off a channel of the\nsame name.

\n\n 		\n \n 
    requests := make(chan int, 5)\n    for i := 1; i <= 5; i++ {\n        requests <- i\n    }\n    close(requests)
\n
\n

This limiter channel will receive a value\nevery 200 milliseconds. This is the regulator in\nour rate limiting scheme.

\n\n 		\n \n 
    limiter := time.Tick(200 * time.Millisecond)
\n
\n

By blocking on a receive from the limiter channel\nbefore serving each request, we limit ourselves to\n1 request every 200 milliseconds.

\n\n 		\n \n 
    for req := range requests {\n        <-limiter\n        fmt.Println("request", req, time.Now())\n    }
\n
\n

We may want to allow short bursts of requests in\nour rate limiting scheme while preserving the\noverall rate limit. We can accomplish this by\nbuffering our limiter channel. This burstyLimiter\nchannel will allow bursts of up to 3 events.

\n\n 		\n \n 
    burstyLimiter := make(chan time.Time, 3)
\n
\n

Fill up the channel to represent allowed bursting.

\n\n 		\n \n 
    for range 3 {\n        burstyLimiter <- time.Now()\n    }
\n
\n

Every 200 milliseconds we’ll try to add a new\nvalue to burstyLimiter, up to its limit of 3.

\n\n 		\n \n 
    go func() {\n        for t := range time.Tick(200 * time.Millisecond) {\n            burstyLimiter <- t\n        }\n    }()
\n
\n

Now simulate 5 more incoming requests. The first\n3 of these will benefit from the burst capability\nof burstyLimiter.

\n\n 		\n \n 
    burstyRequests := make(chan int, 5)\n    for i := 1; i <= 5; i++ {\n        burstyRequests <- i\n    }\n    close(burstyRequests)\n    for req := range burstyRequests {\n        <-burstyLimiter\n        fmt.Println("request", req, time.Now())\n    }\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Running our program we see the first batch of requests\nhandled once every ~200 milliseconds as desired.

\n\n 		\n \n 
$ go run rate-limiting.go\nrequest 1 2012-10-19 00:38:18.687438 +0000 UTC\nrequest 2 2012-10-19 00:38:18.887471 +0000 UTC\nrequest 3 2012-10-19 00:38:19.087238 +0000 UTC\nrequest 4 2012-10-19 00:38:19.287338 +0000 UTC\nrequest 5 2012-10-19 00:38:19.487331 +0000 UTC
\n
\n

For the second batch of requests we serve the first\n3 immediately because of the burstable rate limiting,\nthen serve the remaining 2 with ~200ms delays each.

\n\n 		\n \n 
request 1 2012-10-19 00:38:20.487578 +0000 UTC\nrequest 2 2012-10-19 00:38:20.487645 +0000 UTC\nrequest 3 2012-10-19 00:38:20.487676 +0000 UTC\nrequest 4 2012-10-19 00:38:20.687483 +0000 UTC\nrequest 5 2012-10-19 00:38:20.887542 +0000 UTC
\n
\n \n \n

\n Next example: Atomic Counters.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/reading-files", "content": "\n\n \n \n Go by Example: Reading Files\n \n \n \n \n
\n

Go by Example: Reading Files

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Reading and writing files are basic tasks needed for\nmany Go programs. First we’ll look at some examples of\nreading files.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "bufio"\n    "fmt"\n    "io"\n    "os"\n    "path/filepath"\n)
\n
\n

Reading files requires checking most calls for errors.\nThis helper will streamline our error checks below.

\n\n 		\n \n 
func check(e error) {\n    if e != nil {\n        panic(e)\n    }\n}
\n
\n \n \n \n 
func main() {
\n
\n

Perhaps the most basic file reading task is\nslurping a file’s entire contents into memory.

\n\n 		\n \n 
    path := filepath.Join(os.TempDir(), "dat")\n    dat, err := os.ReadFile(path)\n    check(err)\n    fmt.Print(string(dat))
\n
\n

You’ll often want more control over how and what\nparts of a file are read. For these tasks, start\nby Opening a file to obtain an os.File value.

\n\n 		\n \n 
    f, err := os.Open(path)\n    check(err)
\n
\n

Read some bytes from the beginning of the file.\nAllow up to 5 to be read but also note how many\nactually were read.

\n\n 		\n \n 
    b1 := make([]byte, 5)\n    n1, err := f.Read(b1)\n    check(err)\n    fmt.Printf("%d bytes: %s\\n", n1, string(b1[:n1]))
\n
\n

You can also Seek to a known location in the file\nand Read from there.

\n\n 		\n \n 
    o2, err := f.Seek(6, io.SeekStart)\n    check(err)\n    b2 := make([]byte, 2)\n    n2, err := f.Read(b2)\n    check(err)\n    fmt.Printf("%d bytes @ %d: ", n2, o2)\n    fmt.Printf("%v\\n", string(b2[:n2]))
\n
\n

Other methods of seeking are relative to the\ncurrent cursor position,

\n\n 		\n \n 
    _, err = f.Seek(2, io.SeekCurrent)\n    check(err)
\n
\n

and relative to the end of the file.

\n\n 		\n \n 
    _, err = f.Seek(-4, io.SeekEnd)\n    check(err)
\n
\n

The io package provides some functions that may\nbe helpful for file reading. For example, reads\nlike the ones above can be more robustly\nimplemented with ReadAtLeast.

\n\n 		\n \n 
    o3, err := f.Seek(6, io.SeekStart)\n    check(err)\n    b3 := make([]byte, 2)\n    n3, err := io.ReadAtLeast(f, b3, 2)\n    check(err)\n    fmt.Printf("%d bytes @ %d: %s\\n", n3, o3, string(b3))
\n
\n

There is no built-in rewind, but\nSeek(0, io.SeekStart) accomplishes this.

\n\n 		\n \n 
    _, err = f.Seek(0, io.SeekStart)\n    check(err)
\n
\n

The bufio package implements a buffered\nreader that may be useful both for its efficiency\nwith many small reads and because of the additional\nreading methods it provides.

\n\n 		\n \n 
    r4 := bufio.NewReader(f)\n    b4, err := r4.Peek(5)\n    check(err)\n    fmt.Printf("5 bytes: %s\\n", string(b4))
\n
\n

Close the file when you’re done (usually this would\nbe scheduled immediately after Opening with\ndefer).

\n\n 		\n \n 
    f.Close()\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ echo "hello" > /tmp/dat\n$ echo "go" >>   /tmp/dat\n$ go run reading-files.go\nhello\ngo\n5 bytes: hello\n2 bytes @ 6: go\n2 bytes @ 6: go\n5 bytes: hello
\n
\n

Next we’ll look at writing files.

\n\n 		\n \n \n
\n \n \n

\n Next example: Writing Files.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/recover", "content": "\n\n \n \n Go by Example: Recover\n \n \n \n \n
\n

Go by Example: Recover

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go makes it possible to recover from a panic, by\nusing the recover built-in function. A recover can\nstop a panic from aborting the program and let it\ncontinue with execution instead.

\n\n 		\n \n \n
\n

An example of where this can be useful: a server\nwouldn’t want to crash if one of the client connections\nexhibits a critical error. Instead, the server would\nwant to close that connection and continue serving\nother clients. In fact, this is what Go’s net/http\ndoes by default for HTTP servers.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n

This function panics.

\n\n 		\n \n 
func mayPanic() {\n    panic("a problem")\n}
\n
\n

recover must be called within a deferred function.\nWhen the enclosing function panics, the defer will\nactivate and a recover call within it will catch\nthe panic.

\n\n 		\n \n 
func main() {
\n
\n

The return value of recover is the error raised in\nthe call to panic.

\n\n 		\n \n 
    defer func() {\n        if r := recover(); r != nil {
\n
\n \n \n \n 
            fmt.Println("Recovered. Error:\\n", r)\n        }\n    }()
\n
\n \n \n \n 
    mayPanic()
\n
\n

This code will not run, because mayPanic panics.\nThe execution of main stops at the point of the\npanic and resumes in the deferred closure.

\n\n 		\n \n 
    fmt.Println("After mayPanic()")\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run recover.go\nRecovered. Error:\n a problem
\n
\n \n \n

\n Next example: String Functions.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/recursion", "content": "\n\n \n \n Go by Example: Recursion\n \n \n \n \n
\n

Go by Example: Recursion

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go supports\nrecursive functions.\nHere’s a classic example.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n

This fact function calls itself until it reaches the\nbase case of fact(0).

\n\n 		\n \n 
func fact(n int) int {\n    if n == 0 {\n        return 1\n    }\n    return n * fact(n-1)\n}
\n
\n \n \n \n 
func main() {\n    fmt.Println(fact(7))
\n
\n

Anonymous functions can also be recursive, but this requires\nexplicitly declaring a variable with var to store\nthe function before it’s defined.

\n\n 		\n \n 
    var fib func(n int) int
\n
\n \n \n \n 
    fib = func(n int) int {\n        if n < 2 {\n            return n\n        }
\n
\n

Since fib was previously declared in main, Go\nknows which function to call with fib here.

\n\n 		\n \n 
        return fib(n-1) + fib(n-2)\n    }
\n
\n \n \n \n 
    fmt.Println(fib(7))\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run recursion.go \n5040\n13
\n
\n \n \n

\n Next example: Range over Built-in Types.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/regular-expressions", "content": "\n\n \n \n Go by Example: Regular Expressions\n \n \n \n \n
\n

Go by Example: Regular Expressions

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go offers built-in support for regular expressions.\nHere are some examples of common regexp-related tasks\nin Go.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "bytes"\n    "fmt"\n    "regexp"\n)
\n
\n \n \n \n 
func main() {
\n
\n

This tests whether a pattern matches a string.

\n\n 		\n \n 
    match, _ := regexp.MatchString("p([a-z]+)ch", "peach")\n    fmt.Println(match)
\n
\n

Above we used a string pattern directly, but for\nother regexp tasks you’ll need to Compile an\noptimized Regexp struct.

\n\n 		\n \n 
    r, _ := regexp.Compile("p([a-z]+)ch")
\n
\n

Many methods are available on these structs. Here’s\na match test like we saw earlier.

\n\n 		\n \n 
    fmt.Println(r.MatchString("peach"))
\n
\n

This finds the match for the regexp.

\n\n 		\n \n 
    fmt.Println(r.FindString("peach punch"))
\n
\n

This also finds the first match but returns the\nstart and end indexes for the match instead of the\nmatching text.

\n\n 		\n \n 
    fmt.Println("idx:", r.FindStringIndex("peach punch"))
\n
\n

The Submatch variants include information about\nboth the whole-pattern matches and the submatches\nwithin those matches. For example this will return\ninformation for both p([a-z]+)ch and ([a-z]+).

\n\n 		\n \n 
    fmt.Println(r.FindStringSubmatch("peach punch"))
\n
\n

Similarly this will return information about the\nindexes of matches and submatches.

\n\n 		\n \n 
    fmt.Println(r.FindStringSubmatchIndex("peach punch"))
\n
\n

The All variants of these functions apply to all\nmatches in the input, not just the first. For\nexample to find all matches for a regexp.

\n\n 		\n \n 
    fmt.Println(r.FindAllString("peach punch pinch", -1))
\n
\n

These All variants are available for the other\nfunctions we saw above as well.

\n\n 		\n \n 
    fmt.Println("all:", r.FindAllStringSubmatchIndex(\n        "peach punch pinch", -1))
\n
\n

Providing a non-negative integer as the second\nargument to these functions will limit the number\nof matches.

\n\n 		\n \n 
    fmt.Println(r.FindAllString("peach punch pinch", 2))
\n
\n

Our examples above had string arguments and used\nnames like MatchString. We can also provide\n[]byte arguments and drop String from the\nfunction name.

\n\n 		\n \n 
    fmt.Println(r.Match([]byte("peach")))
\n
\n

When creating global variables with regular\nexpressions you can use the MustCompile variation\nof Compile. MustCompile panics instead of\nreturning an error, which makes it safer to use for\nglobal variables.

\n\n 		\n \n 
    r = regexp.MustCompile("p([a-z]+)ch")\n    fmt.Println("regexp:", r)
\n
\n

The regexp package can also be used to replace\nsubsets of strings with other values.

\n\n 		\n \n 
    fmt.Println(r.ReplaceAllString("a peach", "<fruit>"))
\n
\n

The Func variant allows you to transform matched\ntext with a given function.

\n\n 		\n \n 
    in := []byte("a peach")\n    out := r.ReplaceAllFunc(in, bytes.ToUpper)\n    fmt.Println(string(out))\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run regular-expressions.go\ntrue\ntrue\npeach\nidx: [0 5]\n[peach ea]\n[0 5 1 3]\n[peach punch pinch]\nall: [[0 5 1 3] [6 11 7 9] [12 17 13 15]]\n[peach punch]\ntrue\nregexp: p([a-z]+)ch\na <fruit>\na PEACH
\n
\n

For a complete reference on Go regular expressions check\nthe regexp package docs.

\n\n 		\n \n \n
\n \n \n

\n Next example: JSON.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/select", "content": "\n\n \n \n Go by Example: Select\n \n \n \n \n
\n

Go by Example: Select

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go’s select lets you wait on multiple channel\noperations. Combining goroutines and channels with\nselect is a powerful feature of Go.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "time"\n)
\n
\n \n \n \n 
func main() {
\n
\n

For our example we’ll select across two channels.

\n\n 		\n \n 
    c1 := make(chan string)\n    c2 := make(chan string)
\n
\n

Each channel will receive a value after some amount\nof time, to simulate e.g. blocking RPC operations\nexecuting in concurrent goroutines.

\n\n 		\n \n 
    go func() {\n        time.Sleep(1 * time.Second)\n        c1 <- "one"\n    }()\n    go func() {\n        time.Sleep(2 * time.Second)\n        c2 <- "two"\n    }()
\n
\n

We’ll use select to await both of these values\nsimultaneously, printing each one as it arrives.

\n\n 		\n \n 
    for range 2 {\n        select {\n        case msg1 := <-c1:\n            fmt.Println("received", msg1)\n        case msg2 := <-c2:\n            fmt.Println("received", msg2)\n        }\n    }\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

We receive the values "one" and then "two" as\nexpected.

\n\n 		\n \n 
$ time go run select.go \nreceived one\nreceived two
\n
\n

Note that the total execution time is only ~2 seconds\nsince both the 1 and 2 second Sleeps execute\nconcurrently.

\n\n 		\n \n 
real    0m2.245s
\n
\n \n \n

\n Next example: Timeouts.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/sha256-hashes", "content": "\n\n \n \n Go by Example: SHA256 Hashes\n \n \n \n \n
\n

Go by Example: SHA256 Hashes

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

SHA256 hashes are\nfrequently used to compute short identities for binary\nor text blobs. For example, TLS/SSL certificates use SHA256\nto compute a certificate’s signature. Here’s how to compute\nSHA256 hashes in Go.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n

Go implements several hash functions in various\ncrypto/* packages.

\n\n 		\n \n 
import (\n    "crypto/sha256"\n    "fmt"\n)
\n
\n \n \n \n 
func main() {\n    s := "sha256 this string"
\n
\n

Here we start with a new hash.

\n\n 		\n \n 
    h := sha256.New()
\n
\n

Write expects bytes. If you have a string s,\nuse []byte(s) to coerce it to bytes.

\n\n 		\n \n 
    h.Write([]byte(s))
\n
\n

This gets the finalized hash result as a byte\nslice. The argument to Sum can be used to append\nto an existing byte slice: it usually isn’t needed.

\n\n 		\n \n 
    bs := h.Sum(nil)
\n
\n \n \n \n 
    fmt.Println(s)\n    fmt.Printf("%x\\n", bs)\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Running the program computes the hash and prints it in\na human-readable hex format.

\n\n 		\n \n 
$ go run sha256-hashes.go\nsha256 this string\n1af1dfa857bf1d8814fe1af8983c18080019922e557f15a8a...
\n
\n

You can compute other hashes using a similar pattern to\nthe one shown above. For example, to compute\nSHA512 hashes import crypto/sha512 and use\nsha512.New().

\n\n 		\n \n \n
\n

Note that if you need cryptographically secure hashes,\nyou should carefully research\nhash strength!

\n\n 		\n \n \n
\n \n \n

\n Next example: Base64 Encoding.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/signals", "content": "\n\n \n \n Go by Example: Signals\n \n \n \n \n
\n

Go by Example: Signals

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Sometimes we’d like our Go programs to intelligently\nhandle Unix signals.\nFor example, we might want a server to gracefully\nshutdown when it receives a SIGTERM, or a command-line\ntool to stop processing input if it receives a SIGINT.\nHere’s a modern way to handle signals using contexts.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "context"\n    "fmt"\n    "os/signal"\n    "syscall"\n)
\n
\n

signal.NotifyContext returns a context that’s canceled\nwhen one of the listed signals arrives.

\n\n 		\n \n 
func main() {
\n
\n \n \n \n 
    ctx, stop := signal.NotifyContext(\n        context.Background(), syscall.SIGINT, syscall.SIGTERM)\n    defer stop()
\n
\n

The program will wait here until one of the\nconfigured signals is received.

\n\n 		\n \n 
    fmt.Println("awaiting signal")\n    <-ctx.Done()
\n
\n

context.Cause reports why the context was canceled.\nFor a signal-triggered cancellation, this includes\nthe signal value.

\n\n 		\n \n 
    fmt.Println()\n    fmt.Println(context.Cause(ctx))\n    fmt.Println("exiting")\n}
\n
\n \n \n \n \n \n \n \n \n
\n

When we run this program it will block waiting for a\nsignal. By typing ctrl-C (which the\nterminal shows as ^C) we can send a SIGINT signal,\ncausing the program to print the cancellation cause and then exit.

\n\n 		\n \n 
$ go run signals.go\nawaiting signal\n^C\ninterrupt signal received\nexiting
\n
\n \n \n

\n Next example: Exit.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/site.css", "content": "/* CSS reset: https://meyerweb.com/eric/tools/css/reset/ */\nhtml, body, div, span, applet, object, iframe,\nh1, h2, h3, h4, h5, h6, p, blockquote, pre,\na, abbr, acronym, address, big, cite, code,\ndel, dfn, em, img, ins, kbd, q, s, samp,\nsmall, strike, strong, sub, sup, tt, var,\nb, u, i, center,\ndl, dt, dd, ol, ul, li,\nfieldset, form, label, legend,\ntable, caption, tbody, tfoot, thead, tr, th, td,\narticle, aside, canvas, details, embed,\nfigure, figcaption, footer, header, hgroup,\nmenu, nav, output, ruby, section, summary,\ntime, mark, audio, video {\n margin: 0;\n padding: 0;\n border: 0;\n font-size: 100%;\n font: inherit;\n vertical-align: baseline;\n}\narticle, aside, details, figcaption, figure,\nfooter, header, hgroup, menu, nav, section {\n display: block;\n}\nbody {\n line-height: 1;\n}\nol, ul {\n list-style: none;\n}\nblockquote, q {\n quotes: none;\n}\nblockquote:before, blockquote:after,\nq:before, q:after {\n content: '';\n content: none;\n}\ntable {\n border-collapse: collapse;\n border-spacing: 0;\n}\n\n\n/* Layout and typography */\nbody {\n font-family: 'Georgia', serif;\n font-size: 16px;\n line-height: 20px;\n}\nem {\n font-style: italic;\n}\nh2 {\n font-size: 32px;\n line-height: 40px;\n margin-top: 40px;\n}\nh2 a {\n text-decoration: none;\n}\ndiv.example {\n width: 995px;\n max-width: calc(100% - 24px);\n margin-left: auto;\n margin-right: auto;\n margin-bottom: 120px;\n}\ndiv.example table {\n margin-top: 15px;\n margin-bottom: 20px;\n}\np.next {\n margin-bottom: 20px;\n}\np.footer {\n font-size: 75%;\n}\ndiv#intro {\n width: 420px;\n min-width: 420px;\n max-width: 420px;\n margin-left: auto;\n margin-right: auto;\n margin-bottom: 120px;\n}\ndiv#intro p {\n padding-top: 20px;\n}\ndiv#intro ul {\n padding-top: 20px;\n}\ntable td {\n border: 0;\n outline: 0;\n}\ntd.docs {\n width: 420px;\n max-width: 420px;\n min-width: 420px;\n min-height: 5px;\n vertical-align: top;\n text-align: left;\n}\ntd.docs p {\n padding-right: 5px;\n padding-top: 5px;\n padding-bottom: 15px;\n}\ntd.code {\n width: 575px;\n max-width: 575px;\n min-width: 575px;\n padding-top: 5px;\n padding-right: 5px;\n padding-left: 5px;\n padding-bottom: 5px;\n vertical-align: top;\n}\ntd.code.leading {\n padding-bottom: 11px;\n}\npre, code {\n font-size: 14px; line-height: 18px;\n font-family: 'Menlo', 'Monaco', 'Consolas', 'Lucida Console', monospace;\n}\nimg.copy, img.run {\n height: 16px;\n width: 16px;\n float: right\n}\nimg.copy, img.run {\n cursor: pointer;\n}\nimg.copy {\n margin-right: 4px;\n}\n\n\n/* Colors: light mode */\nbody {\n background-color: #ffffff;\n color: #252519;\n}\ntd.code.empty {\n background: #ffffff;\n}\na, a:visited {\n color: #261a3b;\n}\np.footer {\n color: #808080;\n}\np.footer a, p.footer a:visited {\n color: #808080;\n}\ntd.code {\n background: #f0f0f0;\n}\n\n/* Syntax highlighting: light mode */\nbody .nx { } /* Name.Other: package, variable, struct, param, generic type names, etc. */\nbody .nf { } /* Name.Function: function names (def and call) */\nbody .o { } /* Operator: :=, &, *, +, &&, <, etc. */\nbody .p { } /* Plain: = , . : [ ( { etc. */\nbody .k { color: #954121 } /* Keyword: if, for, range, return, defer, etc. */\nbody .kc { color: #954121 } /* Keyword.Constant: nil, true, false */\nbody .kd { color: #954121 } /* Keyword.Declaration: func, var, type, struct, map, chan, etc. */\nbody .kn { color: #954121 } /* Keyword.Namespace: package, import */\nbody .nb { color: #954121 } /* Name.Builtin: make, len, delete, append, etc. */\nbody .kt { color: #b00040 } /* Keyword.Type: string, int, byte, error, etc. */\nbody .m { color: #666666 } /* Literal.Number */\nbody .mf { color: #666666 } /* Literal.Number.Float */\nbody .mh { color: #666666 } /* Literal.Number.Hex */\nbody .mi { color: #666666 } /* Literal.Number.Integer */\nbody .mo { color: #666666 } /* Literal.Number.Oct */\nbody .s { color: #219161 } /* Literal.String */\nbody .sc { color: #219161 } /* Literal.String.Char */\nbody .gp { color: #000080 } /* Generic.Prompt: shell prompt */\nbody .go { color: #808080 } /* Generic.Output: shell output */\nbody .c1 { color: #808080 } /* Comment.Single */\n\n\n@media (prefers-color-scheme: dark) {\n /* Colors: dark mode */\n body {\n background-color: #1f1f1f;\n color: #dadada;\n }\n td.code.empty {\n background: #1f1f1f;\n }\n a, a:visited {\n color: #e4e4e4;\n }\n p.footer {\n color: #898e98;\n }\n p.footer a, p.footer a:visited {\n color: #898e98;\n }\n td.code {\n background: #282828;\n }\n\n \n /* Syntax highlighting: dark mode */\n body .nx { } /* Name.Other */\n body .nf { } /* Name.Function */\n body .o { } /* Operator */\n body .p { } /* Plain */\n body .k { color: #af5a54 } /* Keyword */\n body .kc { color: #af5a54 } /* Keyword.Constant */\n body .kd { color: #af5a54 } /* Keyword.Declaration */\n body .kn { color: #af5a54 } /* Keyword.Namespace */\n body .nb { color: #af5a54 } /* Name.Builtin */\n body .kt { color: #b64343 } /* Keyword.Type */\n body .m { color: #688ec8 } /* Literal.Number */\n body .mf { color: #688ec8 } /* Literal.Number.Float */\n body .mh { color: #688ec8 } /* Literal.Number.Hex */\n body .mi { color: #688ec8 } /* Literal.Number.Integer */\n body .mo { color: #688ec8 } /* Literal.Number.Oct */\n body .s { color: #718e72 } /* Literal.String */\n body .sc { color: #718e72 } /* Literal.String.Char */\n body .gp { color: #8a6ab1 } /* Generic.Prompt */\n body .go { color: #868686 } /* Generic.Output */\n body .c1 { color: #868686 } /* Comment.Single */\n}\n" }, { "path": "public/site.js", "content": "/*!\r\n * clipboard.js v1.5.13\r\n * https://zenorocha.github.io/clipboard.js\r\n *\r\n * Licensed MIT © Zeno Rocha\r\n */\r\n!function(t){if(\"object\"==typeof exports&&\"undefined\"!=typeof module)module.exports=t();else if(\"function\"==typeof define&&define.amd)define([],t);else{var e;e=\"undefined\"!=typeof window?window:\"undefined\"!=typeof global?global:\"undefined\"!=typeof self?self:this,e.Clipboard=t()}}(function(){var t,e,n;return function t(e,n,o){function r(c,a){if(!n[c]){if(!e[c]){var l=\"function\"==typeof require&&require;if(!a&&l)return l(c,!0);if(i)return i(c,!0);var s=new Error(\"Cannot find module '\"+c+\"'\");throw s.code=\"MODULE_NOT_FOUND\",s}var u=n[c]={exports:{}};e[c][0].call(u.exports,function(t){var n=e[c][1][t];return r(n?n:t)},u,u.exports,t,e,n,o)}return n[c].exports}for(var i=\"function\"==typeof require&&require,c=0;c\n\n \n \n Go by Example: Slices\n \n \n \n \n
\n

Go by Example: Slices

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Slices are an important data type in Go, giving\na more powerful interface to sequences than arrays.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "slices"\n)
\n
\n \n \n \n 
func main() {
\n
\n

Unlike arrays, slices are typed only by the\nelements they contain (not the number of elements).\nAn uninitialized slice equals to nil and has\nlength 0.

\n\n 		\n \n 
    var s []string\n    fmt.Println("uninit:", s, s == nil, len(s) == 0)
\n
\n

To create a slice with non-zero length, use\nthe builtin make. Here we make a slice of\nstrings of length 3 (initially zero-valued).\nBy default a new slice’s capacity is equal to its\nlength; if we know the slice is going to grow ahead\nof time, it’s possible to pass a capacity explicitly\nas an additional parameter to make.

\n\n 		\n \n 
    s = make([]string, 3)\n    fmt.Println("emp:", s, "len:", len(s), "cap:", cap(s))
\n
\n

We can set and get just like with arrays.

\n\n 		\n \n 
    s[0] = "a"\n    s[1] = "b"\n    s[2] = "c"\n    fmt.Println("set:", s)\n    fmt.Println("get:", s[2])
\n
\n

len returns the length of the slice as expected.

\n\n 		\n \n 
    fmt.Println("len:", len(s))
\n
\n

In addition to these basic operations, slices\nsupport several more that make them richer than\narrays. One is the builtin append, which\nreturns a slice containing one or more new values.\nNote that we need to accept a return value from\nappend as we may get a new slice value.

\n\n 		\n \n 
    s = append(s, "d")\n    s = append(s, "e", "f")\n    fmt.Println("apd:", s)
\n
\n

Slices can also be copy’d. Here we create an\nempty slice c of the same length as s and copy\ninto c from s.

\n\n 		\n \n 
    c := make([]string, len(s))\n    copy(c, s)\n    fmt.Println("cpy:", c)
\n
\n

Slices support a “slice” operator with the syntax\nslice[low:high]. For example, this gets a slice\nof the elements s[2], s[3], and s[4].

\n\n 		\n \n 
    l := s[2:5]\n    fmt.Println("sl1:", l)
\n
\n

This slices up to (but excluding) s[5].

\n\n 		\n \n 
    l = s[:5]\n    fmt.Println("sl2:", l)
\n
\n

And this slices up from (and including) s[2].

\n\n 		\n \n 
    l = s[2:]\n    fmt.Println("sl3:", l)
\n
\n

We can declare and initialize a variable for slice\nin a single line as well.

\n\n 		\n \n 
    t := []string{"g", "h", "i"}\n    fmt.Println("dcl:", t)
\n
\n

The slices package contains a number of useful\nutility functions for slices.

\n\n 		\n \n 
    t2 := []string{"g", "h", "i"}\n    if slices.Equal(t, t2) {\n        fmt.Println("t == t2")\n    }
\n
\n

Slices can be composed into multi-dimensional data\nstructures. The length of the inner slices can\nvary, unlike with multi-dimensional arrays.

\n\n 		\n \n 
    twoD := make([][]int, 3)\n    for i := range 3 {\n        innerLen := i + 1\n        twoD[i] = make([]int, innerLen)\n        for j := range innerLen {\n            twoD[i][j] = i + j\n        }\n    }\n    fmt.Println("2d: ", twoD)\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Note that while slices are different types than arrays,\nthey are rendered similarly by fmt.Println.

\n\n 		\n \n 
$ go run slices.go\nuninit: [] true true\nemp: [  ] len: 3 cap: 3\nset: [a b c]\nget: c\nlen: 3\napd: [a b c d e f]\ncpy: [a b c d e f]\nsl1: [c d e]\nsl2: [a b c d e]\nsl3: [c d e f]\ndcl: [g h i]\nt == t2\n2d:  [[0] [1 2] [2 3 4]]
\n
\n

Check out this great blog post\nby the Go team for more details on the design and\nimplementation of slices in Go.

\n\n 		\n \n \n
\n

Now that we’ve seen arrays and slices we’ll look at\nGo’s other key builtin data structure: maps.

\n\n 		\n \n \n
\n \n \n

\n Next example: Maps.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/sorting", "content": "\n\n \n \n Go by Example: Sorting\n \n \n \n \n
\n

Go by Example: Sorting

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go’s slices package implements sorting for builtins\nand user-defined types. We’ll look at sorting for\nbuiltins first.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "slices"\n)
\n
\n \n \n \n 
func main() {
\n
\n

Sorting functions are generic, and work for any\nordered built-in type. For a list of ordered\ntypes, see cmp.Ordered.

\n\n 		\n \n 
    strs := []string{"c", "a", "b"}\n    slices.Sort(strs)\n    fmt.Println("Strings:", strs)
\n
\n

An example of sorting ints.

\n\n 		\n \n 
    ints := []int{7, 2, 4}\n    slices.Sort(ints)\n    fmt.Println("Ints:   ", ints)
\n
\n

We can also use the slices package to check if\na slice is already in sorted order.

\n\n 		\n \n 
    s := slices.IsSorted(ints)\n    fmt.Println("Sorted: ", s)\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run sorting.go\nStrings: [a b c]\nInts:    [2 4 7]\nSorted:  true
\n
\n \n \n

\n Next example: Sorting by Functions.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/sorting-by-functions", "content": "\n\n \n \n Go by Example: Sorting by Functions\n \n \n \n \n
\n

Go by Example: Sorting by Functions

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Sometimes we’ll want to sort a collection by something\nother than its natural order. For example, suppose we\nwanted to sort strings by their length instead of\nalphabetically. Here’s an example of custom sorts\nin Go.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "cmp"\n    "fmt"\n    "slices"\n)
\n
\n \n \n \n 
func main() {\n    fruits := []string{"peach", "banana", "kiwi"}
\n
\n

We implement a comparison function for string\nlengths. cmp.Compare is helpful for this.

\n\n 		\n \n 
    lenCmp := func(a, b string) int {\n        return cmp.Compare(len(a), len(b))\n    }
\n
\n

Now we can call slices.SortFunc with this custom\ncomparison function to sort fruits by name length.

\n\n 		\n \n 
    slices.SortFunc(fruits, lenCmp)\n    fmt.Println(fruits)
\n
\n

We can use the same technique to sort a slice of\nvalues that aren’t built-in types.

\n\n 		\n \n 
    type Person struct {\n        name string\n        age  int\n    }
\n
\n \n \n \n 
    people := []Person{\n        Person{name: "Jax", age: 37},\n        Person{name: "TJ", age: 25},\n        Person{name: "Alex", age: 72},\n    }
\n
\n

Sort people by age using slices.SortFunc.

\n\n

Note: if the Person struct is large,\nyou may want the slice to contain *Person instead\nand adjust the sorting function accordingly. If in\ndoubt, benchmark!

\n\n 		\n \n 
    slices.SortFunc(people,\n        func(a, b Person) int {\n            return cmp.Compare(a.age, b.age)\n        })\n    fmt.Println(people)\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run sorting-by-functions.go \n[kiwi peach banana]\n[{TJ 25} {Jax 37} {Alex 72}]
\n
\n \n \n

\n Next example: Panic.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/spawning-processes", "content": "\n\n \n \n Go by Example: Spawning Processes\n \n \n \n \n
\n

Go by Example: Spawning Processes

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Sometimes our Go programs need to spawn other\nprocesses.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "errors"\n    "fmt"\n    "io"\n    "os/exec"\n)
\n
\n \n \n \n 
func main() {
\n
\n

We’ll start with a simple command that takes no\narguments or input and just prints something to\nstdout. The exec.Command helper creates an object\nto represent this external process.

\n\n 		\n \n 
    dateCmd := exec.Command("date")
\n
\n

The Output method runs the command, waits for it\nto finish and collects its standard output.\n If there were no errors, dateOut will hold bytes\nwith the date info.

\n\n 		\n \n 
    dateOut, err := dateCmd.Output()\n    if err != nil {\n        panic(err)\n    }\n    fmt.Println("> date")\n    fmt.Println(string(dateOut))
\n
\n

Output and other methods of Command will return\n*exec.Error if there was a problem executing the\ncommand (e.g. wrong path), and *exec.ExitError\nif the command ran but exited with a non-zero return\ncode.

\n\n 		\n \n 
    _, err = exec.Command("date", "-x").Output()\n    if err != nil {\n        if e, ok := errors.AsType[*exec.Error](err); ok {\n            fmt.Println("failed executing:", e)\n        } else if e, ok := errors.AsType[*exec.ExitError](err); ok {\n            exitCode := e.ExitCode()\n            fmt.Println("command exit rc =", exitCode)\n        } else {\n            panic(err)\n        }\n    }
\n
\n

Next we’ll look at a slightly more involved case\nwhere we pipe data to the external process on its\nstdin and collect the results from its stdout.

\n\n 		\n \n 
    grepCmd := exec.Command("grep", "hello")
\n
\n

Here we explicitly grab input/output pipes, start\nthe process, write some input to it, read the\nresulting output, and finally wait for the process\nto exit.

\n\n 		\n \n 
    grepIn, _ := grepCmd.StdinPipe()\n    grepOut, _ := grepCmd.StdoutPipe()\n    grepCmd.Start()\n    grepIn.Write([]byte("hello grep\\ngoodbye grep"))\n    grepIn.Close()\n    grepBytes, _ := io.ReadAll(grepOut)\n    grepCmd.Wait()
\n
\n

We omitted error checks in the above example, but\nyou could use the usual if err != nil pattern for\nall of them. We also only collect the StdoutPipe\nresults, but you could collect the StderrPipe in\nexactly the same way.

\n\n 		\n \n 
    fmt.Println("> grep hello")\n    fmt.Println(string(grepBytes))
\n
\n

Note that when spawning commands we need to\nprovide an explicitly delineated command and\nargument array, vs. being able to just pass in one\ncommand-line string. If you want to spawn a full\ncommand with a string, you can use bash’s -c\noption:

\n\n 		\n \n 
    lsCmd := exec.Command("bash", "-c", "ls -a -l -h")\n    lsOut, err := lsCmd.Output()\n    if err != nil {\n        panic(err)\n    }\n    fmt.Println("> ls -a -l -h")\n    fmt.Println(string(lsOut))\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

The spawned programs return output that is the same\nas if we had run them directly from the command-line.

\n\n 		\n \n 
$ go run spawning-processes.go \n> date\nThu 05 May 2022 10:10:12 PM PDT
\n
\n

date doesn’t have a -x flag so it will exit with\nan error message and non-zero return code.

\n\n 		\n \n 
command exit rc = 1\n> grep hello\nhello grep
\n
\n \n \n \n 
> ls -a -l -h\ndrwxr-xr-x  4 mark 136B Oct 3 16:29 .\ndrwxr-xr-x 91 mark 3.0K Oct 3 12:50 ..\n-rw-r--r--  1 mark 1.3K Oct 3 16:28 spawning-processes.go
\n
\n \n \n

\n Next example: Exec'ing Processes.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/stateful-goroutines", "content": "\n\n \n \n Go by Example: Stateful Goroutines\n \n \n \n \n
\n

Go by Example: Stateful Goroutines

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

In the previous example we used explicit locking with\nmutexes to synchronize access to shared state\nacross multiple goroutines. Another option is to use the\nbuilt-in synchronization features of goroutines and\nchannels to achieve the same result. This channel-based\napproach aligns with Go’s ideas of sharing memory by\ncommunicating and having each piece of data owned\nby exactly one goroutine.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "math/rand"\n    "sync/atomic"\n    "time"\n)
\n
\n

In this example our state will be owned by a single\ngoroutine. This will guarantee that the data is never\ncorrupted with concurrent access. In order to read or\nwrite that state, other goroutines will send messages\nto the owning goroutine and receive corresponding\nreplies. These readOp and writeOp structs\nencapsulate those requests and a way for the owning\ngoroutine to respond.

\n\n 		\n \n 
type readOp struct {\n    key  int\n    resp chan int\n}\ntype writeOp struct {\n    key  int\n    val  int\n    resp chan bool\n}
\n
\n \n \n \n 
func main() {
\n
\n

As before we’ll count how many operations we perform.

\n\n 		\n \n 
    var readOps uint64\n    var writeOps uint64
\n
\n

The reads and writes channels will be used by\nother goroutines to issue read and write requests,\nrespectively.

\n\n 		\n \n 
    reads := make(chan readOp)\n    writes := make(chan writeOp)
\n
\n

Here is the goroutine that owns the state, which\nis a map as in the previous example but now private\nto the stateful goroutine. This goroutine repeatedly\nselects on the reads and writes channels,\nresponding to requests as they arrive. A response\nis executed by first performing the requested\noperation and then sending a value on the response\nchannel resp to indicate success (and the desired\nvalue in the case of reads).

\n\n 		\n \n 
    go func() {\n        var state = make(map[int]int)\n        for {\n            select {\n            case read := <-reads:\n                read.resp <- state[read.key]\n            case write := <-writes:\n                state[write.key] = write.val\n                write.resp <- true\n            }\n        }\n    }()
\n
\n

This starts 100 goroutines to issue reads to the\nstate-owning goroutine via the reads channel.\nEach read requires constructing a readOp, sending\nit over the reads channel, and then receiving the\nresult over the provided resp channel.

\n\n 		\n \n 
    for range 100 {\n        go func() {\n            for {\n                read := readOp{\n                    key:  rand.Intn(5),\n                    resp: make(chan int)}\n                reads <- read\n                <-read.resp\n                atomic.AddUint64(&readOps, 1)\n                time.Sleep(time.Millisecond)\n            }\n        }()\n    }
\n
\n

We start 10 writes as well, using a similar\napproach.

\n\n 		\n \n 
    for range 10 {\n        go func() {\n            for {\n                write := writeOp{\n                    key:  rand.Intn(5),\n                    val:  rand.Intn(100),\n                    resp: make(chan bool)}\n                writes <- write\n                <-write.resp\n                atomic.AddUint64(&writeOps, 1)\n                time.Sleep(time.Millisecond)\n            }\n        }()\n    }
\n
\n

Let the goroutines work for a second.

\n\n 		\n \n 
    time.Sleep(time.Second)
\n
\n

Finally, capture and report the op counts.

\n\n 		\n \n 
    readOpsFinal := atomic.LoadUint64(&readOps)\n    fmt.Println("readOps:", readOpsFinal)\n    writeOpsFinal := atomic.LoadUint64(&writeOps)\n    fmt.Println("writeOps:", writeOpsFinal)\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Running our program shows that the goroutine-based\nstate management example completes about 80,000\ntotal operations.

\n\n 		\n \n 
$ go run stateful-goroutines.go\nreadOps: 71708\nwriteOps: 7177
\n
\n

For this particular case the goroutine-based approach\nwas a bit more involved than the mutex-based one. It\nmight be useful in certain cases though, for example\nwhere you have other channels involved or when managing\nmultiple such mutexes would be error-prone. You should\nuse whichever approach feels most natural, especially\nwith respect to understanding the correctness of your\nprogram.

\n\n 		\n \n \n
\n \n \n

\n Next example: Sorting.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/string-formatting", "content": "\n\n \n \n Go by Example: String Formatting\n \n \n \n \n
\n

Go by Example: String Formatting

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go offers excellent support for string formatting in\nthe printf tradition. Here are some examples of\ncommon string formatting tasks.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "os"\n)
\n
\n \n \n \n 
type point struct {\n    x, y int\n}
\n
\n \n \n \n 
func main() {
\n
\n

Go offers several printing “verbs” designed to\nformat general Go values. For example, this prints\nan instance of our point struct.

\n\n 		\n \n 
    p := point{1, 2}\n    fmt.Printf("struct1: %v\\n", p)
\n
\n

If the value is a struct, the %+v variant will\ninclude the struct’s field names.

\n\n 		\n \n 
    fmt.Printf("struct2: %+v\\n", p)
\n
\n

The %#v variant prints a Go syntax representation\nof the value, i.e. the source code snippet that\nwould produce that value.

\n\n 		\n \n 
    fmt.Printf("struct3: %#v\\n", p)
\n
\n

To print the type of a value, use %T.

\n\n 		\n \n 
    fmt.Printf("type: %T\\n", p)
\n
\n

Formatting booleans is straight-forward.

\n\n 		\n \n 
    fmt.Printf("bool: %t\\n", true)
\n
\n

There are many options for formatting integers.\nUse %d for standard, base-10 formatting.

\n\n 		\n \n 
    fmt.Printf("int: %d\\n", 123)
\n
\n

This prints a binary representation.

\n\n 		\n \n 
    fmt.Printf("bin: %b\\n", 14)
\n
\n

This prints the character corresponding to the\ngiven integer.

\n\n 		\n \n 
    fmt.Printf("char: %c\\n", 33)
\n
\n

%x provides hex encoding.

\n\n 		\n \n 
    fmt.Printf("hex: %x\\n", 456)
\n
\n

There are also several formatting options for\nfloats. For basic decimal formatting use %f.

\n\n 		\n \n 
    fmt.Printf("float1: %f\\n", 78.9)
\n
\n

%e and %E format the float in (slightly\ndifferent versions of) scientific notation.

\n\n 		\n \n 
    fmt.Printf("float2: %e\\n", 123400000.0)\n    fmt.Printf("float3: %E\\n", 123400000.0)
\n
\n

For basic string printing use %s.

\n\n 		\n \n 
    fmt.Printf("str1: %s\\n", "\\"string\\"")
\n
\n

To double-quote strings as in Go source, use %q.

\n\n 		\n \n 
    fmt.Printf("str2: %q\\n", "\\"string\\"")
\n
\n

As with integers seen earlier, %x renders\nthe string in base-16, with two output characters\nper byte of input.

\n\n 		\n \n 
    fmt.Printf("str3: %x\\n", "hex this")
\n
\n

To print a representation of a pointer, use %p.

\n\n 		\n \n 
    fmt.Printf("pointer: %p\\n", &p)
\n
\n

When formatting numbers you will often want to\ncontrol the width and precision of the resulting\nfigure. To specify the width of an integer, use a\nnumber after the % in the verb. By default the\nresult will be right-justified and padded with\nspaces.

\n\n 		\n \n 
    fmt.Printf("width1: |%6d|%6d|\\n", 12, 345)
\n
\n

You can also specify the width of printed floats,\nthough usually you’ll also want to restrict the\ndecimal precision at the same time with the\nwidth.precision syntax.

\n\n 		\n \n 
    fmt.Printf("width2: |%6.2f|%6.2f|\\n", 1.2, 3.45)
\n
\n

To left-justify, use the - flag.

\n\n 		\n \n 
    fmt.Printf("width3: |%-6.2f|%-6.2f|\\n", 1.2, 3.45)
\n
\n

You may also want to control width when formatting\nstrings, especially to ensure that they align in\ntable-like output. For basic right-justified width.

\n\n 		\n \n 
    fmt.Printf("width4: |%6s|%6s|\\n", "foo", "b")
\n
\n

To left-justify use the - flag as with numbers.

\n\n 		\n \n 
    fmt.Printf("width5: |%-6s|%-6s|\\n", "foo", "b")
\n
\n

So far we’ve seen Printf, which prints the\nformatted string to os.Stdout. Sprintf formats\nand returns a string without printing it anywhere.

\n\n 		\n \n 
    s := fmt.Sprintf("sprintf: a %s", "string")\n    fmt.Println(s)
\n
\n

You can format+print to io.Writers other than\nos.Stdout using Fprintf.

\n\n 		\n \n 
    fmt.Fprintf(os.Stderr, "io: an %s\\n", "error")\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run string-formatting.go\nstruct1: {1 2}\nstruct2: {x:1 y:2}\nstruct3: main.point{x:1, y:2}\ntype: main.point\nbool: true\nint: 123\nbin: 1110\nchar: !\nhex: 1c8\nfloat1: 78.900000\nfloat2: 1.234000e+08\nfloat3: 1.234000E+08\nstr1: "string"\nstr2: "\\"string\\""\nstr3: 6865782074686973\npointer: 0xc0000ba000\nwidth1: |    12|   345|\nwidth2: |  1.20|  3.45|\nwidth3: |1.20  |3.45  |\nwidth4: |   foo|     b|\nwidth5: |foo   |b     |\nsprintf: a string\nio: an error
\n
\n \n \n

\n Next example: Text Templates.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/string-functions", "content": "\n\n \n \n Go by Example: String Functions\n \n \n \n \n
\n

Go by Example: String Functions

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

The standard library’s strings package provides many\nuseful string-related functions. Here are some examples\nto give you a sense of the package.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    s "strings"\n)
\n
\n

We alias fmt.Println to a shorter name as we’ll use\nit a lot below.

\n\n 		\n \n 
var p = fmt.Println
\n
\n \n \n \n 
func main() {
\n
\n

Here’s a sample of the functions available in\nstrings. Since these are functions from the\npackage, not methods on the string object itself,\nwe need to pass the string in question as the first\nargument to the function. You can find more\nfunctions in the strings\npackage docs.

\n\n 		\n \n 
    p("Contains:  ", s.Contains("test", "es"))\n    p("Count:     ", s.Count("test", "t"))\n    p("HasPrefix: ", s.HasPrefix("test", "te"))\n    p("HasSuffix: ", s.HasSuffix("test", "st"))\n    p("Index:     ", s.Index("test", "e"))\n    p("Join:      ", s.Join([]string{"a", "b"}, "-"))\n    p("Repeat:    ", s.Repeat("a", 5))\n    p("Replace:   ", s.Replace("foo", "o", "0", -1))\n    p("Replace:   ", s.Replace("foo", "o", "0", 1))\n    p("Split:     ", s.Split("a-b-c-d-e", "-"))\n    p("ToLower:   ", s.ToLower("TEST"))\n    p("ToUpper:   ", s.ToUpper("test"))\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run string-functions.go\nContains:   true\nCount:      2\nHasPrefix:  true\nHasSuffix:  true\nIndex:      1\nJoin:       a-b\nRepeat:     aaaaa\nReplace:    f00\nReplace:    f0o\nSplit:      [a b c d e]\nToLower:    test\nToUpper:    TEST
\n
\n \n \n

\n Next example: String Formatting.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/strings-and-runes", "content": "\n\n \n \n Go by Example: Strings and Runes\n \n \n \n \n
\n

Go by Example: Strings and Runes

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

A Go string is a read-only slice of bytes. The language\nand the standard library treat strings specially - as\ncontainers of text encoded in UTF-8.\nIn other languages, strings are made of “characters”.\nIn Go, the concept of a character is called a rune - it’s\nan integer that represents a Unicode code point.\nThis Go blog post is a good\nintroduction to the topic.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "unicode/utf8"\n)
\n
\n \n \n \n 
func main() {
\n
\n

s is a string assigned a literal value\nrepresenting the word “hello” in the Thai\nlanguage. Go string literals are UTF-8\nencoded text.

\n\n 		\n \n 
    const s = "สวัสดี"
\n
\n

Since strings are equivalent to []byte, this\nwill produce the length of the raw bytes stored within.

\n\n 		\n \n 
    fmt.Println("Len:", len(s))
\n
\n

Indexing into a string produces the raw byte values at\neach index. This loop generates the hex values of all\nthe bytes that constitute the code points in s.

\n\n 		\n \n 
    for i := 0; i < len(s); i++ {\n        fmt.Printf("%x ", s[i])\n    }\n    fmt.Println()
\n
\n

To count how many runes are in a string, we can use\nthe utf8 package. Note that the run-time of\nRuneCountInString depends on the size of the string,\nbecause it has to decode each UTF-8 rune sequentially.\nSome Thai characters are represented by UTF-8 code points\nthat can span multiple bytes, so the result of this count\nmay be surprising.

\n\n 		\n \n 
    fmt.Println("Rune count:", utf8.RuneCountInString(s))
\n
\n

A range loop handles strings specially and decodes\neach rune along with its offset in the string.

\n\n 		\n \n 
    for idx, runeValue := range s {\n        fmt.Printf("%#U starts at %d\\n", runeValue, idx)\n    }
\n
\n

We can achieve the same iteration by using the\nutf8.DecodeRuneInString function explicitly.

\n\n 		\n \n 
    fmt.Println("\\nUsing DecodeRuneInString")\n    for i, w := 0, 0; i < len(s); i += w {\n        runeValue, width := utf8.DecodeRuneInString(s[i:])\n        fmt.Printf("%#U starts at %d\\n", runeValue, i)\n        w = width
\n
\n

This demonstrates passing a rune value to a function.

\n\n 		\n \n 
        examineRune(runeValue)\n    }\n}
\n
\n \n \n \n 
func examineRune(r rune) {
\n
\n

Values enclosed in single quotes are rune literals. We\ncan compare a rune value to a rune literal directly.

\n\n 		\n \n 
    if r == 't' {\n        fmt.Println("found tee")\n    } else if r == 'ส' {\n        fmt.Println("found so sua")\n    }\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run strings-and-runes.go\nLen: 18\ne0 b8 aa e0 b8 a7 e0 b8 b1 e0 b8 aa e0 b8 94 e0 b8 b5 \nRune count: 6\nU+0E2A 'ส' starts at 0\nU+0E27 'ว' starts at 3\nU+0E31 'ั' starts at 6\nU+0E2A 'ส' starts at 9\nU+0E14 'ด' starts at 12\nU+0E35 'ี' starts at 15
\n
\n \n \n \n 
Using DecodeRuneInString\nU+0E2A 'ส' starts at 0\nfound so sua\nU+0E27 'ว' starts at 3\nU+0E31 'ั' starts at 6\nU+0E2A 'ส' starts at 9\nfound so sua\nU+0E14 'ด' starts at 12\nU+0E35 'ี' starts at 15
\n
\n \n \n

\n Next example: Structs.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/struct-embedding", "content": "\n\n \n \n Go by Example: Struct Embedding\n \n \n \n \n
\n

Go by Example: Struct Embedding

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go supports embedding of structs and interfaces\nto express a more seamless composition of types.\nThis is not to be confused with //go:embed which is\na go directive introduced in Go version 1.16+ to embed\nfiles and folders into the application binary.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n \n \n \n 
type base struct {\n    num int\n}
\n
\n \n \n \n 
func (b base) describe() string {\n    return fmt.Sprintf("base with num=%v", b.num)\n}
\n
\n

A container embeds a base. An embedding looks\nlike a field without a name.

\n\n 		\n \n 
type container struct {\n    base\n    str string\n}
\n
\n \n \n \n 
func main() {
\n
\n

When creating structs with literals, we have to\ninitialize the embedding explicitly; here the\nembedded type serves as the field name.

\n\n 		\n \n 
    co := container{\n        base: base{\n            num: 1,\n        },\n        str: "some name",\n    }
\n
\n

We can access the base’s fields directly on co,\ne.g. co.num.

\n\n 		\n \n 
    fmt.Printf("co={num: %v, str: %v}\\n", co.num, co.str)
\n
\n

Alternatively, we can spell out the full path using\nthe embedded type name.

\n\n 		\n \n 
    fmt.Println("also num:", co.base.num)
\n
\n

Since container embeds base, the methods of\nbase also become methods of a container. Here\nwe invoke a method that was embedded from base\ndirectly on co.

\n\n 		\n \n 
    fmt.Println("describe:", co.describe())
\n
\n \n \n \n 
    type describer interface {\n        describe() string\n    }
\n
\n

Embedding structs with methods may be used to bestow\ninterface implementations onto other structs. Here\nwe see that a container now implements the\ndescriber interface because it embeds base.

\n\n 		\n \n 
    var d describer = co\n    fmt.Println("describer:", d.describe())\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run struct-embedding.go\nco={num: 1, str: some name}\nalso num: 1\ndescribe: base with num=1\ndescriber: base with num=1
\n
\n \n \n

\n Next example: Generics.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/structs", "content": "\n\n \n \n Go by Example: Structs\n \n \n \n \n
\n

Go by Example: Structs

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go’s structs are typed collections of fields.\nThey’re useful for grouping data together to form\nrecords.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n

This person struct type has name and age fields.

\n\n 		\n \n 
type person struct {\n    name string\n    age  int\n}
\n
\n

newPerson constructs a new person struct with the given name.

\n\n 		\n \n 
func newPerson(name string) *person {
\n
\n

Go is a garbage collected language; you can safely\nreturn a pointer to a local variable - it will only\nbe cleaned up by the garbage collector when there\nare no active references to it.

\n\n 		\n \n 
    p := person{name: name}\n    p.age = 42\n    return &p\n}
\n
\n \n \n \n 
func main() {
\n
\n

This syntax creates a new struct.

\n\n 		\n \n 
    fmt.Println(person{"Bob", 20})
\n
\n

You can name the fields when initializing a struct.

\n\n 		\n \n 
    fmt.Println(person{name: "Alice", age: 30})
\n
\n

Omitted fields will be zero-valued.

\n\n 		\n \n 
    fmt.Println(person{name: "Fred"})
\n
\n

An & prefix yields a pointer to the struct.

\n\n 		\n \n 
    fmt.Println(&person{name: "Ann", age: 40})
\n
\n

It’s idiomatic to encapsulate new struct creation in constructor functions

\n\n 		\n \n 
    fmt.Println(newPerson("Jon"))
\n
\n

Access struct fields with a dot.

\n\n 		\n \n 
    s := person{name: "Sean", age: 50}\n    fmt.Println(s.name)
\n
\n

You can also use dots with struct pointers - the\npointers are automatically dereferenced.

\n\n 		\n \n 
    sp := &s\n    fmt.Println(sp.age)
\n
\n

Structs are mutable.

\n\n 		\n \n 
    sp.age = 51\n    fmt.Println(sp.age)
\n
\n

If a struct type is only used for a single value, we don’t\nhave to give it a name. The value can have an anonymous\nstruct type. This technique is commonly used for\ntable-driven tests.

\n\n 		\n \n 
    dog := struct {\n        name   string\n        isGood bool\n    }{\n        "Rex",\n        true,\n    }\n    fmt.Println(dog)\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run structs.go\n{Bob 20}\n{Alice 30}\n{Fred 0}\n&{Ann 40}\n&{Jon 42}\nSean\n50\n51\n{Rex true}
\n
\n \n \n

\n Next example: Methods.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/switch", "content": "\n\n \n \n Go by Example: Switch\n \n \n \n \n
\n

Go by Example: Switch

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Switch statements express conditionals across many\nbranches.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "time"\n)
\n
\n \n \n \n 
func main() {
\n
\n

Here’s a basic switch.

\n\n 		\n \n 
    i := 2\n    fmt.Print("Write ", i, " as ")\n    switch i {\n    case 1:\n        fmt.Println("one")\n    case 2:\n        fmt.Println("two")\n    case 3:\n        fmt.Println("three")\n    }
\n
\n

You can use commas to separate multiple expressions\nin the same case statement. We use the optional\ndefault case in this example as well.

\n\n 		\n \n 
    switch time.Now().Weekday() {\n    case time.Saturday, time.Sunday:\n        fmt.Println("It's the weekend")\n    default:\n        fmt.Println("It's a weekday")\n    }
\n
\n

switch without an expression is an alternate way\nto express if/else logic. Here we also show how the\ncase expressions can be non-constants.

\n\n 		\n \n 
    t := time.Now()\n    switch {\n    case t.Hour() < 12:\n        fmt.Println("It's before noon")\n    default:\n        fmt.Println("It's after noon")\n    }
\n
\n

A type switch compares types instead of values. You\ncan use this to discover the type of an interface\nvalue. In this example, the variable t will have the\ntype corresponding to its clause.

\n\n 		\n \n 
    whatAmI := func(i interface{}) {\n        switch t := i.(type) {\n        case bool:\n            fmt.Println("I'm a bool")\n        case int:\n            fmt.Println("I'm an int")\n        default:\n            fmt.Printf("Don't know type %T\\n", t)\n        }\n    }\n    whatAmI(true)\n    whatAmI(1)\n    whatAmI("hey")\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run switch.go \nWrite 2 as two\nIt's a weekday\nIt's after noon\nI'm a bool\nI'm an int\nDon't know type string
\n
\n \n \n

\n Next example: Arrays.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/tcp-server", "content": "\n\n \n \n Go by Example: TCP Server\n \n \n \n \n
\n

Go by Example: TCP Server

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

The net package provides the tools we need to easily build\nTCP socket servers.

\n\n 		\n \n 
package main
\n
\n \n \n \n 
import (\n    "bufio"\n    "fmt"\n    "log"\n    "net"\n    "strings"\n)
\n
\n \n \n \n 
func main() {
\n
\n

net.Listen starts the server on the given network\n(TCP) and address (port 8090 on all interfaces).

\n\n 		\n \n 
    listener, err := net.Listen("tcp", ":8090")\n    if err != nil {\n        log.Fatal("Error listening:", err)\n    }
\n
\n

Close the listener to free the port\nwhen the application exits.

\n\n 		\n \n 
    defer listener.Close()
\n
\n

Loop indefinitely to accept new client connections.

\n\n 		\n \n 
    for {
\n
\n

Wait for a connection.

\n\n 		\n \n 
        conn, err := listener.Accept()\n        if err != nil {\n            log.Println("Error accepting conn:", err)\n            continue\n        }
\n
\n

We use a goroutine here to handle the connection\nso that the main loop can continue accepting more\nconnections.

\n\n 		\n \n 
        go handleConnection(conn)\n    }\n}
\n
\n

handleConnection handles a single client connection,\nreading one line of text from the client and returning a response.

\n\n 		\n \n 
func handleConnection(conn net.Conn) {
\n
\n

Closing the connection releases resources when\nwe are finished interacting with the client.

\n\n 		\n \n 
    defer conn.Close()
\n
\n

Use bufio.NewReader to read one line of data\nfrom the client (terminated by a newline).

\n\n 		\n \n 
    reader := bufio.NewReader(conn)\n    message, err := reader.ReadString('\\n')\n    if err != nil {\n        log.Printf("Read error: %v", err)\n        return\n    }
\n
\n

Create and send a response back to the client,\ndemonstrating two-way communication.

\n\n 		\n \n 
    ackMsg := strings.ToUpper(strings.TrimSpace(message))\n    response := fmt.Sprintf("ACK: %s\\n", ackMsg)\n    _, err = conn.Write([]byte(response))\n    if err != nil {\n        log.Printf("Server write error: %v", err)\n    }\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Run the TCP server in the background.

\n\n 		\n \n 
$ go run tcp-server.go &
\n
\n

Send data and capture the response using netcat.

\n\n 		\n \n 
$ echo "Hello from netcat" | nc localhost 8090\nACK: HELLO FROM NETCAT
\n
\n \n \n

\n Next example: Context.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/temporary-files-and-directories", "content": "\n\n \n \n Go by Example: Temporary Files and Directories\n \n \n \n \n
\n

Go by Example: Temporary Files and Directories

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Throughout program execution, we often want to create\ndata that isn’t needed after the program exits.\nTemporary files and directories are useful for this\npurpose since they don’t pollute the file system over\ntime.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "os"\n    "path/filepath"\n)
\n
\n \n \n \n 
func check(e error) {\n    if e != nil {\n        panic(e)\n    }\n}
\n
\n \n \n \n 
func main() {
\n
\n

The easiest way to create a temporary file is by\ncalling os.CreateTemp. It creates a file and\nopens it for reading and writing. We provide ""\nas the first argument, so os.CreateTemp will\ncreate the file in the default location for our OS.

\n\n 		\n \n 
    f, err := os.CreateTemp("", "sample")\n    check(err)
\n
\n

Display the name of the temporary file. On\nUnix-based OSes the directory will likely be /tmp.\nThe file name starts with the prefix given as the\nsecond argument to os.CreateTemp and the rest\nis chosen automatically to ensure that concurrent\ncalls will always create different file names.

\n\n 		\n \n 
    fmt.Println("Temp file name:", f.Name())
\n
\n

Clean up the file after we’re done. The OS is\nlikely to clean up temporary files by itself after\nsome time, but it’s good practice to do this\nexplicitly.

\n\n 		\n \n 
    defer os.Remove(f.Name())
\n
\n

We can write some data to the file.

\n\n 		\n \n 
    _, err = f.Write([]byte{1, 2, 3, 4})\n    check(err)
\n
\n

If we intend to write many temporary files, we may\nprefer to create a temporary directory.\nos.MkdirTemp’s arguments are the same as\nCreateTemp’s, but it returns a directory name\nrather than an open file.

\n\n 		\n \n 
    dname, err := os.MkdirTemp("", "sampledir")\n    check(err)\n    fmt.Println("Temp dir name:", dname)
\n
\n \n \n \n 
    defer os.RemoveAll(dname)
\n
\n

Now we can synthesize temporary file names by\nprefixing them with our temporary directory.

\n\n 		\n \n 
    fname := filepath.Join(dname, "file1")\n    err = os.WriteFile(fname, []byte{1, 2}, 0666)\n    check(err)\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run temporary-files-and-directories.go\nTemp file name: /tmp/sample610887201\nTemp dir name: /tmp/sampledir898854668
\n
\n \n \n

\n Next example: Embed Directive.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/testing-and-benchmarking", "content": "\n\n \n \n Go by Example: Testing and Benchmarking\n \n \n \n \n
\n

Go by Example: Testing and Benchmarking

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Unit testing is an important part of writing\nprincipled Go programs. The testing package\nprovides the tools we need to write unit tests\nand the go test command runs tests.

\n\n 		\n \n \n
\n

For the sake of demonstration, this code is in package\nmain, but it could be any package. Testing code\ntypically lives in the same package as the code it tests.

\n\n 		\n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "testing"\n)
\n
\n

We’ll be testing this simple implementation of an\ninteger minimum. Typically, the code we’re testing\nwould be in a source file named something like\nintutils.go, and the test file for it would then\nbe named intutils_test.go.

\n\n 		\n \n 
func IntMin(a, b int) int {\n    if a < b {\n        return a\n    }\n    return b\n}
\n
\n

A test is created by writing a function with a name\nbeginning with Test.

\n\n 		\n \n 
func TestIntMinBasic(t *testing.T) {\n    ans := IntMin(2, -2)\n    if ans != -2 {
\n
\n

t.Error* will report test failures but continue\nexecuting the test. t.Fatal* will report test\nfailures and stop the test immediately.

\n\n 		\n \n 
        t.Errorf("IntMin(2, -2) = %d; want -2", ans)\n    }\n}
\n
\n

Writing tests can be repetitive, so it’s idiomatic to\nuse a table-driven style, where test inputs and\nexpected outputs are listed in a table and a single loop\nwalks over them and performs the test logic.

\n\n 		\n \n 
func TestIntMinTableDriven(t *testing.T) {\n    var tests = []struct {\n        a, b int\n        want int\n    }{\n        {0, 1, 0},\n        {1, 0, 0},\n        {2, -2, -2},\n        {0, -1, -1},\n        {-1, 0, -1},\n    }
\n
\n

t.Run enables running “subtests”, one for each\ntable entry. These are shown separately\nwhen executing go test -v.

\n\n 		\n \n 
    for _, tt := range tests {
\n
\n \n \n \n 
        testname := fmt.Sprintf("%d,%d", tt.a, tt.b)\n        t.Run(testname, func(t *testing.T) {\n            ans := IntMin(tt.a, tt.b)\n            if ans != tt.want {\n                t.Errorf("got %d, want %d", ans, tt.want)\n            }\n        })\n    }\n}
\n
\n

Benchmark tests typically go in _test.go files and are\nnamed beginning with Benchmark.\nAny code that’s required for the benchmark to run but should\nnot be measured goes before this loop.

\n\n 		\n \n 
func BenchmarkIntMin(b *testing.B) {\n    for b.Loop() {
\n
\n

The benchmark runner will automatically execute this loop\nbody many times to determine a reasonable estimate of the\nrun-time of a single iteration.

\n\n 		\n \n 
        IntMin(1, 2)\n    }\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Run all tests in the current project in verbose mode.

\n\n 		\n \n 
$ go test -v\n== RUN   TestIntMinBasic\n--- PASS: TestIntMinBasic (0.00s)\n=== RUN   TestIntMinTableDriven\n=== RUN   TestIntMinTableDriven/0,1\n=== RUN   TestIntMinTableDriven/1,0\n=== RUN   TestIntMinTableDriven/2,-2\n=== RUN   TestIntMinTableDriven/0,-1\n=== RUN   TestIntMinTableDriven/-1,0\n--- PASS: TestIntMinTableDriven (0.00s)\n    --- PASS: TestIntMinTableDriven/0,1 (0.00s)\n    --- PASS: TestIntMinTableDriven/1,0 (0.00s)\n    --- PASS: TestIntMinTableDriven/2,-2 (0.00s)\n    --- PASS: TestIntMinTableDriven/0,-1 (0.00s)\n    --- PASS: TestIntMinTableDriven/-1,0 (0.00s)\nPASS\nok      examples/testing-and-benchmarking    0.023s
\n
\n

Run all benchmarks in the current project. All tests\nare run prior to benchmarks. The bench flag filters\nbenchmark function names with a regexp.

\n\n 		\n \n 
$ go test -bench=.\ngoos: darwin\ngoarch: arm64\npkg: examples/testing\nBenchmarkIntMin-8 1000000000 0.3136 ns/op\nPASS\nok      examples/testing-and-benchmarking    0.351s
\n
\n \n \n

\n Next example: Command-Line Arguments.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/text-templates", "content": "\n\n \n \n Go by Example: Text Templates\n \n \n \n \n
\n

Go by Example: Text Templates

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go offers built-in support for creating dynamic content or showing customized\noutput to the user with the text/template package. A sibling package\nnamed html/template provides the same API but has additional security\nfeatures and should be used for generating HTML.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "os"\n    "text/template"\n)
\n
\n \n \n \n 
func main() {
\n
\n

We can create a new template and parse its body from\na string.\nTemplates are a mix of static text and “actions” enclosed in\n{{...}} that are used to dynamically insert content.

\n\n 		\n \n 
    t1 := template.New("t1")\n    t1, err := t1.Parse("Value is {{.}}\\n")\n    if err != nil {\n        panic(err)\n    }
\n
\n

Alternatively, we can use the template.Must function to\npanic in case Parse returns an error. This is especially\nuseful for templates initialized in the global scope.

\n\n 		\n \n 
    t1 = template.Must(t1.Parse("Value: {{.}}\\n"))
\n
\n

By “executing” the template we generate its text with\nspecific values for its actions. The {{.}} action is\nreplaced by the value passed as a parameter to Execute.

\n\n 		\n \n 
    t1.Execute(os.Stdout, "some text")\n    t1.Execute(os.Stdout, 5)\n    t1.Execute(os.Stdout, []string{\n        "Go",\n        "Rust",\n        "C++",\n        "C#",\n    })
\n
\n

Helper function we’ll use below.

\n\n 		\n \n 
    Create := func(name, t string) *template.Template {\n        return template.Must(template.New(name).Parse(t))\n    }
\n
\n

If the data is a struct we can use the {{.FieldName}} action to access\nits fields. The fields should be exported to be accessible when a\ntemplate is executing.

\n\n 		\n \n 
    t2 := Create("t2", "Name: {{.Name}}\\n")
\n
\n \n \n \n 
    t2.Execute(os.Stdout, struct {\n        Name string\n    }{"Jane Doe"})
\n
\n

The same applies to maps; with maps there is no restriction on the\ncase of key names.

\n\n 		\n \n 
    t2.Execute(os.Stdout, map[string]string{\n        "Name": "Mickey Mouse",\n    })
\n
\n

if/else provide conditional execution for templates. A value is considered\nfalse if it’s the default value of a type, such as 0, an empty string,\nnil pointer, etc.\nThis sample demonstrates another\nfeature of templates: using - in actions to trim whitespace.

\n\n 		\n \n 
    t3 := Create("t3",\n        "{{if . -}} yes {{else -}} no {{end}}\\n")\n    t3.Execute(os.Stdout, "not empty")\n    t3.Execute(os.Stdout, "")
\n
\n

range blocks let us loop through slices, arrays, maps or channels. Inside\nthe range block {{.}} is set to the current item of the iteration.

\n\n 		\n \n 
    t4 := Create("t4",\n        "Range: {{range .}}{{.}} {{end}}\\n")\n    t4.Execute(os.Stdout,\n        []string{\n            "Go",\n            "Rust",\n            "C++",\n            "C#",\n        })\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run templates.go \nValue: some text\nValue: 5\nValue: [Go Rust C++ C#]\nName: Jane Doe\nName: Mickey Mouse\nyes \nno \nRange: Go Rust C++ C#
\n
\n \n \n

\n Next example: Regular Expressions.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/tickers", "content": "\n\n \n \n Go by Example: Tickers\n \n \n \n \n
\n

Go by Example: Tickers

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Timers are for when you want to do\nsomething once in the future - tickers are for when\nyou want to do something repeatedly at regular\nintervals. Here’s an example of a ticker that ticks\nperiodically until we stop it.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "time"\n)
\n
\n \n \n \n 
func main() {
\n
\n

Tickers use a similar mechanism to timers: a\nchannel that is sent values. Here we’ll use the\nselect builtin on the channel to await the\nvalues as they arrive every 500ms.

\n\n 		\n \n 
    ticker := time.NewTicker(500 * time.Millisecond)\n    done := make(chan bool)
\n
\n \n \n \n 
    go func() {\n        for {\n            select {\n            case <-done:\n                return\n            case t := <-ticker.C:\n                fmt.Println("Tick at", t)\n            }\n        }\n    }()
\n
\n

Tickers can be stopped like timers. Once a ticker\nis stopped it won’t receive any more values on its\nchannel. We’ll stop ours after 1600ms.

\n\n 		\n \n 
    time.Sleep(1600 * time.Millisecond)\n    ticker.Stop()\n    done <- true\n    fmt.Println("Ticker stopped")\n}
\n
\n \n \n \n \n \n \n \n \n
\n

When we run this program the ticker should tick 3 times\nbefore we stop it.

\n\n 		\n \n 
$ go run tickers.go\nTick at 2012-09-23 11:29:56.487625 -0700 PDT\nTick at 2012-09-23 11:29:56.988063 -0700 PDT\nTick at 2012-09-23 11:29:57.488076 -0700 PDT\nTicker stopped
\n
\n \n \n

\n Next example: Worker Pools.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/time", "content": "\n\n \n \n Go by Example: Time\n \n \n \n \n
\n

Go by Example: Time

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go offers extensive support for times and durations;\nhere are some examples.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "time"\n)
\n
\n \n \n \n 
func main() {\n    p := fmt.Println
\n
\n

We’ll start by getting the current time.

\n\n 		\n \n 
    now := time.Now()\n    p(now)
\n
\n

You can build a time struct by providing the\nyear, month, day, etc. Times are always associated\nwith a Location, i.e. time zone.

\n\n 		\n \n 
    then := time.Date(\n        2009, 11, 17, 20, 34, 58, 651387237, time.UTC)\n    p(then)
\n
\n

You can extract the various components of the time\nvalue as expected.

\n\n 		\n \n 
    p(then.Year())\n    p(then.Month())\n    p(then.Day())\n    p(then.Hour())\n    p(then.Minute())\n    p(then.Second())\n    p(then.Nanosecond())\n    p(then.Location())
\n
\n

The Monday-Sunday Weekday is also available.

\n\n 		\n \n 
    p(then.Weekday())
\n
\n

These methods compare two times, testing if the\nfirst occurs before, after, or at the same time\nas the second, respectively.

\n\n 		\n \n 
    p(then.Before(now))\n    p(then.After(now))\n    p(then.Equal(now))
\n
\n

The Sub methods returns a Duration representing\nthe interval between two times.

\n\n 		\n \n 
    diff := now.Sub(then)\n    p(diff)
\n
\n

We can compute the length of the duration in\nvarious units.

\n\n 		\n \n 
    p(diff.Hours())\n    p(diff.Minutes())\n    p(diff.Seconds())\n    p(diff.Nanoseconds())
\n
\n

You can use Add to advance a time by a given\nduration, or with a - to move backwards by a\nduration.

\n\n 		\n \n 
    p(then.Add(diff))\n    p(then.Add(-diff))\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run time.go\n2012-10-31 15:50:13.793654 +0000 UTC\n2009-11-17 20:34:58.651387237 +0000 UTC\n2009\nNovember\n17\n20\n34\n58\n651387237\nUTC\nTuesday\ntrue\nfalse\nfalse\n25891h15m15.142266763s\n25891.25420618521\n1.5534752523711128e+06\n9.320851514226677e+07\n93208515142266763\n2012-10-31 15:50:13.793654 +0000 UTC\n2006-12-05 01:19:43.509120474 +0000 UTC
\n
\n

Next we’ll look at the related idea of time relative to\nthe Unix epoch.

\n\n 		\n \n \n
\n \n \n

\n Next example: Epoch.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/time-formatting-parsing", "content": "\n\n \n \n Go by Example: Time Formatting / Parsing\n \n \n \n \n
\n

Go by Example: Time Formatting / Parsing

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go supports time formatting and parsing via\npattern-based layouts.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "time"\n)
\n
\n \n \n \n 
func main() {\n    p := fmt.Println
\n
\n

Here’s a basic example of formatting a time\naccording to RFC3339, using the corresponding layout\nconstant.

\n\n 		\n \n 
    t := time.Now()\n    p(t.Format(time.RFC3339))
\n
\n

Time parsing uses the same layout values as Format.

\n\n 		\n \n 
    t1, _ := time.Parse(time.RFC3339, "2012-11-01T22:08:41+00:00")\n    p(t1)
\n
\n

Format and Parse use example-based layouts. Usually\nyou’ll use a constant from time for these layouts, but\nyou can also supply custom layouts. Layouts must use the\nreference time Mon Jan 2 15:04:05 MST 2006 to show the\npattern with which to format/parse a given time/string.\nThe example time must be exactly as shown: the year 2006,\n15 for the hour, Monday for the day of the week, etc.

\n\n 		\n \n 
    p(t.Format("3:04PM"))\n    p(t.Format("Mon Jan _2 15:04:05 2006"))\n    p(t.Format("2006-01-02T15:04:05.999999-07:00"))\n    form := "3 04 PM"\n    t2, _ := time.Parse(form, "8 41 PM")\n    p(t2)
\n
\n

For purely numeric representations you can also\nuse standard string formatting with the extracted\ncomponents of the time value.

\n\n 		\n \n 
    fmt.Printf("%d-%02d-%02dT%02d:%02d:%02d-00:00\\n",\n        t.Year(), t.Month(), t.Day(),\n        t.Hour(), t.Minute(), t.Second())
\n
\n

Parse will return an error on malformed input\nexplaining the parsing problem.

\n\n 		\n \n 
    _, err := time.Parse("Mon Jan _2 15:04:05 2006", "8:41PM")\n    p(err)\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run time-formatting-parsing.go \n2014-04-15T18:00:15-07:00\n2012-11-01 22:08:41 +0000 +0000\n6:00PM\nTue Apr 15 18:00:15 2014\n2014-04-15T18:00:15.161182-07:00\n0000-01-01 20:41:00 +0000 UTC\n2014-04-15T18:00:15-00:00\nparsing time "8:41PM" as "Mon Jan _2 15:04:05 2006": ...
\n
\n \n \n

\n Next example: Random Numbers.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/timeouts", "content": "\n\n \n \n Go by Example: Timeouts\n \n \n \n \n
\n

Go by Example: Timeouts

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Timeouts are important for programs that connect to\nexternal resources or that otherwise need to bound\nexecution time. Implementing timeouts in Go is easy and\nelegant thanks to channels and select.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "time"\n)
\n
\n \n \n \n 
func main() {
\n
\n

For our example, suppose we’re executing an external\ncall that returns its result on a channel c1\nafter 2s. Note that the channel is buffered, so the\nsend in the goroutine is nonblocking. This is a\ncommon pattern to prevent goroutine leaks in case the\nchannel is never read.

\n\n 		\n \n 
    c1 := make(chan string, 1)\n    go func() {\n        time.Sleep(2 * time.Second)\n        c1 <- "result 1"\n    }()
\n
\n

Here’s the select implementing a timeout.\nres := <-c1 awaits the result and <-time.After\nawaits a value to be sent after the timeout of\n1s. Since select proceeds with the first\nreceive that’s ready, we’ll take the timeout case\nif the operation takes more than the allowed 1s.

\n\n 		\n \n 
    select {\n    case res := <-c1:\n        fmt.Println(res)\n    case <-time.After(1 * time.Second):\n        fmt.Println("timeout 1")\n    }
\n
\n

If we allow a longer timeout of 3s, then the receive\nfrom c2 will succeed and we’ll print the result.

\n\n 		\n \n 
    c2 := make(chan string, 1)\n    go func() {\n        time.Sleep(2 * time.Second)\n        c2 <- "result 2"\n    }()\n    select {\n    case res := <-c2:\n        fmt.Println(res)\n    case <-time.After(3 * time.Second):\n        fmt.Println("timeout 2")\n    }\n}
\n
\n \n \n \n \n \n \n \n \n
\n

Running this program shows the first operation timing\nout and the second succeeding.

\n\n 		\n \n 
$ go run timeouts.go \ntimeout 1\nresult 2
\n
\n \n \n

\n Next example: Non-Blocking Channel Operations.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/timers", "content": "\n\n \n \n Go by Example: Timers\n \n \n \n \n
\n

Go by Example: Timers

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

We often want to execute Go code at some point in the\nfuture, or repeatedly at some interval. Go’s built-in\ntimer and ticker features make both of these tasks\neasy. We’ll look first at timers and then\nat tickers.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "time"\n)
\n
\n \n \n \n 
func main() {
\n
\n

Timers represent a single event in the future. You\ntell the timer how long you want to wait, and it\nprovides a channel that will be notified at that\ntime. This timer will wait 2 seconds.

\n\n 		\n \n 
    timer1 := time.NewTimer(2 * time.Second)
\n
\n

The <-timer1.C blocks on the timer’s channel C\nuntil it sends a value indicating that the timer\nfired.

\n\n 		\n \n 
    <-timer1.C\n    fmt.Println("Timer 1 fired")
\n
\n

If you just wanted to wait, you could have used\ntime.Sleep. One reason a timer may be useful is\nthat you can cancel the timer before it fires.\nHere’s an example of that.

\n\n 		\n \n 
    timer2 := time.NewTimer(time.Second)\n    go func() {\n        <-timer2.C\n        fmt.Println("Timer 2 fired")\n    }()\n    stop2 := timer2.Stop()\n    if stop2 {\n        fmt.Println("Timer 2 stopped")\n    }
\n
\n

Give the timer2 enough time to fire, if it ever\nwas going to, to show it is in fact stopped.

\n\n 		\n \n 
    time.Sleep(2 * time.Second)\n}
\n
\n \n \n \n \n \n \n \n \n
\n

The first timer will fire ~2s after we start the\nprogram, but the second should be stopped before it has\na chance to fire.

\n\n 		\n \n 
$ go run timers.go\nTimer 1 fired\nTimer 2 stopped
\n
\n \n \n

\n Next example: Tickers.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/url-parsing", "content": "\n\n \n \n Go by Example: URL Parsing\n \n \n \n \n
\n

Go by Example: URL Parsing

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

URLs provide a uniform way to locate resources.\nHere’s how to parse URLs in Go.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "net"\n    "net/url"\n)
\n
\n \n \n \n 
func main() {
\n
\n

We’ll parse this example URL, which includes a\nscheme, authentication info, host, port, path,\nquery params, and query fragment.

\n\n 		\n \n 
    s := "postgres://user:pass@host.com:5432/path?k=v#f"
\n
\n

Parse the URL and ensure there are no errors.

\n\n 		\n \n 
    u, err := url.Parse(s)\n    if err != nil {\n        panic(err)\n    }
\n
\n

Accessing the scheme is straightforward.

\n\n 		\n \n 
    fmt.Println(u.Scheme)
\n
\n

User contains all authentication info; call\nUsername and Password on this for individual\nvalues.

\n\n 		\n \n 
    fmt.Println(u.User)\n    fmt.Println(u.User.Username())\n    p, _ := u.User.Password()\n    fmt.Println(p)
\n
\n

The Host contains both the hostname and the port,\nif present. Use SplitHostPort to extract them.

\n\n 		\n \n 
    fmt.Println(u.Host)\n    host, port, _ := net.SplitHostPort(u.Host)\n    fmt.Println(host)\n    fmt.Println(port)
\n
\n

Here we extract the path and the fragment after\nthe #.

\n\n 		\n \n 
    fmt.Println(u.Path)\n    fmt.Println(u.Fragment)
\n
\n

To get query params in a string of k=v format,\nuse RawQuery. You can also parse query params\ninto a map. The parsed query param maps are from\nstrings to slices of strings, so index into [0]\nif you only want the first value.

\n\n 		\n \n 
    fmt.Println(u.RawQuery)\n    m, _ := url.ParseQuery(u.RawQuery)\n    fmt.Println(m)\n    fmt.Println(m["k"][0])\n}
\n
\n \n \n \n \n \n \n \n \n
\n

Running our URL parsing program shows all the different\npieces that we extracted.

\n\n 		\n \n 
$ go run url-parsing.go \npostgres\nuser:pass\nuser\npass\nhost.com:5432\nhost.com\n5432\n/path\nf\nk=v\nmap[k:[v]]\nv
\n
\n \n \n

\n Next example: SHA256 Hashes.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/values", "content": "\n\n \n \n Go by Example: Values\n \n \n \n \n
\n

Go by Example: Values

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go has various value types including strings,\nintegers, floats, booleans, etc. Here are a few\nbasic examples.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n \n \n \n 
func main() {
\n
\n

Strings, which can be added together with +.

\n\n 		\n \n 
    fmt.Println("go" + "lang")
\n
\n

Integers and floats.

\n\n 		\n \n 
    fmt.Println("1+1 =", 1+1)\n    fmt.Println("7.0/3.0 =", 7.0/3.0)
\n
\n

Booleans, with boolean operators as you’d expect.

\n\n 		\n \n 
    fmt.Println(true && false)\n    fmt.Println(true || false)\n    fmt.Println(!true)\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run values.go\ngolang\n1+1 = 2\n7.0/3.0 = 2.3333333333333335\nfalse\ntrue\nfalse
\n
\n \n \n

\n Next example: Variables.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/variables", "content": "\n\n \n \n Go by Example: Variables\n \n \n \n \n
\n

Go by Example: Variables

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

In Go, variables are explicitly declared and used by\nthe compiler to e.g. check type-correctness of function\ncalls.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n \n \n \n 
func main() {
\n
\n

var declares 1 or more variables.

\n\n 		\n \n 
    var a = "initial"\n    fmt.Println(a)
\n
\n

You can declare multiple variables at once.

\n\n 		\n \n 
    var b, c int = 1, 2\n    fmt.Println(b, c)
\n
\n

Go will infer the type of initialized variables.

\n\n 		\n \n 
    var d = true\n    fmt.Println(d)
\n
\n

Variables declared without a corresponding\ninitialization are zero-valued. For example, the\nzero value for an int is 0.

\n\n 		\n \n 
    var e int\n    fmt.Println(e)
\n
\n

The := syntax is shorthand for declaring and\ninitializing a variable, e.g. for\nvar f string = "apple" in this case.\nThis syntax is only available inside functions.

\n\n 		\n \n 
    f := "apple"\n    fmt.Println(f)\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run variables.go\ninitial\n1 2\ntrue\n0\napple
\n
\n \n \n

\n Next example: Constants.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/variadic-functions", "content": "\n\n \n \n Go by Example: Variadic Functions\n \n \n \n \n
\n

Go by Example: Variadic Functions

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Variadic functions\ncan be called with any number of trailing arguments.\nFor example, fmt.Println is a common variadic\nfunction.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import "fmt"
\n
\n

Here’s a function that will take an arbitrary number\nof ints as arguments.

\n\n 		\n \n 
func sum(nums ...int) {\n    fmt.Print(nums, " ")\n    total := 0
\n
\n

Within the function, the type of nums is\nequivalent to []int. We can call len(nums),\niterate over it with range, etc.

\n\n 		\n \n 
    for _, num := range nums {\n        total += num\n    }\n    fmt.Println(total)\n}
\n
\n \n \n \n 
func main() {
\n
\n

Variadic functions can be called in the usual way\nwith individual arguments.

\n\n 		\n \n 
    sum(1, 2)\n    sum(1, 2, 3)
\n
\n

If you already have multiple args in a slice,\napply them to a variadic function using\nfunc(slice...) like this.

\n\n 		\n \n 
    nums := []int{1, 2, 3, 4}\n    sum(nums...)\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run variadic-functions.go \n[1 2] 3\n[1 2 3] 6\n[1 2 3 4] 10
\n
\n

Another key aspect of functions in Go is their ability\nto form closures, which we’ll look at next.

\n\n 		\n \n \n
\n \n \n

\n Next example: Closures.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/waitgroups", "content": "\n\n \n \n Go by Example: WaitGroups\n \n \n \n \n
\n

Go by Example: WaitGroups

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

To wait for multiple goroutines to finish, we can\nuse a wait group.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "sync"\n    "time"\n)
\n
\n

This is the function we’ll run in every goroutine.

\n\n 		\n \n 
func worker(id int) {\n    fmt.Printf("Worker %d starting\\n", id)
\n
\n

Sleep to simulate an expensive task.

\n\n 		\n \n 
    time.Sleep(time.Second)\n    fmt.Printf("Worker %d done\\n", id)\n}
\n
\n \n \n \n 
func main() {
\n
\n

This WaitGroup is used to wait for all the\ngoroutines launched here to finish. Note: if a WaitGroup is\nexplicitly passed into functions, it should be done by pointer.

\n\n 		\n \n 
    var wg sync.WaitGroup
\n
\n

Launch several goroutines using WaitGroup.Go

\n\n 		\n \n 
    for i := 1; i <= 5; i++ {\n        wg.Go(func() {\n            worker(i)\n        })\n    }
\n
\n

Block until all the goroutines started by wg are\ndone. A goroutine is done when the function it invokes\nreturns.

\n\n 		\n \n 
    wg.Wait()
\n
\n

Note that this approach has no straightforward way\nto propagate errors from workers. For more\nadvanced use cases, consider using the\nerrgroup package.

\n\n 		\n \n 
}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run waitgroups.go\nWorker 5 starting\nWorker 3 starting\nWorker 4 starting\nWorker 1 starting\nWorker 2 starting\nWorker 4 done\nWorker 1 done\nWorker 2 done\nWorker 5 done\nWorker 3 done
\n
\n

The order of workers starting up and finishing\nis likely to be different for each invocation.

\n\n 		\n \n \n
\n \n \n

\n Next example: Rate Limiting.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/worker-pools", "content": "\n\n \n \n Go by Example: Worker Pools\n \n \n \n \n
\n

Go by Example: Worker Pools

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

In this example we’ll look at how to implement\na worker pool using goroutines and channels.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "fmt"\n    "time"\n)
\n
\n

Here’s the worker, of which we’ll run several\nconcurrent instances. These workers will receive\nwork on the jobs channel and send the corresponding\nresults on results. We’ll sleep a second per job to\nsimulate an expensive task.

\n\n 		\n \n 
func worker(id int, jobs <-chan int, results chan<- int) {\n    for j := range jobs {\n        fmt.Println("worker", id, "started  job", j)\n        time.Sleep(time.Second)\n        fmt.Println("worker", id, "finished job", j)\n        results <- j * 2\n    }\n}
\n
\n \n \n \n 
func main() {
\n
\n

In order to use our pool of workers we need to send\nthem work and collect their results. We make 2\nchannels for this.

\n\n 		\n \n 
    const numJobs = 5\n    jobs := make(chan int, numJobs)\n    results := make(chan int, numJobs)
\n
\n

This starts up 3 workers, initially blocked\nbecause there are no jobs yet.

\n\n 		\n \n 
    for w := 1; w <= 3; w++ {\n        go worker(w, jobs, results)\n    }
\n
\n

Here we send 5 jobs and then close that\nchannel to indicate that’s all the work we have.

\n\n 		\n \n 
    for j := 1; j <= numJobs; j++ {\n        jobs <- j\n    }\n    close(jobs)
\n
\n

Finally we collect all the results of the work.\nThis also ensures that the worker goroutines have\nfinished. An alternative way to wait for multiple\ngoroutines is to use a WaitGroup.

\n\n 		\n \n 
    for a := 1; a <= numJobs; a++ {\n        <-results\n    }\n}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Our running program shows the 5 jobs being executed by\nvarious workers. The program only takes about 2 seconds\ndespite doing about 5 seconds of total work because\nthere are 3 workers operating concurrently.

\n\n 		\n \n 
$ time go run worker-pools.go \nworker 1 started  job 1\nworker 2 started  job 2\nworker 3 started  job 3\nworker 1 finished job 1\nworker 1 started  job 4\nworker 2 finished job 2\nworker 2 started  job 5\nworker 3 finished job 3\nworker 1 finished job 4\nworker 2 finished job 5
\n
\n \n \n \n 
real    0m2.358s
\n
\n \n \n

\n Next example: WaitGroups.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/writing-files", "content": "\n\n \n \n Go by Example: Writing Files\n \n \n \n \n
\n

Go by Example: Writing Files

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Writing files in Go follows similar patterns to the\nones we saw earlier for reading.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "bufio"\n    "fmt"\n    "os"\n    "path/filepath"\n)
\n
\n \n \n \n 
func check(e error) {\n    if e != nil {\n        panic(e)\n    }\n}
\n
\n \n \n \n 
func main() {
\n
\n

To start, here’s how to dump a string (or just\nbytes) into a file.

\n\n 		\n \n 
    d1 := []byte("hello\\ngo\\n")\n    path1 := filepath.Join(os.TempDir(), "dat1")\n    err := os.WriteFile(path1, d1, 0644)\n    check(err)
\n
\n

For more granular writes, open a file for writing.

\n\n 		\n \n 
    path2 := filepath.Join(os.TempDir(), "dat2")\n    f, err := os.Create(path2)\n    check(err)
\n
\n

It’s idiomatic to defer a Close immediately\nafter opening a file.

\n\n 		\n \n 
    defer f.Close()
\n
\n

You can Write byte slices as you’d expect.

\n\n 		\n \n 
    d2 := []byte{115, 111, 109, 101, 10}\n    n2, err := f.Write(d2)\n    check(err)\n    fmt.Printf("wrote %d bytes\\n", n2)
\n
\n

A WriteString is also available.

\n\n 		\n \n 
    n3, err := f.WriteString("writes\\n")\n    check(err)\n    fmt.Printf("wrote %d bytes\\n", n3)
\n
\n

Issue a Sync to flush writes to stable storage.

\n\n 		\n \n 
    f.Sync()
\n
\n

bufio provides buffered writers in addition\nto the buffered readers we saw earlier.

\n\n 		\n \n 
    w := bufio.NewWriter(f)\n    n4, err := w.WriteString("buffered\\n")\n    check(err)\n    fmt.Printf("wrote %d bytes\\n", n4)
\n
\n

Use Flush to ensure all buffered operations have\nbeen applied to the underlying writer.

\n\n 		\n \n 
    w.Flush()
\n
\n \n \n \n 
}
\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Try running the file-writing code.

\n\n 		\n \n 
$ go run writing-files.go \nwrote 5 bytes\nwrote 7 bytes\nwrote 9 bytes
\n
\n

Then check the contents of the written files.

\n\n 		\n \n 
$ cat /tmp/dat1\nhello\ngo\n$ cat /tmp/dat2\nsome\nwrites\nbuffered
\n
\n

Next we’ll look at applying some of the file I/O ideas\nwe’ve just seen to the stdin and stdout streams.

\n\n 		\n \n \n
\n \n \n

\n Next example: Line Filters.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "public/xml", "content": "\n\n \n \n Go by Example: XML\n \n \n \n \n
\n

Go by Example: XML

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

Go offers built-in support for XML and XML-like\nformats with the encoding/xml package.

\n\n 		\n \n \n
\n \n \n \n 
package main
\n
\n \n \n \n 
import (\n    "encoding/xml"\n    "fmt"\n)
\n
\n

Plant will be mapped to XML. Similarly to the\nJSON examples, field tags contain directives for the\nencoder and decoder. Here we use some special features\nof the XML package: the XMLName field name dictates\nthe name of the XML element representing this struct;\nid,attr means that the Id field is an XML\nattribute rather than a nested element.

\n\n 		\n \n 
type Plant struct {\n    XMLName xml.Name `xml:"plant"`\n    Id      int      `xml:"id,attr"`\n    Name    string   `xml:"name"`\n    Origin  []string `xml:"origin"`\n}
\n
\n \n \n \n 
func (p Plant) String() string {\n    return fmt.Sprintf("Plant id=%v, name=%v, origin=%v",\n        p.Id, p.Name, p.Origin)\n}
\n
\n \n \n \n 
func main() {\n    coffee := &Plant{Id: 27, Name: "Coffee"}\n    coffee.Origin = []string{"Ethiopia", "Brazil"}
\n
\n

Emit XML representing our plant; using\nMarshalIndent to produce a more\nhuman-readable output.

\n\n 		\n \n 
    out, _ := xml.MarshalIndent(coffee, " ", "  ")\n    fmt.Println(string(out))
\n
\n

To add a generic XML header to the output, append\nit explicitly.

\n\n 		\n \n 
    fmt.Println(xml.Header + string(out))
\n
\n

Use Unmarshal to parse a stream of bytes with XML\ninto a data structure. If the XML is malformed or\ncannot be mapped onto Plant, a descriptive error\nwill be returned.

\n\n 		\n \n 
    var p Plant\n    if err := xml.Unmarshal(out, &p); err != nil {\n        panic(err)\n    }\n    fmt.Println(p)
\n
\n \n \n \n 
    tomato := &Plant{Id: 81, Name: "Tomato"}\n    tomato.Origin = []string{"Mexico", "California"}
\n
\n

The parent>child>plant field tag tells the encoder\nto nest all plants under <parent><child>...

\n\n 		\n \n 
    type Nesting struct {\n        XMLName xml.Name `xml:"nesting"`\n        Plants  []*Plant `xml:"parent>child>plant"`\n    }
\n
\n \n \n \n 
    nesting := &Nesting{}\n    nesting.Plants = []*Plant{coffee, tomato}
\n
\n \n \n \n 
    out, _ = xml.MarshalIndent(nesting, " ", "  ")\n    fmt.Println(string(out))\n}
\n
\n \n \n \n \n \n \n \n \n
\n \n \n \n 
$ go run xml.go\n <plant id="27">\n   <name>Coffee</name>\n   <origin>Ethiopia</origin>\n   <origin>Brazil</origin>\n </plant>\n<?xml version="1.0" encoding="UTF-8"?>\n <plant id="27">\n   <name>Coffee</name>\n   <origin>Ethiopia</origin>\n   <origin>Brazil</origin>\n </plant>\nPlant id=27, name=Coffee, origin=[Ethiopia Brazil]\n <nesting>\n   <parent>\n     <child>\n       <plant id="27">\n         <name>Coffee</name>\n         <origin>Ethiopia</origin>\n         <origin>Brazil</origin>\n       </plant>\n       <plant id="81">\n         <name>Tomato</name>\n         <origin>Mexico</origin>\n         <origin>California</origin>\n       </plant>\n     </child>\n   </parent>\n </nesting>
\n
\n \n \n

\n Next example: Time.\n

\n \n\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n\n
\n \n \n \n\n" }, { "path": "templates/404.tmpl", "content": "\n\n \n \n Go by Example: Not Found\n \n \n \n
\n

Go by Example

\n

Sorry, we couldn't find that! Check out the home page?

\n{{ template \"footer\" }}\n
\n \n\n" }, { "path": "templates/example.tmpl", "content": "\n\n \n \n Go by Example: {{.Name}}\n \n \n \n \n
\n

Go by Example: {{.Name}}

\n {{range .Segs}}\n \n {{range .}}\n \n \n \n \n {{end}}\n
\n {{.DocsRendered}}\n \n {{if .CodeRun}}{{end}}\n {{.CodeRendered}}\n
\n {{end}}\n {{if .NextExample}}\n

\n Next example: {{.NextExample.Name}}.\n

\n {{end}}\n{{ template \"footer\" }}\n
\n \n \n \n\n" }, { "path": "templates/footer.tmpl", "content": "{{define \"footer\"}}\n

\n by Mark McGranaghan and Eli Bendersky | source | license\n

\n{{end}}\n" }, { "path": "templates/index.tmpl", "content": "\n\n \n \n Go by Example\n \n \n \n
\n

Go by Example

\n

\n Go is an\n open source programming language designed for\n building scalable, secure and reliable software.\n Please read the\n official documentation\n to learn more.\n

\n\n

\n Go by Example is a hands-on introduction\n to Go using annotated example programs. Check out\n the first example or\n browse the full list below.\n

\n\n

\n Unless stated otherwise, examples here assume the\n latest major release Go\n and may use new language features. Try to upgrade to the latest\n version if something isn't working.\n

\n\n \n{{ template \"footer\" }}\n
\n \n\n" }, { "path": "templates/site.css", "content": "/* CSS reset: https://meyerweb.com/eric/tools/css/reset/ */\nhtml, body, div, span, applet, object, iframe,\nh1, h2, h3, h4, h5, h6, p, blockquote, pre,\na, abbr, acronym, address, big, cite, code,\ndel, dfn, em, img, ins, kbd, q, s, samp,\nsmall, strike, strong, sub, sup, tt, var,\nb, u, i, center,\ndl, dt, dd, ol, ul, li,\nfieldset, form, label, legend,\ntable, caption, tbody, tfoot, thead, tr, th, td,\narticle, aside, canvas, details, embed,\nfigure, figcaption, footer, header, hgroup,\nmenu, nav, output, ruby, section, summary,\ntime, mark, audio, video {\n margin: 0;\n padding: 0;\n border: 0;\n font-size: 100%;\n font: inherit;\n vertical-align: baseline;\n}\narticle, aside, details, figcaption, figure,\nfooter, header, hgroup, menu, nav, section {\n display: block;\n}\nbody {\n line-height: 1;\n}\nol, ul {\n list-style: none;\n}\nblockquote, q {\n quotes: none;\n}\nblockquote:before, blockquote:after,\nq:before, q:after {\n content: '';\n content: none;\n}\ntable {\n border-collapse: collapse;\n border-spacing: 0;\n}\n\n\n/* Layout and typography */\nbody {\n font-family: 'Georgia', serif;\n font-size: 16px;\n line-height: 20px;\n}\nem {\n font-style: italic;\n}\nh2 {\n font-size: 32px;\n line-height: 40px;\n margin-top: 40px;\n}\nh2 a {\n text-decoration: none;\n}\ndiv.example {\n width: 995px;\n max-width: calc(100% - 24px);\n margin-left: auto;\n margin-right: auto;\n margin-bottom: 120px;\n}\ndiv.example table {\n margin-top: 15px;\n margin-bottom: 20px;\n}\np.next {\n margin-bottom: 20px;\n}\np.footer {\n font-size: 75%;\n}\ndiv#intro {\n width: 420px;\n min-width: 420px;\n max-width: 420px;\n margin-left: auto;\n margin-right: auto;\n margin-bottom: 120px;\n}\ndiv#intro p {\n padding-top: 20px;\n}\ndiv#intro ul {\n padding-top: 20px;\n}\ntable td {\n border: 0;\n outline: 0;\n}\ntd.docs {\n width: 420px;\n max-width: 420px;\n min-width: 420px;\n min-height: 5px;\n vertical-align: top;\n text-align: left;\n}\ntd.docs p {\n padding-right: 5px;\n padding-top: 5px;\n padding-bottom: 15px;\n}\ntd.code {\n width: 575px;\n max-width: 575px;\n min-width: 575px;\n padding-top: 5px;\n padding-right: 5px;\n padding-left: 5px;\n padding-bottom: 5px;\n vertical-align: top;\n}\ntd.code.leading {\n padding-bottom: 11px;\n}\npre, code {\n font-size: 14px; line-height: 18px;\n font-family: 'Menlo', 'Monaco', 'Consolas', 'Lucida Console', monospace;\n}\nimg.copy, img.run {\n height: 16px;\n width: 16px;\n float: right\n}\nimg.copy, img.run {\n cursor: pointer;\n}\nimg.copy {\n margin-right: 4px;\n}\n\n\n/* Colors: light mode */\nbody {\n background-color: #ffffff;\n color: #252519;\n}\ntd.code.empty {\n background: #ffffff;\n}\na, a:visited {\n color: #261a3b;\n}\np.footer {\n color: #808080;\n}\np.footer a, p.footer a:visited {\n color: #808080;\n}\ntd.code {\n background: #f0f0f0;\n}\n\n/* Syntax highlighting: light mode */\nbody .nx { } /* Name.Other: package, variable, struct, param, generic type names, etc. */\nbody .nf { } /* Name.Function: function names (def and call) */\nbody .o { } /* Operator: :=, &, *, +, &&, <, etc. */\nbody .p { } /* Plain: = , . : [ ( { etc. */\nbody .k { color: #954121 } /* Keyword: if, for, range, return, defer, etc. */\nbody .kc { color: #954121 } /* Keyword.Constant: nil, true, false */\nbody .kd { color: #954121 } /* Keyword.Declaration: func, var, type, struct, map, chan, etc. */\nbody .kn { color: #954121 } /* Keyword.Namespace: package, import */\nbody .nb { color: #954121 } /* Name.Builtin: make, len, delete, append, etc. */\nbody .kt { color: #b00040 } /* Keyword.Type: string, int, byte, error, etc. */\nbody .m { color: #666666 } /* Literal.Number */\nbody .mf { color: #666666 } /* Literal.Number.Float */\nbody .mh { color: #666666 } /* Literal.Number.Hex */\nbody .mi { color: #666666 } /* Literal.Number.Integer */\nbody .mo { color: #666666 } /* Literal.Number.Oct */\nbody .s { color: #219161 } /* Literal.String */\nbody .sc { color: #219161 } /* Literal.String.Char */\nbody .gp { color: #000080 } /* Generic.Prompt: shell prompt */\nbody .go { color: #808080 } /* Generic.Output: shell output */\nbody .c1 { color: #808080 } /* Comment.Single */\n\n\n@media (prefers-color-scheme: dark) {\n /* Colors: dark mode */\n body {\n background-color: #1f1f1f;\n color: #dadada;\n }\n td.code.empty {\n background: #1f1f1f;\n }\n a, a:visited {\n color: #e4e4e4;\n }\n p.footer {\n color: #898e98;\n }\n p.footer a, p.footer a:visited {\n color: #898e98;\n }\n td.code {\n background: #282828;\n }\n\n \n /* Syntax highlighting: dark mode */\n body .nx { } /* Name.Other */\n body .nf { } /* Name.Function */\n body .o { } /* Operator */\n body .p { } /* Plain */\n body .k { color: #af5a54 } /* Keyword */\n body .kc { color: #af5a54 } /* Keyword.Constant */\n body .kd { color: #af5a54 } /* Keyword.Declaration */\n body .kn { color: #af5a54 } /* Keyword.Namespace */\n body .nb { color: #af5a54 } /* Name.Builtin */\n body .kt { color: #b64343 } /* Keyword.Type */\n body .m { color: #688ec8 } /* Literal.Number */\n body .mf { color: #688ec8 } /* Literal.Number.Float */\n body .mh { color: #688ec8 } /* Literal.Number.Hex */\n body .mi { color: #688ec8 } /* Literal.Number.Integer */\n body .mo { color: #688ec8 } /* Literal.Number.Oct */\n body .s { color: #718e72 } /* Literal.String */\n body .sc { color: #718e72 } /* Literal.String.Char */\n body .gp { color: #8a6ab1 } /* Generic.Prompt */\n body .go { color: #868686 } /* Generic.Output */\n body .c1 { color: #868686 } /* Comment.Single */\n}\n" }, { "path": "templates/site.js", "content": "/*!\r\n * clipboard.js v1.5.13\r\n * https://zenorocha.github.io/clipboard.js\r\n *\r\n * Licensed MIT © Zeno Rocha\r\n */\r\n!function(t){if(\"object\"==typeof exports&&\"undefined\"!=typeof module)module.exports=t();else if(\"function\"==typeof define&&define.amd)define([],t);else{var e;e=\"undefined\"!=typeof window?window:\"undefined\"!=typeof global?global:\"undefined\"!=typeof self?self:this,e.Clipboard=t()}}(function(){var t,e,n;return function t(e,n,o){function r(c,a){if(!n[c]){if(!e[c]){var l=\"function\"==typeof require&&require;if(!a&&l)return l(c,!0);if(i)return i(c,!0);var s=new Error(\"Cannot find module '\"+c+\"'\");throw s.code=\"MODULE_NOT_FOUND\",s}var u=n[c]={exports:{}};e[c][0].call(u.exports,function(t){var n=e[c][1][t];return r(n?n:t)},u,u.exports,t,e,n,o)}return n[c].exports}for(var i=\"function\"==typeof require&&require,c=0;c 0\n}\n\nfunc check(err error) {\n\tif err != nil {\n\t\tpanic(err)\n\t}\n}\n\nfunc isDir(path string) bool {\n\tfileStat, _ := os.Stat(path)\n\treturn fileStat.IsDir()\n}\n\nfunc ensureDir(dir string) {\n\terr := os.MkdirAll(dir, 0755)\n\tcheck(err)\n}\n\nfunc copyFile(src, dst string) {\n\tdat, err := os.ReadFile(src)\n\tcheck(err)\n\terr = os.WriteFile(dst, dat, 0644)\n\tcheck(err)\n}\n\nfunc sha1Sum(s string) string {\n\th := sha1.New()\n\th.Write([]byte(s))\n\tb := h.Sum(nil)\n\treturn fmt.Sprintf(\"%x\", b)\n}\n\nfunc mustReadFile(path string) string {\n\tbytes, err := os.ReadFile(path)\n\tcheck(err)\n\treturn string(bytes)\n}\n\nfunc markdown(src string) string {\n\treturn string(blackfriday.Run([]byte(src)))\n}\n\nfunc readLines(path string) []string {\n\tsrc := mustReadFile(path)\n\treturn strings.Split(src, \"\\n\")\n}\n\nfunc mustGlob(glob string) []string {\n\tpaths, err := filepath.Glob(glob)\n\tcheck(err)\n\treturn paths\n}\n\nfunc whichLexer(path string) string {\n\tif strings.HasSuffix(path, \".go\") {\n\t\treturn \"go\"\n\t} else if strings.HasSuffix(path, \".sh\") {\n\t\treturn \"console\"\n\t}\n\tpanic(\"No lexer for \" + path)\n}\n\nfunc debug(msg string) {\n\tif os.Getenv(\"DEBUG\") == \"1\" {\n\t\tfmt.Fprintln(os.Stderr, msg)\n\t}\n}\n\nvar docsPat = regexp.MustCompile(`^(\\s*(\\/\\/|#)\\s|\\s*\\/\\/$)`)\nvar dashPat = regexp.MustCompile(`\\-+`)\n\n// Seg is a segment of an example\ntype Seg struct {\n\tDocs, DocsRendered string\n\tCode, CodeRendered, CodeForJs string\n\tCodeEmpty, CodeLeading, CodeRun bool\n}\n\n// Example is info extracted from an example file\ntype Example struct {\n\tID, Name string\n\tGoCode, GoCodeHash, URLHash string\n\tSegs [][]*Seg\n\tPrevExample *Example\n\tNextExample *Example\n}\n\nfunc parseHashFile(sourcePath string) (string, string) {\n\tlines := readLines(sourcePath)\n\treturn lines[0], lines[1]\n}\n\nfunc resetURLHashFile(codehash, code, sourcePath string) string {\n\tif verbose() {\n\t\tfmt.Println(\" Sending request to play.golang.org\")\n\t}\n\tpayload := strings.NewReader(code)\n\tresp, err := http.Post(\"https://play.golang.org/share\", \"text/plain\", payload)\n\tcheck(err)\n\tdefer resp.Body.Close()\n\tbody, err := io.ReadAll(resp.Body)\n\tcheck(err)\n\turlkey := string(body)\n\tdata := fmt.Sprintf(\"%s\\n%s\\n\", codehash, urlkey)\n\tos.WriteFile(sourcePath, []byte(data), 0644)\n\treturn urlkey\n}\n\nfunc parseSegs(sourcePath string) ([]*Seg, string) {\n\tvar (\n\t\tlines []string\n\t\tsource []string\n\t)\n\t// Convert tabs to spaces for uniform rendering.\n\tfor _, line := range readLines(sourcePath) {\n\t\tlines = append(lines, strings.Replace(line, \"\\t\", \" \", -1))\n\t\tsource = append(source, line)\n\t}\n\tsegs := []*Seg{}\n\tlastSeen := \"\"\n\tfor _, line := range lines {\n\t\tif line == \"\" {\n\t\t\tlastSeen = \"\"\n\t\t\tcontinue\n\t\t}\n\t\tmatchDocs := docsPat.MatchString(line)\n\t\tmatchCode := !matchDocs\n\t\tnewDocs := (lastSeen == \"\") || ((lastSeen != \"docs\") && (segs[len(segs)-1].Docs != \"\"))\n\t\tnewCode := (lastSeen == \"\") || ((lastSeen != \"code\") && (segs[len(segs)-1].Code != \"\"))\n\t\tif newDocs || newCode {\n\t\t\tdebug(\"NEWSEG\")\n\t\t}\n\t\tif matchDocs {\n\t\t\ttrimmed := docsPat.ReplaceAllString(line, \"\")\n\t\t\tif newDocs {\n\t\t\t\tnewSeg := Seg{Docs: trimmed, Code: \"\"}\n\t\t\t\tsegs = append(segs, &newSeg)\n\t\t\t} else {\n\t\t\t\tsegs[len(segs)-1].Docs = segs[len(segs)-1].Docs + \"\\n\" + trimmed\n\t\t\t}\n\t\t\tdebug(\"DOCS: \" + line)\n\t\t\tlastSeen = \"docs\"\n\t\t} else if matchCode {\n\t\t\tif newCode {\n\t\t\t\tnewSeg := Seg{Docs: \"\", Code: line}\n\t\t\t\tsegs = append(segs, &newSeg)\n\t\t\t} else {\n\t\t\t\tlastSeg := segs[len(segs)-1]\n\t\t\t\tif len(lastSeg.Code) == 0 {\n\t\t\t\t\tlastSeg.Code = line\n\t\t\t\t} else {\n\t\t\t\t\tlastSeg.Code = lastSeg.Code + \"\\n\" + line\n\t\t\t\t}\n\t\t\t}\n\t\t\tdebug(\"CODE: \" + line)\n\t\t\tlastSeen = \"code\"\n\t\t}\n\t}\n\tfor i, seg := range segs {\n\t\tseg.CodeEmpty = (seg.Code == \"\")\n\t\tseg.CodeLeading = (i < (len(segs) - 1))\n\t\tseg.CodeRun = strings.Contains(seg.Code, \"package main\")\n\t}\n\treturn segs, strings.Join(source, \"\\n\")\n}\n\nfunc chromaFormat(code, filePath string) string {\n\tlexer := lexers.Get(filePath)\n\tif lexer == nil {\n\t\tlexer = lexers.Fallback\n\t}\n\n\tif strings.HasSuffix(filePath, \".sh\") {\n\t\tlexer = SimpleShellOutputLexer\n\t}\n\n\tlexer = chroma.Coalesce(lexer)\n\n\tstyle := styles.Get(\"swapoff\")\n\tif style == nil {\n\t\tstyle = styles.Fallback\n\t}\n\tformatter := html.New(html.WithClasses(true))\n\titerator, err := lexer.Tokenise(nil, string(code))\n\tcheck(err)\n\tbuf := new(bytes.Buffer)\n\terr = formatter.Format(buf, style, iterator)\n\tcheck(err)\n\treturn buf.String()\n}\n\nfunc parseAndRenderSegs(sourcePath string) ([]*Seg, string) {\n\tsegs, filecontent := parseSegs(sourcePath)\n\tlexer := whichLexer(sourcePath)\n\tfor _, seg := range segs {\n\t\tif seg.Docs != \"\" {\n\t\t\tseg.DocsRendered = markdown(seg.Docs)\n\t\t}\n\t\tif seg.Code != \"\" {\n\t\t\tseg.CodeRendered = chromaFormat(seg.Code, sourcePath)\n\n\t\t\t// adding the content to the js code for copying to the clipboard\n\t\t\tif strings.HasSuffix(sourcePath, \".go\") {\n\t\t\t\tseg.CodeForJs = strings.Trim(seg.Code, \"\\n\") + \"\\n\"\n\t\t\t}\n\t\t}\n\t}\n\t// we are only interested in the 'go' code to pass to play.golang.org\n\tif lexer != \"go\" {\n\t\tfilecontent = \"\"\n\t}\n\treturn segs, filecontent\n}\n\nfunc parseExamples() []*Example {\n\tvar exampleNames []string\n\tfor _, line := range readLines(\"examples.txt\") {\n\t\tif line != \"\" && !strings.HasPrefix(line, \"#\") {\n\t\t\texampleNames = append(exampleNames, line)\n\t\t}\n\t}\n\texamples := make([]*Example, 0)\n\tfor i, exampleName := range exampleNames {\n\t\tif verbose() {\n\t\t\tfmt.Printf(\"Processing %s [%d/%d]\\n\", exampleName, i+1, len(exampleNames))\n\t\t}\n\t\texample := Example{Name: exampleName}\n\t\texampleID := strings.ToLower(exampleName)\n\t\texampleID = strings.Replace(exampleID, \" \", \"-\", -1)\n\t\texampleID = strings.Replace(exampleID, \"/\", \"-\", -1)\n\t\texampleID = strings.Replace(exampleID, \"'\", \"\", -1)\n\t\texampleID = dashPat.ReplaceAllString(exampleID, \"-\")\n\t\texample.ID = exampleID\n\t\texample.Segs = make([][]*Seg, 0)\n\t\tsourcePaths := mustGlob(\"examples/\" + exampleID + \"/*\")\n\t\tfor _, sourcePath := range sourcePaths {\n\t\t\tif !isDir(sourcePath) {\n\t\t\t\tif strings.HasSuffix(sourcePath, \".hash\") {\n\t\t\t\t\texample.GoCodeHash, example.URLHash = parseHashFile(sourcePath)\n\t\t\t\t} else {\n\t\t\t\t\tsourceSegs, filecontents := parseAndRenderSegs(sourcePath)\n\t\t\t\t\tif filecontents != \"\" {\n\t\t\t\t\t\texample.GoCode = filecontents\n\t\t\t\t\t}\n\t\t\t\t\texample.Segs = append(example.Segs, sourceSegs)\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tnewCodeHash := sha1Sum(example.GoCode)\n\t\tif example.GoCodeHash != newCodeHash {\n\t\t\texample.URLHash = resetURLHashFile(newCodeHash, example.GoCode, \"examples/\"+example.ID+\"/\"+example.ID+\".hash\")\n\t\t}\n\t\texamples = append(examples, &example)\n\t}\n\tfor i, example := range examples {\n\t\tif i > 0 {\n\t\t\texample.PrevExample = examples[i-1]\n\t\t}\n\t\tif i < (len(examples) - 1) {\n\t\t\texample.NextExample = examples[i+1]\n\t\t}\n\t}\n\treturn examples\n}\n\nfunc renderIndex(examples []*Example) {\n\tif verbose() {\n\t\tfmt.Println(\"Rendering index\")\n\t}\n\tindexTmpl := template.New(\"index\")\n\ttemplate.Must(indexTmpl.Parse(mustReadFile(\"templates/footer.tmpl\")))\n\ttemplate.Must(indexTmpl.Parse(mustReadFile(\"templates/index.tmpl\")))\n\tindexF, err := os.Create(siteDir + \"/index.html\")\n\tcheck(err)\n\tdefer indexF.Close()\n\tcheck(indexTmpl.Execute(indexF, examples))\n}\n\nfunc renderExamples(examples []*Example) {\n\tif verbose() {\n\t\tfmt.Println(\"Rendering examples\")\n\t}\n\texampleTmpl := template.New(\"example\")\n\ttemplate.Must(exampleTmpl.Parse(mustReadFile(\"templates/footer.tmpl\")))\n\ttemplate.Must(exampleTmpl.Parse(mustReadFile(\"templates/example.tmpl\")))\n\tfor _, example := range examples {\n\t\texampleF, err := os.Create(siteDir + \"/\" + example.ID)\n\t\tcheck(err)\n\t\tdefer exampleF.Close()\n\t\tcheck(exampleTmpl.Execute(exampleF, example))\n\t}\n}\n\nfunc render404() {\n\tif verbose() {\n\t\tfmt.Println(\"Rendering 404\")\n\t}\n\ttmpl := template.New(\"404\")\n\ttemplate.Must(tmpl.Parse(mustReadFile(\"templates/footer.tmpl\")))\n\ttemplate.Must(tmpl.Parse(mustReadFile(\"templates/404.tmpl\")))\n\tfile, err := os.Create(siteDir + \"/404.html\")\n\tcheck(err)\n\tdefer file.Close()\n\tcheck(tmpl.Execute(file, \"\"))\n}\n\nfunc main() {\n\tif len(os.Args) > 1 {\n\t\tsiteDir = os.Args[1]\n\t}\n\tensureDir(siteDir)\n\n\tcopyFile(\"templates/site.css\", siteDir+\"/site.css\")\n\tcopyFile(\"templates/site.js\", siteDir+\"/site.js\")\n\tcopyFile(\"templates/favicon.ico\", siteDir+\"/favicon.ico\")\n\tcopyFile(\"templates/play.png\", siteDir+\"/play.png\")\n\tcopyFile(\"templates/clipboard.png\", siteDir+\"/clipboard.png\")\n\texamples := parseExamples()\n\trenderIndex(examples)\n\trenderExamples(examples)\n\trender404()\n}\n\nvar SimpleShellOutputLexer = chroma.MustNewLexer(\n\t&chroma.Config{\n\t\tName: \"Shell Output\",\n\t\tAliases: []string{\"console\"},\n\t\tFilenames: []string{\"*.sh\"},\n\t\tMimeTypes: []string{},\n\t},\n\tfunc() chroma.Rules {\n\t\treturn chroma.Rules{\n\t\t\t\"root\": {\n\t\t\t\t// $ or > triggers the start of prompt formatting\n\t\t\t\t{`^\\$`, chroma.GenericPrompt, chroma.Push(\"prompt\")},\n\t\t\t\t{`^>`, chroma.GenericPrompt, chroma.Push(\"prompt\")},\n\n\t\t\t\t// empty lines are just text\n\t\t\t\t{`^$\\n`, chroma.Text, nil},\n\n\t\t\t\t// otherwise its all output\n\t\t\t\t{`[^\\n]+$\\n?`, chroma.GenericOutput, nil},\n\t\t\t},\n\t\t\t\"prompt\": {\n\t\t\t\t// when we find newline, do output formatting rules\n\t\t\t\t{`\\n`, chroma.Text, chroma.Push(\"output\")},\n\t\t\t\t// otherwise its all text\n\t\t\t\t{`[^\\n]+$`, chroma.Text, nil},\n\t\t\t},\n\t\t\t\"output\": {\n\t\t\t\t// sometimes there isn't output so we go right back to prompt\n\t\t\t\t{`^\\$`, chroma.GenericPrompt, chroma.Pop(1)},\n\t\t\t\t{`^>`, chroma.GenericPrompt, chroma.Pop(1)},\n\t\t\t\t// otherwise its all output\n\t\t\t\t{`[^\\n]+$\\n?`, chroma.GenericOutput, nil},\n\t\t\t},\n\t\t}\n\t},\n)\n" }, { "path": "tools/measure", "content": "#!/usr/bin/env bash\n\nexec go run tools/measure.go\n" }, { "path": "tools/measure.go", "content": "package main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\t\"path/filepath\"\n\t\"regexp\"\n\t\"strings\"\n\t\"unicode/utf8\"\n)\n\nfunc check(err error) {\n\tif err != nil {\n\t\tpanic(err)\n\t}\n}\n\nfunc readLines(path string) []string {\n\tsrcBytes, err := os.ReadFile(path)\n\tcheck(err)\n\treturn strings.Split(string(srcBytes), \"\\n\")\n}\n\nfunc isDir(path string) bool {\n\tfileStat, _ := os.Stat(path)\n\treturn fileStat.IsDir()\n}\n\nvar commentPat = regexp.MustCompile(\"\\\\s*\\\\/\\\\/\")\n\nfunc main() {\n\tsourcePaths, err := filepath.Glob(\"./examples/*/*\")\n\tcheck(err)\n\tfoundLongFile := false\n\tfor _, sourcePath := range sourcePaths {\n\t\tfoundLongLine := false\n\t\tif !isDir(sourcePath) {\n\t\t\tlines := readLines(sourcePath)\n\t\t\tfor i, line := range lines {\n\t\t\t\t// Convert tabs to spaces before measuring, so we get an accurate measure\n\t\t\t\t// of how long the output will end up being.\n\t\t\t\tline := strings.Replace(line, \"\\t\", \" \", -1)\n\t\t\t\tif !foundLongLine && !commentPat.MatchString(line) && (utf8.RuneCountInString(line) > 68) {\n\t\t\t\t\tfmt.Printf(\"measure: %s:%d (rune count = %d)\\n\", sourcePath, i+1, utf8.RuneCountInString(line))\n\t\t\t\t\tfoundLongLine = true\n\t\t\t\t\tfoundLongFile = true\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\tif foundLongFile {\n\t\tos.Exit(1)\n\t}\n}\n" }, { "path": "tools/serve", "content": "#!/usr/bin/env bash\n\nexec go run tools/serve.go\n" }, { "path": "tools/serve.go", "content": "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n)\n\nfunc main() {\n\tport := \"8000\"\n\tpublicDir := \"public\"\n\tfmt.Printf(\"Serving Go by Example at http://127.0.0.1:%s\\n\", port)\n\thttp.ListenAndServe(\":\"+port, http.FileServer(http.Dir(publicDir)))\n}\n" }, { "path": "tools/test", "content": "#!/usr/bin/env bash\n\n# Sanity testing of the examples.\n\nset -eo pipefail\n\n# go vet will attempt to build each example, making sure it compiles. It will\n# also report known issues with the code. Disabling the -unreachable check\n# because it will fire false positives for some examples demonstrating panics.\ngo vet -unreachable=false ./examples/...\n" }, { "path": "tools/upload", "content": "#!/usr/bin/env bash\n\nexec go run tools/upload.go -region us-east-1 -bucket gobyexample.com\n" }, { "path": "tools/upload.go", "content": "// Uploads the generated site from the public/ directory to the S3 bucket from\n// which it's served.\n// To invoke this program, the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY\n// env vars have to be set appropriately, and the -region and -bucket flags\n// have to be passed in.\npackage main\n\nimport (\n\t\"context\"\n\t\"flag\"\n\t\"log\"\n\t\"os\"\n\t\"path/filepath\"\n\n\t\"github.com/aws/aws-sdk-go-v2/aws\"\n\t\"github.com/aws/aws-sdk-go-v2/config\"\n\t\"github.com/aws/aws-sdk-go-v2/service/s3\"\n)\n\n// guessContentType guesses the HTTP content type appropriate for the given\n// filename.\nfunc guessContentType(filename string) string {\n\tswitch filepath.Ext(filename) {\n\tcase \".ico\":\n\t\treturn \"image/x-icon\"\n\tcase \".png\":\n\t\treturn \"image/png\"\n\tcase \".css\":\n\t\treturn \"text/css\"\n\tdefault:\n\t\treturn \"text/html\"\n\t}\n}\n\nfunc main() {\n\tregion := flag.String(\"region\", \"\", \"S3 region\")\n\tbucket := flag.String(\"bucket\", \"\", \"S3 bucket name\")\n\tflag.Parse()\n\n\tif len(*region) == 0 || len(*bucket) == 0 {\n\t\tlog.Fatalf(\"region and bucket must be specified [region=%s, bucket=%s]\", *region, *bucket)\n\t}\n\n\tcfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion(*region))\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tclient := s3.NewFromConfig(cfg)\n\n\t// The whole contents of the public/ directory are uploaded. This code assumes\n\t// the directory structure is flat - there are no subdirectories.\n\tpublicDir := \"./public/\"\n\tc, err := os.ReadDir(publicDir)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tfor _, entry := range c {\n\t\tif !entry.IsDir() {\n\t\t\tfile, err := os.Open(filepath.Join(publicDir, entry.Name()))\n\t\t\tif err != nil {\n\t\t\t\tlog.Fatal(err)\n\t\t\t}\n\t\t\tdefer file.Close()\n\n\t\t\tcontentType := guessContentType(entry.Name())\n\t\t\tlog.Printf(\"Uploading %s (%s)\", entry.Name(), contentType)\n\n\t\t\tcfg := &s3.PutObjectInput{\n\t\t\t\tBucket: bucket,\n\t\t\t\tKey: aws.String(entry.Name()),\n\t\t\t\tBody: file,\n\t\t\t\tContentType: aws.String(contentType),\n\t\t\t}\n\n\t\t\t_, err = client.PutObject(context.TODO(), cfg)\n\t\t\tif err != nil {\n\t\t\t\tlog.Fatal(err)\n\t\t\t}\n\t\t}\n\t}\n}\n" } ]