class Ame::Class

The superclass of a Ruby class that wants to be able to be invoked from the command line (or with any list of String options and arguments). Subclassed by {Root}, which should be used as the root of any command-line processing interface. See {Root} for an example.

Attributes

parent[RW]

@api developer @return [Class] The parent of the receiver

Public Class Methods

basename(basename = nil) click to toggle source

Sets or returns, depending on if BASENAME is nil or not, the basename of the receiver. The basename is the downcased last component of the double-colon-separated name of the class with all camel-cased sub-words separated by dashes. @api developer @example Basename of A::B::CToTheD

class A::B::CToTheD < Ame::Class; end
A::B::CToTheD.basename # ⇒ "c-to-the-d"

@param [String, nil] basename @return [String]

# File lib/ame-1.0/class.rb, line 386
def basename(basename = nil)
  @basename = basename if basename
  return @basename if defined? @basename
  name.split('::').last.scan(/[[:upper:]][[:lower:]]*/).join('-').downcase
end
call(method, arguments = nil, options = nil) click to toggle source

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. @param [#to_sym] method @param [Array] arguments @param [Hash<String, Object>] options @raise (see Method#call) @raise [UnrecognizedMethod] If the method argument to a dispatch isn’t a

known method

@return [self]

# File lib/ame-1.0/class.rb, line 41
def call(method, arguments = nil, options = nil)
  catch Ame::AbortProcessing do
    methods[method].call new, arguments, options
  end
  self
end
description(description = nil) click to toggle source

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. @param [String, nil] description @return [String] @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
# File lib/ame-1.0/class.rb, line 58
def description(description = nil)
  return method.description(description) if description
  defined?(@description) ? @description : ''
end
fullname() click to toggle source

@api developer @return [String] The full name of the space-separated concatenation of

the basenames of the receiver and its {.parent}s

@example Fullname of A::B::CToTheD

class A::B::CToTheD < Ame::Class; end
A::B::CToTheD.fullname # ⇒ "a b c-to-the-d"
# File lib/ame-1.0/class.rb, line 398
def fullname
  [].tap{ |names|
    klass = self
    until klass.nil? or klass.basename.empty?
      names << klass.basename
      klass = klass.parent
    end
  }.reverse.join(' ')
end
help(help = nil) click to toggle source

Sets the HELP object to use for displaying usage information, or returns it if HELP is nil. The default is to delegate the request to the {.parent}. @api developer @param [#method, dispatch, error, version] help @return [#method, dispatch, error, version]

# File lib/ame-1.0/class.rb, line 371
def help(help = nil)
  return @help = help if help
  @help ||= Ame::Help::Delegate.new(parent.help)
end
methods() click to toggle source

@api developer @return [Methods] The methods defined on the receiver

# File lib/ame-1.0/class.rb, line 410
def methods
  @methods ||= Ame::Methods.new
end
process(method, arguments = []) click to toggle source

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. @param [#to_sym] method @param [Array<String>] arguments @raise (see Method#process) @raise [UnrecognizedMethod] If the method argument to a dispatch isn’t a

known method

@return [self]

# File lib/ame-1.0/class.rb, line 21
def process(method, arguments = [])
  catch Ame::AbortProcessing do
    methods[method].process new, arguments
  end
  self
end

Private Class Methods

argument(name, type, description, &validate) click to toggle source

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. @param (see Method::Undefined#argument) @yield (see Method::Undefined#argument) @yieldparam (see Method::Undefined#argument) @raise (see Method::Undefined#argument) @return [self] @example An Argument

class Git::CLI::Git::Annotate < Ame::Class
  argument 'FILE', String, 'File to annotate'
end
# File lib/ame-1.0/class.rb, line 231
def argument(name, type, description, &validate)
  method.argument name, type, description, &validate
  self
rescue; $!.set_backtrace(caller[1..-1]); raise
end
dispatch(klass, options = {}) click to toggle source

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. @param [::Class] klass @param [Hash<String, Object>] options @option options [String] :default The default method to run; if given,

method argument will be optional

@raise [ArgumentError] If any arguments have been defined on the method @return [self] @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
# File lib/ame-1.0/class.rb, line 327
def dispatch(klass, options = {})
  klass.parent = self
  description klass.description
  options_must_precede_arguments
  flag '', 'help', nil, 'Display help for this method' do
    help.dispatch methods[klass.basename], klass
    throw Ame::AbortAllProcessing
  end unless method.option? :help
  method.arguments? and
    raise ArgumentError,
      'arguments may not be defined for a dispatch: %s' % klass
  if options[:default]
    optional 'method', options[:default], 'Method to run'
  else
    argument 'method', String, 'Method to run'
  end
  splat 'arguments', String, 'Arguments to pass to METHOD'
  define_method Ame::Method.ruby_name(klass.basename) do |method, arguments|
    klass.process method, arguments
  end
  self
rescue; $!.set_backtrace(caller[1..-1]); raise
end
flag(short, long, default, description, &validate) click to toggle source

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`. @param (see Method::Undefined#flag) @yield (see Method::Undefined#flag) @yieldparam (see Method::Undefined#flag) @raise (see Method::Undefined#flag) @return [self] @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
# File lib/ame-1.0/class.rb, line 95
def flag(short, long, default, description, &validate)
  method.flag short, long, default, description, &validate
  self
rescue; $!.set_backtrace(caller[1..-1]); raise
end
method() click to toggle source

@api developer @return [Method::Undefined] The undefined method about to be defined

# File lib/ame-1.0/class.rb, line 353
def method
  @method ||= Ame::Method::Undefined.new(self)
end
method_added(ruby_name) click to toggle source

Defines the previously undefined {.method} now that it’s been added to the class. @api internal @param [Symbol] ruby_name @raise [ArgumentError] If RUBY_NAME is the name of a non-public method

that’s being defined

@return [self]

# File lib/ame-1.0/class.rb, line 423
def method_added(ruby_name)
  if ruby_name == :initialize
    @description = method.define(ruby_name).description
  elsif public_method_defined? ruby_name
    methods << method.define(ruby_name)
  elsif method.valid?
    raise ArgumentError, 'non-public method cannot be used by Ame: %s' % ruby_name, caller
  end
  @method = nil
  self
end
multioption(short, long, argument, type, description, &validate) click to toggle source

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. @param (see Method::Undefined#multioption) @yield (see Method::Undefined#multioption) @yieldparam (see Method::Undefined#multioption) @raise (see Method::Undefined#multioption) @return [self] @example An Option

class Git::CLI::Git::FormatPatch < Ame::Class
  multioption '', 'to', 'address', String,
    'Add a To: header to the email headers'
end
# File lib/ame-1.0/class.rb, line 211
def multioption(short, long, argument, type, description, &validate)
  method.multioption short, long, argument, type, description, &validate
  self
rescue; $!.set_backtrace(caller[1..-1]); raise
end
option(short, long, argument, default, description, &validate) click to toggle source

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. @param (see Method::Undefined#option) @yield (see Method::Undefined#option) @yieldparam (see Method::Undefined#option) @raise (see Method::Undefined#option) @return [self] @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
# File lib/ame-1.0/class.rb, line 183
def option(short, long, argument, default, description, &validate)
  method.option short, long, argument, default, description, &validate
  self
rescue; $!.set_backtrace(caller[1..-1]); raise
end
optional(name, default, description, &validate) click to toggle source

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. @param (see Method::Undefined#optional) @yield (see Method::Undefined#optional) @yieldparam (see Method::Undefined#optional) @raise (see Method::Undefined#optional) @return [self] @example An Optional Argument

class Git::CLI::Git::FormatPatch < Ame::Class
  optional 'SINCE', String, 'Generate patches for commits after SINCE'
end
# File lib/ame-1.0/class.rb, line 252
def optional(name, default, description, &validate)
  method.optional name, default, description, &validate
  self
rescue; $!.set_backtrace(caller[1..-1]); raise
end
options_must_precede_arguments() click to toggle source

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` has been set or not. @return [self]

# File lib/ame-1.0/class.rb, line 69
def options_must_precede_arguments
  method.options_must_precede_arguments
  self
end
splat(name, type, description, &validate) click to toggle source

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. @param (see Method::Undefined#splat) @yield (see Method::Undefined#splat) @yieldparam (see Method::Undefined#splat) @raise (see Method::Undefined#splat) @return [self] @example A Splat Argument

class Git::CLI::Git::Add < Ame::Class
  splat 'PATHSPEC', String, 'Files to add content from'
end
# File lib/ame-1.0/class.rb, line 272
def splat(name, type, description, &validate)
  method.splat name, type, description, &validate
  self
rescue; $!.set_backtrace(caller[1..-1]); raise
end
splus(name, type, description, &validate) click to toggle source

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. @param (see Method::Undefined#splus) @yield (see Method::Undefined#splus) @yieldparam (see Method::Undefined#splus) @raise (see Method::Undefined#splus) @return [self] @example A Splus Argument

class Git::CLI::Git::CheckAttr < Ame::Class
  splus 'PATHNAME', String, 'Files to list attributes of'
end
# File lib/ame-1.0/class.rb, line 292
def splus(name, type, description, &validate)
  method.splus name, type, description, &validate
  self
rescue; $!.set_backtrace(caller[1..-1]); raise
end
switch(short, long, argument, default, argument_default, description, &validate) click to toggle source

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. @param (see Method::Undefined#switch) @yield (see Method::Undefined#switch) @yieldparam (see Method::Undefined#switch) @raise (see Method::Undefined#switch) @return [self] @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
# File lib/ame-1.0/class.rb, line 157
def switch(short, long, argument, default, argument_default, description, &validate)
  method.switch short, long, argument, default, argument_default, description, &validate
  self
rescue; $!.set_backtrace(caller[1..-1]); raise
end
toggle(short, long, default, description, &validate) click to toggle source

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`. @param (see Method::Undefined#toggle) @yield (see Method::Undefined#toggle) @yieldparam (see Method::Undefined#toggle) @raise (see Method::Undefined#toggle) @return [self] @example A Toggle

class Git::CLI::Git::FormatPatch < Ame::Class
  toggle ?s, 'signoff', false,
    'Add Signed-off-by: line to the commit message'
end
# File lib/ame-1.0/class.rb, line 122
def toggle(short, long, default, description, &validate)
  method.toggle short, long, default, description, &validate
  self
rescue; $!.set_backtrace(caller[1..-1]); raise
end