From 42d5a894715e6bb58d9d1516e39ca7026b163c64 Mon Sep 17 00:00:00 2001 From: Leon Mika Date: Sun, 19 Jan 2025 10:11:55 +1100 Subject: [PATCH] Started working on more package docs --- Makefile | 9 ++++++--- _docs/{ => mod}/core.md | 7 ++++--- _docs/mod/csv.md | 29 +++++++++++++++++++++++++++++ _docs/mod/fs.md | 11 +++++++++++ _docs/mod/index.md | 8 ++++++++ _docs/mod/os.md | 17 +++++++++++++++++ _site/playground/index.html | 2 +- cmd/gendocs/frame.tmpl | 2 +- cmd/gendocs/main.go | 18 ++++++++++++++---- 9 files changed, 91 insertions(+), 12 deletions(-) rename _docs/{ => mod}/core.md (96%) create mode 100644 _docs/mod/csv.md create mode 100644 _docs/mod/fs.md create mode 100644 _docs/mod/index.md create mode 100644 _docs/mod/os.md diff --git a/Makefile b/Makefile index 0bb4177..3af4ec2 100644 --- a/Makefile +++ b/Makefile @@ -7,10 +7,13 @@ test: site: clean mkdir build mkdir build/site - mkdir build/site/core cp -r _site/* build/site/. - go run ./cmd/gendocs/main.go ./_docs/index.md > build/site/index.html - go run ./cmd/gendocs/main.go ./_docs/core.md > build/site/core/index.html + go run ./cmd/gendocs/main.go ./_docs/index.md build/site/index.html + go run ./cmd/gendocs/main.go ./_docs/mod/index.md build/site/mod/index.html + go run ./cmd/gendocs/main.go ./_docs/mod/core.md build/site/mod/core/index.html + go run ./cmd/gendocs/main.go ./_docs/mod/csv.md build/site/mod/csv/index.html + go run ./cmd/gendocs/main.go ./_docs/mod/fs.md build/site/mod/fs/index.html + go run ./cmd/gendocs/main.go ./_docs/mod/os.md build/site/mod/os/index.html GOOS=js GOARCH=wasm go build -o build/site/playwasm.wasm ./cmd/playwasm/. site-deploy: site diff --git a/_docs/core.md b/_docs/mod/core.md similarity index 96% rename from _docs/core.md rename to _docs/mod/core.md index 21e1d65..711ccd7 100644 --- a/_docs/core.md +++ b/_docs/mod/core.md @@ -1,7 +1,7 @@ --- --- -# Core Functions +# Core Builtins ### call @@ -33,15 +33,16 @@ If COL is a hash, BLOCK receives both the key and value of each element. BLOCK can call `break` and `continue` which will exit out of the loop, or jump to the start of the next iteration respectively. - The return value of `foreach` will be the result of the last iteration, unless `break` is called with a value. +This is implemented as a macro but can be used in a pipeline. + ``` foreach [1 2 3] { |e| echo "Element = $e" } -foreach [a:"one" b:"two"] { |k v| +[a:"one" b:"two"] | foreach { |k v| echo "Key $k = $v" } ``` diff --git a/_docs/mod/csv.md b/_docs/mod/csv.md new file mode 100644 index 0000000..e630c0c --- /dev/null +++ b/_docs/mod/csv.md @@ -0,0 +1,29 @@ +# CSV Module + +Functions for operating over CSV data. + +### each-record + +``` +csv:each-record FILE BLOCK +``` + +Opens the CSV file at FILE and calls BLOCK on each record. It is expected that this +CSV file has a header which appears as the first row. This command will read and +index the header, then start calling BLOCK from the row directly below the header. + +BLOCK is called with the arguments _|row header|_ where: + +- _row_ contains the fields of the current row as a list. +- _header_ contains a hash mapping a header name to a field index. + +The return value will be nil. + +``` +csv:each-record "winds.csv" { |row hdr| + set name $row.($hdr.name) + set bearing $row.($hdr.bearing) + + echo "Wind $name has bearing $bearing" +} +``` \ No newline at end of file diff --git a/_docs/mod/fs.md b/_docs/mod/fs.md new file mode 100644 index 0000000..8d52d0b --- /dev/null +++ b/_docs/mod/fs.md @@ -0,0 +1,11 @@ +# FS Module + +Functions for accessing the file system. + +### lines + +``` +fs:lines FILE +``` + +Returns a list containing the scanned lines of FILE. diff --git a/_docs/mod/index.md b/_docs/mod/index.md new file mode 100644 index 0000000..0c4707e --- /dev/null +++ b/_docs/mod/index.md @@ -0,0 +1,8 @@ +# Modules + +Modules of the standard library: + +- [core](/mod/core): Core builtins +- [csv](/mod/csv): Functions for operating over CSV data. +- [fs](/mod/fs): File system functions +- [os](/mod/os): Operating system functions \ No newline at end of file diff --git a/_docs/mod/os.md b/_docs/mod/os.md new file mode 100644 index 0000000..cfcd97b --- /dev/null +++ b/_docs/mod/os.md @@ -0,0 +1,17 @@ +# OS Module + +Functions for accessing the operating system. + +### env + +``` +os:env NAME [DEFAULT] +``` + +Returns the value of the environment variable NAME. If no environment with NAME +is defined, then DEFAULT will be returned, if specified. Otherwise, nil will be +returned. + +``` +echo "User's home directory is: " (os:env "HOME") +``` diff --git a/_site/playground/index.html b/_site/playground/index.html index fcba6ea..b7b4d9d 100644 --- a/_site/playground/index.html +++ b/_site/playground/index.html @@ -11,7 +11,7 @@

UCL

diff --git a/cmd/gendocs/frame.tmpl b/cmd/gendocs/frame.tmpl index 2c5e142..671fd34 100644 --- a/cmd/gendocs/frame.tmpl +++ b/cmd/gendocs/frame.tmpl @@ -9,7 +9,7 @@

UCL

diff --git a/cmd/gendocs/main.go b/cmd/gendocs/main.go index e53b1e7..0acee9d 100644 --- a/cmd/gendocs/main.go +++ b/cmd/gendocs/main.go @@ -10,6 +10,7 @@ import ( "html/template" "log" "os" + "path/filepath" ) //go:embed frame.tmpl @@ -18,13 +19,16 @@ var frameTmpl embed.FS func main() { flag.Parse() - if flag.NArg() != 1 { - log.Fatalln("usage: gendocs [markdown]") + if flag.NArg() != 2 { + log.Fatalln("usage: gendocs MARKDOWN OUTFILE") } + srcFile := flag.Arg(0) + dstFile := flag.Arg(1) + md := goldmark.New(goldmark.WithExtensions(&frontmatter.Extender{})) - mdData, err := os.ReadFile(flag.Arg(0)) + mdData, err := os.ReadFile(srcFile) if err != nil { log.Fatal(err) } @@ -57,5 +61,11 @@ func main() { log.Fatal(err) } - os.Stdout.Write(res.Bytes()) + destDir := filepath.Dir(dstFile) + if err := os.MkdirAll(destDir, 0755); err != nil { + log.Fatal(err) + } + if err := os.WriteFile(dstFile, res.Bytes(), 0644); err != nil { + log.Fatal(err) + } }