Class: Epi::Slop

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

Overview

rubocop:disable Metrics/ClassLength

Defined Under Namespace

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

Constant Summary collapse

VERSION = 
'3.4.0'.freeze
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
}.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Enumerable

#*, #**, #average, #blank?, #combination, #counts, #cross_product, #foldl, #group_neighbours_by, #grouped_to_h, #groups, #map_recursively, #parallel_map, #permutation, #powerset, #reverse, #reverse_each, #rle, #rzip, #select_recursively, #skip, #sort_numerically, #split_after, #split_at, #split_before, #split_between, #sum, #to_iter, #uniq, #unzip

Methods included from Array::ToCSV

#to_csv, #to_tsv

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.



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/epitools/slop.rb', line 127

def initialize(config = {}, &block)
  @config = DEFAULT_OPTIONS.merge(config)
  @options = []
  @commands = {}
  @trash = []
  @triggered_options = []
  @unknown_options = []
  @callbacks = {}
  @separators = {}
  @runner = nil

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

  return unless config[:help]

  on('-h', '--help', 'Display this help message.', tail: true) do
    warn help
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

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

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



454
455
456
457
458
459
460
461
462
 
# File 'lib/epitools/slop.rb', line 454

def method_missing(method, *args, &block)
  meth = method.to_s
  if meth.end_with?('?')
    meth.chop!
    present?(meth) || present?(meth.tr('_', '-'))
  else
    super
  end
end

Instance Attribute Details

#config ⇒ Object (readonly)

The Hash of configuration options for this Slop instance.



118
119
120
 
# File 'lib/epitools/slop.rb', line 118

def config
  @config
end

#options ⇒ Object (readonly)

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



121
122
123
 
# File 'lib/epitools/slop.rb', line 121

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.



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/epitools/slop.rb', line 97

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.



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

def parse(items = ARGV, config = {}, &block)
  parse! items.dup, 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.



63
64
65
66
67
68
69
70
71
 
# File 'lib/epitools/slop.rb', line 63

def parse!(items = ARGV, config = {}, &block)
  if items.is_a?(Hash) && config.empty?
    config = items
    items = ARGV
  end
  slop = Epi::Slop.new config, &block
  slop.parse! items
  slop
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.



278
279
280
281
 
# File 'lib/epitools/slop.rb', line 278

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.



398
399
400
 
# File 'lib/epitools/slop.rb', line 398

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.



168
169
170
171
 
# File 'lib/epitools/slop.rb', line 168

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.



159
160
161
 
# File 'lib/epitools/slop.rb', line 159

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

#command(command, options = {}, &block) ⇒ Object

Add a new command.

command - The Symbol or String used to identify this command. options - A Hash of configuration options (see Slop::new)

Returns a new instance of Slop mapped to this command.



196
197
198
 
# File 'lib/epitools/slop.rb', line 196

def command(command, options = {}, &block)
  @commands[command.to_s] = Epi::Slop.new(options, &block)
end

#description(desc = nil) ⇒ Object

Get or set the description (used for commands).

desc - The String to set the description.

Returns the description String.



185
186
187
188
 
# File 'lib/epitools/slop.rb', line 185

def description(desc = nil)
  config[:description] = desc if desc
  config[:description]
end

#description=(desc) ⇒ Object

Set the description (used for commands).

desc - The String to set the description.



176
177
178
 
# File 'lib/epitools/slop.rb', line 176

def description=(desc)
  config[:description] = desc
end

#each(&block) ⇒ Object

Enumerable interface. Yields each Slop::Option.



297
298
299
 
# File 'lib/epitools/slop.rb', line 297

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

#fetch_command(command) ⇒ Object

Fetch a Slop object associated with this command.

command - The String or Symbol name of the command.

Examples:

opts.command :foo do
  on :v, :verbose, 'Enable verbose mode'
end

# ruby run.rb foo -v
opts.fetch_command(:foo).verbose? #=> true



389
390
391
 
# File 'lib/epitools/slop.rb', line 389

def fetch_command(command)
  @commands[command.to_s]
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.



373
374
375
 
# File 'lib/epitools/slop.rb', line 373

def fetch_option(key)
  options.find { |option| [option.long, option.short].include?(clean(key)) }
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.



357
358
359
 
# File 'lib/epitools/slop.rb', line 357

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.



265
266
267
268
269
 
# File 'lib/epitools/slop.rb', line 265

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.



206
207
208
209
 
