Merge branch 'master' into add-stats-linalg-bench

16 files changed, 94 insertions, 19 deletions

diff --git a/doc/argparse.mdz b/doc/argparse.mdz
index 0f3d0a6..bb97e7b 100644
--- a/doc/argparse.mdz
+++ b/doc/argparse.mdz
@@ -2,7 +2,7 @@
  :author "Calvin Rose"
  :license "MIT"
  :template "mdzdoc/main.html"
- :order 6}
+ :order 0}
 ---
 
 A moderately opinionated argument parser for
diff --git a/doc/data.mdz b/doc/data.mdz
new file mode 100644
index 0000000..da0302a
--- /dev/null
+++ b/doc/data.mdz
@@ -0,0 +1,37 @@
+{:title "data"
+ :author "Caleb Figgers"
+ :license "MIT"
+ :template "mdzdoc/main.html"
+ :order 1}
+---
+@link[https://clojure.org/]{Clojure} contains a very useful core library (or "namespace" in Clojure parlance) called @link[https://clojure.github.io/clojure/clojure.data-api.html]{clojure.data} (@link[https://github.com/clojure/clojure/blob/51c6d7a70912a8f65e81a8e11ae6f56c94920725/src/clj/clojure/data.clj]{source}). It contains one "exported" function: @code`clojure.data/diff`. This addition to spork, @code`data.janet`, should exactly replicate the behavior of @code`clojure.data/diff` using Janet tables, structs, arrays, and tuples in place of their Clojure equivalents.
+
+## Function
+
+The @code`diff` function recursively compares the structure and contents of two data structures (struct, table, tuple, array) and returns an array with three elements:
+
+@codeblock`@[things-only-in-a things-only-in-b things-in-both]`
+
+In the case of nested associative data structures (i.e., tables and structs), the comparison is recursive and the data structures are neatly partitioned into the same @code`@[things-only-in-a things-only-in-b things-in-both]` structure, but arbitrary levels deep in the two original associative data structures.
+
+This function makes comparing two structs or tables for changes trivial. (An example use case: compare the decoded JSON returned from a REST API call made seconds ago against the version of that same decoded JSON from that same API that was returned from the same call made an hour ago and stored locally in a database for comparison an hour later.)
+
+## Example
+
+So for example, @code`diff`'ing the two nested structs @code`{:a 1 :b 2 :c {:d 3 :e 4}}` and @code`{:a 4 :b 2 :c {:d 3 :e 5 :f 6}}` looks like this:
+
+@codeblock[janet]```
+repl:1:> (import spork/data :as d)
+repl:2:> (d/diff {:a 1 :b 2 :c {:d 3 :e 4}} {:a 4 :b 2 :c {:d 3 :e 5 :f 6}})
+@[@{:a 1 :c @{:e 4}} @{:a 4 :c @{:e 5 :f 6}} @{:b 2 :c @{:d 3}}]
+```
+
+The return is @code`@[@{:a 1 :c @{:e 4}} @{:a 4 :c @{:e 5 :f 6}} @{:b 2 :c @{:d 3}}]` because:
+
+@ul{
+  @li{the value for @code`:a` appears in both and is different in each one (so @code`:a` is a key in both the first and second returned table, with each value set as seen in the first and second original structs)}
+  @li{the value for @code`:b` appears in both and is the same in each (so @code`:b` is a key only in the third returned table, containing the shared value in both original strucs)}
+  @li{the nested value of @code`:d` appears in both and is the same in each (so @code`:c` is a key in the third returned table, containing the value of @code`:d` that is shared in both original structs)}
+  @li{the nested value of @code`:e` appears in both and is different in each one (so @code`:c` is a key in both the first and second returned table, containing the value @code`:e` with with each value set as seen in the first and second original structs), and}
+  @li{the key/value pair @code`:f` 6 only appears in the latter original struct (so only the second returned table contains @code`:f` and its value).}
+}
diff --git a/doc/formatting.mdz b/doc/formatting.mdz
index ba3779d..f5842a4 100644
--- a/doc/formatting.mdz
+++ b/doc/formatting.mdz
@@ -2,7 +2,7 @@
  :author "Calvin Rose"
  :license "MIT"
  :template "mdzdoc/main.html"
- :order 1}
+ :order 2}
 ---
 
 Provides a way to format Janet code strings and files.
