Class: Optout

Inherits:
Object
  • Object
show all
Defined in:
lib/optout.rb

Defined Under Namespace

Modules: Validator Classes: Boolean, Dir, File, Option, OptionError, OptionInvalid, OptionRequired, OptionUnknown

Constant Summary collapse

VERSION = 
"0.0.2"

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args = {}) ⇒ Optout

Returns a new instance of Optout.



91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/optout.rb', line 91

def initialize(args = {})
  @options = {}
  @check_keys = args.include?(:check_keys) ? args[:check_keys] : true
  @required_context = option_context(:required => true)
  @optional_context = option_context(:required => false)  
  @default_opt_options = {
    :required => args[:required],
    :multiple => args[:multiple],
    :arg_separator => args[:arg_separator]
  }
end

Class Method Details

.options(config = {}, &block) ⇒ Object Also known as: keys

Define a set of options. After the options are defined call Optout#argv or Optout#shell to create them.

optz = Optout.options config do on :key, "-switch", ValidationRule, :multiple => false, :required => true

...

end

Parameters

[config (Hash)] Configuration options [block (Proc)] Option definitions

Configuration Options

[:arg_separator] Set the default argument seperator (i.e., the char used to seperate a switch from its value) for all subsequent options defined via Optout#on. [:check_keys] If true an OptionUnknown error will be raised when the incoming option hash contains a key that has not been associated with an option via Optout#on. Defaults to true. [:multiple] Set the default for all subsequent options defined via on. See Optout#on. [:required] Set the default for all subsequent options defined via on. See Optout#on.

Errors

[ArgumentError] Calls to on from inside a block can raise an ArgumentError.

Examples

optz = Optout.options do on :all, "-a" on :size, "-b", /\A\d+\z/, :required => true on :file, Optout::File.under("/home/sshaw"), :default => "/home/sshaw/tmp" end

optz = Optout.options :required => true, :check_keys => false do on :lib on :prefix, "--prefix" , %w/sshaw/usr/lib, :arg_separator => "=" end

Same as above

optz = Optout.options :check_keys => false do required do on :lib on :prefix, "--prefix" , %w/sshaw/usr/lib, :arg_separator => "=" end end



82
83
84
85
86
 
# File 'lib/optout.rb', line 82

def options(config = {}, &block)
  optout = new(config)
  optout.instance_eval(&block) if block_given?
  optout
end

Instance Method Details

#argv(options = {}) ⇒ Object

Create an argv array that can be to passed to an exec like function. Options must first be defined via Optout#on.

Parameters

[options (Hash)] The options hash used to construct the argv array.

Returns

[Array] The argv array, each element is a String

Errors

[ArgumentError] If options are not a Hash [Optout::OptionRequired] The option hash is missing a required value. [Optout::OptionUnknown] The option hash contains an unknown key. [Optout::OptionInvalid] The option hash contains a value the does not conform to the defined specification.

Examples

Create ["--prefix='/sshaw/usr/lib'", "libssl2"]

optz = Optout.options do on :all, "-a" on :size, "-b", /\A\d+\z/, :required => true on :file, Optout::File.under("/home/sshaw"), :default => "/home/sshaw/tmp" end

optz.argv(:lib => "libssl2", :prefix => "/sshaw/usr/lib")



320
321
322
 
# File 'lib/optout.rb', line 320

def argv(options = {})
  create_options(options).map { |opt| opt.to_a }.flatten
end

#on(*args) ⇒ Object

Define an option.

Parameters

[key (Symbol)] The key of the option in the option hash passed to shell or argv. [switch (String)] Optional. The option's command line switch. If no switch is given only the option's value is output. [rule (Object)] Optional. Validation rule, see Optout#on@Validating. [options (Hash)] Additional option configuration, see Optout#on@Options.

Options

[:arg_separator] The String used to separate the option's switch from its value. Defaults to " " (space). This can be set globally via Optout::options. [:default] The option's default value. This will be used if the option is nil or empty?. [:multiple] If true the option will accept multiple values. If false an Optout::OptionInvalid error will be raised if the option contains multiple values. By default multiple values are joined on a comma, you can set this to a String to join on that string instead. Defaults to false. This can be set globally via Optout::options. [:required] If true the option must contian a value i.e., it must not be false or nil otherwise an Optout::OptionRequired exception will be raised. Defaults to false. This can be set globally via Optout::options or for a set of options via Optout#required or Optout#optional.

