From 17a9882f40900787f1315f985fdf3c7e029522d9 Mon Sep 17 00:00:00 2001
From: Jeremy Wall <jeremy@marzhillstudios.com>
Date: Sun, 13 Jan 2019 21:25:15 -0600
Subject: [PATCH] DOCS: Document our standard library.

---
 docsite/site/content/how-to/_index.md  |  2 +-
 docsite/site/content/stdlib/_index.md  | 15 +++++
 docsite/site/content/stdlib/lists.md   | 68 +++++++++++++++++++
 docsite/site/content/stdlib/testing.md | 91 ++++++++++++++++++++++++++
 docsite/site/content/stdlib/tuples.md  | 44 +++++++++++++
 5 files changed, 219 insertions(+), 1 deletion(-)
 create mode 100644 docsite/site/content/stdlib/_index.md
 create mode 100644 docsite/site/content/stdlib/lists.md
 create mode 100644 docsite/site/content/stdlib/testing.md
 create mode 100644 docsite/site/content/stdlib/tuples.md

diff --git a/docsite/site/content/how-to/_index.md b/docsite/site/content/how-to/_index.md
index 0510367..b840a9b 100644
--- a/docsite/site/content/how-to/_index.md
+++ b/docsite/site/content/how-to/_index.md
@@ -1,6 +1,6 @@
 +++
 title = "HowTo Guides"
-weight = 3
+weight = 4
 sort_by = "weight"
 in_search_index = true
 +++
