Give a way to get the usage string. (#25)

Fixes #15.

Author: floitsch

src/cli.toit

@@ -4,6 +4,7 @@
 
 import .parser_
 import .utils_
+import .help_generator_
 
 /**
 When the arg-parser needs to report an error, or write a help message, it
@@ -32,40 +33,40 @@ class Command:
   Usually constructed from the name and the arguments of the command. However, in
     some cases, a different (shorter) usage string is desired.
   */
-  usage/string?
+  usage_/string?
 
   /** A short (one line) description of the command. */
-  short_help/string?
+  short_help_/string?
 
   /** A longer description of the command. */
-  long_help/string?
+  long_help_/string?
 
   /** Examples of the command. */
-  examples/List
+  examples_/List
 
   /** Aliases of the command. */
-  aliases/List
+  aliases_/List
 
   /** Options to the command. */
-  options/List
+  options_/List
 
   /** The rest arguments. */
-  rest/List
+  rest_/List
 
   /** Whether this command should show up in the help. */
-  is_hidden/bool
+  is_hidden_/bool
 
   /**
   Subcommands.
   Use $add to add new subcommands.
   */
-  subcommands/List
+  subcommands_/List
 
   /**
   The function to invoke when this command is executed.
   May be null, in which case at least one subcommand must be specified.
   */
-  run_callback/Lambda?
+  run_callback_/Lambda?
 
   /**
   Constructs a new command.
@@ -83,11 +84,19 @@ class Command:
     line, but it can span multiple lines/paragraphs if necessary. Use indented lines to
     continue paragraphs (just like toitdoc).
   */
-  constructor .name --.usage=null --.short_help=null --.long_help=null --.examples=[] \
-      --.aliases=[] --.options=[] --.rest=[] --.subcommands=[] --hidden/bool=false \
+  constructor .name --usage/string?=null --short_help/string?=null --long_help/string?=null --examples/List=[] \
+      --aliases/List=[] --options/List=[] --rest/List=[] --subcommands/List=[] --hidden/bool=false \
       --run/Lambda?=null:
-    run_callback = run
-    is_hidden = hidden
+    usage_ = usage
+    short_help_ = short_help
+    long_help_ = long_help
+    examples_ = examples
+    aliases_ = aliases
+    options_ = options
+    rest_ = rest
+    subcommands_ = subcommands
+    run_callback_ = run
+    is_hidden_ = hidden
     if not subcommands.is_empty and not rest.is_empty:
       throw "Cannot have both subcommands and rest arguments."
     if run and not subcommands.is_empty:
@@ -105,11 +114,23 @@ class Command:
   It is an error to add a subcommand to a command that has a run callback.
   */
   add command/Command:
-    if not rest.is_empty:
+    if not rest_.is_empty:
       throw "Cannot add subcommands to a command with rest arguments."
-    if run_callback:
+    if run_callback_:
       throw "Cannot add subcommands to a command with a run callback."
-    subcommands.add command
+    subcommands_.add command
+
+  /** Returns the help string of this command. */
+  help --invoked_command/string=program_name -> string:
+    generator := HelpGenerator [this] --invoked_command=invoked_command
+    generator.build_all
+    return generator.to_string
+
+  /** Returns the usage string of this command. */
+  usage --invoked_command/string=program_name -> string:
+    generator := HelpGenerator [this] --invoked_command=invoked_command
+    generator.build_usage --as_section=false
+    return generator.to_string
 
   /**
   Runs this command.
@@ -125,7 +146,7 @@ class Command:
   run arguments/List --invoked_command=program_name --ui/Ui=Ui_ -> none:
     parser := Parser_ --ui=ui --invoked_command=invoked_command
     parsed := parser.parse this arguments
-    parsed.command.run_callback.call parsed
+    parsed.command.run_callback_.call parsed
 
   /**
   Checks this command and all subcommands for errors.
@@ -144,12 +165,12 @@ class Command:
     available through supercommands.
   */
   check_ --path/List --outer_long_options/Set={} --outer_short_options/Set={}:
-    examples.do: it as Example
-    aliases.do: it as string
+    examples_.do: it as Example
+    aliases_.do: it as string
 
     long_options := {}
     short_options := {}
-    options.do: | option/Option |
+    options_.do: | option/Option |
       if long_options.contains option.name:
         throw "Ambiguous option of '$(path.join " ")': --$option.name."
       if outer_long_options.contains option.name:
@@ -164,9 +185,9 @@ class Command:
         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:
+    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."
       if long_options.contains option.name:
         throw "Rest name '$option.name' of '$(path.join " ")' already used."
@@ -189,8 +210,8 @@ class Command:
       outer_short_options.add_all short_options
 
     subnames := {}
-    subcommands.do: | command/Command |
-      names := [command.name] + command.aliases
+    subcommands_.do: | command/Command |
+      names := [command.name] + command.aliases_
       names.do: | name/string? |
         if subnames.contains name:
           throw "Ambiguous subcommand of '$(path.join " ")': '$name'."
@@ -203,12 +224,12 @@ class Command:
     // 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:
+    if subcommands_.is_empty and not run_callback_:
       throw "Command '$(path.join " ")' has no subcommands and no run callback."
 
   find_subcommand_ name/string -> Command?:
-    subcommands.do: | command/Command |
-      if command.name == name or command.aliases.contains name:
+    subcommands_.do: | command/Command |
+      if command.name == name or command.aliases_.contains name:
         return command
     return null
 
@@ -305,6 +326,7 @@ abstract class Option:
   */
   abstract parse str/string --for_help_example/bool=false -> any
 
+
 /**
 A string option.
 */

src/help_generator_.toit

@@ -88,34 +88,40 @@ class HelpGenerator:
   global_options_ -> List:
     result := []
     for i := 0; i < path_.size - 1; i++:
-      result.add_all path_[i].options
+      result.add_all path_[i].options_
     return result
 
   /**
   Builds the description.
 
-  If available, the description is the $Command.long_help, otherwise, the
-    $Command.short_help is used. If none exists, no description is built.
+  If available, the description is the $Command.long_help_, otherwise, the
+    $Command.short_help_ is used. If none exists, no description is built.
   */
   build_description -> none:
-    if help := command_.long_help:
+    if help := command_.long_help_:
       ensure_vertical_space_
       writeln_ (help.trim --right)
-    else if short_help := command_.short_help:
+    else if short_help := command_.short_help_:
       ensure_vertical_space_
       writeln_ (short_help.trim --right)
 
   /**
   Builds the usage section.
 
-  If the command has a $Command.usage line, then that one is used. Otherwise the
+  If the command has a $Command.usage_ line, then that one is used. Otherwise the
     usage line is built from the available options or subcommands.
+
+  If $as_section is true, then the section is preceded by a "Usage:" title, indented,
+    and followed by an empty line.
   */
-  build_usage -> none:
+  build_usage --as_section/bool=true -> none:
     ensure_vertical_space_
-    writeln_ "Usage:"
-    if command_.usage:
-      writeln_ command_.usage --indentation=2
+    if as_section:
+      writeln_ "Usage:"
+    indentation := as_section ? 2 : 0
+    if command_.usage_:
+      write_ command_.usage_ --indentation=indentation
+      if as_section: writeln_
       return
 
     // We want to construct a usage line like
@@ -125,12 +131,12 @@ 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=2
+    write_ invoked_command_ --indentation=indentation
     has_more_options := false
     for i := 0; i < path_.size; i++:
-      current_command := path_[i]
+      current_command/Command := path_[i]
       if i != 0: write_ " $current_command.name"
-      current_options := current_command.options
+      current_options := current_command.options_
       sorted := current_options.sort: | a/Option b/Option | a.name.compare_to b.name
       sorted.do: | option/Option |
         if option.is_required:
@@ -140,29 +146,29 @@ class HelpGenerator:
         else if not option.is_hidden:
           has_more_options = true
 
-    if not command_.subcommands.is_empty: write_ " <command>"
+    if not command_.subcommands_.is_empty: write_ " <command>"
     if has_more_options: write_ " [<options>]"
-    if not command_.rest.is_empty: write_ " [--]"
-    command_.rest.do: | option/Option |
+    if not command_.rest_.is_empty: write_ " [--]"
+    command_.rest_.do: | option/Option |
       type := option.type
       option_str/string := ?
       if type == "string": option_str = "<$option.name>"
       else: option_str = "<$option.name:$option.type>"
       if option.is_multi: option_str = "$option_str..."
       if not option.is_required: option_str = "[$option_str]"
       write_ " $option_str"
-    writeln_
+    if as_section: writeln_
 
   /**
   Builds the aliases section.
 
   Only generates the alias section if the command is not the root command.
   */
   build_aliases -> none:
-    if is_root_command_ or command_.aliases.is_empty: return
+    if is_root_command_ or command_.aliases_.is_empty: return
     ensure_vertical_space_
     writeln_ "Aliases:"
-    writeln_ (command_.aliases.join ", ") --indentation=2
+    writeln_ (command_.aliases_.join ", ") --indentation=2
 
   /**
   Builds the commands section.
@@ -173,22 +179,22 @@ class HelpGenerator:
   If the command is the root-command also adds the 'help' command.
   */
   build_commands -> none:
-    if command_.subcommands.is_empty: return
+    if command_.subcommands_.is_empty: return
     ensure_vertical_space_
     writeln_ "Commands:"
 
     commands_and_help := []
     has_help_subcommand := false
-    command_.subcommands.do: | subcommand/Command |
+    command_.subcommands_.do: | subcommand/Command |
       if subcommand.name == "help": has_help_subcommand = true
-      subcommand.aliases.do: if it == "help": has_help_subcommand = true
+      subcommand.aliases_.do: if it == "help": has_help_subcommand = true
 
-      if subcommand.is_hidden: continue.do
+      if subcommand.is_hidden_: continue.do
 
       help_str := ?
-      if help := subcommand.short_help:
+      if help := subcommand.short_help_:
         help_str = help
-      else if long_help := subcommand.long_help:
+      else if long_help := subcommand.long_help_:
         // Take the first paragraph (potentially multiple lines) of the long help.
         paragraph_index := long_help.index_of "\n\n"
         if paragraph_index == -1:
@@ -211,8 +217,8 @@ class HelpGenerator:
   Automatically adds the help option if it is not already defined.
   */
   build_local_options -> none:
-    build_options_ --title="Options" command_.options --add_help
-    build_options_ --title="Rest" command_.rest --rest
+    build_options_ --title="Options" command_.options_ --add_help
+    build_options_ --title="Rest" command_.rest_ --rest
 
   /**
   Builds the global options section.
@@ -313,7 +319,7 @@ class HelpGenerator:
   build_examples:
     // Get the local examples directly, as we want to keep them on top, and as we
     // don't want to filter them.
-    this_examples := command_.examples.map: | example/Example | [example, path_]
+    this_examples := command_.examples_.map: | example/Example | [example, path_]
     sub_examples := []
     add_global_examples_ command_ sub_examples --path=path_ --skip_first_level
     sub_examples.sort --in_place: | a/List b/List | a[0].global_priority - b[0].global_priority
@@ -342,11 +348,11 @@ class HelpGenerator:
   */
   add_global_examples_ command/Command all_examples/List --path/List --skip_first_level/bool=false -> none:
     if not skip_first_level:
-      global_examples := (command.examples.filter: it.global_priority > 0)
+      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
+    command.subcommands_.do: | subcommand/Command |
+      if subcommand.is_hidden_: continue.do
       add_global_examples_ subcommand all_examples --path=(path + [subcommand])
 
   /**
@@ -399,7 +405,7 @@ class HelpGenerator:
     for j := 0; j < parsed_path.size; j++:
       current_command/Command := parsed_path[j]
       command_level[current_command] = j
-      current_command.options.do: | option/Option |
+      current_command.options_.do: | option/Option |
         if not parsed.was_provided option.name: continue.do
         option_to_command["--$option.name"] = current_command
         if option.short_name: option_to_command["-$option.short_name"] = current_command