Errors

[ArgumentError] An ArgumentError is raised if key is nil or has already been defined

Validating

An option's value can be restricted by a validation rule. If validation fails an Optout::OptionInvalid exception is raised.

Validation rules will only be applied if the option hash contains a non-nil value for the given option's key.
If the option is required you must either define it in a Optout#required block or set the :required option to true when calling Optout#on.

Validation rules can be in one of the following forms:

Regex

A pattern to match the option's value against.

on :key, /\d+/ on :key, "-switch", /\d+/

Array

Only accept value(s) contained in the given array.

on :key, %w(item_a item_b item_c) on :key, "-switch", %w(item_a item_b item_c)

Class

Must be an instance of the given class.

on :key, Fixnum on :key, "-switch", Fixnum

Optout::Boolean

Must be true or false.

on :key, Optout::Boolean on :key, "-switch", Optout::Boolean

Optout::File

Must be a file. Note that the file does not have to exist.

on :key, Optout::File on :key, "-switch", Optout::File

Optout::File has several methods that can be used to tune validation:

on :key, "-switch", Optout::File.named(/-\d2$/).under("/home/sshaw")

In this case the file's basename must match the given regexp and exist under the given directory. See Optout::File for more info.

Optout::Dir

Like Optout::File except for directories. Optout::Dir has several methods that can be used to tune validation, see Optout::Dir.

on :key, Optout::Dir on :key, "-switch", Optout::Dir

Custom Validator

A class that responds to validate! and accepts a single argument containing the option (as an instance of Optout::Option).

class MyValidator def validate!(option) if option.empty? || option.value.size % 2 != 1 raise Optout::OptionInvalid.new(option.key, "bad option!") end end end

on :key, MyValidator.new on :key, "-switch", MyValidator.new

Raises:

  • (ArgumentError) 


197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/optout.rb', line 197

def on(*args)
  key = args.shift

  # switch is optional, this could be a validation rule
  switch = args.shift if String === args[0]
  raise ArgumentError, "option key required" if key.nil?

  key = key.to_sym
  raise ArgumentError, "option already defined: '#{key}'" if @options[key]

  opt_options = Hash === args.last ? @default_opt_options.merge(args.pop) : @default_opt_options.dup
  opt_options[:index] ||= @options.size
  opt_options[:validator] = args.shift

  @options[key] = Option.create(key, switch, opt_options)
end

#optional(&block) ⇒ Object

Create a set of options that are optional. This can also be set on a per option basis, see Optout#on.

Examples

optz = Optout.options do optional do on :ignore, "-i" on :recurse, "-r" end end

optz.optional { on :path, Optout::File }



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

def optional(&block)
  @optional_context.instance_eval(&block)
end

#required(&block) ⇒ Object

Create a set of options that are required.

If any required option is missing from the option hash passed to Optout#argv or Optout#shell an Optout::OptionRequired exception is raised.

This can also be set on a per option basis, see Optout#on.

Examples

optz = Optout.options do required do on :ignore, "-i" on :recurse, "-r" end end

optz.required { on :path, Optout::File }



252
253
254
 
# File 'lib/optout.rb', line 252

def required(&block)    
  @required_context.instance_eval(&block)
end

#shell(options = {}) ⇒ Object

Create an argument string that can be to passed to a system like function. Options must first be defined via Optout#on.

Parameters

[options (Hash)] The option hash used to construct the argument string.

Returns

[String] The argument string.

Errors

See Optout#argv@Errors

Examples

Create "-a -b '1024' '/home/sshaw/some file'"

optz = Optout.options do on :all, "-a" on :size, "-b", /\A\d+\z/, :required => true on :file, Optout::File.under("/home/sshaw"), :default => "/home/sshaw/tmp" end

optz.shell(:all => true, :size => 1024, :file => "/home/sshaw/some file")



284
285
286
 
# File 'lib/optout.rb', line 284

def shell(options = {})
  create_options(options).map { |opt| opt.to_s }.join " "
end