Class: Slop

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

Defined Under Namespace

Classes: InvalidArgumentError, InvalidOptionError, MissingArgumentError, Option, Options

Constant Summary collapse

VERSION = 
'1.2.1'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

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

Returns a new instance of Slop.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :help (Boolean) —

    Automatically add the help option

  • :strict (Boolean) —

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



48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/slop.rb', line 48

def initialize(options={}, &block)
  @options = Options.new
  @banner = nil
  @longest_flag = 0
  @strict = options[:strict]
  @invalid_options = []

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

  if options[: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.

See Also:



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

def method_missing(meth, *args, &block)
  meth.to_s[/\?$/] ? !!self[meth.to_s.chomp('?')] : super
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.

See Also:



76
77
78
79
 
# File 'lib/slop.rb', line 76

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

#longest_flag ⇒ Object

Returns the value of attribute longest_flag.



42
43
44
 
# File 'lib/slop.rb', line 42

def longest_flag
  @longest_flag
end

#options ⇒ Options (readonly)

Returns:



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

def options
  @options
end

Class Method Details

.parse(items = ARGV, options = {}) { ... } ⇒ 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.

Yields:

  • Specify available CLI arguments using Slop# methods such as Slop#banner and Slop#option

Returns:

  • (Slop) —

    Returns an instance of Slop.

See Also:



26
27
28
 
# File 'lib/slop.rb', line 26

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

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

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

Yields:

  • Specify available CLI arguments using Slop# methods such as Slop#banner and Slop#option

Returns:

  • (Slop) —

    Returns an instance of Slop.



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

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 object associated with that option.

See Also:



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

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

#each ⇒ Object

Enumerable interface



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

def each
  return enum_for(:each) unless block_given?
  @options.each { |option| yield option }
end

#option(*args, &block) ⇒ Object 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 # Optional argument
  on :g, :gender, 'Your gender', :optional => false # Required argument
  on :V, :verbose, 'Run in verbose mode', :default => true # Runs verbose mode by default
  on :P, :people, 'Your friends', true, :as => Array # Required, list of people.
  on :h, :help, 'Print this help screen' do
    puts help
  end # Runs a block
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.



133
134
135
136
137
138
139
140
141
142
 
# File 'lib/slop.rb', line 133

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) 


84
85
86
 
# File 'lib/slop.rb', line 84

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) 


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

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

#to_hash(symbols = nil) ⇒ 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) —

    Returns a hash with each specified option as a symbolic key with an associated value.



156
157
158
 
# File 'lib/slop.rb', line 156

def to_hash(symbols=nil)
  @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
opts.to_s
#=> "Usage - ruby foo.rb [options]\n    -v, --verbose      Enable verbose mode"

Returns:

  • (String) —

    Help text.

See Also:



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

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