# File 'lib/epitools/slop.rb', line 206

def parse(items = ARGV, &block)
  parse! items.dup, &block
  items
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.



219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
 
# File 'lib/epitools/slop.rb', line 219

def parse!(items = ARGV, &block)
  if items.empty? && @callbacks[:empty]
    @callbacks[:empty].each { |cb| cb.call(self) }
    return items
  end

  if (cmd = @commands[items[0]])
    return cmd.parse! items[1..-1]
  end

  items.each_with_index do |item, index|
    @trash << index && break if item == '--'
    autocreate(items, index) if config[:autocreate]
    process_item(items, index, &block) unless @trash.include?(index)
  end
  items.reject!.with_index { |_item, index| @trash.include?(index) }

  missing_options = options.select { |opt| opt.required? && opt.count < 1 }
  if missing_options.any?
    raise MissingOptionError,
          "Missing required option(s): #{missing_options.map(&:key).join(', ')}"
  end

  if @unknown_options.any?
    raise InvalidOptionError, "Unknown options #{@unknown_options.join(', ')}"
  end

  if @triggered_options.empty? && @callbacks[:no_options]
    @callbacks[:no_options].each { |cb| cb.call(self) }
  end

  @runner.call(self, items) if @runner.respond_to?(:call)

  items
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) 


333
334
335
 
# File 'lib/epitools/slop.rb', line 333

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

#respond_to_missing?(method_name, include_all = false) ⇒ 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) 


340
341
342
 
# File 'lib/epitools/slop.rb', line 340

def respond_to_missing?(method_name, include_all = false)
  options.any? { |o| o.key == method_name.to_s.chop } || super
end

#run(callable = nil, &block) ⇒ Object

Specify code to be executed when these options are parsed.

callable - An object responding to a call method.

yields - The instance of Slop parsing these options

An Array of unparsed arguments

Example:

Slop.parse do
  on :v, :verbose

  run do |opts, args|
    puts "Arguments: #{args.inspect}" if opts.verbose?
  end
end

Raises:

  • (ArgumentError) 


317
318
319
320
321
322
 
# File 'lib/epitools/slop.rb', line 317

def run(callable = nil, &block)
  @runner = callable || block
  return if @runner.respond_to?(:call)

  raise ArgumentError, "You must specify a callable object or a block to #run"
end

#separator(text) ⇒ Object

Add string separators between options.

text - The String text to print.



405
406
407
408
409
410
411
 
# File 'lib/epitools/slop.rb', line 405

def separator(text)
  if @separators[options.size]
    @separators[options.size] << "\n#{text}"
  else
    @separators[options.size] = text
  end
end

#strict? ⇒ Boolean

Is strict mode enabled?

Returns true if strict mode is enabled, false otherwise.

Returns:

  • (Boolean) 


152
153
154
 
# File 'lib/epitools/slop.rb', line 152

def strict?
  config[:strict]
end

#to_hash(include_commands = false) ⇒ Object Also known as: to_h

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

include_commands - If true, merge options from all sub-commands.



287
288
289
290
291
292
293
 
# File 'lib/epitools/slop.rb', line 287

def to_hash(include_commands = false)
  hash = Hash[options.map { |opt| [opt.key.to_sym, opt.value] }]
  if include_commands
    @commands.each { |cmd, opts| hash.merge!(cmd.to_sym => opts.to_hash) }
  end
  hash
end

#to_s ⇒ Object Also known as: help

Print a handy Slop help string.

Returns the banner followed by available option help strings.



416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
 
# File 'lib/epitools/slop.rb', line 416

def to_s
  heads  = options.reject(&:tail?)
  tails  = (options - heads)
  opts = (heads + tails).select(&:help).map(&:to_s)
  optstr = opts.each_with_index.map do |o, i|
    (str = @separators[i + 1]) ? [o, str].join("\n") : o
  end.join("\n")

  if @commands.any?
    optstr << "\n" unless optstr.empty?
    optstr << "\nAvailable commands:\n\n"
    optstr << commands_to_help
    optstr << "\n\nSee `<command> --help` for more information on a specific command."
  end

  banner = config[:banner]
  banner ||= "Usage: #{File.basename($PROGRAM_NAME, '.*')}" \
             "#{' [command]' if @commands.any?} [options]"
  if banner
    "#{banner}\n#{@separators[0] ? "#{@separators[0]}\n" : ''}#{optstr}"
  else
    optstr
  end
end