Skip to content

Accessing Values

Jump to bottom
mosop edited this page Dec 31, 2016 · 38 revisions

To access parsed values, use value containers or value accessors.

Value Container

A value container is an object for storing parsed values. A value container is one of the following types:

Option Value Container

An option value container is a set of Hash objects that contains option values of a model object.

Every option value container has 3 hashes that are different types:

  • String
  • Bool
  • Array(String)

To access option value container, use the Optarg::Model#options method.

To access the hashes, use the option value container's #[] method with a target type.

class Model < Optarg::Model
  string "-s"
  bool "-b"
  array "-a"
end

result = Model.parse(%w(-s foo -b -a bar -a baz))
result.options[String] # => {"-s" => "foo"}
result.options[Bool] # => {"-b" => true}
result.options[Array(String)] # => {"-a" => ["bar", "baz"]}

Key for Multiple Names

If an option has multiple names, only the first name can be used as a hash key.

class Model < Optarg::Model
  bool %w(-f --force)
end

result = Model.parse(%w(--force))
result.options[Bool]["-f"] # => true
result.options[Bool]["--force"] # raises a KeyError

Argument Value Container

An argument value container is an Array-like object that contains argument values of a model object.

To access argument value containers, use the Optarg::Model#args method.

class Model < Optarg::Model
end

result = Model.parse(%w(foo bar baz))
result.args.size # => 3
result.args[0] # => "foo"
result.args[1] # => "bar"
result.args[2] # => "baz"
result.args.map{|i| "#{i}!"} # => ["foo!", "bar!", "baz!"]

An argument value container also has a set of Hash objects that contains argument values of a model object.

Every argument value container has 2 hashes that are different types:

  • String
  • Array(String)

To access the hashes, use the argument value container's #[] method with a target type.

class Model < Optarg::Model
  arg "arg"
  arg_array "item"
end

result = Model.parse(%w(foo bar baz))
result.options[String] # => {"arg" => "foo"}
result.options[Array(String)] # => {"item" => ["bar", "baz"]}

Named Argument Value Hash

A named argument value hash is a Hash object that contains named argument values of a model object.

To access named argument value hashes, use the Optarg::Model#named_args method.

class Model < Optarg::Model
  arg "named"
end

result = Model.parse(%w(foo bar baz))
result.named_args # => {"named" => "foo"}

Nameless Argument Value Array

A nameless argument value array is an Array object that contains nameless argument values of a model object.

To access nameless argument value arrays, use the Optarg::Model#nameless_args method.

class Model < Optarg::Model
  arg "named"
end

result = Model.parse(%w(foo bar baz))
result.nameless_args # => ["bar", "baz"]

Parsed Argument Value Array

A parsed argument value array is an Array object that contains parsed argument values of a model object, regardless of named or nameless.

To access parsed argument value arrays, use the Optarg::Model#parsed_args method.

class Model < Optarg::Model
  arg "named"
end

result = Model.parse(%w(foo bar baz))
result.parsed_args # => ["foo", "bar", "baz"]

Parsed Argument Value Array and Argument Value Container

Parsed argument value arrays are very similar to argument value containers in enumeration functionality. They are different in that an argument value container is an Array-like object and provides value accessors, whereas a parsed argument value array is just an Array object.

Unparsed Argument Value Array

An unparsed argument value array is an Array object that contains unparsed argument values of a model object.

To access unparsed argument value arrays, use the Optarg::Model#unparsed_args method.

class Model < Optarg::Model
  arg "stopper", stop: true
end

result = Model.parse(%w(foo bar baz))
result.unparsed_args # => ["bar", "baz"]

Value Accessor

A value accessor is a method to get a named value. A named value is a value of either an option or a named argument.

Value accessors are automatically defined in model objects and value containers.

A name of a value accessor is determined by a name of an option or argument. Any leading minus signs (-) are eliminated and other minus signs are converted to underscore letters (_). For example, --option-name is converted to option_name.

A value accessor is one of the following types:

String Option Value Accessor

A string option value accessor is a method to get a string option's value.

For a string option, a nilable value accessor is also defined. If a value is not set, the nilable value accessor returns nil instead raises an exception. The name of a nilable value accessor has a trailing ? character.

String option value accessors are defined in model objects and option value containers.

class Model < Optarg::Model
  string "-s"
end

result = Model.parse(%w(-s value))
result.s # => "value"
result.options.s # equivalent to result.s

not_set = Model.parse(%w())
not_set.s # raises a KeyError
not_set.s? # => nil
not_set.options.s # equivalent to not_set.s
not_set.options.s? # equivalent to not_set.s?

Bool Option Value Accessor

A bool option value accessor is a method to get a bool option's value.

The name of a bool option value accessor has a trailing ? character.

If a value is not set, a bool option value accessor returns false.

Bool option value accessors are defined in model objects and option value containers.

class Model < Optarg::Model
  bool "-b"
end

result = Model.parse(%w(-b))
result.b? # => true
result.options.b? # equivalent to result.b?

not_set = Model.parse(%w())
not_set.b? # => false
not_set.options.b? # equivalent to not_set.b?

String-Array Option Value Accessor

A string-array option value accessor is a method to get an string-array option's value.

String-array option value accessors are defined in model objects and option value containers.

class Model < Optarg::Model
  array "-a"
end

result = Model.parse(%w(-a foo -a bar -a baz))
result.a # => ["foo", "bar", "baz"]
result.options.a # equivalent to result.a

Named Argument Value Accessor

A named argument value accessor is a method to get a named argument's value.

For a named argument, a nilable value accessor is also defined. If a value is not set, the nilable value accessor returns nil instead raises an exception. The name of a nilable value accessor has a trailing ? character.

Named argument value accessors are defined in model objects and argument value containers.

class Model < Optarg::Model
  arg "arg"
end

result = Model.parse(%w(foo))
result.arg # => "foo"
result.args.arg # equivalent to result.arg

not_set = Model.parse(%w())
not_set.arg # => raises a KeyError
not_set.arg? # => nil
not_set.args.arg # equivalent to not_set.arg
not_set.args.arg? # equivalent to not_set.arg?

Avoiding Overriding Methods

If an accessor's name is used for any methods that are already defined, the accessor won't be defined and the predefined method won't be overridden.

For a model objects (Optarg::Model), all the methods of its ancestor classes (Reference and Object) and the following methods are not overridden:

  • args
  • named_args
  • nameless_args
  • options
  • parse
  • parsed_args
  • parser
  • unparsed_args

For option value container objects and argument value container objects, all the methods of their ancestor classes (Reference and Object) are not overridden.

class Model < Optarg::Model
  string "--class"
end

result = Model.parse(%w(--class foo))
result.class # => Model
result.options[String]["--class"] # => "foo"

Clone this wiki locally