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.yamlindex a14b17f..fa3cbd9 100644--- a/cloudbuild.yaml+++ b/cloudbuild.yaml@@ -41,6 +41,15 @@ steps:apt-get -y install postgresql libpq-devstack 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/gsutilentrypoint: 'bash'diff --git a/docs/source/index.rst b/docs/source/index.rstindex 58cb105..c2f4db8 100644--- a/docs/source/index.rst+++ b/docs/source/index.rst@@ -13,6 +13,7 @@ radicleguide/GettingStarted.rstguide/Basics.lradguide/Chains.lrad+ reference.mddiff --git a/exe/ReferenceDoc.hs b/exe/ReferenceDoc.hsnew file mode 100644index 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 rdiff --git a/package.yaml b/package.yamlindex ab9ce1d..2e19ea1 100644--- a/package.yaml+++ b/package.yaml@@ -160,6 +160,18 @@ executables:- pandocghc-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- ConstraintKindsdiff --git a/rad/chain.rad b/rad/chain.radindex 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-headdiff --git a/rad/prelude.rad b/rad/prelude.radindex 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.radindex 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.radindex 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.radindex 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.radindex 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 filediff --git a/rad/prelude/recursion.rad b/rad/prelude/recursion.radindex 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.radindex 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.shindex 88495dc..9982696 100755--- a/scripts/build-docs.sh+++ b/scripts/build-docs.sh@@ -24,6 +24,7 @@ popd () {}build(){+ stack exec ref-docpushd "$PWD"/docs[ -z "$IS_NIX" ] && pip install -r requirements.txtmake htmldiff --git a/src/Radicle/Internal/Doc.hs b/src/Radicle/Internal/Doc.hsindex 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 :: QuasiQuotermd = QuasiQuoter- { quoteExp = \s -> [| case checkPandocMd s of+ { quoteExp = \s -> [| case cleanupPandocMd s ofLeft e -> panic $ "Not valid pandoc-markdown: " <> show eRight s' -> s' |], quoteType = err@@ -45,7 +45,7 @@ md = QuasiQuoterwhereerr = panic "pan only works for expressions"-checkPandocMd :: Text -> Either PandocError Text-checkPandocMd s = runPure $ do+cleanupPandocMd :: Text -> Either PandocError Text+cleanupPandocMd s = runPure $ dop <- readMarkdown Default.def swriteMarkdown Default.def p