diff --git a/docsite/site/content/stdlib/_index.md b/docsite/site/content/stdlib/_index.md
new file mode 100644
index 0000000..2871e61
--- /dev/null
+++ b/docsite/site/content/stdlib/_index.md
@@ -0,0 +1,15 @@
++++
+title = "The UCG Standard Library"
+slug = "stdlib"
+weight = 3
+sort_by = "weight"
+in_search_index = true
++++
+
+UCG has some builtin libraries for common tasks. List processing, Tuple
+manipulation, and some helpful testing assertions can all be found in the
+standard library.
+
+Each library is documented here in it's own section. Most operations in
+the standard library are in the form of modules and by convention you get
+the result of an operation from the `result` field after running the module.
\ No newline at end of file
diff --git a/docsite/site/content/stdlib/lists.md b/docsite/site/content/stdlib/lists.md
new file mode 100644
index 0000000..0b7e76a
--- /dev/null
+++ b/docsite/site/content/stdlib/lists.md
@@ -0,0 +1,68 @@
++++
+title = "UCG List Modules"
+weight = 1
+sort_by = "weight"
+in_search_index = true
++++
+
+The UCG list modules can be imported like so `let l = import "std/lists.ucg";` It has a number of useful operations.
+
+## reverse
+
+The reverse module reverses a list. It has a single required parameter:
+
+* `list` the list to reverse.
+
+```
+let l = import "std/lists.ucg";
+l.reverse{list=[1, 2, 3]}.result == [3, 2, 1];
+```
+
+## str_join
+
+The str_join module joins a list with the string representation of each element.
+It has two parameters:
+
+* `list` which is required. The list to reverse.
+* `sep` which is optional and defines the separater to use when joining the elements. Defaults to a single space
+
+```
+let l = import "std/lists.ucg";
+l.str_join{
+    sep=" ",
+    list=[1, 2, 3]
+}.result == "1,2,3";
+```
+
+## len
+
+The len module returns the length of a list. It has a single required parameter.
+
+* `list` The list to reverse.
+
+```
+let l = import "std/lists.ucg";
+l.len{list=[0, 1, 2, 3]}.result == 4;
+```
+
+## enumerate
+
+The enumerate module enumerates the elements of a list. It has three parameters.
+
+* `list` which is required and is the list to enumerate.
+* `start` which is optional and defines the start number of the enumeration. (defaults to 0)
+* `step` which is optional and defines the step amount for the enumeration. (defaults to 1)
+
+```
+let l = import "std/lists.ucg";
+
+// with defaults
+l.enumerate{list=[1, 2, 3]}.result == [[0, 1], [1, 2], [3, 4]];
+
+// With all parameters
+l.enumerate{
+    start=1,
+    step=2,
+    list=["foo", "bar", "foobar"],
+}.result == [[1, "foo"], [3, "bar"], [5, "foobar"]];
+```
\ No newline at end of file
diff --git a/docsite/site/content/stdlib/testing.md b/docsite/site/content/stdlib/testing.md
new file mode 100644
index 0000000..2b14445
--- /dev/null
+++ b/docsite/site/content/stdlib/testing.md
@@ -0,0 +1,91 @@
++++
+title = "UCG Testing Modules"
+weight = 3
+sort_by = "weight"
+in_search_index = true
++++
+
+The UCG testing modules can be imported like so `let t = import "std/testing.ucg";`
+It has a number of helpful assertions you can use in unit testing.
+
+## The asserts modules
+
+The asserts module exposes a number of asserts. It contains nested modules for each
+available assertion. You can configure the asserts module with a default description if desired.
+
+Each of the asserts results in a `result` field that is a tuple with the shape that
+the assert statement expects.
+
+The asserts module has one parameter.
+
+* `default_description` which is optional and defaults to "TODO description"
+
+### ok assertion
+
+The `ok` assertion module tests that something is true. It has two parameters.
+
+* `test` which is required and is represents the expression to test.
+* `desc` which is an optional description to output for your test. This defaults to
+    the `default_description` that the `asserts` modules was set to.
+
+```
+let t = import "std/testing.ucg".asserts{};
+
+assert t.ok{
+    test=true,
+};
+```
+
+### no_ok assertion
+
+The `not_ok` assertion module tests that something is not true. It has two
+parameters.
+
+* `test` which is required and is represents the expression to test.
+* `desc` which is an optional description to output for your test. This defaults to
+    the `default_description` that the `asserts` modules was set to.
+
+```
+let t = import "std/testing.ucg".asserts{};
+
+assert t.ok{
+    test=true,
+};
+```
+
+### equal assertion
+
+The `equal` assertion module tests that two items are equal. It has two parameters.
+
+* `left` which is required and is the left hand side expression to compare
+* `right` which is required is the right hand side expression to compare.
+
+This module will create a description for you from the compared values.
+
+```
+let t = import "std/testing.ucg".asserts{};
+
+assert t.equal{
+    left=1,
+    right=1,
+};
+```
+
+### not_equal assertion
+
+The `not_equal` assertion module tests that two items are not equal. It has two
+parameters.
+
+* `left` which is required and is the left hand side expression to compare
+* `right` which is required is the right hand side expression to compare.
+
+This module will create a description for you from the compared values.
+
+```
+let t = import "std/testing.ucg".asserts{};
+
+assert t.not_equal{
+    left=1,
+    right=2,
+};
+```
\ No newline at end of file
diff --git a/docsite/site/content/stdlib/tuples.md b/docsite/site/content/stdlib/tuples.md
new file mode 100644
index 0000000..44f7a05
--- /dev/null
+++ b/docsite/site/content/stdlib/tuples.md
@@ -0,0 +1,44 @@
++++
+title = "UCG Tuple Modules"
+weight = 2
+sort_by = "weight"
+in_search_index = true
++++
+
+The UCG tuples modules can be imported like so `let t = import "std/tuples.ucg";` 
+and contains a number of useful operations on tuples.
+
+## fields
+
+The `fields` module retrieves all the field names in a tuple. It has one
+parameter.
+
+* `tpl` which is required and is the tuple to process.
+
+```
+let tpl = import "std/tuples.ucg";
+tpl.fields{tpl={foo=1, bar=2}}.result == ["foo", "bar"];
+```
+
+## values
+
+The `values` module retrieves all the values in a tuple. It has one parameter.
+
+* `tpl` which is required and is the tuple to process.
+
+```
+let tpl = import "std/tuples.ucg";
+tpl.values{tpl={foo=1, bar=2}}.result == [1, 2];
+```
+
+## iter
+
+The `iter` module retrieves a list of all the field and value pairs in a tuple.
+It has one parameter.
+
+* `tpl` which is required and is the tuple to process.
+
+```
+let tpl = import "std/tuples.ucg";
+tpl.enumerate{tpl={foo=1, bar=2}}.result == [["foo", 1], ["bar", 2]];
+```
\ No newline at end of file