Fix documentation

smores56 · Jul 11, 2024 · 3b17253 · 3b17253
1 parent c6ae0b6
commit 3b17253
Show file tree

Hide file tree

Showing 7 changed files with 304 additions and 449 deletions.
diff --git a/examples/default-values.roc b/examples/default-values.roc
@@ -0,0 +1,38 @@
+app [main] {
+    pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.10.0/vNe6s9hWzoTZtFmNkvEICPErI9ptji_ySjicO6CkucY.tar.br",
+    weaver: "../package/main.roc",
+}
+
+import pf.Stdout
+import pf.Arg
+import pf.Task exposing [Task]
+import weaver.Opt
+import weaver.Cli
+import weaver.Param
+
+main =
+    args = Arg.list!
+
+    when Cli.parseOrDisplayMessage cliParser args is
+        Ok data ->
+            Stdout.line! "Successfully parsed! Here's what I got:"
+            Stdout.line! ""
+            Stdout.line! (Inspect.toStr data)
+
+        Err message ->
+            Stdout.line! message
+
+            Task.err (Exit 1 "")
+
+cliParser =
+    { Cli.weave <-
+        alpha: Opt.maybeU64 { short: "a", long: "alpha", help: "Set the alpha level. [default: 123]" }
+        |> Cli.map \a -> Result.withDefault a 123,,
+        file: Param.maybeStr { name: "file", help: "The file to process. [default: NONE]" }
+        |> Cli.map \f -> Result.withDefault f "NONE",
+    }
+    |> Cli.finish {
+        name: "default-values",
+        version: "v0.0.1",
+    }
+    |> Cli.assertValid
diff --git a/examples/single-arg.roc b/examples/single-arg.roc
@@ -27,9 +27,7 @@ cliParser =
     Opt.u64 { short: "a", long: "alpha", help: "Set the alpha level." }
     |> Cli.map Alpha
     |> Cli.finish {
-        name: "basic",
+        name: "single-arg",
         version: "v0.0.1",
-        authors: ["Some One <[email protected]>"],
-        description: "This is a basic example of what you can build with Weaver. You get safe parsing, useful error messages, and help pages all for free!",
     }
     |> Cli.assertValid
diff --git a/package/Cli.roc b/package/Cli.roc
@@ -1,4 +1,4 @@
-## Weave together a CLI parser using the `: <- ` builder notation!
+## Weave together a CLI parser using the `<- ` builder notation!
 ##
 ## This module is the entry point for creating CLIs using Weaver.
 ## To get started, call the [weave] method and pass a
@@ -9,10 +9,10 @@
 ## you set.
 ##
 ## ```roc
-## Cli.weave {
-##     alpha: <- Opt.u64 { short: "a", help: "Set the alpha level" },
-##     verbosity: <- Opt.count { short: "v", long: "verbose", help: "How loud we should be." },
-##     files: <- Param.strList { name: "files", help: "The files to process." },
+## { Cli.weave <-
+##     alpha: Opt.u64 { short: "a", help: "Set the alpha level" },
+##     verbosity: Opt.count { short: "v", long: "verbose", help: "How loud we should be." },
+##     files: Param.strList { name: "files", help: "The files to process." },
 ## }
 ## |> Cli.finish {
 ##     name: "example",
@@ -27,35 +27,26 @@
 ##
 ## ```roc
 ## fooSubcommand =
-##     Cli.weave {
-##         alpha: <- Opt.u64 {
-##             short: "a",
-##             help: "Set the alpha level",
-##         },
-##     }
+##     Opt.u64 { short: "a", help: "Set the alpha level" }
 ##     |> Subcommand.finish {
 ##         name: "foo",
 ##         description: "Foo some stuff."
 ##         mapper: Foo,
 ##     }
 ##
 ## barSubcommand =
-##     Cli.weave {
-##         # We allow two subcommands of the same parent to have overlapping
-##         # fields since only one can ever be parsed at a time.
-##         alpha: <- Opt.u64 {
-##             short: "a",
-##             help: "Set the alpha level",
-##         },
-##     }
+##     # We allow two subcommands of the same parent to have overlapping
+##     # fields since only one can ever be parsed at a time.
+##     Opt.u64 { short: "a", help: "Set the alpha level" }
 ##     |> Subcommand.finish {
 ##         name: "bar",
 ##         description: "Bar some stuff."
 ##         mapper: Bar,
 ##     }
 ##
-## Cli.weave {
-##     sc: <- Subcommand.optional [fooSubcommand, barSubcommand],
+## { Cli.weave <-
+##     verbosity: Opt.count { short: "v", long: "verbose" },
+##     sc: Subcommand.optional [fooSubcommand, barSubcommand],
 ## }
 ## ```
 ##
@@ -70,10 +61,10 @@
 ##
 ## ```roc
 ## cliParser =
-##     Cli.weave {
-##         alpha: <- Opt.u64 { short: "a", help: "Set the alpha level" },
-##         verbosity: <- Opt.count { short: "v", long: "verbose", help: "How loud we should be." },
-##         files: <- Param.strList { name: "files", help: "The files to process." },
+##     { Cli.weave <-
+##         alpha: Opt.u64 { short: "a", help: "Set the alpha level" },
+##         verbosity: Opt.count { short: "v", long: "verbose", help: "How loud we should be." },
+##         files: Param.strList { name: "files", help: "The files to process." },
 ##     }
 ##     |> Cli.finish {
 ##         name: "example",
@@ -110,7 +101,7 @@ module [
 ]
 
 import Opt
