Class: Slop

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/slop.rb,
lib/slop/option.rb,
lib/slop/commands.rb

Defined Under Namespace

Classes: Commands, Error, InvalidArgumentError, InvalidCommandError, InvalidOptionError, MissingArgumentError, MissingOptionError, Option

Constant Summary collapse

VERSION = 
'3.0.4'
DEFAULT_OPTIONS =

Returns a default Hash of configuration options this Slop instance uses.

{
  :strict => false,
  :help => false,
  :banner => nil,
  :ignore_case => false,
  :autocreate => false,
  :arguments => false,
  :optional_arguments => false,
  :multiple_switches => true,
  :longest_flag => 0
}

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config = {}, &block) ⇒ Slop

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.



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# 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

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method, *args, &block) ⇒ Object

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().



261
262
263
264
265
266
267
268
 
# File 'lib/slop.rb', line 261

def method_missing(method, *args, &block)
  meth = method.to_s
  if meth[-1] == ??
    present?(meth.chop)
  else
    super
  end
end

Instance Attribute Details

#config ⇒ Object (readonly)

The Hash of configuration options for this Slop instance.



128
129
130
 
# File 'lib/slop.rb', line 128

def config
  @config
end

#options ⇒ Object (readonly)

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



131
132
133
 
# File 'lib/slop.rb', line 131

def options
  @options
end

Class Method Details

.optspec(string, config = {}) ⇒ Object

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.



90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/slop.rb', line 90

def optspec(string, config = {})
  config[:banner], optspec = string.split(/^--+$/, 2) if string[/^--+$/]
  lines = string.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[-1] == ?$
      long.sub!(/\=$/, '')
      opt.config[:argument] = true
    end
  end

  opts
end

.parse(items = ARGV, config = {}, &block) ⇒ Object

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.



53
54
55
 
# File 'lib/slop.rb', line 53

def parse(items = ARGV, config = {}, &block)
  init_and_parse(items, false, config, &block)
end

.parse!(items = ARGV, config = {}, &block) ⇒ Object

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.



62
63
64
 
# File 'lib/slop.rb', line 62

def parse!(items = ARGV, config = {}, &block)
  init_and_parse(items, true, config, &block)
end

Instance Method Details

#[](key) ⇒ Object Also known as: get

Fetch an options argument value.

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

Returns the Object value for this option, or nil.



221
222
223
224
 
# File 'lib/slop.rb', line 221

def [](key)
  option = fetch_option(key)
  option.value if option
end

#add_callback(label, &block) ⇒ Object

Add a callback.

label - The Symbol identifier to attach this callback.

Returns nothing.



320
321
322
 
# File 'lib/slop.rb', line 320

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.



171
172
173
174
 
# File 'lib/slop.rb', line 171

def banner(banner = nil)
  config[:banner] = banner if banner
  config[:banner]
end

#banner=(banner) ⇒ Object

Set the banner.

banner - The String to set the banner.

Returns nothing.



162
163
164
 
# File 'lib/slop.rb', line 162

def banner=(banner)
  config[:banner] = banner
end

#each(&block) ⇒ Object

Enumerable interface. Yields each Slop::Option.



234
235
236
 
# File 'lib/slop.rb', line 234

def each(&block)
  options.each(&block)
end

#fetch_option(key) ⇒ Object

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.



311
312
313
 
# File 'lib/slop.rb', line 311

def fetch_option(key)
  options.find { |option| [option.long, option.short].include?(clean(key)) }
end

#inspect ⇒ Object

Returns the String inspection text.



346
347
348
 
# File 'lib/slop.rb', line 346

def inspect
  "#<Slop #{config.inspect} #{options.map(&:inspect)}>"
end

#missing ⇒ Object

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.



295
296
297
 
# File 'lib/slop.rb', line 295

def missing
  (options - @triggered_options).map(&:key)
end

#on(*objects, &block) ⇒ Object Also known as: option, opt

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.



208
209
210
211
212
 
# File 'lib/slop.rb', line 208

def on(*objects, &block)
  option = build_option(objects, &block)
  options << option
  option
end

#parse(items = ARGV, &block) ⇒ Object

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.



182
183
184
 
# File 'lib/slop.rb', line 182

def parse(items = ARGV, &block)
  parse_items(items, false, &block)
end

#parse!(items = ARGV, &block) ⇒ Object

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.



194
195
196
 
# File 'lib/slop.rb', line 194

def parse!(items = ARGV, &block)
  parse_items(items, true, &block)
end

#present?(*keys) ⇒ Boolean

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.

Returns:

  • (Boolean) 


247
248
249
 
# File 'lib/slop.rb', line 247

def present?(*keys)
  keys.all? { |key| (opt = fetch_option(key)) && opt.count > 0 }
end

#respond_to?(method) ⇒ Boolean

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

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

Returns:

  • (Boolean) 


273
274
275
276
277
278
279
280
 
# File 'lib/slop.rb', line 273

def respond_to?(method)
  method = method.to_s
  if method[-1] == ?? && options.any? { |o| o.key == method.chop }
    true
  else
    super
  end
end

#separator(text) ⇒ Object

Add string separators between options.

text - The String text to print.



327
328
329
 
# File 'lib/slop.rb', line 327

def separator(text)
  @separators[options.size] = text
end

#to_hash ⇒ Object Also known as: to_h

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



228
229
230
 
# File 'lib/slop.rb', line 228

def to_hash
  Hash[options.map { |opt| [opt.key.to_sym, opt.value] }]
end

#to_s ⇒ Object Also known as: help

Print a handy Slop help string.

Returns the banner followed by available option help strings.



334
335
336
337
338
339
340
341
342
 
# File 'lib/slop.rb', line 334

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")
  config[:banner] ? config[:banner] + "\n" + optstr : optstr
end