class Topt::Parser

Attributes

arguments[R]
options[R]

Public Class Methods

new() { |self| ... } click to toggle source

Create a parser for parsing ARGV input into options.

# File lib/topt/parser.rb, line 13
def initialize
  @options = {}
  @arguments = []
  yield self if block_given?
end

Public Instance Methods

argument(name, opts={}) click to toggle source

Adds an argument to the class and creates an attr_accessor for it.

Arguments are different from options in several aspects. The first one is how they are parsed from the command line, arguments are retrieved from position:

thor task NAME

Instead of:

thor task --name=NAME

Besides, arguments are used inside your code as an accessor (self.argument), while options are all kept in a hash (self.options).

Finally, arguments cannot have type :default or :boolean but can be optional (supplying :optional => :true or :required => false), although you cannot have a required argument after a non-required argument. If you try it, an error is raised.

Parameters

name<Symbol>

The name of the argument.

options<Hash>

Described below.

Options

:desc - Description for the argument. :required - If the argument is required or not. :optional - If the argument is optional or not. :type - The type of the argument, can be :string, :hash, :array, :numeric. :default - Default value for this argument. It cannot be required and have default values. :banner - String to show on usage notes.

Errors

ArgumentError

Raised if you supply a required argument after a non required one.

# File lib/topt/parser.rb, line 76
def argument(name, opts={})
  required = if opts.key?(:optional)
    !opts[:optional]
  elsif opts.key?(:required)
    opts[:required]
  else
    opts[:default].nil?
  end

  remove_argument name

  if required
    @arguments.each do |argument|
      next if argument.required?
      raise ArgumentError,
        "You cannot have #{name.to_s.inspect} as required argument after " \
        "the non-required argument #{argument.human_name.inspect}."
    end
  end

  opts[:required] = required

  @arguments << Topt::Argument.new(name, opts)
end
option(name, opts) click to toggle source

Adds an option to the set of method options. If :for is given as option, it allows you to change the options from a previous defined task.

parser.option :foo => :bar

Parameters

name<Symbol>

The name of the argument.

options<Hash>

Described below.

Options

:desc - Description for the argument. :required - If the argument is required or not. :default - Default value for this argument. It cannot be required and have default values. :aliases - Aliases for this option. :type - The type of the argument, can be :string, :hash, :array, :numeric or :boolean. :banner - String to show on usage notes. :hide - If you want to hide this option from the help.

# File lib/topt/parser.rb, line 37
def option(name, opts)
  @options[name] = Topt::Option.new(name, opts)
end
parse(given_args=ARGV, defaults_hash = {}) click to toggle source

Parse the given argv-style arguments and return options, arguments, and any remaining unnamed arguments

# File lib/topt/parser.rb, line 119
def parse(given_args=ARGV, defaults_hash = {})
  # split inbound arguments at the first argument
  # that looks like an option (starts with - or --).
  argv_args, argv_switches = Topt::Options.split(given_args.dup)

  # Let Thor::Options parse the options first, so it can remove
  # declared options from the array. This will leave us with
  # a list of arguments that weren't declared.
  parsed_options, remaining = parse_options(argv_switches, defaults_hash)

  # Add the remaining arguments from the options parser to the
  # arguments from argv_args. Then remove any positional
  # arguments declared using #argument. This will leave us with
  # the remaining positional arguments.
  to_parse = argv_args + remaining
  parsed_arguments, parsed_remaining = parse_arguments(to_parse)

  [parsed_options, parsed_arguments, parsed_remaining]
end
parse_arguments(to_parse) click to toggle source

Parse declared arguments from the given argument array, returning a hash of argument name and values, and an array of remaining args.

# File lib/topt/parser.rb, line 148
def parse_arguments(to_parse)
  args_parser = Topt::Arguments.new(@arguments)
  [args_parser.parse(to_parse), args_parser.remaining]
end
parse_options(argv_switches, defaults_hash) click to toggle source

Parse option switches array into options and remaining non-option positional arguments.

# File lib/topt/parser.rb, line 141
def parse_options(argv_switches, defaults_hash)
  options_parser = Topt::Options.new(@options, defaults_hash)
  [options_parser.parse(argv_switches), options_parser.remaining]
end
remove_argument(*names) click to toggle source

Removes a previous defined argument.

Parameters

names<Array>

Arguments to be removed

Examples

parser.remove_argument :foo
parser.remove_argument :foo, :bar, :baz
# File lib/topt/parser.rb, line 111
def remove_argument(*names)
  names.each do |name|
    @arguments.delete_if { |a| a.name == name.to_s }
  end
end