Slop

The Hash of configuration options for this Slop instance.

The Array of Slop::Option objects tied to this Slop instance.

Create a new instance of Slop and optionally build options via a block.

config - A Hash of configuration options. block - An optional block used to specify options.

# File lib/slop.rb, line 137
def initialize(config = {}, &block)
  @config = DEFAULT_OPTIONS.merge(config)
  @options = []
  @trash = []
  @triggered_options = []
  @unknown_options = []
  @callbacks = {}
  @separators = {}

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

  if config[:help]
    on('-h', '--help', 'Display this help message.', :tail => true) do
      $stderr.puts help
    end
  end
end

Build a Slop object from a option specification.

This allows you to design your options via a simple String rather than programatically. Do note though that with this method, you're unable to pass any advanced options to the on() method when creating options.

string - The optspec String config - A Hash of configuration options to pass to Slop.new

Examples:

opts = Slop.optspec(<<-SPEC)
ruby foo.rb [options]
---
n,name=     Your name
a,age=      Your age
A,auth      Sign in with auth
p,passcode= Your secret pass code
SPEC

opts.fetch_option(:name).description #=> "Your name"

Returns a new instance of Slop.

# File lib/slop.rb, line 90
def optspec(string, config = {})
  config[:banner], optspec = string.split(/^--+$/, 2) if string[/^--+$/]
  lines = optspec.split("\n").reject(&:empty?)
  opts  = Slop.new(config)

  lines.each do |line|
    opt, description = line.split(' ', 2)
    short, long = opt.split(',').map { |s| s.sub(/\A--?/, '') }
    opt = opts.on(short, long, description)

    if long && long.end_with?('=')
      long.sub!(/\=$/, '')
      opt.config[:argument] = true
    end
  end

  opts
end

items - The Array of items to extract options from (default: ARGV). config - The Hash of configuration options to send to Slop.new(). block - An optional block used to add options.

Examples:

Slop.parse(ARGV, :help => true) do
  on '-n', '--name', 'Your username', :argument => true
end

Returns a new instance of Slop.

# File lib/slop.rb, line 53
def parse(items = ARGV, config = {}, &block)
  init_and_parse(items, false, config, &block)
end

items - The Array of items to extract options from (default: ARGV). config - The Hash of configuration options to send to Slop.new(). block - An optional block used to add options.

Returns a new instance of Slop.

# File lib/slop.rb, line 62
def parse!(items = ARGV, config = {}, &block)
  init_and_parse(items, true, config, &block)
end

Fetch an options argument value.

key - The Symbol or String option short or long flag.

Returns the Object value for this option, or nil.

# File lib/slop.rb, line 228
def [](key)
  option = fetch_option(key)
  option.value if option
end

Add a callback.

label - The Symbol identifier to attach this callback.

Returns nothing.

# File lib/slop.rb, line 327
def add_callback(label, &block)
  (@callbacks[label] ||= []) << block
end

Get or set the banner.

banner - The String to set the banner.

Returns the banner String.

# File lib/slop.rb, line 178
def banner(banner = nil)
  config[:banner] = banner if banner
  config[:banner]
end

Set the banner.

banner - The String to set the banner.

Returns nothing.

# File lib/slop.rb, line 169
def banner=(banner)
  config[:banner] = banner
end

Enumerable interface. Yields each Slop::Option.

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

Fetch a Slop::Option object.

key - The Symbol or String option key.

Examples:

opts.on(:foo, 'Something fooey', :argument => :optional)
opt = opts.fetch_option(:foo)
opt.class #=> Slop::Option
opt.accepts_optional_argument? #=> true

Returns an Option or nil if none were found.

# File lib/slop.rb, line 318
def fetch_option(key)
  options.find { |option| [option.long, option.short].include?(clean(key)) }
end

Returns the String inspection text.

# File lib/slop.rb, line 364
def inspect
  "#<Slop #{config.inspect} #{options.map(&:inspect)}>"
end

Convenience method for present?(:option).

Examples:

opts.parse %( --verbose )
opts.verbose? #=> true
opts.other?   #=> false

Returns true if this option is present. If this method does not end with a ? character it will instead call super().

# File lib/slop.rb, line 268
def method_missing(method, *args, &block)
  meth = method.to_s
  if meth.end_with?('?')
    present?(meth.chop)
  else
    super
  end
end

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

Examples:

opts = Slop.new do
  on :n, :name=
  on :p, :password=
end

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

Returns an Array of Strings representing missing options.

# File lib/slop.rb, line 302
def missing
  (options - @triggered_options).map(&:key)
end

Add an Option.

objects - An Array with an optional Hash as the last element.

Examples:

on '-u', '--username=', 'Your username'
on :v, :verbose, 'Enable verbose mode'

Returns the created instance of Slop::Option.

# File lib/slop.rb, line 215
def on(*objects, &block)
  option = build_option(objects, &block)
  options << option
  option
end

Parse a list of items, executing and gathering options along the way.

items - The Array of items to extract options from (default: ARGV). block - An optional block which when used will yield non options.

Returns an Array of original items.

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

Parse a list of items, executing and gathering options along the way. unlike parse() this method will remove any options and option arguments from the original Array.

items - The Array of items to extract options from (default: ARGV). block - An optional block which when used will yield non options.

Returns an Array of original items with options removed.

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

Check for an options presence.

Examples:

opts.parse %w( --foo )
opts.present?(:foo) #=> true
opts.present?(:bar) #=> false

Returns true if all of the keys are present in the parsed arguments.

# File lib/slop.rb, line 254
def present?(*keys)
  keys.all? { |key| (opt = fetch_option(key)) && opt.count > 0 }
end

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

Returns true if this option key exists in our list of options.

# File lib/slop.rb, line 280
def respond_to?(method)
  method = method.to_s
  if method.end_with?('?') && options.any? { |o| o.key == method.chop }
    true
  else
    super
  end
end

Add string separators between options.

text - The String text to print.

# File lib/slop.rb, line 334
def separator(text)
  if @separators[options.size]
    @separators[options.size] << "\n#{text}"
  else
    @separators[options.size] = text
  end
end

Is strict mode enabled?

Returns true if strict mode is enabled, false otherwise.

# File lib/slop.rb, line 160
def strict?
  config[:strict]
end

Returns a new Hash with option flags as keys and option values as values.

# File lib/slop.rb, line 235
def to_hash
  Hash[options.map { |opt| [opt.key.to_sym, opt.value] }]
end

Print a handy Slop help string.

Returns the banner followed by available option help strings.

# File lib/slop.rb, line 345
def to_s
  heads  = options.reject(&:tail?)
  tails  = (options - heads)
  opts = (heads + tails).select(&:help).map(&:to_s)
  optstr = opts.each_with_index.map { |o, i|
    (str = @separators[i + 1]) ? [o, str].join("\n") : o
  }.join("\n")

  if config[:banner]
    config[:banner] << "\n"
    config[:banner] << "#{@separators[0]}\n" if @separators[0]
    config[:banner] + optstr
  else
    optstr
  end
end