Slop

@return [Array] A list of aliases this command uses

@overload banner=(string)

Set the banner
@param [String] string The text to set the banner to

@return [Hash]

@overload description=(string)

Set the description
@param [String] string The text to set the description to

@return [Integer] The length of the longest flag slop knows of

@return [Options]

@overload summary=(string)

Set the summary
@param [String] string The text to set the summary to

@option opts [Boolean] :help

* Automatically add the `help` option

@option opts [Boolean] :strict

* Raises when a non listed option is found, false by default

@option opts [Boolean] :multiple_switches

* Allows `-abc` to be processed as the options 'a', 'b', 'c' and will
  force their argument values to true. By default Slop with parse this
  as 'a' with the argument 'bc'

@option opts [String] :banner

* The banner text used for the help

@option opts [Proc, call] :on_empty

* Any object that respondes to `call` which is executed when Slop has
  no items to parse

@option opts [IO, puts] :io ($stderr)

* An IO object for writing to when :help => true is used

@option opts [Boolean] :exit_on_help (true)

* When false and coupled with the :help option, Slop will not exit
  inside of the `help` option

@option opts [Boolean] :ignore_case (false)

* Ignore options case

@option opts [Proc, call] :on_noopts

* Trigger an event when no options are found

@option opts [Boolean] :autocreate (false)

