Skip to content

Accessing Values

Jump to bottom
mosop edited this page Nov 23, 2016 · 38 revisions

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!"]

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 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 dash signs (-) are eliminated and other dashes 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 object (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 an option value container object and an argument value container object, 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