process(method_{#to_sym}, arguments_{Array<String>} = [])_self#⚙

Process arguments as a list of options and arguments, then call method with the results of this processing on a new instance of the receiver. This method catches AbortProcessing. Options are arguments that begin with - or --. If .options_must_precede_arguments has been called on the receiver, then options must precede arguments. Either way, a -- argument will always end the processing of options and begin processing of arguments instead.

Raises

UnrecognizedMethod

If the method argument to a dispatch isn’t a known method

UnrecognizedOption

If an unrecognized option has been given

MissingArgument

If a required argument to an option is missing

MalformedArgument

If an argument to an option can’t be parsed

SuperfluousArgument

If more arguments than required/optional have been given

MissingArgument

If a required argument is missing

MalformedArgument

If an argument can’t be parsed

call(method_{#to_sym}, arguments_Array = nil, options_{Hash<String, Object>} = nil)_self#⚙

Call method with arguments and options on a new instance of the receiver. This method catches AbortProcessing. Options are arguments that begin with - or --. If .options_must_precede_arguments has been called on the receiver, then options must precede arguments. Either way, a -- argument will always end the processing of options and begin processing of arguments instead.

Raises

UnrecognizedMethod

If the method argument to a dispatch isn’t a known method

UnrecognizedOption

If an unrecognized option has been given

MissingArgument

If a required argument to an option is missing

MalformedArgument

If an argument to an option can’t be parsed

SuperfluousArgument

If more arguments than required/optional have been given

MissingArgument

If a required argument is missing

MalformedArgument

If an argument can’t be parsed

description(description_String^? = nil)_String#⚙

Sets the description of the method about to be defined, or returns it if description is nil. The description is used in help output and similar circumstances. A description can only be given to a public method, as only public methods can be used as Ame methods.

Example: Set The Description of the Format-patch Method

class Git::CLI::Git::FormatPatch < Ame::Class
  description 'Prepare patches for e-mail submission'
  def format_patch

options_must_precede_arguments_selfprivate#⚙

Forces options to the method about to be defined to precede any arguments, lest they be seen as arguments. If not given, the behaviour will depend on whether ENV['POSIXLY_CORRECT'] has been set or not.

flag(short_String, long_String, default_Boolean, description_String){ |options_{Hash<String, Object>}, value_Boolean| … }^?_selfprivate#⚙

Defines short and/or long as a boolean flag with default and description. An optional block will be used for any validation or further processing of the parsed value of the argument, where options are the options processed so far and their values and value is the parsed value itself or the inverse of default, if no argument was passed. An argument isn’t required, but if one is to be explicitly given, it must be passed as -short=ARGUMENT or --long=ARGUMENT and may be given as any of “true”, “yes”, “on” or “false”, “no”, “off”. Multiple short flags may be juxtaposed as -abc.

Example: A Couple of Flags

class Git::CLI::Git::FormatPatch < Ame::Class
  flag   ?n, 'numbered', false, 'Name output in [PATCH n/m] format'
  flag   ?N, 'no-numbered', nil, 'Name output in [PATCH] format' do |opt|
    opt['numbered'] = false
  end
end

Raises

ArgumentError

If short or long have already been defined

ArgumentError

If short and long are #strip#empty?

ArgumentError

If short#strip#length > 1

toggle(short_String, long_String, default_Boolean, description_String){ |options_{Hash<String, Object>}, value_Boolean| … }^?_selfprivate#⚙

Defines short and/or long as a boolean toggle with default and description. A toggle acts like a flag, but also supports --no-long for explicitly specifying that the inverse of the inverse of the default should be used. An optional block will be used for any validation or further processing of the parsed value of the argument, where options are the options processed so far and their values and value is the parsed value itself or the inverse of default, if no argument was passed. An argument isn’t required, but if one is to be explicitly given, it must be passed as -short=ARGUMENT or --long=ARGUMENT and may be given as any of “true”, “yes”, “on” or “false”, “no”, “off”. Multiple short toggles may be juxtaposed as -abc.

Example: A Toggle

class Git::CLI::Git::FormatPatch < Ame::Class
  toggle ?s, 'signoff', false,
    'Add Signed-off-by: line to the commit message'
end

Raises

ArgumentError

If long is #strip#empty?

ArgumentError

If short or long have already been defined

ArgumentError

If short and long are #strip#empty?

ArgumentError

If short#strip#length > 1

switch(short_String, long_String, argument_String, default_Object, argument_default_Object, description_String){ |options_{Hash<String, Object>}, value_Object| … }^?_selfprivate#⚙

Defines short and/or long as a switch with default taking argument with argument_default and description. A switch acts like an option, but the argument is optional and defaults to argument_default. An optional block will be used for any validation or further processing of the parsed value of the argument, where options are the options processed so far and their values and value is the parsed value itself or argument_default, if no argument was passed. An argument must be passed as -short=ARG, or --long=ARG. Multiple short switches may be juxtaposed as -abc. The type of the argument is determined by the type of argument_default, or the type of default if argument_default is nil. If both are nil, String will be used. Also, if argument_default’s type responds to #default, the result of invoking it will be used as the default value of the argument. See Types::Enumeration for an example of a type that abuses this fact.

Example: A Switch Using An Enumeration

class Git::CLI::Git::FormatPatch < Ame::Class
  switch '', 'thread', 'STYLE', nil,
    Ame::Types::Enumeration[:shallow, :deep],
    'Controls addition of In-Reply-To and References headers'
  flag   '', 'no-thread', nil,
    'Disables addition of In-Reply-To and Reference headers' do |o, _|
     o.delete 'thread'
  end
end

Raises

ArgumentError

If short or long have already been defined

ArgumentError

If the type of argument_default or, if argument_default is nil, default isn’t one that Ame knows how to parse

ArgumentError

If short and long are #strip#empty?

ArgumentError

If short#strip#length > 1

option(short_String, long_String, argument_String, default_Object, description_String){ |options_{Hash<String, Object>}, value_Object| … }^?_selfprivate#⚙

Defines short and/or long as an option with default and description. An option always takes an argument. An optional block will be used for any validation or further processing of the parsed value of the argument, where options are the options processed so far and their values and value is the parsed value itself. An argument may be passed as -shortARG, -short=ARG, or --long=ARG or as -short ARG or --long ARG. Multiple short options can thus not be juxtaposed, as anything following the short option will be used as an argument. The type of the argument is determined by the type of default, or String if it’s nil.

Example: An Option

class Git::CLI::Git::FormatPatch < Ame::Class
  option '', 'start-number', 'N', 1,
    'Start numbering the patches at N instead of 1'
end

Raises

ArgumentError

If short or long have already been defined

ArgumentError

If the type of default isn’t one that Ame knows how to parse

ArgumentError

If short and long are #strip#empty?

ArgumentError

If short#strip#length > 1

multioption(short_String, long_String, argument_String, type_::Class, description_String){ |options_{Hash<String, Object>}, value_Object| … }^?_selfprivate#⚙

Defines short and/or long as a multi-option that takes arguments of type and has description. A multi-option always takes an argument and may be given any number of times. Each parsed value of each argument will be added to an Array that’s stored in the options Hash instead of the usual atom types used for the other forms of options. An optional block will be used for any validation or further processing of the parsed value of the argument, where options are the options processed so far and their values and value is the parsed value itself. An argument may be passed as -shortARG, -short=ARG, or --long=ARG or as -short ARG or --long ARG. Multiple short options can thus not be juxtaposed, as anything following the short option will be used as an argument.

Example: An Option

class Git::CLI::Git::FormatPatch < Ame::Class
  multioption '', 'to', 'address', String,
    'Add a To: header to the email headers'
end

Raises

ArgumentError

If short or long have already been defined

ArgumentError

If type isn’t one that Ame knows how to parse

ArgumentError

If short and long are #strip#empty?

ArgumentError

If short#strip#length > 1

argument(name_String, type_::Class, description_String){ |options_{Hash<String, Object>}, processed_{Array<String>}, argument_Object| … }^?_selfprivate#⚙

Defines argument name of type with description. An optional block will be used for any validation or further processing of the parsed value of the argument, where options are the options processed so far and their values, processed are the values of the arguments processed so far, and VALUE is the parsed value itself.

Example: An Argument

class Git::CLI::Git::Annotate < Ame::Class
  argument 'FILE', String, 'File to annotate'
end

Raises

ArgumentError

If type isn’t one that Ame knows how to parse

ArgumentError

If an optional argument has been defined

ArgumentError

If a splat or splus argument has been defined

optional(name_String, default_Object, description_String){ |options_{Hash<String, Object>}, processed_{Array<String>}, argument_Object| … }^?_selfprivate#⚙

Defines optional argument name with default and description. An optional block will be used for any validation or further processing of the parsed value of the argument, where options are the options processed so far and their values, processed are the values of the arguments processed so far, and VALUE is the parsed value itself or default, if no argument was given.

Example: An Optional Argument

class Git::CLI::Git::FormatPatch < Ame::Class
  optional 'SINCE', String, 'Generate patches for commits after SINCE'
end

Raises

ArgumentError

If the type of default isn’t one that Ame knows how to parse

ArgumentError

If a splat or splus argument has been defined

splat(name_String, type_::Class, description_String){ |options_{Hash<String, Object>}, processed_{Array<String>}, argument_Object| … }^?_selfprivate#⚙

Defines splat argument name of type with description. A splat argument may be given zero or more times. An optional block will be used for any validation or further processing, where options are the options processed so far and their values, processed are the values of the arguments processed so far, and argument is the parsed value itself.

Example: A Splat Argument

class Git::CLI::Git::Add < Ame::Class
  splat 'PATHSPEC', String, 'Files to add content from'
end

Raises

ArgumentError

If type isn’t one that Ame knows how to parse

ArgumentError

If a splat or splus argument has been defined

splus(name_String, type_::Class, description_String){ |options_{Hash<String, Object>}, processed_{Array<String>}, argument_Object| … }^?_selfprivate#⚙

Defines required splat argument name of type with description. An optional block will be used for any validation or further processing, where options are the options processed so far and their values, processed are the values of the arguments processed so far, and argument is the parsed value itself.

Example: A Splus Argument

class Git::CLI::Git::CheckAttr < Ame::Class
  splus 'PATHNAME', String, 'Files to list attributes of'
end

Raises

ArgumentError

If type isn’t one that Ame knows how to parse

ArgumentError

If an optional argument has been defined

ArgumentError

If a splat or splus argument has been defined

dispatch(klass_::Class, options_{Hash<String, Object>} = {})_selfprivate#⚙

Sets up a dispatch method to klass. A dispatch method delegates processing to another class based on the first argument passed to it. This is useful if you want to support sub-commands in a simple manner. The description of klass will be used as the description of the dispatch method.

Example: A Git-like Command-line Interface

class Git::CLI::Git < Ame::Class
  description 'The stupid content tracker'
  def initialize; end

  dispatch Remote
end
class Git::CLI::Git::Remote < Ame::Class
  description 'Manage set of remote repositories'
  def initialize; end

  description 'Adds a remote named NAME for the repository at URL'
  argument :name, 'Name of the remote to add'
  argument :url, 'URL to the repository of the remote to add'
  def add(name, url)
    …
  end
end

Options

:default_String

The default method to run; if given, method argument will be optional

Raises_{ArgumentError}

If any arguments have been defined on the method