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.4.1'

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'



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/slop.rb', line 57

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

  @options = Options.new
  @longest_flag = 0
  @strict = sloptions[:strict]
  @invalid_options = []
  @multiple_switches = sloptions[:multiple_switches]

  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
      puts help
      exit
    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.



178
179
180
181
 
# File 'lib/slop.rb', line 178

def method_missing(meth, *args, &block)
  super unless meth.to_s =~ /\?\z/
  !!self[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) —

    Returns current banner.



89
90
91
92
 
# File 'lib/slop.rb', line 89

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

#longest_flag ⇒ Object

Returns the value of attribute longest_flag.



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

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

Return the value of an option via the subscript operator.

Examples:

opts[:name] #=> "Emily"

Parameters:

  • key (Symbol) —

    Option symbol.

Returns:

  • (Object) —

    Returns the value associated with that option.



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

def [](key)
  option = @options[key]
  option.argument_value if option
end

#each ⇒ Object

Enumerable interface



109
110
111
112
 
# File 'lib/slop.rb', line 109

def each
  return enum_for(:each) unless block_given?
  @options.each { |option| yield option }
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 a required option or not.

  • :options (Hash) —

    Optional option configurations.

Returns:



145
146
147
148
149
150
151
152
153
154
 
# File 'lib/slop.rb', line 145

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 (defaults to: ARGV) 


97
98
99
 
# File 'lib/slop.rb', line 97

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 (defaults to: ARGV) 


104
105
106
 
# File 'lib/slop.rb', line 104

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


166
167
168
 
# File 'lib/slop.rb', line 166

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.



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

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