-# import Param
+import Param
 import Base exposing [
     TextStyle,
     ArgParserResult,
@@ -135,25 +126,45 @@ CliParser state : {
     textStyle : TextStyle,
 }
 
+## Map over the parsed value of a Weaver field.
+##
+## Useful for naming bare fields, or handling default values.
+##
+## ```roc
+## expect
+##     { parser } =
+##         { Cli.weave <-
+##             verbosity: Opt.count { short: "v", long: "verbose" }
+##                 |> Cli.map Verbosity,
+##             file: Param.maybeStr { name: "file" }
+##                 |> Cli.map \f -> Result.withDefault f "NO_FILE",
+##         }
+##         |> Cli.finish { name: "example" }
+##         |> Cli.assertValid
+##
+##    parser ["example", "-vvv"]
+##    == SuccessfullyParsed { verbosity: Verbosity 3, file: "NO_FILE" }
+## ```
 map : CliBuilder a fromAction toAction, (a -> b) -> CliBuilder b fromAction toAction
 map = \builder, mapper ->
     Builder.map builder mapper
 
-## Begin weaving together a CLI builder using the `: <- ` builder notation.
+## Begin weaving together a CLI builder using the `<- ` builder notation.
 ##
 ## Check the module-level documentation for general usage instructions.
 ##
 ## ```roc
 ## expect
 ##     { parser } =
-##         Cli.weave {
-##             verbosity: <- Opt.count { short: "v", long: "verbose" },
+##         { Cli.weave <-
+##             verbosity: Opt.count { short: "v", long: "verbose" },
+##             file: Param.str { name: "file" },
 ##         }
 ##         |> Cli.finish { name: "example" }
 ##         |> Cli.assertValid
 ##
-##    parser ["example", "-vvv"]
-##    == SuccessfullyParsed { verbosity: 3 }
+##    parser ["example", "file.txt", "-vvv"]
+##    == SuccessfullyParsed { verbosity: 3, file: "file.txt" }
 ## ```
 weave : CliBuilder a action1 action2, CliBuilder b action2 action3, (a, b -> c) -> CliBuilder c action1 action3
 weave = \left, right, combiner ->
@@ -205,15 +216,17 @@ ensureAllArgsWereParsed = \remainingArgs ->
 ##
 ## ```roc
 ## expect
-##     Cli.weave {
-##         verbosity: <- Opt.count { short: "v", long: "verbose" },
+##     { Cli.weave <-
+##         verbosity: Opt.count { short: "v", long: "verbose" },
+##         file: Param.str { name: "file" },
 ##     }
 ##     |> Cli.finish { name: "example" }
 ##     |> Result.isOk
 ##
 ## expect
-##     Cli.weave {
-##         verbosity: <- Opt.count { short: "" },
+##     { Cli.weave <-
+##         verbosity: Opt.count { short: "" },
+##         file: Param.str { name: "" },
 ##     }
 ##     |> Cli.finish { name: "example" }
 ##     |> Result.isErr
@@ -235,13 +248,14 @@ finish = \builder, params ->
 ## ```roc
 ## expect
 ##     { parser } =
-##         Cli.weave {
-##             verbosity: <- Opt.count { short: "v", long: "verbose" },
+##         { Cli.weave <-
+##             verbosity: Opt.count { short: "v", long: "verbose" },
+##             file: Param.maybeStr { name: "file" },
 ##         }
 ##         |> Cli.finishWithoutValidating { name: "example" }
 ##
 ##     parser ["example", "-v", "-v"]
-##     == SuccessfullyParsed { verbosity: 2 }
+##     == SuccessfullyParsed { verbosity: 2, file: Err NoValue }
 ## ```
 finishWithoutValidating : CliBuilder data fromAction toAction, CliConfigParams -> CliParser data
 finishWithoutValidating = \builder, { name, authors ? [], version ? "", description ? "", textStyle ? Color } ->
@@ -284,9 +298,7 @@ finishWithoutValidating = \builder, { name, authors ? [], version ? "", descript
 ## for correct parsing.
 ##
 ## ```roc
-## Cli.weave {
-##     a: <- Opt.num { short: "a" }
-## }
+## Opt.num { short: "a" }
 ## |> Cli.finish { name: "example" }
 ## |> Cli.assertValid
 ## ```
@@ -311,8 +323,9 @@ assertValid = \result ->
 ##
 ## ```roc
 ## exampleCli =
-##     Cli.weave {
-##         verbosity: <- Opt.count { short: "v", help: "How verbose our logs should be." },
+##     { Cli.weave <-
+##         verbosity: Opt.count { short: "v", long: "verbose" },
+##         alpha: Opt.maybeNum { short: "a", long: "alpha" },
 ##     }
 ##     |> Cli.finish {
 ##         name: "example",
@@ -335,6 +348,7 @@ assertValid = \result ->
 ##
 ##         Options:
 ##           -v             How verbose our logs should be.
+##           -a, --alpha    Set the alpha level.
 ##           -h, --help     Show this help page.
 ##           -V, --version  Show the version.
 ##         """

diff --git a/package/Help.roc b/package/Help.roc
@@ -64,9 +64,7 @@ findSubcommand = \command, path ->
 ##
 ## ```roc
 ## exampleCli =
-##     Cli.weave {
-##         verbosity: <- Opt.count { short: "v", help: "How verbose our logs should be." },
-##     }
+##     Opt.count { short: "v", help: "How verbose our logs should be." }
 ##     |> Cli.finish {
 ##         name: "example",
 ##         version: "v0.1.0",
@@ -160,9 +158,7 @@ helpText = \baseConfig, path, textStyle ->
 ##
 ## ```roc
 ## exampleCli =
-##     Cli.weave {
-##         verbosity: <- Opt.count { short: "v", help: "How verbose our logs should be." },
-##     }
+##     Opt.count { short: "v", help: "How verbose our logs should be." }
 ##     |> Cli.finish {
 ##         name: "example",
 ##         version: "v0.1.0",