CommandSpec¶

CommandSpec describes the specification of a parent or leaf command. Each command has the following attributes:

a name: a simple string token that identifies the command.
a description: used in the syntax message.
a map of options: the valid options for this command.
an optional help option+command name for help parsing
one of:
a Map of child commands.
an Array of arguments.

class ref CommandSpec

Constructors¶

parent¶

[Source]

Creates a command spec that can accept options and child commands, but not arguments.

new ref parent(
  name': String val,
  descr': String val = "",
  options': Array[OptionSpec val] box = Array[OptionSpec](),
    commands': Array[CommandSpec] box = Array[CommandSpec]()) ?
  =>
    """
    Creates a command spec that can accept options and child commands, but not
    arguments.
    """
    _type = _CommandSpecParent
    _name = _assert_name(name')?
    _descr = descr'
    for o in options'.values() do
      _options.update(o.name(), o)
    end
    for c in commands'.values() do
      _commands.update(c.name(), c)
    end

  new leaf(
    name': String,
    descr': String = "",
    options': Array[OptionSpec] box = Array[OptionSpec](),
    args': Array[ArgSpec] box = Array[ArgSpec]()) ?
  =>
    """
    Creates a command spec that can accept options and arguments, but not child
    commands.
    """
    _type = _CommandSpecLeaf
    _name = _assert_name(name')?
    _descr = descr'
    for o in options'.values() do
      _options.update(o.name(), o)
    end
    for a in args'.values() do
      _args.push(a)
    end

  fun tag _assert_name(nm: String): String ? =>
    for b in nm.values() do
      if (b != '-') and (b != '_') and
        not ((b >= '0') and (b <= '9')) and
        not ((b >= 'A') and (b <= 'Z')) and
        not ((b >= 'a') and (b <= 'z')) then
        error
      end
    end
    nm

  fun ref add_command(cmd: CommandSpec box) ? =>
    """
    Adds an additional child command to this parent command.
    """
    if is_leaf() then error end
    _commands.update(cmd.name(), cmd)

  fun ref add_help(hname: String = "help", descr': String = "") ? =>
    """
    Adds a standard help option and, optionally command, to a root command.
    """
    _help_name = hname
    _help_info = descr'
    let help_option = OptionSpec.bool(_help_name, _help_info, 'h', false)
    _options.update(_help_name, help_option)
    if is_parent() then
      let help_cmd =
        CommandSpec.leaf(
          _help_name,
          "",
          Array[OptionSpec](),
          [
            ArgSpec.string("command" where default' = "")
          ])?
      _commands.update(_help_name, help_cmd)
    end

  fun name(): String =>
    """
    Returns the name of this command.
    """
    _name

  fun descr(): String =>
    """
    Returns the description for this command.
    """
    _descr

  fun options(): Map[String, OptionSpec] box =>
    """
    Returns a map by name of the named options of this command.
    """
    _options

  fun commands(): Map[String, CommandSpec box] box =>
    """
    Returns a map by name of the child commands of this command.
    """
    _commands

  fun args(): Array[ArgSpec] box =>
    """
    Returns an array of the positional arguments of this command.
    """
    _args

  fun is_leaf(): Bool => _type is _CommandSpecLeaf

  fun is_parent(): Bool => _type is _CommandSpecParent

  fun help_name(): String =>
    """
    Returns the name of the help command, which defaults to "help".
    """
    _help_name

  fun help_string(): String =>
    """
    Returns a formatted help string for this command and all of its arguments.
    """
    let s = _name.clone()
    s.append(" ")
    let args_iter = _args.values()
    for a in args_iter do
      s.append(a.help_string())
      if args_iter.has_next() then s.append(" ") end
    end
    s

class,
  commands': Array[CommandSpec ref] box = class CommandSpec
  """
  CommandSpec describes the specification of a parent or leaf command. Each
  command has the following attributes:

  - a name: a simple string token that identifies the command.
  - a description: used in the syntax message.
  - a map of options: the valid options for this command.
  - an optional help option+command name for help parsing
  - one of:
     - a Map of child commands.
     - an Array of arguments.
  """
  let _type: _CommandSpecType
  let _name: String
  let _descr: String
  let _options: Map[String, OptionSpec] = _options.create()
  var _help_name: String = ""
  var _help_info: String = ""
  // A parent commands can have sub-commands; leaf commands can have args.
  let _commands: Map[String, CommandSpec box] = _commands.create()
  let _args: Array[ArgSpec] = _args.create()

  new parent(
    name': String,
    descr': String = "",
    options': Array[OptionSpec] box = Array[OptionSpec](),
    commands': Array[CommandSpec] box = Array[CommandSpec]())
: CommandSpec ref^ ?

Parameters¶

name': String val
descr': String val = ""
options': Array[OptionSpec val] box = ArrayOptionSpec, commands': Array[CommandSpec] box = ArrayCommandSpec) ? => """ Creates a command spec that can accept options and child commands, but not arguments. """ _type = _CommandSpecParent _name = _assert_name(name')? _descr = descr' for o in options'.values() do _options.update(o.name(), o) end for c in commands'.values() do _commands.update(c.name(), c) end

new leaf( name': String, descr': String = "", options': Array[OptionSpec] box = ArrayOptionSpec, args': Array[ArgSpec] box = ArrayArgSpec) ? => """ Creates a command spec that can accept options and arguments, but not child commands. """ _type = _CommandSpecLeaf _name = _assert_name(name')? _descr = descr' for o in options'.values() do _options.update(o.name(), o) end for a in args'.values() do _args.push(a) end

fun tag assert_name(nm: String): String ? => for b in nm.values() do if (b != '-') and (b != '') and not ((b >= '0') and (b <= '9')) and not ((b >= 'A') and (b <= 'Z')) and not ((b >= 'a') and (b <= 'z')) then error end end nm

fun ref add_command(cmd: CommandSpec box) ? => """ Adds an additional child command to this parent command. """ if is_leaf() then error end _commands.update(cmd.name(), cmd)

fun ref add_help(hname: String = "help", descr': String = "") ? => """ Adds a standard help option and, optionally command, to a root command. """ _help_name = hname _help_info = descr' let help_option = OptionSpec.bool(_help_name, _help_info, 'h', false) _options.update(_help_name, help_option) if is_parent() then let help_cmd = CommandSpec.leaf( _help_name, "", ArrayOptionSpec, [ ArgSpec.string("command" where default' = "") ])? _commands.update(_help_name, help_cmd) end

fun name(): String => """ Returns the name of this command. """ _name

fun descr(): String => """ Returns the description for this command. """ _descr

fun options(): Map[String, OptionSpec] box => """ Returns a map by name of the named options of this command. """ _options

fun commands(): Map[String, CommandSpec box] box => """ Returns a map by name of the child commands of this command. """ _commands

fun args(): Array[ArgSpec] box => """ Returns an array of the positional arguments of this command. """ _args

fun is_leaf(): Bool => _type is _CommandSpecLeaf

fun is_parent(): Bool => _type is _CommandSpecParent

fun help_name(): String => """ Returns the name of the help command, which defaults to "help". """ _help_name

fun help_string(): String => """ Returns a formatted help string for this command and all of its arguments. """ let s = _name.clone() s.append(" ") let args_iter = _args.values() for a in args_iter do s.append(a.help_string()) if args_iter.has_next() then s.append(" ") end end s

class * commands': Array[CommandSpec ref] box = class CommandSpec """ CommandSpec describes the specification of a parent or leaf command. Each command has the following attributes:

a name: a simple string token that identifies the command.
a description: used in the syntax message.
a map of options: the valid options for this command.
an optional help option+command name for help parsing
one of:
- a Map of child commands.
- an Array of arguments. """ let _type: _CommandSpecType let _name: String let _descr: String let _options: Map[String, OptionSpec] = _options.create() var _help_name: String = "" var _help_info: String = "" // A parent commands can have sub-commands; leaf commands can have args. let _commands: Map[String, CommandSpec box] = _commands.create() let _args: Array[ArgSpec] = _args.create()

new parent( name': String, descr': String = "", options': Array[OptionSpec] box = ArrayOptionSpec, commands': Array[CommandSpec] box = ArrayCommandSpec

Returns¶

CommandSpec ref^ ?

leaf¶

[Source]

Creates a command spec that can accept options and arguments, but not child commands.

new ref leaf(
  name': String val,
  descr': String val = "",
  options': Array[OptionSpec val] box = Array[OptionSpec](),
    args': Array[ArgSpec] box = Array[ArgSpec]()) ?
  =>
    """
    Creates a command spec that can accept options and arguments, but not child
    commands.
    """
    _type = _CommandSpecLeaf
    _name = _assert_name(name')?
    _descr = descr'
    for o in options'.values() do
      _options.update(o.name(), o)
    end
    for a in args'.values() do
      _args.push(a)
    end

  fun tag _assert_name(nm: String): String ? =>
    for b in nm.values() do
      if (b != '-') and (b != '_') and
        not ((b >= '0') and (b <= '9')) and
        not ((b >= 'A') and (b <= 'Z')) and
        not ((b >= 'a') and (b <= 'z')) then
        error
      end
    end
    nm

  fun ref add_command(cmd: CommandSpec box) ? =>
    """
    Adds an additional child command to this parent command.
    """
    if is_leaf() then error end
    _commands.update(cmd.name(), cmd)

  fun ref add_help(hname: String = "help", descr': String = "") ? =>
    """
    Adds a standard help option and, optionally command, to a root command.
    """
    _help_name = hname
    _help_info = descr'
    let help_option = OptionSpec.bool(_help_name, _help_info, 'h', false)
    _options.update(_help_name, help_option)
    if is_parent() then
      let help_cmd =
        CommandSpec.leaf(
          _help_name,
          "",
          Array[OptionSpec](),
          [
            ArgSpec.string("command" where default' = "")
          ])?
      _commands.update(_help_name, help_cmd)
    end

  fun name(): String =>
    """
    Returns the name of this command.
    """
    _name

  fun descr(): String =>
    """
    Returns the description for this command.
    """
    _descr

  fun options(): Map[String, OptionSpec] box =>
    """
    Returns a map by name of the named options of this command.
    """
    _options

  fun commands(): Map[String, CommandSpec box] box =>
    """
    Returns a map by name of the child commands of this command.
    """
    _commands

  fun args(): Array[ArgSpec] box =>
    """
    Returns an array of the positional arguments of this command.
    """
    _args

  fun is_leaf(): Bool => _type is _CommandSpecLeaf

  fun is_parent(): Bool => _type is _CommandSpecParent

  fun help_name(): String =>
    """
    Returns the name of the help command, which defaults to "help".
    """
    _help_name

  fun help_string(): String =>
    """
    Returns a formatted help string for this command and all of its arguments.
    """
    let s = _name.clone()
    s.append(" ")
    let args_iter = _args.values()
    for a in args_iter do
      s.append(a.help_string())
      if args_iter.has_next() then s.append(" ") end
    end
    s

class,
  args': Array[ArgSpec val] box = Array[ArgSpec]()) ?
  =>
    """
    Creates a command spec that can accept options and arguments, but not child
    commands.
    """
    _type = _CommandSpecLeaf
    _name = _assert_name(name')?
    _descr = descr'
    for o in options'.values() do
      _options.update(o.name(), o)
    end
    for a in args'.values() do
      _args.push(a)
    end

  fun tag _assert_name(nm: String): String ? =>
    for b in nm.values() do
      if (b != '-') and (b != '_') and
        not ((b >= '0') and (b <= '9')) and
        not ((b >= 'A') and (b <= 'Z')) and
        not ((b >= 'a') and (b <= 'z')) then
        error
      end
    end
    nm

  fun ref add_command(cmd: CommandSpec box) ? =>
    """
    Adds an additional child command to this parent command.
    """
    if is_leaf() then error end
    _commands.update(cmd.name(), cmd)

  fun ref add_help(hname: String = "help", descr': String = "") ? =>
    """
    Adds a standard help option and, optionally command, to a root command.
    """
    _help_name = hname
    _help_info = descr'
    let help_option = OptionSpec.bool(_help_name, _help_info, 'h', false)
    _options.update(_help_name, help_option)
    if is_parent() then
      let help_cmd =
        CommandSpec.leaf(
          _help_name,
          "",
          Array[OptionSpec](),
          [
            ArgSpec.string("command" where default' = "")
          ])?
      _commands.update(_help_name, help_cmd)
    end

  fun name(): String =>
    """
    Returns the name of this command.
    """
    _name

  fun descr(): String =>
    """
    Returns the description for this command.
    """
    _descr

  fun options(): Map[String, OptionSpec] box =>
    """
    Returns a map by name of the named options of this command.
    """
    _options

  fun commands(): Map[String, CommandSpec box] box =>
    """
    Returns a map by name of the child commands of this command.
    """
    _commands

  fun args(): Array[ArgSpec] box =>
    """
    Returns an array of the positional arguments of this command.
    """
    _args

  fun is_leaf(): Bool => _type is _CommandSpecLeaf

  fun is_parent(): Bool => _type is _CommandSpecParent

  fun help_name(): String =>
    """
    Returns the name of the help command, which defaults to "help".
    """
    _help_name

  fun help_string(): String =>
    """
    Returns a formatted help string for this command and all of its arguments.
    """
    let s = _name.clone()
    s.append(" ")
    let args_iter = _args.values()
    for a in args_iter do
      s.append(a.help_string())
      if args_iter.has_next() then s.append(" ") end
    end
    s

class val OptionSpec
  """
  OptionSpec describes the specification of a named Option. They have a name,
  descr(iption), a short-name, a typ(e), and a default value when they are not
  required.

  Options can be placed anywhere before or after commands, and can be thought
  of as named arguments.
  """
  let _name: String
  let _descr: String
  let _short: (U8 | None)
  let _typ: _ValueType
  let _default: _Value
  let _required: Bool

  fun tag _init(typ': _ValueType, default': (_Value | None))
    : (_ValueType, _Value, Bool)
  =>
    match \exhaustive\ default'
    | None => (typ', false, true)
    | let d: _Value => (typ', d, false)
    end

  new val bool(
    name': String,
    descr': String = "",
    short': (U8 | None) = None,
    default': (Bool | None) = None)
  =>
    """
    Creates an Option with a Bool typed value that can be used like
      `--opt` or `-O` or `--opt=true` or `-O=true`
    to yield an option value like
      `cmd.option("opt").bool() == true`.
    """
    _name = name'
    _descr = descr'
    _short = short'
    (_typ, _default, _required) = _init(_BoolType, default')

  new val string(
    name': String,
    descr': String = "",
    short': (U8 | None) = None,
    default': (String | None) = None)
  =>
    """
    Creates an Option with a String typed value that can be used like
      `--file=dir/filename` or `-F=dir/filename` or `-Fdir/filename`
    to yield an option value like
      `cmd.option("file").string() == "dir/filename"`.
    """
    _name = name'
    _descr = descr'
    _short = short'
    (_typ, _default, _required) = _init(_StringType, default')

  new val i64(name': String,
    descr': String = "",
    short': (U8 | None) = None,
    default': (I64 | None) = None)
  =>
    """
    Creates an Option with an I64 typed value that can be used like
      `--count=42 -C=42`
    to yield an option value like
      `cmd.option("count").i64() == I64(42)`.
    """
    _name = name'
    _descr = descr'
    _short = short'
    (_typ, _default, _required) = _init(_I64Type, default')

  new val u64(name': String,
    descr': String = "",
    short': (U8 | None) = None,
    default': (U64 | None) = None)
  =>
    """
    Creates an Option with an U64 typed value that can be used like
      `--count=47 -C=47`
    to yield an option value like
      `cmd.option("count").u64() == U64(47)`.
    """
    _name = name'
    _descr = descr'
    _short = short'
    (_typ, _default, _required) = _init(_U64Type, default')

  new val f64(name': String,
    descr': String = "",
    short': (U8 | None) = None,
    default': (F64 | None) = None)
  =>
    """
    Creates an Option with a F64 typed value that can be used like
      `--ratio=1.039` or `-R=1.039`
    to yield an option value like
      `cmd.option("ratio").f64() == F64(1.039)`.
    """
    _name = name'
    _descr = descr'
    _short = short'
    (_typ, _default, _required) = _init(_F64Type, default')

  new val string_seq(
    name': String,
    descr': String = "",
    short': (U8 | None) = None)
  =>
    """
    Creates an Option with a ReadSeq[String] typed value that can be used like
      `--files=file1 --files=files2 --files=files2`
    to yield a sequence of three strings equivalent to
      `cmd.option("ratio").string_seq() (equiv) ["file1"; "file2"; "file3"]`.
    """
    _name = name'
    _descr = descr'
    _short = short'
    (_typ, _default, _required) = _init(_StringSeqType, _StringSeq.empty())

  fun name(): String =>
    """
    Returns the name of this option.
    """
    _name

  fun descr(): String =>
    """
    Returns the description for this option.
    """
    _descr

  fun _typ_p(): _ValueType => _typ

  fun _default_p(): _Value => _default

  fun required(): Bool =>
    """
    Returns true iff this option is required to be present in the command line.
    """
    _required

  // Other than bools, all options require args.
  fun _requires_arg(): Bool =>
    match _typ
    | let _: _BoolType => false
    else
      true
    end

  // Used for bool options to get the true arg when option is present w/o arg
  fun _default_arg(): _Value =>
    match _typ
    | let _: _BoolType => true
    else
      false
    end

  fun _has_short(sh: U8): Bool =>
    match _short
    | let ss: U8 => sh == ss
    else
      false
    end

  fun help_string(): String =>
    """
    Returns a formatted help string for this option.
    """
    let s =
      match _short
      | let ss: U8 => "-" + String.from_utf32(ss.u32()) + ", "
      else
        "    "
      end
    s + "--" + _name +
      if not _required then "=" + _default.string() else "" end

  fun deb_string(): String =>
    "--" + _name + "[" + _typ.string() + "]" +
      if not _required then "(=" + _default.string() + ")" else "" end

class val ArgSpec
  """
  ArgSpec describes the specification of a positional Arg(ument). They have a
  name, descr(iption), a typ(e), and a default value when they are not
  required.

  Args always come after a leaf command, and are assigned in their positional
  order.
  """
  let _name: String
  let _descr: String
  let _typ: _ValueType
  let _default: _Value
  let _required: Bool

  fun tag _init(typ': _ValueType, default': (_Value | None))
    : (_ValueType, _Value, Bool)
  =>
    match \exhaustive\ default'
    | None => (typ', false, true)
    | let d: _Value => (typ', d, false)
    end)
: CommandSpec ref^ ?

Parameters¶

name': String val
descr': String val = ""
options': Array[OptionSpec val] box = ArrayOptionSpec, args': Array[ArgSpec] box = ArrayArgSpec) ? => """ Creates a command spec that can accept options and arguments, but not child commands. """ _type = _CommandSpecLeaf _name = _assert_name(name')? _descr = descr' for o in options'.values() do _options.update(o.name(), o) end for a in args'.values() do _args.push(a) end