merge upstream

.gitattributes

@@ -1,3 +1,2 @@
-public/* linguist-generated=true
-vendor/* linguist-vendored=true
+public/** linguist-generated
 

.github/workflows/test.yml

@@ -0,0 +1,30 @@
+name: test
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+
+  build:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        go-version: [1.26.0]
+
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Set up Go
+      uses: actions/setup-go@v3
+      with:
+        go-version: ${{ matrix.go-version }}
+
+    - name: Test
+      run: tools/build
+      env:
+        VERBOSE: 1
+        TESTING: 1

CONTRIBUTING.md

@@ -2,17 +2,22 @@
 
 Thanks for your interest in contributing to Go by Example!
 
-* When sending a PR that affects the displayed contents of the site, run
-  `tools/build` locally and include the generated HTML in the PR. If you
-  only want to submit a simple typo suggestion (for example, through the
-  Github website), feel free to send a PR anyway - we'll regenerate the
-  HTML and merge with your commit.
+* When sending a PR that affects the displayed contents of the site, 
+  updating the HTML in the `public` directory by itself is insufficient, since
+  the source of truth for the website is in the `examples` directory.
+
+  Instead, update the proper source file(s) in the `examples` directory and
+  run `tools/build` locally to regenerate the HTML; include both changes in
+  your PR.  
+
+  If you don't want to deal with getting a proper PR in, feel free to just
+  open an issue and point out the change you suggest.
 
 * We're open to adding more examples to the site. They should be on things
   used by many programmers and only require the standard library. If you're
   interested in adding an example, _please open an issue to discuss the topic
   first_.
 
 * We're not going to change the navigation of the site, in particular adding
-  a "previous section" link or an "index" link other than the on the title
+  a "previous section" link or an "index" link other than the one on the title
   text.

README.md

@@ -7,23 +7,22 @@ a site that teaches Go via annotated example programs.
 
 The Go by Example site is built by extracting code and
 comments from source files in `examples` and rendering
-them via the `templates` into a static `public`
+them using `templates` into a static `public`
 directory. The programs implementing this build process
-are in `tools`, along with some vendor'd dependencies
-in `vendor`.
+are in `tools`, along with dependencies specified in
+the `go.mod`file.
 
 The built `public` directory can be served by any
 static content system. The production site uses S3 and
 CloudFront, for example.
 
 ### Building
 
-[![Build Status](https://travis-ci.com/mmcgrana/gobyexample.svg "Travis CI status")](https://travis-ci.com/mmcgrana/gobyexample)
+[![test](https://github.com/mmcgrana/gobyexample/actions/workflows/test.yml/badge.svg)](https://github.com/mmcgrana/gobyexample/actions/workflows/test.yml)
 
-To build the site you'll need Go and Python installed. Run:
+To build the site you'll need Go installed. Run:
 
 ```console
-$ go get github.com/russross/blackfriday
 $ tools/build
 ```
 
@@ -35,7 +34,7 @@ $ tools/build-loop
 
 To see the site locally:
 
-```
+```console
 $ tools/serve
 ```
 
@@ -46,7 +45,6 @@ and open `http://127.0.0.1:8000/` in your browser.
 To upload the site:
 
 ```console
-$ gem install aws-sdk
 $ export AWS_ACCESS_KEY_ID=...
 $ export AWS_SECRET_ACCESS_KEY=...
 $ tools/upload
@@ -57,7 +55,7 @@ $ tools/upload
 This work is copyright Mark McGranaghan and licensed under a
 [Creative Commons Attribution 3.0 Unported License](http://creativecommons.org/licenses/by/3.0/).
 
-The Go Gopher is copyright [Renée French](http://reneefrench.blogspot.com/) and licensed under a
+The Go Gopher is copyright [Renée French](https://reneefrench.blogspot.com/) and licensed under a
 [Creative Commons Attribution 3.0 Unported License](http://creativecommons.org/licenses/by/3.0/).
 
 
@@ -66,17 +64,53 @@ The Go Gopher is copyright [Renée French](http://reneefrench.blogspot.com/) and
 Contributor translations of the Go by Example site are available in:
 
 * [Chinese](https://gobyexample-cn.github.io/) by [gobyexample-cn](https://github.com/gobyexample-cn)
-* [Czech](http://gobyexamples.sweb.cz/) by [martinkunc](https://github.com/martinkunc/gobyexample-cz)
 * [French](http://le-go-par-l-exemple.keiruaprod.fr) by [keirua](https://github.com/keirua/gobyexample)
-* [Italian](http://gobyexample.it) by the [Go Italian community](https://github.com/golangit/gobyexample-it)
+* [Italian](https://gobyexampleit.andrearaponi.it/) by [andrearaponi](https://github.com/andrearaponi/gobyexample-it)
 * [Japanese](http://spinute.org/go-by-example) by [spinute](https://github.com/spinute)
 * [Korean](https://mingrammer.com/gobyexample/) by [mingrammer](https://github.com/mingrammer)
-* [Russian](https://gobyexample.com.ru/) by [badkaktus](https://github.com/badkaktus)
-* [Spanish](http://goconejemplos.com) by the [Go Mexico community](https://github.com/dabit/gobyexample)
-* [Ukrainian](http://butuzov.github.io/gobyexample/) by [butuzov](https://github.com/butuzov/gobyexample)
+* [Ukrainian](https://butuzov.github.io/gobyexample/) by [butuzov](https://github.com/butuzov/gobyexample)
+* [Brazilian Portuguese](https://lcslitx.github.io/GoEmExemplos/) by [lcslitx](https://github.com/LCSLITX)
+* [Burmese](https://setkyar.github.io/gobyexample) by [Set Kyar Wa Lar](https://github.com/setkyar/gobyexample)
 
 ### Thanks
 
 Thanks to [Jeremy Ashkenas](https://github.com/jashkenas)
-for [Docco](http://jashkenas.github.com/docco/), which
+for [Docco](http://jashkenas.github.io/docco/), which
 inspired this project.
+
+### FAQ
+
+#### I found a problem with the examples; what do I do?
+
+We're very happy to fix problem reports and accept contributions! Please submit
+[an issue](https://github.com/mmcgrana/gobyexample/issues) or send a Pull Request.
+See `CONTRIBUTING.md` for more details.
+
+#### What version of Go is required to run these examples?
+
+Given Go's strong [backwards compatibility guarantees](https://go.dev/doc/go1compat),
+we expect the vast majority of examples to work on the latest released version of Go
+as well as many older releases going back years.
+
+That said, some examples show off new features added in recent releases; therefore,
+it's recommended to try running examples with the latest officially released Go version
+(see Go's [release history](https://go.dev/doc/devel/release) for details).
+
+#### I'm getting output in a different order from the example. Is the example wrong?
+
+Some of the examples demonstrate concurrent code which has a non-deterministic
+execution order. It depends on how the Go runtime schedules its goroutines and
+may vary by operating system, CPU architecture, or even Go version.
+
+Similarly, examples that iterate over maps may produce items in a different order
+from what you're getting on your machine. This is because the order of iteration
+over maps in Go is [not specified and is not guaranteed to be the same from one
+iteration to the next](https://go.dev/ref/spec#RangeClause).
+
+It doesn't mean anything is wrong with the example. Typically the code in these
+examples will be insensitive to the actual order of the output; if the code is
+sensitive to the order - that's probably a bug - so feel free to report it.
+
+
+
+

examples.txt

@@ -8,17 +8,23 @@ Switch
 Arrays
 Slices
 Maps
-Range
 Functions
 Multiple Return Values
 Variadic Functions
 Closures
 Recursion
+Range over Built-in Types
 Pointers
+Strings and Runes
 Structs
 Methods
 Interfaces
+Enums
+Struct Embedding
+Generics
+Range over Iterators
 Errors
+Custom Errors
 Goroutines
 Channels
 Channel Buffering
@@ -41,9 +47,10 @@ Sorting
 Sorting by Functions
 Panic
 Defer
-Collection Functions
+Recover
 String Functions
 String Formatting
+Text Templates
 Regular Expressions
 JSON
 XML
@@ -53,21 +60,24 @@ Time Formatting / Parsing
 Random Numbers
 Number Parsing
 URL Parsing
-SHA1 Hashes
+SHA256 Hashes
 Base64 Encoding
 Reading Files
 Writing Files
 Line Filters
 File Paths
 Directories
 Temporary Files and Directories
-Testing
+Embed Directive
+Testing and Benchmarking
 Command-Line Arguments
 Command-Line Flags
 Command-Line Subcommands
 Environment Variables
-HTTP Clients
-HTTP Servers
+Logging
+HTTP Client
+HTTP Server
+TCP Server
 Context
 Spawning Processes
 Exec'ing Processes

examples/arrays/arrays.go

@@ -1,5 +1,7 @@
 // In Go, an _array_ is a numbered sequence of elements of a
-// specific length.
+// specific length. In typical Go code, [slices](slices) are
+// much more common; arrays are useful in some special
+// scenarios.
 
 package main
 
@@ -29,14 +31,32 @@ func main() {
 	b := [5]int{1, 2, 3, 4, 5}
 	fmt.Println("dcl:", b)
 
+	// You can also have the compiler count the number of
+	// elements for you with `...`
+	b = [...]int{1, 2, 3, 4, 5}
+	fmt.Println("dcl:", b)
+
+	// If you specify the index with `:`, the elements in
+	// between will be zeroed.
+	b = [...]int{100, 3: 400, 500}
+	fmt.Println("idx:", b)
+
 	// Array types are one-dimensional, but you can
 	// compose types to build multi-dimensional data
 	// structures.
 	var twoD [2][3]int
-	for i := 0; i < 2; i++ {
-		for j := 0; j < 3; j++ {
+	for i := range 2 {
+		for j := range 3 {
 			twoD[i][j] = i + j
 		}
 	}
 	fmt.Println("2d: ", twoD)
+
+	// You can create and initialize multi-dimensional
+	// arrays at once too.
+	twoD = [2][3]int{
+		{1, 2, 3},
+		{1, 2, 3},
+	}
+	fmt.Println("2d: ", twoD)
 }

examples/arrays/arrays.hash

@@ -1,2 +1,2 @@
-e71f2d3763eb2950727faa39b90cf1bc037d85fa
-TaahifSGSwU
+96cbe484a18a0dd8c1839a92963447bed94cc997
+-NFSggT7dFH

examples/arrays/arrays.sh

@@ -6,7 +6,7 @@ set: [0 0 0 0 100]
 get: 100
 len: 5
 dcl: [1 2 3 4 5]
+dcl: [1 2 3 4 5]
+idx: [100 0 0 400 500]
 2d:  [[0 1 2] [1 2 3]]
-
-# You'll see _slices_ much more often than arrays in
-# typical Go. We'll look at slices next.
+2d:  [[1 2 3] [1 2 3]]

examples/atomic-counters/atomic-counters.go

@@ -15,38 +15,30 @@ import (
 
 func main() {
 
-	// We'll use an unsigned integer to represent our
+	// We'll use an atomic integer type to represent our
 	// (always-positive) counter.
-	var ops uint64
+	var ops atomic.Uint64
 
 	// A WaitGroup will help us wait for all goroutines
 	// to finish their work.
 	var wg sync.WaitGroup
 
 	// We'll start 50 goroutines that each increment the
 	// counter exactly 1000 times.
-	for i := 0; i < 50; i++ {
-		wg.Add(1)
-
-		go func() {
-			for c := 0; c < 1000; c++ {
-				// To atomically increment the counter we
-				// use `AddUint64`, giving it the memory
-				// address of our `ops` counter with the
-				// `&` syntax.
-				atomic.AddUint64(&ops, 1)
+	for range 50 {
+		wg.Go(func() {
+			for range 1000 {
+				// To atomically increment the counter we use `Add`.
+				ops.Add(1)
 			}
-			wg.Done()
-		}()
+		})
 	}
 
 	// Wait until all the goroutines are done.
 	wg.Wait()
 
-	// It's safe to access `ops` now because we know
-	// no other goroutine is writing to it. Reading
-	// atomics safely while they are being updated is
-	// also possible, using functions like
-	// `atomic.LoadUint64`.
-	fmt.Println("ops:", ops)
+	// Here no goroutines are writing to 'ops', but using
+	// `Load` it's safe to atomically read a value even while
+	// other goroutines are (atomically) updating it.
+	fmt.Println("ops:", ops.Load())
 }

examples/atomic-counters/atomic-counters.hash

@@ -1,2 +1,2 @@
-7b491b40d56a77b01d8e2bd08366de081a4e8d99
-j-14agntvEO
+d898b7b79368f70c6f6d1c181575f7b83c592718
+yiGAVfTH49v

examples/atomic-counters/atomic-counters.sh

@@ -1,9 +1,10 @@
 # We expect to get exactly 50,000 operations. Had we
-# used the non-atomic `ops++` to increment the counter,
-# we'd likely get a different number, changing between
-# runs, because the goroutines would interfere with
-# each other. Moreover, we'd get data race failures
-# when running with the `-race` flag.
+# used a non-atomic integer and incremented it with
+# `ops++`, we'd likely get a different number,
+# changing between runs, because the goroutines
+# would interfere with each other. Moreover, we'd
+# get data race failures when running with the
+# `-race` flag.
 $ go run atomic-counters.go
 ops: 50000