gatherexamples

Overview ¶

Command gatherexamples extracts examples in a Go module into a JSON-formatted object. This is used as input for building the GDK Hugo website.

Examples must include a comment "// PRAGMA: This example is used on github.com/sraphs/gdk; PRAGMA comments adjust how it is shown and can be ignored." somewhere in the function body in order to be included in this tool's output.

gatherexamples does some minimal rewriting of the example source code for presentation:

• Any imports the example uses will be prepended to the code.
• log.Fatal(err) -> return err
• A comment line "// PRAGMA: On github.com/sraphs/gdk, hide lines until the next blank line." will remove any code up to the next blank line. This is intended for compiler-mandated setup like `ctx := context.Background()`.
• A comment line "// PRAGMA: On github.com/sraphs/gdk, hide the rest of the function." will remove any code until the end of the function. This is intended for compiler-mandated assignments like `_ = bucket`.
• A comment line "// PRAGMA: On github.com/sraphs/gdk, add a blank import: _ "example.com/foo"" will add the blank import to the example's imports.

The key of each JSON object entry will be the import path of the package, followed by a dot ("."), followed by the name of the example function. The value of each JSON object entry is an object like {"imports": "import (\n\t\"fmt\"\n)", "code": "/* ... */"}. These are separated so that templating can format or show them separately.