From 2e5833d29ce323b63005a2371fcf34de3755f4aa Mon Sep 17 00:00:00 2001
From: Paul Chiusano <paul.chiusano@gmail.com>
Date: Tue, 6 Oct 2020 14:09:33 -0400
Subject: [PATCH] WIP of transcripts and docs

---
 unison-src/new-runtime-transcripts/README     |  1 +
 unison-src/new-runtime-transcripts/hashing.md | 54 ++++++++++++++++++-
 2 files changed, 53 insertions(+), 2 deletions(-)
 create mode 100644 unison-src/new-runtime-transcripts/README

diff --git a/unison-src/new-runtime-transcripts/README b/unison-src/new-runtime-transcripts/README
new file mode 100644
index 000000000..f61a2fe30
--- /dev/null
+++ b/unison-src/new-runtime-transcripts/README
@@ -0,0 +1 @@
+Transcripts in this directory are only run using the new runtime.
diff --git a/unison-src/new-runtime-transcripts/hashing.md b/unison-src/new-runtime-transcripts/hashing.md
index 18f98cb16..ea1349b78 100644
--- a/unison-src/new-runtime-transcripts/hashing.md
+++ b/unison-src/new-runtime-transcripts/hashing.md
@@ -5,12 +5,18 @@
 .> cd builtin
 ```
 
-Unison has some cryptographic builtins for hashing and computing [HMACs](https://en.wikipedia.org/wiki/HMAC) (hash-based message authentication codes). In order to print out and test these hashes we will be using some new primitives for base16 encoding and decoding:
+Unison has some cryptographic builtins for hashing and computing [HMACs](https://en.wikipedia.org/wiki/HMAC) (hash-based message authentication codes). This transcript shows their usage and has some test cases.
+
+## Setup
+
+You can skip this section, it's just needed to make the transcript self-contained. In order to print out and test these hashes we will be using some builtins for base16 (aka hexidecimal) encoding and decoding.
 
 ```ucm
 .builtin> ls Bytes
 ```
 
+Notice the `fromBase16` and `toBase16` functions. Here's some (somewhat inefficient) convenience functions for converting `Bytes` to and from base 16 `Text`. These could be replaced by use of `Text.toUtf8` and `Text.tryFromUtf8` once those builtins exist:
+
 ```unison
 a |> f = f a
 
@@ -38,12 +44,56 @@ Bytes.fromHex txt =
     Left e -> bug e
     Right bs -> bs
 
-> hex (fromHex "18293857103947109284ff")
+check : Boolean -> [Result]
+check = cases
+  true  -> [Ok "Passed."]
+  false -> [Fail "Failed."]
+
 ```
 
+The test shows that `hex (fromHex str) == str` as expected.
+
+```ucm
+.scratch> add
+```
+
+## API overview
+
+Here's a few examples.
+
+```unison
+ex1 = fromHex "2947db"
+        |> crypto.hashBytes Sha3_512
+        |> hex
+
+ex2 = fromHex "02f3ab"
+        |> crypto.hashBytes Blake2b_256
+        |> hex
+
+mysecret : Bytes
+mysecret = fromHex "237be2"
+
+ex3 = fromHex "50d3ab"
+        |> crypto.hmacBytes Sha2_256 mysecret
+        |> hex
+
+> ex1
+> ex2
+> ex3
+```
+
+And here's the full API:
+
 ```ucm
 .builtin.crypto> find
 ```
 
+Note that the universal versions of `hash` and `hmac` are currently unimplemented and will bomb at runtime:
+
+```unison:error
+> crypto.hash Sha3_256 (fromHex "3849238492")
+```
+
+## Tests