diff --git a/doc/generators.mdz b/doc/generators.mdz
index 995f561..0817e26 100644
--- a/doc/generators.mdz
+++ b/doc/generators.mdz
@@ -2,7 +2,7 @@
  :author "Z. D. Smith"
  :license "BSD3"
  :template "mdzdoc/main.html"
- :order 11}
+ :order 3}
 ---
 
 # Generators for Janet
diff --git a/doc/htmlgen.mdz b/doc/htmlgen.mdz
index 5a7471c..1c989ad 100644
--- a/doc/htmlgen.mdz
+++ b/doc/htmlgen.mdz
@@ -2,7 +2,7 @@
  :author "Calvin Rose"
  :license "MIT"
  :template "mdzdoc/main.html"
- :order 12}
+ :order 4}
 ---
 
 HTMLgen is a rendering engine that can render plain data structures into
diff --git a/doc/http.mdz b/doc/http.mdz
index d206726..b677e4e 100644
--- a/doc/http.mdz
+++ b/doc/http.mdz
@@ -2,7 +2,7 @@
  :author "Calvin Rose"
  :license "MIT"
  :template "mdzdoc/main.html"
- :order 0}
+ :order 5}
 ---
 
 The @code`http` module is an HTTP/1.1 parser, server and client module. It proves a simple server implementation, client, support for chunked encoding.
diff --git a/doc/index.mdz b/doc/index.mdz
index 1461999..0759cc8 100644
--- a/doc/index.mdz
+++ b/doc/index.mdz
@@ -2,7 +2,7 @@
  :author "Calvin Rose"
  :license "MIT"
  :template "mdzdoc/main.html"
- :order 0}
+ :order 6}
 ---
 
 Spork is a utility library for Janet. It contains a number of small
diff --git a/doc/message-protocol.mdz b/doc/message-protocol.mdz
index 315adf4..058f804 100644
--- a/doc/message-protocol.mdz
+++ b/doc/message-protocol.mdz
@@ -2,7 +2,7 @@
  :author "Calvin Rose"
  :license "MIT"
  :template "mdzdoc/main.html"
- :order 2}
+ :order 7}
 ---
 
 Provide a symmetric way to send and receive seqential messages over a
diff --git a/doc/misc.mdz b/doc/misc.mdz
index af8a004..f224796 100644
--- a/doc/misc.mdz
+++ b/doc/misc.mdz
@@ -2,7 +2,7 @@
  :author "Calvin Rose"
  :license "MIT"
  :template "mdzdoc/main.html"
- :order 9}
+ :order 8}
 ---
 
 ## Dedent
@@ -126,7 +126,7 @@ pairs arguments and setting its prototype to prototype.
 Factory function for creating new objects from prototypes.
 
 @codeblock[janet]```
-(def Proto @{:greet |(string "Hello " ($ :name))})
+(def Proto @{:greet (fn [self] (string "Hello " (self :name)))})
 (def t (misc/make Proto :name "pepe"))
 (:greet t)
 # => "Hello pepe"
@@ -384,3 +384,19 @@ Returns an array of hexs from the string with pgp words.
 (misc/pgp/words->hexs "absurd-scavenger accrue_universe upshot.village")
 # => @["01" "D1" "02" "EE" "F4" "F6"]
 ```
+
+## base64/encode
+Converts a string of any format (UTF-8, binary, ..) to base64 encoding.
+@codeblock[janet]```
+(misc/base64/encode "this is a test")
+# => "dGhpcyBpcyBhIHRlc3Q="
+```
+
+
+## base64/decode
+Converts a base64 encoded string to its binary representation of any format (UTF-8, binary, ..).
+@codeblock[janet]```
+(misc/base64/decode "dGhpcyBpcyBhIHRlc3Q=")
+# => "this is a test"
+```
+
diff --git a/doc/networked-repl.mdz b/doc/networked-repl.mdz
index c0be04c..541c399 100644
--- a/doc/networked-repl.mdz
+++ b/doc/networked-repl.mdz
@@ -2,7 +2,7 @@
  :author "Calvin Rose"
  :license "MIT"
  :template "mdzdoc/main.html"
- :order 3}
+ :order 9}
 ---
 
 Launch a networked REPL server on one machine and connect to it from
