Add examples-check to check. (#73)

Also refactor the commands-path list and create a class for it.

Author: floitsch

src/cli.toit

@@ -7,9 +7,10 @@ import system
 
 import .cache
 import .config
+import .help-generator_
 import .parser_
+import .path_
 import .utils_
-import .help-generator_
 import .ui
 
 export Ui
@@ -251,7 +252,8 @@ class Command:
 
   /** Returns the help string of this command. */
   help --invoked-command/string=system.program-name -> string:
-    generator := HelpGenerator [this] --invoked-command=invoked-command
+    path := Path this --invoked-command=invoked-command
+    generator := HelpGenerator path
     generator.build-all
     return generator.to-string
 
@@ -273,7 +275,8 @@ class Command:
 
   /** Returns the usage string of this command. */
   usage --invoked-command/string=system.program-name -> string:
-    generator := HelpGenerator [this] --invoked-command=invoked-command
+    path := Path this --invoked-command=invoked-command
+    generator := HelpGenerator path
     generator.build-usage --as-section=false
     return generator.to-string
 
@@ -300,8 +303,8 @@ class Command:
         add-ui-options_
       cli = Cli_ name --ui=ui --cache=null --config=null
     parser := Parser_ --invoked-command=invoked-command
-    parser.parse this arguments: | path/List parameters/Parameters |
-      invocation := Invocation.private_ cli path parameters
+    parser.parse this arguments: | path/Path parameters/Parameters |
+      invocation := Invocation.private_ cli path.commands parameters
       invocation.command.run-callback_.call invocation
 
   add-ui-options_:
@@ -343,9 +346,15 @@ class Command:
 
   /**
   Checks this command and all subcommands for errors.
+
+  If an error is found, an exception is thrown with a message describing the error.
+
+  Typically, a call to this method is added to the program's main function in an
+    assert block.
   */
   check --invoked-command=system.program-name:
-    check_ --path=[invoked-command]
+    path := Path this --invoked-command=invoked-command
+    check_ --path=path --invoked-command=invoked-command
 
   are-prefix-of-each-other_ str1/string str2/string -> bool:
     m := min str1.size str2.size
@@ -357,39 +366,39 @@ class Command:
   The $outer-long-options and $outer-short-options are the options that are
     available through supercommands.
   */
-  check_ --path/List --outer-long-options/Set={} --outer-short-options/Set={}:
+  check_ --path/Path --invoked-command/string --outer-long-options/Set={} --outer-short-options/Set={}:
     examples_.do: it as Example
     aliases_.do: it as string
 
     long-options := {}
     short-options := {}
     options_.do: | option/Option |
       if long-options.contains option.name:
-        throw "Ambiguous option of '$(path.join " ")': --$option.name."
+        throw "Ambiguous option of '$path.to-string': --$option.name."
       if outer-long-options.contains option.name:
-        throw "Ambiguous option of '$(path.join " ")': --$option.name conflicts with global option."
+        throw "Ambiguous option of '$path.to-string': --$option.name conflicts with global option."
       long-options.add option.name
 
       if option.short-name:
         if (short-options.any: are-prefix-of-each-other_ it option.short-name):
-          throw "Ambiguous option of '$(path.join " ")': -$option.short-name."
+          throw "Ambiguous option of '$path.to-string': -$option.short-name."
         if (outer-short-options.any: are-prefix-of-each-other_ it option.short-name):
-          throw "Ambiguous option of '$(path.join " ")': -$option.short-name conflicts with global option."
+          throw "Ambiguous option of '$path.to-string': -$option.short-name conflicts with global option."
         short-options.add option.short-name
 
     have-seen-optional-rest := false
     for i := 0; i < rest_.size; i++:
       option/Option := rest_[i]
       if option.is-multi and not i == rest_.size - 1:
-        throw "Multi-option '$option.name' of '$(path.join " ")' must be the last rest argument."
+        throw "Multi-option '$option.name' of '$path.to-string' must be the last rest argument."
       if long-options.contains option.name:
-        throw "Rest name '$option.name' of '$(path.join " ")' already used."
+        throw "Rest name '$option.name' of '$path.to-string' already used."
       if outer-long-options.contains option.name:
-        throw "Rest name '$option.name' of '$(path.join " ")' already a global option."
+        throw "Rest name '$option.name' of '$path.to-string' already a global option."
       if have-seen-optional-rest and option.is-required:
-        throw "Required rest argument '$option.name' of '$(path.join " ")' cannot follow optional rest argument."
+        throw "Required rest argument '$option.name' of '$path.to-string' cannot follow optional rest argument."
       if option.is-hidden:
-        throw "Rest argument '$option.name' of '$(path.join " ")' cannot be hidden."
+        throw "Rest argument '$option.name' of '$path.to-string' cannot be hidden."
       have-seen-optional-rest = not option.is-required
       long-options.add option.name
 
@@ -407,18 +416,25 @@ class Command:
       names := [command.name] + command.aliases_
       names.do: | name/string? |
         if subnames.contains name:
-          throw "Ambiguous subcommand of '$(path.join " ")': '$name'."
+          throw "Ambiguous subcommand of '$path.to-string': '$name'."
         subnames.add name
 
-      command.check_ --path=(path + [command.name])
+      command.check_
+          --path=(path + command)
+          --invoked-command=invoked-command
           --outer-long-options=outer-long-options
           --outer-short-options=outer-short-options
 
     // We allow a command with a run callback if all subcommands are hidden.
     // As such, we could also allow commands without either. If desired, it should be
     // safe to remove the following check.
     if subcommands_.is-empty and not run-callback_:
-      throw "Command '$(path.join " ")' has no subcommands and no run callback."
+      throw "Command '$path.to-string' has no subcommands and no run callback."
+
+    if not examples_.is-empty:
+      generator := HelpGenerator path
+      examples_.do: | example/Example |
+        generator.build-example_ example --example-path=path
 
   find-subcommand_ name/string -> Command?:
     subcommands_.do: | command/Command |

src/help-generator_.toit

@@ -4,6 +4,7 @@
 
 import .cli
 import .parser_
+import .path_
 import .utils_
 import .ui
 import system
@@ -13,10 +14,7 @@ The 'help' command that can be executed on the root command.
 
 It finds the selected command and prints its help.
 */
-help-command_ path/List arguments/List --invoked-command/string --ui/Ui:
-  // We are modifying the path, so make a copy.
-  path = path.copy
-
+help-command_ path/Path arguments/List --ui/Ui:
   command/Command := path.last
 
   for i := 0; i < arguments.size; i++:
@@ -32,25 +30,25 @@ help-command_ path/List arguments/List --invoked-command/string --ui/Ui:
       ui.abort "Unknown command: $argument"
       unreachable
     command = subcommand
-    path.add command
+    path += command
 
-  emit-help_ path --invoked-command=invoked-command --ui=ui
+  emit-help_ path --ui=ui
 
 /**
 Emits the help for the given command.
 
 The command is identified by the $path where the command is the last element.
 */
-emit-help_ path/List --invoked-command/string --ui/Ui:
+emit-help_ path/Path --ui/Ui:
   ui.emit --kind=Ui.RESULT
       --structured=:
-        build-json-help_ path --invoked-command=invoked-command
+        build-json-help_ path
       --text=:
-        generator := HelpGenerator path --invoked-command=invoked-command
+        generator := HelpGenerator path
         generator.build-all
         generator.to-string
 
-build-json-help_ path/List --invoked-command/string -> Map:
+build-json-help_ path/Path -> Map:
   // Local block to build json objects for the given command.
   // Adds the converted json object to the out-map.
   extract-options := : | command/Command out-map/Map |
@@ -88,7 +86,8 @@ build-json-help_ path/List --invoked-command/string -> Map:
 
   return {
     "name": command.name,
-    "path": path.map: | command/Command | command.name,
+    "path": path.commands.map: | command/Command | command.name,
+    "invoked-command": path.invoked-command,
     "help": command.help_,
     "aliases": command.aliases_,
     "options": extract-options.call command {:},
@@ -105,14 +104,12 @@ The class also serves as a string builder for the `build_X` methods. The methods
 */
 class HelpGenerator:
   command_/Command
-  path_/List
-  invoked-command_/string
+  path_/Path
   buffer_/List := []  // Buffered string.
   // The index in the buffer of the last separator.
   last-separator-pos_/int := 0
 
-  constructor .path_ --invoked-command/string:
-    invoked-command_ = invoked-command
+  constructor .path_:
     command_=path_.last
 
   /**
@@ -181,7 +178,7 @@ class HelpGenerator:
     // They are sorted by name.
     // For the usage line we don't care for the short names of options.
 
-    write_ invoked-command_ --indentation=indentation
+    write_ path_.invoked-command --indentation=indentation
     has-more-options := false
     for i := 0; i < path_.size; i++:
       current-command/Command := path_[i]
@@ -376,7 +373,7 @@ class HelpGenerator:
       if i != 0: writeln_
       example-and-path := all-examples[i]
       example/Example := example-and-path[0]
-      example-path/List := example-and-path[1]
+      example-path/Path := example-and-path[1]
 
       build-example_ example --example-path=example-path
 
@@ -389,22 +386,22 @@ class HelpGenerator:
   If $skip-first-level is true, then does not add the examples of this command, but only
     those of subcommands.
   */
-  add-global-examples_ command/Command all-examples/List --path/List --skip-first-level/bool=false -> none:
+  add-global-examples_ command/Command all-examples/List --path/Path --skip-first-level/bool=false -> none:
     if not skip-first-level:
       global-examples := (command.examples_.filter: it.global-priority > 0)
       all-examples.add-all (global-examples.map: [it, path])
 
     command.subcommands_.do: | subcommand/Command |
       if subcommand.is-hidden_: continue.do
-      add-global-examples_ subcommand all-examples --path=(path + [subcommand])
+      add-global-examples_ subcommand all-examples --path=(path + subcommand)
 
   /**
   Builds a single example.
 
   The $example contains the description and arguments, and the $example-path is
     the path to the command that contains the example.
   */
-  build-example_ example/Example --example-path/List:
+  build-example_ example/Example --example-path/Path:
     description := example.description.trim --right
     description-lines := ?
     if description.contains "\n": description-lines = description.split "\n"
@@ -423,11 +420,11 @@ class HelpGenerator:
   Builds the example command line for the given $arguments-line.
   The command that defined the example is identified by the $example-path.
   */
-  build-example-command-line_ arguments-line/string --example-path/List:
+  build-example-command-line_ arguments-line/string --example-path/Path:
     // Start by constructing a valid command line.
 
     // The prefix consists of the subcommands.
-    prefix := example-path[1..].map: | command/Command | command.name
+    prefix := example-path.commands[1..].map: | command/Command | command.name
     // Split the arguments line into individual arguments.
     // For example, `"foo --bar \"my password\""` is split into `["foo", "--bar", "my password"]`.
     example-arguments := split-arguments_ arguments-line
@@ -436,14 +433,14 @@ class HelpGenerator:
     // Parse it, to verify that it actually is valid.
     // We are also using the result to reorder the options.
     parser := Parser_ --invoked-command="root" --for-help-example
-    invocation-path/List? := null
+    invocation-path/Path? := null
     invocation-parameters/Parameters? := null
     exception := catch:
       parser.parse example-path.first command-line: | path parameters |
         invocation-path = path
         invocation-parameters = parameters
     if exception:
-      throw "Error in example '$arguments-line': $exception"
+      throw "Error in example '$arguments-line': $exception."
 
     // For each command, collect the options that are defined on it and that were
     // used in the example.
@@ -528,8 +525,8 @@ class HelpGenerator:
     is-root := true
     // For examples, we don't want the full path that was used to invoke the
     // command (like `build/bin/artemis`), but only the basename.
-    app-name := basename_ invoked-command_
-    invocation-path.do: | current-command |
+    app-name := basename_ example-path.invoked-command
+    invocation-path.commands.do: | current-command |
       if is-root:
         is-root = false
         full-command.add app-name

src/parser_.toit

@@ -4,6 +4,7 @@
 
 import .cli
 import .help-generator_
+import .path_
 import .ui
 import .utils_
 import host.pipe
@@ -29,7 +30,7 @@ class Parser_:
 
   The program was called with wrong arguments.
   */
-  fatal path/List str/string:
+  fatal path/Path str/string:
     if for-help-example_:
       throw str
 
@@ -38,7 +39,7 @@ class Parser_:
     // print the usage on stderr, followed by an exit 1.
     ui := test-ui_ or (Ui --level=Ui.QUIET-LEVEL --printer=StderrPrinter_)
     ui.emit --error str
-    help-command_ path [] --invoked-command=invoked-command_ --ui=ui
+    help-command_ path [] --ui=ui
     ui.abort
     unreachable
 
@@ -51,7 +52,7 @@ class Parser_:
   - The $Parameters that were parsed.
   */
   parse root-command/Command arguments/List [block] -> none:
-    path := []
+    path := Path root-command --invoked-command=invoked-command_
     // Populate the options from the default values or empty lists (for multi-options)
     options := {:}
 
@@ -74,12 +75,13 @@ class Parser_:
 
     return-help := : | arguments/List |
       help-command := Command "help" --run=:: | app/Invocation |
-        help-command_ path arguments --invoked-command=invoked-command_ --ui=app.cli.ui
-      block.call [help-command] (Parameters.private_ {:} {})
+        help-command_ path arguments --ui=app.cli.ui
+      help-path := Path help-command --invoked-command=invoked-command_
+      block.call help-path (Parameters.private_ {:} {})
       return
 
     command/Command? := null
-    set-command := : | new-command/Command |
+    set-command := : | new-command/Command add-to-path/bool |
       new-command.options_.do: | option/Option |
         all-named-options[option.name] = option
         if option.short-name: all-short-options[option.short-name] = option
@@ -92,9 +94,9 @@ class Parser_:
           options[option.name] = option.default
 
       command = new-command
-      path.add command
+      if add-to-path: path += command
 
-    set-command.call root-command
+    set-command.call root-command false
 
     rest := []
 
@@ -180,7 +182,7 @@ class Parser_:
             return-help.call arguments[index..]
 
           fatal path "Unknown command: $argument"
-        set-command.call subcommand
+        set-command.call subcommand true
 
       else:
         rest.add argument