Class: Slop

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

Defined Under Namespace

Classes: InvalidArgumentError, InvalidOptionError, MissingArgumentError, Option, Options

Constant Summary collapse

VERSION =

Returns The current version string.

Returns:

  • (String) —

    The current version string

'1.6.0'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*opts, &block) ⇒ Slop

Returns a new instance of Slop.

Parameters:

  • options (Hash)
  • opts (Hash) —

    a customizable set of options

Options Hash (*opts):

  • :help (Boolean) —

    Automatically add the help option

  • :strict (Boolean) —

    Strict mode raises when a non listed option is found, false by default

  • :multiple_switches (Boolean) —

    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'

  • :banner (String) —

    The banner text used for the help

  • :on_empty (Proc, #call) —

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

  • :io (IO, #puts) — default: $stderr —

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

  • :exit_on_help (Boolean) — default: true —

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

  • :ignore_case (Boolean) — default: false —

    Ignore options case

  • :on_noopts (Proc, #call) —

    Trigger an event when no options are found



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/slop.rb', line 75

def initialize(*opts, &block)
  sloptions = {}
  sloptions.merge! opts.pop if opts.last.is_a? Hash
  sloptions[:banner] = opts.shift if opts[0].respond_to?(:to_str)
  opts.each { |o| sloptions[o] = true }

  @options = Options.new
  @commands = {}

  @longest_flag = 0
  @invalid_options = []

  @banner = sloptions[:banner]
  @strict = sloptions[:strict]
  @ignore_case = sloptions[:ignore_case]
  @multiple_switches = sloptions[:multiple_switches]
  @on_empty = sloptions[:on_empty]
  @on_noopts = sloptions[:on_noopts] || sloptions[:on_optionless]
  @sloptions = sloptions

  io = sloptions[:io] || $stderr
  eoh = true if sloptions[:exit_on_help].nil?

  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 if eoh
    end
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(meth, *args, &block) ⇒ Boolean

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

Examples:

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

Returns:

  • (Boolean) —

    Whether the desired option was specified.



267
268
269
270
 
# File 'lib/slop.rb', line 267

def method_missing(meth, *args, &block)
  super unless meth.to_s =~ /\?\z/
  present? meth.to_s.chomp '?'
end

Instance Attribute Details

Set or return banner text.

Examples:

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

Parameters:

  • text (String) (defaults to: nil) —

    Displayed banner text.

Returns:

  • (String) —

    The current banner.



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

def banner(text=nil)
  @banner = text if text
  @banner
end

#commands ⇒ Hash (readonly)

Returns:

  • (Hash) 


48
49
50
 
# File 'lib/slop.rb', line 48

def commands
  @commands
end

#longest_flag ⇒ Integer

Returns The length of the longest flag slop knows of.

Returns:

  • (Integer) —

    The length of the longest flag slop knows of



56
57
58
 
# File 'lib/slop.rb', line 56

def longest_flag
  @longest_flag
end

#options ⇒ Options (readonly)

Returns:



45
46
47
 
# File 'lib/slop.rb', line 45

def options
  @options
end

Class Method Details

.parse(items = ARGV, options = {}, &block) ⇒ Slop

Parses the items from a CLI format into a friendly object.

Examples:

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
-------
program.rb --verbose -n 'Emily' -a 25

Parameters:

  • items (Array) (defaults to: ARGV) —

    Items to parse into options.

Returns:

  • (Slop) —

    Returns an instance of Slop.



33
34
35
 
# File 'lib/slop.rb', line 33

def self.parse(items=ARGV, options={}, &block)
  initialize_and_parse(items, false, options, &block)
end

.parse!(items = ARGV, options = {}, &block) ⇒ Slop

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

Returns:

  • (Slop) —

    Returns an instance of Slop.



40
41
42
 
# File 'lib/slop.rb', line 40

def self.parse!(items=ARGV, options={}, &block)
  initialize_and_parse(items, true, options, &block)
end

Instance Method Details

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

Returns the value associated with that option. If an option doesn't exist, a command will instead be searched for

Examples:

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

Parameters:

  • key (Symbol) —

    Option symbol.

Returns:

  • (Object) —

    Returns the value associated with that option. If an option doesn't exist, a command will instead be searched for



148
149
150
151
 
# File 'lib/slop.rb', line 148

def [](key)
  option = @options[key]
  option ? option.argument_value : @commands[key]
end

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

Namespace options depending on what command is executed

Examples:

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

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

Parameters:

  • label (Symbol, String)
  • options (Hash) (defaults to: {})

Returns:

  • (Slop) —

    a new instance of Slop namespaced to +label+

Since:

  • 1.5.0



203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/slop.rb', line 203

def command(label, options={}, &block)
  if @commands[label]
    raise ArgumentError, "command `#{label}` already exists"
  end

  options = @sloptions.merge(options)
  slop = Slop.new(options)
  @commands[label] = slop

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

  slop
end

#each(&block) ⇒ Object

Enumerable interface



138
139
140
 
# File 'lib/slop.rb', line 138

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

#inspect ⇒ Object 



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

def inspect
  "#<Slop config_options=#{@sloptions.inspect}\n  " +
  options.map(&:inspect).join("\n  ") + "\n>"
end

#on_empty(obj = nil, &block) ⇒ Object Also known as: on_empty=

Trigger an event when Slop has no values to parse

Examples:

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

Parameters:

  • proc (Object, nil) —

    The object (which can be anything responding to call)

Since:

  • 1.5.0



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

def on_empty(obj=nil, &block)
  @on_empty ||= (obj || block)
end

#on_noopts(obj = nil, &block) ⇒ Object Also known as: on_optionless

Trigger an event when the arguments contain no options

Examples:

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

Parameters:

  • obj (Object, nil) (defaults to: nil) —

    The object to be triggered (anything responding to call)

Since:

  • 1.6.0



242
243
244
 
# File 'lib/slop.rb', line 242

def on_noopts(obj=nil, &block)
  @on_noopts ||= (obj || block)
end

#option(*args, &block) ⇒ Slop::Option Also known as: opt, on

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

Examples:

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

Parameters:

  • args (*) —

    Option configuration.

Options Hash (*args):

  • :short_flag (Symbol, String) —

    Short option name.

  • :long_flag (Symbol, String) —

    Full option name.

  • :description (String) —

    Option description for use in Slop#help

  • :argument (Boolean) —

    Specifies whether this option requires an argument

  • :options (Hash) —

    Optional option configurations.

Returns:



175
176
177
178
179
180
181
182
183
184
 
# File 'lib/slop.rb', line 175

def option(*args, &block)
  options = args.pop if args.last.is_a?(Hash)
  options ||= {}

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

  option
end

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

Parse a list of options, leaving the original Array unchanged.

Parameters:

  • items (Array) (defaults to: ARGV) —

    A list of items to parse



126
127
128
 
# File 'lib/slop.rb', line 126

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

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

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

Parameters:

  • items (Array) (defaults to: ARGV) —

    A list of items to parse



133
134
135
 
# File 'lib/slop.rb', line 133

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

#present?(option_name) ⇒ Boolean

Check if an option is specified in the parsed list. Does the same as Slop#option? but a convenience method for unacceptable method names.

Parameters:

  • The (Object) —

    object name to check

Returns:

  • (Boolean) —

    true if this option is present

Since:

  • 1.5.0



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

def present?(option_name)
  !!get(option_name)
end

#to_hash(symbols = false) ⇒ Hash Also known as: to_h

Returns the parsed list into a option/value hash.

Examples:

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

# symbols!
opts.to_hash(true) #=> { :name => 'Emily' }

Returns:

  • (Hash) 


255
256
257
 
# File 'lib/slop.rb', line 255

def to_hash(symbols=false)
  @options.to_hash(symbols)
end

#to_s ⇒ String Also known as: help

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

Examples:

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

Returns:

  • (String) —

    Help text.



291
292
293
294
 
# File 'lib/slop.rb', line 291

def to_s
  banner = "#{@banner}\n" if @banner
  (banner || '') + options.to_help
end