wip

hbs2-cli/lib/HBS2/CLI/Prelude.hs

@@ -7,6 +7,7 @@ module HBS2.CLI.Prelude
   , module Control.Monad.Reader
   , module HBS2.System.Logger.Simple.ANSI
   , module HBS2.Misc.PrettyStuff
+  , qc,qq,q
   , Generic
   ) where
 
@@ -21,4 +22,5 @@ import Data.Config.Suckless
 import Control.Monad.Reader
 import UnliftIO
 
+import Text.InterpolatedString.Perl6 (qc,q,qq)
 

hbs2-cli/lib/HBS2/CLI/Run/Internal.hs

@@ -103,6 +103,9 @@ instance Pretty ManDesc where
   pretty = \case
     ManDescRaw t -> pretty t
 
+instance IsString ManDesc where
+  fromString s = ManDescRaw (Text.pack s)
+
 instance Pretty (Man a) where
   pretty e =   "NAME"
              <> line
@@ -122,8 +125,7 @@ instance Pretty (Man a) where
       Just (ManReturns t s) ->
         line <> "RETURN VALUE" <> line
         <> indent 8 (
-            pretty t <> line
+            pretty t <> hsep ["","-",""] <> pretty s) <> line
-            <> pretty s) <> line
 
     fmtDescription = line
       <> "DESCRIPTION" <> line
@@ -155,6 +157,9 @@ instance Pretty (Man a) where
       indent 8 do
         parens (pretty (manName e) <+>
          hsep [ pretty n | ManApplyArg t n <- xs ]  )
+         <> line
+         <> line
+         <> vcat [ pretty n <+> ":" <+> pretty t | ManApplyArg t n <- xs ]
 
 pattern StringLike :: forall {c} . String -> Syntax c
 pattern StringLike e <- (stringLike -> Just e)
@@ -398,6 +403,11 @@ makeDict w = execWriter ( fromMakeDict w )
 entry :: Dict c m  -> MakeDictM c m ()
 entry = tell
 
+desc :: Doc ann -> MakeDictM c m () -> MakeDictM c m ()
+desc txt = censor (HM.map setDesc)
+  where
+    w0 = mempty { manDesc = Just (ManDescRaw $ Text.pack $ show txt) }
+    setDesc (Bind w x) = Bind (Just (maybe w0 (<> w0) w)) x
 
 brief :: ManBrief -> MakeDictM c m () -> MakeDictM c m ()
 brief txt = censor (HM.map setBrief)
@@ -680,7 +690,30 @@ internalEntries = do
         pure $ mkForm "dict" [ mkList [a, b] ]
       _ -> throwIO (BadFormException @C nil)
 
-    entry $ bindMatch "kw" $ \syn -> do
+    brief "creates a dict from a linear list of string-like items"
+      $ args [arg "list-of-terms" "..."]
+      $ desc (    "macro; syntax sugar" <> line
+               <> "useful for creating function args" <> line
+               <> "leftover records are skipped"
+             )
+      $ returns "dict" ""
+      $ examples [qc|
+[kw a 1 b 2 c 3]
+(dict (a 1) (b 2) (c 3))
+
+[kw a]
+(dict (a ()))
+
+[kw a b]
+(dict (a b))
+
+[kw 1 2 3]
+(dict)
+
+[kw a b c]
+(dict (a b) (c ()))
+      |]
+      $ entry $ bindMatch "kw" $ \syn -> do
          let wat = [ mkList @c [mkSym i, e] | (i,e) <- optlist syn ]
          pure $ mkForm "dict" wat
 

hbs2-cli/lib/HBS2/CLI/Run/LWWRef.hs

@@ -26,7 +26,10 @@ import Control.Monad.Trans.Cont
 lwwRefEntries :: forall c m . (c ~ C, IsContext c, MonadUnliftIO m) => MakeDictM  c m ()
 lwwRefEntries = do
 
-  entry $ bindMatch "hbs2:lwwref:create" $ \case
+  brief "creates a new lwwref"
+    $ desc "Creates a new keyring; adds it to keyman and subsribes hbs2-peer to listen this lwwref"
+    $ returns "string" "lwwref public key"
+    $ entry $ bindMatch "hbs2:lwwref:create" $ \case
         [] -> do
           reflog <- keymanNewCredentials (Just "lwwref") 0
 
@@ -38,7 +41,10 @@ lwwRefEntries = do
 
         _ -> throwIO (BadFormException @C nil)
 
-  entry $ bindMatch "hbs2:lwwref:list" $ \case
+  brief "lists all lwwref that hbs2-peer is subscribed to"
+    $ noArgs
+    $ returns "list of string" "lwwref list"
+    $ entry $ bindMatch "hbs2:lwwref:list" $ \case
       [] -> do
         flip runContT pure do
           so <- detectRPC `orDie` "rpc not found"
@@ -50,7 +56,11 @@ lwwRefEntries = do
       _ -> throwIO (BadFormException @C nil)
 
 
-  entry $ bindMatch "hbs2:lwwref:fetch" $ \case
+  brief "fetches lwwref value"
+    $ desc "makes peer to request lwwref from neighbors"
+    $ args [arg "string" "lwwref"]
+    $ returns "atom" "okay"
+    $ entry $ bindMatch "hbs2:lwwref:fetch" $ \case
       [StringLike puk] -> do
         flip runContT pure do
           lww <- orThrowUser "bad lwwref key" (fromStringMay puk)
@@ -62,7 +72,18 @@ lwwRefEntries = do
       _ -> throwIO (BadFormException @C nil)
 
 
-  entry $ bindMatch "hbs2:lwwref:get" $ \case
+  brief "get lwwref value"
+    $ args [arg "string" "lwwref"]
+    $ returns "string" "hashref"
+    $ examples [qc|
+
+(hbs2:lwwref:get BTThPdHKF8XnEq4m6wzbKHKA6geLFK4ydYhBXAqBdHSP)
+(lwwref
+  (seq 4)
+  (value "74vDGwBYebH3oM6xPXC7kqpgu6deqi7E549QpvHvvQKf")
+  )
+    |]
+    $ entry $ bindMatch "hbs2:lwwref:get" $ \case
       [StringLike puk] -> do
 
         flip runContT pure do
@@ -76,7 +97,11 @@ lwwRefEntries = do
       _ -> throwIO (BadFormException @C nil)
 
 
-  entry $ bindMatch "hbs2:lwwref:update" $ \case
+  brief "updates lwwref"
+    $ desc "updates lwwref value and increments it's counter"
+    $ args [arg "string" "lwwref", arg "string" "hash"]
+    $ returns "nil" ""
+    $ entry $ bindMatch "hbs2:lwwref:update" $ \case
       [StringLike puks, HashLike new] -> do
 
         flip runContT pure do