Skip to content

A peer-to-peer stack for code collaboration

Add an executable which creates the radicle reference doc. (#180)

James Haydon5e131526d3d7
diff --git a/cloudbuild.yaml b/cloudbuild.yaml
index a14b17f..fa3cbd9 100644
--- a/cloudbuild.yaml
+++ b/cloudbuild.yaml
@@ -41,6 +41,15 @@ steps:
apt-get -y install postgresql libpq-dev
stack build --fast --test --no-terminal --pedantic
+ - id: "Build reference document"
+ name: 'haskell:8.4.3'
+ env: ['STACK_ROOT=/workspace/.stack']
+ entrypoint: bash
+ args:
+ - '-c'
+ - |
+ stack exec ref-doc
+
- id: "Save cache"
name: gcr.io/cloud-builders/gsutil
entrypoint: 'bash'
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 58cb105..c2f4db8 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -13,6 +13,7 @@ radicle
guide/GettingStarted.rst
guide/Basics.lrad
guide/Chains.lrad
+ reference.md
diff --git a/exe/ReferenceDoc.hs b/exe/ReferenceDoc.hs
new file mode 100644
index 0000000..7f4c553
--- /dev/null
+++ b/exe/ReferenceDoc.hs
@@ -0,0 +1,122 @@
+{-# LANGUAGE QuasiQuotes #-}
+-- | This executable generates the radicle reference docs. This is a markdown
+-- document which contains documentation for all the primitive functions and all
+-- the functions defined in the prelude.
+module ReferenceDoc where
+
+import Protolude
+
+import Data.List
+import qualified Data.Map.Strict as Map
+import Data.String.Interpolate
+import qualified Data.Text as T
+import qualified GHC.Exts as GhcExts
+import Radicle
+import Radicle.Internal.Doc (md)
+import qualified Radicle.Internal.Doc as Doc
+import System.Console.Haskeline (defaultSettings, runInputT)
+
+main :: IO ()
+main = do
+ res_ <- runInputT defaultSettings $
+ interpret
+ "reference-doc"
+ "(do (load! \"rad/prelude.rad\") (get-current-env))"
+ replBindings
+ res <- res_ `lPanic` "Error running the prelude."
+ s :: Bindings () <- fromRad res `lPanic` "Couldn't convert radicle state."
+ let vars = GhcExts.toList (bindingsEnv s)
+ let undocd = [ fromIdent iden | (iden, Nothing, _) <- vars ]
+ checkAllDocumented undocd
+ let e = Map.fromList [ (fromIdent iden, d) | (iden, Just d, _) <- vars ]
+ checkAllInReference e
+ d <- Doc.cleanupPandocMd (doc e) `lPanic` "Invalid markdown."
+ writeFile "docs/source/reference.md" d
+ where
+ doc e =
+ let sec (tit :: Text) fns p = toS [i|## #{tit}\n\n#{p}\n\n#{funs e fns}|] in
+ T.intercalate "\n\n"
+ [ "# Radicle reference"
+ , "These are the functions that are available in a new radicle chain after the prelude has been loaded."
+ , sec "Basics" basics
+ "Basic function used for checking equality, determining the type of a value, etc."
+ , sec "Numerical functions" maths "Operations on numbers."
+ , sec "Lists" lists $ typ "lists"
+ , sec "Vectors" vecs $ typ "vectors"
+ , sec "Sequences" seqs $ typ "boths lists and vectors"
+ , sec "Dicts" dicts $ typ "dicts"
+ , sec "Structures" structs $ typ "lists, vectors and dicts"
+ , sec "Refs" refs "Functions for creating, querying and modifying refs."
+ , sec "Evaluation functions" evalFns "Utilities for creating and extending evaluation functions."
+ , sec "Documentation and testing" docs
+ "Functions for creating and querying documentation of variables in scope, and testing functions."
+ , sec "Environment functions" envStuff "Utilities for modifying the current environment."
+ , sec "Input/Output" io
+ "Effectful functions. These functions are not available in 'pure' chains, but are available in the local REPL."
+ , sec "Lenses" lens
+ "Functional references into radicle values."
+ , sec "Cryptography" crypto
+ "Tools for creating and verifying cryptographic signatures, and generating private/public key pairs."
+ , sec "Chain tools" chainTools
+ [md|These functions can be used to simulate remote chains in the local REPL.
+ This is useful for experimenting with inputs or even new evaluation functions"
+ before sending these to a remote chain.|]
+ ]
+
+ basics =
+ [ "eq?", "not", "and", "or", "all", "some", "show", "string-append", "apply", "type", "atom?"
+ , "boolean?", "string?", "number?", "keyword?", "list?", "dict?", "read", "throw"
+ , "Y", "Y2", "to-json", "uuid?", "make-counter" ]
+ maths = ["+", "*", "-", "<", ">"]
+ evalFns = ["base-eval", "eval", "updatable-eval"]
+ envStuff = ["pure-env", "get-current-env", "set-current-env", "set-env!"]
+ seqs = ["nth", "foldl", "foldr", "map", "seq"]
+ lists =
+ [ "list", "nil", "head", "tail", "empty?", "cons", "reverse", "length", "concat"
+ , "filter", "range", "list-with-head" ]
+ vecs = ["<>", "add-left", "add-right"]
+ dicts =
+ ["dict", "lookup", "insert", "delete", "dict-from-list", "keys", "rekey"
+ , "map-values", "modify-map"]
+ structs = ["member?"]
+ refs = ["ref", "read-ref", "write-ref", "modify-ref"]
+ docs = ["doc", "doc!", "apropos!", "document", "should-be"]
+ io =
+ ["print!", "get-line!", "load!", "read-file!", "read-code!", "send-code!"
+ , "send-prelude!", "subscribe-to!", "uuid!", "read-line!"]
+ lens = ["@", "make-lens", "view", "view-ref", "set", "set-ref", "over", "over-ref", "id-lens", "..", "..."]
+ crypto = ["verify-signature", "default-ecc-curve", "gen-key-pair!", "gen-signature!"]
+ chainTools =
+ [ "new-chain", "eval-in-chain", "enter-remote-chain", "update-chain", "add-quit", "add-send"
+ , "load-chain", "pure-prelude-files", "pure-prelude-code", "store-exprs", "eval-fn-app"
+ , "state-machine-eval", "state-machine-input", "state-machine-new-trans", "state-machine-agree", "state-machine-disagree", "simple-trans"]
+
+ typ s = "Functions for manipulating " <> s <> "."
+
+ -- Functions which shouldn't be in the reference docs.
+ doNotInclude = ["head-shots", "get-head-shot", "eval__", "kim-trans", "pr-thread", "pr-trans"]
+
+ allFns =
+ basics ++ maths ++ evalFns ++ envStuff ++ seqs ++ lists ++ vecs
+ ++ dicts ++ structs ++ refs ++ docs ++ io ++ lens ++ crypto ++ chainTools
+ ++ doNotInclude
+
+ -- Function symbol followed by a hard line break, followed by it's doc.
+ funs e fns = T.intercalate "\n\n\n" $ [ toS [i|`#{f}` \n#{getDoc e f}|] | f <- fns ]
+
+ getDoc e f = case Map.lookup f e of
+ Just d -> d
+ Nothing -> panic $ "While creating reference doc, couldn't find the docs for: " <> f
+
+ checkAllDocumented = \case
+ [] -> pure ()
+ vs -> panic $ "The following functions have no documentation strings: " <> T.intercalate ", " vs
+
+ checkAllInReference e =
+ let notDocumented = Map.keys e \\ allFns in
+ if null notDocumented
+ then pure ()
+ else panic $ "The following functions need to be added to the reference doc: " <> T.intercalate ", " notDocumented
+
+ lPanic (Left _) m = panic m
+ lPanic (Right r) _ = pure r
diff --git a/package.yaml b/package.yaml
index ab9ce1d..2e19ea1 100644
--- a/package.yaml
+++ b/package.yaml
@@ -160,6 +160,18 @@ executables:
- pandoc
ghc-options: -main-is Doc
+ ref-doc:
+ main: ReferenceDoc.hs
+ source-dirs: exe/
+ other-modules: []
+ when:
+ - condition: impl(ghcjs)
+ buildable: false
+ dependencies:
+ - radicle
+ - interpolate
+ ghc-options: -main-is ReferenceDoc
+
default-extensions:
- AutoDeriveTypeable
- ConstraintKinds
diff --git a/rad/chain.rad b/rad/chain.rad
index cf3e7f6..e92348b 100644
--- a/rad/chain.rad
+++ b/rad/chain.rad
@@ -111,6 +111,7 @@
;; enter-remote-chain
(def enter-remote-chain
+ "Make the eval behave as that of a remote chain."
(fn [url]
(def chain (load-chain url))
(def chain-state (lookup :state chain))
@@ -126,8 +127,12 @@
mod-state2))
(list :ok mod-state3)))
-(def eval__ eval)
+(def eval__ "The eval in place when `chain.rad` is loaded." eval)
+
(def eval
+ "An eval in which one can use `(:enter-chain url)` to make the
+ eval behave as that of a remote chain, and `:send` to send all
+ enqueued expressions."
(fn [expr env]
(if (list? expr)
(cond
@@ -137,12 +142,17 @@
(eval__ expr env))))
(def eval-fn-app
+ "Given a state, a function, an argument and a callback, returns
+ the result of evaluating the function call on the arg in the given
+ state, while also calling the callback on the result."
(fn [state f arg cb]
(def exec (base-eval (list f (list 'quote arg)) state))
(cb (head exec))
exec))
(def updatable-eval
+ "Given an evaluation function `f`, returns a new one which augments `f` with a new
+ command `(update expr)` which evaluates arbitrary expression using `base-eval`."
(fn [sub-eval]
(fn [expr state]
(list-with-head
diff --git a/rad/prelude.rad b/rad/prelude.rad
index 141bb02..f43cf14 100644
--- a/rad/prelude.rad
+++ b/rad/prelude.rad
@@ -46,15 +46,10 @@
"Send the pure prelude to a chain.")
(def make-counter
+ "Creates a stateful counter. Returns a dict with two keys: the function at `:next-will-be`
+ will return the next number (without incrementing it), while the function at `:next`
+ increments the number and returns it."
(fn []
(def i (ref -1))
{:next-will-be (fn [] (+ 1 (read-ref i)))
:next (fn [] (modify-ref i (fn [x] (+ x 1))))}))
-
-(def list-with-head
- (fn [x f g]
- (if (list? x)
- (if (> (length x) 0)
- (f (head x))
- (g))
- (g))))
diff --git a/rad/prelude/bool.rad b/rad/prelude/bool.rad
index 68868da..0bb0a65 100644
--- a/rad/prelude/bool.rad
+++ b/rad/prelude/bool.rad
@@ -2,7 +2,8 @@
;; not
-(def not (fn [x] (if x #f #t)))
+(def not
+ (fn [x] (if x #f #t)))
(document 'not
'(("arg" any))
@@ -41,6 +42,7 @@
;; all
(def all
+ "Checks that all the items of a list are truthy."
(fn [xs] (foldr and #t xs)))
(should-be "all" (all '()) #t)
@@ -52,6 +54,7 @@
;; some
(def some
+ "Checks that there is a least one truthy value in a list."
(fn [xs] (foldr or #f xs)))
(should-be "some" (some '()) #f)
diff --git a/rad/prelude/dict.rad b/rad/prelude/dict.rad
index 0d39333..05db920 100644
--- a/rad/prelude/dict.rad
+++ b/rad/prelude/dict.rad
@@ -44,8 +44,10 @@
{:b 5})
;; modify-map
-(def modify-map (fn [key f mp]
- (insert key (f (lookup key mp)) mp)))
+(def modify-map
+ "Given a key, a function and a dict, applies the function to the value associated to that key."
+ (fn [key f mp]
+ (insert key (f (lookup key mp)) mp)))
(should-be "modify-map"
(modify-map 'a (fn [x] (+ x 1)) (dict 'a 5))
diff --git a/rad/prelude/io.rad b/rad/prelude/io.rad
index 9491fc5..badab8e 100644
--- a/rad/prelude/io.rad
+++ b/rad/prelude/io.rad
@@ -1,5 +1,6 @@
;; read-line
(def read-line!
+ "Read a single line of input and interpret it as radicle data."
(fn [] (read (get-line!))))
(def read-code!
diff --git a/rad/prelude/list.rad b/rad/prelude/list.rad
index 5e05fc6..5cf0505 100644
--- a/rad/prelude/list.rad
+++ b/rad/prelude/list.rad
@@ -2,7 +2,7 @@
;; nil
-(def nil (list))
+(def nil "The empty list." (list))
;; empty?
@@ -84,4 +84,14 @@
(should-be "filter"
(filter (fn [x] (< x 10)) (list 3 10 11))
- (list 3))
\ No newline at end of file
+ (list 3))
+
+(def list-with-head
+ "Given a value `x`, and two functions `f` and `g`, checks if `x` is a list with a
+ head. If so applies `f` to the head, otherwise calls `g` with no args."
+ (fn [x f g]
+ (if (list? x)
+ (if (> (length x) 0)
+ (f (head x))
+ (g))
+ (g))))
\ No newline at end of file
diff --git a/rad/prelude/recursion.rad b/rad/prelude/recursion.rad
index d1af30e..9d2da38 100644
--- a/rad/prelude/recursion.rad
+++ b/rad/prelude/recursion.rad
@@ -1,11 +1,13 @@
;; y-combinators ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(def Y
+ "A combinator used to create recursive functions of one variable."
(fn [h]
((fn [x] (x x))
(fn [g]
(h (fn [arg] ((g g) arg)))))))
(def Y2
+ "A combinator used to create recursive functions of two variables."
(fn [h]
((fn [x] (x x))
(fn [g]
diff --git a/rad/state-machine.rad b/rad/state-machine.rad
index 622281b..2995b04 100644
--- a/rad/state-machine.rad
+++ b/rad/state-machine.rad
@@ -1,5 +1,6 @@
(def head-shots
+ "Avatars for some of the monadic team members."
(dict "onur" "https://res.cloudinary.com/juliendonck/image/upload/v1536080565/avatars/1712926.png"
"ele" "https://res.cloudinary.com/juliendonck/image/upload/v1536080565/avatars/853825.png"
"alexis" "https://res.cloudinary.com/juliendonck/image/upload/v1536080565/avatars/40774.png"
@@ -7,6 +8,7 @@
"julien" "https://res.cloudinary.com/juliendonck/image/upload/v1536080565/avatars/2326909.jpg"))
(def get-head-shot
+ "Get a monadic team-member head-shot or return Julien's."
(fn [x]
(def y (lookup x head-shots))
(if (eq? y '())
@@ -14,6 +16,7 @@
y)))
(def pr-trans
+ "PR state transition function."
(fn [state inp]
(def c (dict "key" (show (view (@ :next-id) state))
"username" (nth 0 inp)
@@ -27,13 +30,14 @@
:output c)))
(def kim-trans
+ "PR state transition function tailored to comments by Kim."
(fn [state i]
(if (eq? (nth 0 i) "kim")
(pr-trans state (list "kim" "LGTM"))
(pr-trans state i))))
-;; Handle an input in the morphing state-machine.
(def state-machine-input
+ "Handle an input in the morphing state-machine."
(fn [state i]
(def trans-fn (view-ref state (@ :transition-fn)))
(def current-state (view-ref state (@ :machine-state)))
@@ -41,8 +45,9 @@
(set-ref state (@ :machine-state) (view (@ :state) next))
(view (@ :output) next)))
-;; Trigger a new vote
+
(def state-machine-new-trans
+ "Trigger a new vote."
(fn [state func]
(if (eq? (view-ref state (@ :voting)) :nothing)
(do (set-ref state (@ :voting) (dict :votes (dict)
@@ -51,6 +56,7 @@
(throw 'invalid-input "Can't propose new transition function while vote is ongoing."))))
(def state-machine-agree
+ "Vote to agree on a new transition function."
(fn [state voters userid]
(if (member? userid voters)
(do (set-ref state (... (list (@ :voting) (@ :votes) (@ userid))) #t)
@@ -62,15 +68,15 @@
(throw 'invalid-input "Not allowed to vote."))))
(def state-machine-disagree
+ "Vote to disagree on a new transition function."
(fn [state voters userid]
(if (member? userid voters)
(do (set-ref state (@ :voting) :nothing)
"Voting has ended; someone disagreed.")
(throw 'invalid-input "You are not allowed to vote."))))
-;; Returns an eval which operates a state machine whose transition function may
-;; be updated. To update the transition function all voters must agree on it.
(def state-machine-eval
+ "Returns an eval which operates a state machine whose transition function may be updated. To update the transition function all voters must agree on it."
(fn [voters init-state init-transition]
(def state (ref (dict :machine-state init-state
:transition-fn init-transition
@@ -86,6 +92,7 @@
:else (throw 'invalid-input (string-append "The only valid commands are 'input', 'new-trans-func', 'agree' and 'disagree': " (show expr)))))))
(def simple-trans
+ "Given a function `f`, makes a transition function who's output is also the next state."
(fn [f]
(fn [s i]
(def y (f s i))
@@ -93,6 +100,7 @@
:output y))))
(def pr-thread
+ "A PR thread with two voters: `\"alice\"` and `\"bob\"`."
(state-machine-eval
(list "alice" "bob")
(dict :next-id 0 :comments (list))
diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh
index 88495dc..9982696 100755
--- a/scripts/build-docs.sh
+++ b/scripts/build-docs.sh
@@ -24,6 +24,7 @@ popd () {
}
build(){
+ stack exec ref-doc
pushd "$PWD"/docs
[ -z "$IS_NIX" ] && pip install -r requirements.txt
make html
diff --git a/src/Radicle/Internal/Doc.hs b/src/Radicle/Internal/Doc.hs
index 7b46e31..6bbf206 100644
--- a/src/Radicle/Internal/Doc.hs
+++ b/src/Radicle/Internal/Doc.hs
@@ -35,7 +35,7 @@ noDocs = fmap $ \(x,y) -> (x, Nothing, y)
-- returns the markdown with better formatting.
md :: QuasiQuoter
md = QuasiQuoter
- { quoteExp = \s -> [| case checkPandocMd s of
+ { quoteExp = \s -> [| case cleanupPandocMd s of
Left e -> panic $ "Not valid pandoc-markdown: " <> show e
Right s' -> s' |]
, quoteType = err
@@ -45,7 +45,7 @@ md = QuasiQuoter
where
err = panic "pan only works for expressions"
-checkPandocMd :: Text -> Either PandocError Text
-checkPandocMd s = runPure $ do
+cleanupPandocMd :: Text -> Either PandocError Text
+cleanupPandocMd s = runPure $ do
p <- readMarkdown Default.def s
writeMarkdown Default.def p