* Autocreate options depending on the Array passed to {#parse}

@option opts [Boolean] :arguments (false)

* Set to true to enable all specified options to accept arguments
  by default

@option opts [Array] :aliases ([])

* Primary uses by commands to implement command aliases

@option opts [Boolean] :completion (true)

* When true, commands will be auto completed. Ie `foobar` will be
  executed simply when `foo` `fo` or `foob` are used

@option options [Boolean] :all_accept_arguments (false)

* When true, every option added will take an argument, this saves
  having to enable it for every option

# File lib/slop.rb, line 405
def initialize(*opts, &block)
  sloptions = opts.last.is_a?(Hash) ? opts.pop : {}
  sloptions[:banner] = opts.shift if opts[0].respond_to?(:to_str)
  opts.each { |o| sloptions[o] = true }

  @options = Options.new
  @commands = {}
  @execution_block = nil

  @longest_flag = 0
  @invalid_options = []

  @banner = sloptions[:banner]
  @strict = sloptions[:strict]
  @ignore_case = sloptions[:ignore_case]
  @multiple_switches = sloptions.fetch(:multiple_switches, true)
  @autocreate = sloptions[:autocreate]
  @completion = sloptions.fetch(:completion, true)
  @arguments = sloptions[:arguments]
  @on_empty = sloptions[:on_empty]
  @io = sloptions.fetch(:io, $stderr)
  @on_noopts = sloptions[:on_noopts] || sloptions[:on_optionless]
  @sloptions = sloptions

  if block_given?
    block.arity == 1 ? yield(self) : instance_eval(&block)
  end

  if sloptions[:help]
    on :h, :help, 'Print this help message', :tail => true do
      @io.puts help
      exit unless sloptions[:exit_on_help] == false
    end
  end
end

Build options from an optspec string

@param [String] optspec The option spec string @param [Array] options A list of options to forward to Slop.new @return [Slop] A new instance of Slop

# File lib/slop.rb, line 311
def self.optspec(optspec, *options)
  if optspec[/^--+$/]
    banner, optspec = optspec.split(/^--+$/, 2)
  end

  lines = optspec.split("\n").reject(&:empty?)
  opts  = Slop.new(banner, *options)

  lines.each do |line|
    opt, description = line.split(' ', 2)
    short, long = opt.split(',').map { |s| s.sub(/\A--?/, '') }
    argument = long && long[-1] == $$
    long.sub!(/\=$/, '') if argument
    opts.on short, long, description, argument
  end

  opts
end

Parses the items from a CLI format into a friendly object

@param [Array] items Items to parse into options. @example Specifying three options to parse:

opts = Slops.parse do
  on :v, :verbose, 'Enable verbose mode'
  on :n, :name,    'Your name'
  on :a, :age,     'Your age'
end

@return [Slop] Returns an instance of Slop

# File lib/slop.rb, line 294
def self.parse(items=ARGV, options={}, &block)
  initialize_and_parse items, false, options, &block
end

Identical to {Slop.parse}, but removes parsed options from the original Array

@return [Slop] Returns an instance of Slop

# File lib/slop.rb, line 302
def self.parse!(items=ARGV, options={}, &block)
  initialize_and_parse items, true, options, &block
end

@param [Symbol] key Option symbol @example

opts[:name] #=> "Emily"
opts.get(:name) #=> "Emily"

@return [Object] Returns the value associated with that option. If an

option doesn't exist, a command will instead be searched for

# File lib/slop.rb, line 505
def [](key)
  option = @options[key]
  option ? option.argument_value : @commands[key]
end

Set or return banner text

@param [String] text Displayed banner text @example

opts = Slop.parse do
  banner "Usage - ruby foo.rb [arguments]"
end

@return [String] The current banner

# File lib/slop.rb, line 449
def banner(text=nil)
  @banner = text if text
  @banner
end

Namespace options depending on what command is executed

@param [Symbol, String] label @param [Hash] options @example

opts = Slop.new do
  command :create do
    on :v, :verbose
  end
end

# ARGV is `create -v`
opts.commands[:create].verbose? #=> true

@since 1.5.0 @raise [ArgumentError] When this command already exists @return [Slop] a new instance of Slop namespaced to label

# File lib/slop.rb, line 563
def command(label, options={}, &block)
  if @commands.key?(label)
    raise ArgumentError, "command `#{label}` already exists"
  end

  slop = Slop.new @sloptions.merge(options)
  slop.aliases = Array(options.delete(:aliases) || options.delete(:alias))
  @commands[label] = slop

  slop.aliases.each { |a| @commands[a] = @commands[label] }

  if block_given?
    block.arity == 1 ? yield(slop) : slop.instance_eval(&block)
  end

  slop
end

Set or return the description

@param [String] text Displayed description text @example

opts = Slop.parse do
  description "This command does a lot of stuff with other stuff."
end

@return [String] The current description

# File lib/slop.rb, line 475
def description(text=nil)
  @description = text if text
  @description
end

Enumerable interface

# File lib/slop.rb, line 495
def each(&block)
  @options.each(&block)
end

Add an execution block (for commands)

@example

opts = Slop.new do
  command :foo do
    on :v, :verbose

    execute { |o| p o.verbose? }
  end
end
opts.parse %w[foo --verbose] #=> true

@param [Array] args The list of arguments to send to this command

is invoked

@since 1.8.0 @yield [Slop] an instance of Slop for this command

# File lib/slop.rb, line 625
def execute(args=[], &block)
  if block_given?
    @execution_block = block
  elsif @execution_block.respond_to?(:call)
    @execution_block.call(self, args)
  end
end

@return [String] This Slop object will options and configuration

settings revealed

# File lib/slop.rb, line 769
def inspect
  "#<Slop config_options=#{@sloptions.inspect}\n  " +
  options.map(&:inspect).join("\n  ") + "\n>"
end

Allows you to check whether an option was specified in the parsed list

Merely sugar for `present?`

@example

#== ruby foo.rb -v
opts.verbose? #=> true
opts.name?    #=> false

@see Slop#present? @return [Boolean] true if this option is present, false otherwise

# File lib/slop.rb, line 706
def method_missing(meth, *args, &block)
  meth = meth.to_s
  if meth[-1] == ??
    present?(meth.chop)
  else
    super
  end
end

Fetch a list of options which were missing from the parsed list

@example

opts = Slop.new do
  on :n, :name, 'Your name', true
  on :p, :password, 'Your password', true
  on :A, 'Use auth?'
end

opts.parse %w[ --name Lee ]
opts.missing #=> ['password', 'a']

@return [Array] A list of options missing from the parsed string @since 2.1.0

# File lib/slop.rb, line 692
def missing
  @options.select { |opt| not present?(opt.key) }.map(&:key)
end

Trigger an event when Slop has no values to parse

@param [Object, call] obj The object (which can be anything

responding to `call`)

@example

Slop.parse do
  on_empty { puts 'No argument given!' }
end

@since 1.5.0

# File lib/slop.rb, line 590
def on_empty(obj=nil, &block)
  @on_empty ||= (obj || block)
end

Trigger an event when the arguments contain no options

@param [Object, call] obj The object to be triggered (anything

responding to `call`)

@example

Slop.parse do
  on_noopts { puts 'No options here!' }
end

@since 1.6.0

# File lib/slop.rb, line 604
def on_noopts(obj=nil, &block)
  @on_noopts ||= (obj || block)
end

Specify an option with a short or long version, description and type

@param [*] args Option configuration. @option args [Symbol, String] :short_flag Short option name. @option args [Symbol, String] :long_flag Full option name. @option args [String] :description Option description for use in Slop#help @option args [Boolean] :argument Specifies whether this option requires

an argument

@option args [Hash] :options Optional option configurations. @example

opts = Slop.parse do
  on :n, :name, 'Your username', true # Required argument
  on :a, :age,  'Your age (optional)', :optional => true
  on :g, :gender, 'Your gender', :optional => false
  on :V, :verbose, 'Run in verbose mode', :default => true
  on :P, :people, 'Your friends', true, :as => Array
  on :h, :help, 'Print this help screen' do
    puts help
  end
end

@return [Slop::Option]

# File lib/slop.rb, line 532
def option(*args, &block)
  options = args.last.is_a?(Hash) ? args.pop : {}
  short, long, desc, arg, extras = clean_options(args)

  options.merge!(extras)
  options[:argument] = true if @sloptions[:all_accept_arguments]

  option = Option.new(self, short, long, desc, arg, options, &block)
  @options << option

  option
end

Parse a list of options, leaving the original Array unchanged

@param [Array] items A list of items to parse

# File lib/slop.rb, line 483
def parse(items=ARGV, &block)
  parse_items items, &block
end

Parse a list of options, removing parsed options from the original Array

@param [Array] items A list of items to parse

# File lib/slop.rb, line 490
def parse!(items=ARGV, &block)
  parse_items items, true, &block
end

Check if an option is specified in the parsed list

Does the same as Slop#option? but a convenience method for unacceptable method names

@param [Object] The object name(s) to check @since 1.5.0 @return [Boolean] true if these options are present, false otherwise

# File lib/slop.rb, line 733
def present?(*option_names)
  option_names.all? { |opt| @options[opt] && @options[opt].count > 0 }
end

Override this method so we can check if an option? method exists

# File lib/slop.rb, line 716
def respond_to?(method)
  method = method.to_s
  if method[-1] == ?? and @options.any? { |o| o.key == method.chop }
    true
  else
    super
  end
end

Set or return the summary

@param [String] text Displayed summary text @example

opts = Slop.parse do
  summary "do stuff with more stuff"
end

@return [String] The current summary

# File lib/slop.rb, line 462
def summary(text=nil)
  @summary = text if text
  @summary
end

Returns the parsed list into a option/value hash

@example

opts.to_hash #=> { :name => 'Emily' }

# strings!
opts.to_hash(false) #=> { 'name' => 'Emily' }

@return [Hash]

# File lib/slop.rb, line 641
def to_hash(symbols=true)
  @options.reduce({}) do |hsh, option|
    key = option.key
    key = key.to_sym if symbols
    hsh[key] = option.argument_value
    hsh
  end
end

Returns the banner followed by available options listed on the next line

@example

opts = Slop.parse do
  banner "Usage - ruby foo.rb [arguments]"
  on :v, :verbose, "Enable verbose mode"
end
puts opts

@return [String] Help text.

# File lib/slop.rb, line 746
def to_s
  parts = []

  parts << banner if banner
  parts << summary if summary
  parts << wrap_and_indent(description, 80, 4) if description

  if options.size > 0
    parts << "options:"

    heads = @options.reject(&:tail)
    tails = @options.select(&:tail)
    all = (heads + tails).select(&:help)

    parts << all.map(&:to_s).join("\n")
  end

  parts.join("\n\n")
end

Return parsed items as a new Class

@example

opts = Slop.new do
  on :n, :name, 'Persons name', true
  on :a, :age, 'Persons age', true, :as => :int
  on :s, :sex, 'Persons sex m/f', true, :match => /^[mf]$/
  on :A, :admin, 'Enable admin mode'
end

opts.parse %w[ --name Lee --age 22 -s m --admin ]

person = opts.to_struct("Person")
person.class  #=> Struct::Person
person.name   #=> 'Lee'
person.age    #=> 22
person.sex    #=> m
person.admin  #=> true

@param [String] name The name of this class @return [Class] The new class, or nil if there are no options @since 2.0.0

# File lib/slop.rb, line 673
def to_struct(name=nil)
  hash = to_hash
  Struct.new(name, *hash.keys).new(*hash.values) unless hash.empty?
end