diff --git a/doc/path.mdz b/doc/path.mdz
index 2e272ee..0fc6206 100644
--- a/doc/path.mdz
+++ b/doc/path.mdz
@@ -2,9 +2,8 @@
  :author "Calvin Rose"
  :license "MIT"
  :template "mdzdoc/main.html"
- :order 5}
+ :order 10}
 ---
-
 Simple path manipulation module for Janet. Supports manipulation both
 windows and posix paths on any platform, and provides functions that
 work according to the current host platform.
@@ -14,6 +13,7 @@ All functions have three forms, under @code`path`, @code`path/win`, and
 manipulates.
 
 @codeblock[janet]```
+
 (import spork/path)
 
 # Examples for a non-windows system, use path/win/ for windows and
@@ -29,5 +29,7 @@ path/delim # -> ":" on posix, ";" on windows
 (path/join "some/path" "../thing/file.txt") # -> "some/thing/file.txt"
 (path/abspath? "/home/blah") # -> true
 (path/abspath "file.txt") # -> "/home/me/cwd/file.txt"
-(path/relpath "a/nested/directory/with/a/few/children" "a/nested/directory/with/different/children") # -> "../../../different/children"
+(path/relpath
+  "a/nested/directory/with/a/few/children"
+  "a/nested/directory/with/different/children") # -> "../../../different/children"
 ```
diff --git a/doc/randgen.mdz b/doc/randgen.mdz
new file mode 100644
index 0000000..e1a1f22
--- /dev/null
+++ b/doc/randgen.mdz
@@ -0,0 +1,20 @@
+{:title "Random Generator"
+ :author "Calvin Rose"
+ :license "MIT"
+ :template "mdzdoc/main.html"
+ :order 11}
+---
+
+A small utility for random number generation, especially with a focus on
+discrete numbers. The most powerful idea here is the ability to have branches
+that execute in a probabilistic manner - i.e. one branch is taken half the time
+randomly, and another is taken otherwise.
+
+@codeblock[janet]```
+# Print either a, b, or c
+(import spork/randgen)
+(randgen/rand-path
+  (print "a")
+  (print "b")
+  (print "c"))
+```
diff --git a/doc/regex.mdz b/doc/regex.mdz
index a38a38c..644c945 100644
--- a/doc/regex.mdz
+++ b/doc/regex.mdz
@@ -2,7 +2,7 @@
  :author "Calvin Rose"
  :license "MIT"
  :template "mdzdoc/main.html"
- :order 10}
+ :order 12}
 ---
 
 A module for compiling a subset of regexes to Janet PEGs.
@@ -23,4 +23,4 @@ Supported regex features:
   - Non-capture groups, e.g. @code`(?:abc)`
 
 Features found in other regex may never be added - for more complex usage,
-use Janet's native PEG library.
\ No newline at end of file
+use Janet's native PEG library.
diff --git a/doc/rpc-protocol.mdz b/doc/rpc-protocol.mdz
index 815e922..e6cbe5a 100644
--- a/doc/rpc-protocol.mdz
+++ b/doc/rpc-protocol.mdz
@@ -2,7 +2,7 @@
  :author "Calvin Rose"
  :license "MIT"
  :template "mdzdoc/main.html"
- :order 4}
+ :order 13}
 ---
 
 A simple remote procedure call tool for Janet.
diff --git a/doc/temple.mdz b/doc/temple.mdz
index a4662ba..9fafcfa 100644
--- a/doc/temple.mdz
+++ b/doc/temple.mdz
@@ -2,7 +2,7 @@
  :author "Calvin Rose"
  :license "MIT"
  :template "mdzdoc/main.html"
- :order 7}
+ :order 14}
 ---
 
 HTML templates for Janet.
@@ -22,7 +22,7 @@ output.
 
 ### foo.temple
 
-@codeblock[janet]```
+@codeblock```
 {$ (def n 20) # Run at template compile time $}
 <html>
   <body>
diff --git a/doc/test.mdz b/doc/test.mdz
index bc973eb..5b5e4b2 100644
--- a/doc/test.mdz
+++ b/doc/test.mdz
@@ -2,7 +2,7 @@
  :author "Calvin Rose"
  :license "MIT"
  :template "mdzdoc/main.html"
- :order 8}
+ :order 15}
 ---
 
 This module contains a simple test helper when you do not need a specialized