Class: Slop
- Inherits:
-
Object
- Object
- Slop
- 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.3.2'
- 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
-
#config ⇒ Object
readonly
The Hash of configuration options for this Slop instance.
-
#options ⇒ Object
readonly
The Array of Slop::Option objects tied to this Slop instance.
Class Method Summary collapse
-
.optspec(string, config = {}) ⇒ Object
Build a Slop object from a option specification.
-
.parse(items = ARGV, config = {}, &block) ⇒ Object
items - The Array of items to extract options from (default: ARGV).
-
.parse!(items = ARGV, config = {}, &block) ⇒ Object
items - The Array of items to extract options from (default: ARGV).
Instance Method Summary collapse
-
#[](key) ⇒ Object
(also: #get)
Fetch an options argument value.
-
#add_callback(label, &block) ⇒ Object
Add a callback.
-
#banner(banner = nil) ⇒ Object
Get or set the banner.
-
#banner=(banner) ⇒ Object
Set the banner.
-
#each(&block) ⇒ Object
Enumerable interface.
-
#fetch_option(key) ⇒ Object
Fetch a Slop::Option object.
-
#initialize(config = {}, &block) ⇒ Slop
constructor
Create a new instance of Slop and optionally build options via a block.
-
#inspect ⇒ Object
Returns the String inspection text.
-
#method_missing(method, *args, &block) ⇒ Object
Convenience method for present?(:option).
-
#missing ⇒ Object
Fetch a list of options which were missing from the parsed list.
-
#on(*objects, &block) ⇒ Object
(also: #option, #opt)
Add an Option.
-
#parse(items = ARGV, &block) ⇒ Object
Parse a list of items, executing and gathering options along the way.
-
#parse!(items = ARGV, &block) ⇒ Object
Parse a list of items, executing and gathering options along the way.
-
#present?(*keys) ⇒ Boolean
Check for an options presence.
-
#respond_to?(method) ⇒ Boolean
Override this method so we can check if an option? method exists.
-
#separator(text) ⇒ Object
Add string separators between options.
-
#strict? ⇒ Boolean
Is strict mode enabled?.
-
#to_hash ⇒ Object
(also: #to_h)
Returns a new Hash with option flags as keys and option values as values.
-
#to_s ⇒ Object
(also: #help)
Print a handy Slop help string.
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().
268 269 270 271 272 273 274 275 |
# 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 |
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 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 = 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 |
.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.
228 229 230 231 |
# File 'lib/slop.rb', line 228 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.
327 328 329 |
# File 'lib/slop.rb', line 327 def add_callback(label, &block) (@callbacks[label] ||= []) << block end |
#banner(banner = nil) ⇒ Object
Get or set the banner.
banner - The String to set the banner.
Returns the banner String.
178 179 180 181 |
# File 'lib/slop.rb', line 178 def ( = nil) config[:banner] = if config[:banner] end |
#banner=(banner) ⇒ Object
Set the banner.
banner - The String to set the banner.
Returns nothing.
169 170 171 |
# File 'lib/slop.rb', line 169 def () config[:banner] = end |
#each(&block) ⇒ Object
Enumerable interface. Yields each Slop::Option.
241 242 243 |
# File 'lib/slop.rb', line 241 def each(&block) .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.
318 319 320 |
# File 'lib/slop.rb', line 318 def fetch_option(key) .find { |option| [option.long, option.short].include?(clean(key)) } end |
#inspect ⇒ Object
Returns the String inspection text.
364 365 366 |
# File 'lib/slop.rb', line 364 def inspect "#<Slop #{config.inspect} #{.map(&:inspect)}>" end |
#missing ⇒ Object
302 303 304 |
# File 'lib/slop.rb', line 302 def missing ( - @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.
215 216 217 218 219 |
# File 'lib/slop.rb', line 215 def on(*objects, &block) option = build_option(objects, &block) << 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.
189 190 191 |
# File 'lib/slop.rb', line 189 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.
201 202 203 |
# File 'lib/slop.rb', line 201 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.
254 255 256 |
# File 'lib/slop.rb', line 254 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.
280 281 282 283 284 285 286 287 |
# File 'lib/slop.rb', line 280 def respond_to?(method) method = method.to_s if method.end_with?('?') && .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.
334 335 336 337 338 339 340 |
# File 'lib/slop.rb', line 334 def separator(text) if @separators[.size] @separators[.size] << "\n#{text}" else @separators[.size] = text end end |
#strict? ⇒ Boolean
Is strict mode enabled?
Returns true if strict mode is enabled, false otherwise.
160 161 162 |
# File 'lib/slop.rb', line 160 def strict? config[:strict] end |
#to_hash ⇒ Object Also known as: to_h
Returns a new Hash with option flags as keys and option values as values.
235 236 237 |
# File 'lib/slop.rb', line 235 def to_hash Hash[.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.
345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 |
# File 'lib/slop.rb', line 345 def to_s heads = .reject(&:tail?) tails = ( - 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 |