Started working on more package docs

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

_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"
 }
 ```

_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"
+}
+```

_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.

_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 

_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")
+```

_site/playground/index.html

@@ -11,7 +11,7 @@
         <h1>UCL</h1>
         <nav>
             <a href="/">Home</a>
-            <a href="/core/">Core</a>
+            <a href="/mod/">Modules</a>
             <a href="/playground/">Playground</a>
         </nav>
     </header>

cmd/gendocs/frame.tmpl

@@ -9,7 +9,7 @@
         <h1>UCL</h1>
         <nav>
             <a href="/">Home</a>
-            <a href="/core/">Core</a>
+            <a href="/mod/">Modules</a>
             <a href="/playground/">Playground</a>
         </nav>
     </header>

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)
+	}
 }