Class: OptParseBuilder::ArgumentBuilder

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

Overview

Builds arguments using a builder style DSL. You never create an instance of this class yourself. Instead, an instance is yielded to you by OptParseBuilder.

See the README for examples.

Instance Method Summary collapse

Constructor Details

#initialize ⇒ ArgumentBuilder

:nodoc:



10
11
12
13
14
15
16
17
18
19
 
# File 'lib/opt_parse_builder/argument_builder.rb', line 10

def initialize # :nodoc:
  @key = nil
  @default = nil
  @on = []
  @handler = nil
  @operand_class = nil
  @operand_help_name = nil
  @banner_lines = []
  @separator_lines = []
end

Instance Method Details

#argument ⇒ Object

:nodoc:



152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/opt_parse_builder/argument_builder.rb', line 152

def argument # :nodoc:
  check_for_build_errors
  bundle = ArgumentBundle.new
  unless @banner_lines.empty?
    bundle << BannerArgument.new(@banner_lines)
  end
  unless @separator_lines.empty?
    bundle << SeparatorArgument.new(@separator_lines)
  end
  if !@on.empty?
    bundle << OptionArgument.new(@key, @default, @on, @handler)
  elsif @operand_class
    bundle << @operand_class.new(
      @key,
      @default,
      @operand_help_name,
    )
  else
    if @key || @default
      bundle << ConstantArgument.new(@key, @default)
    end
  end
  bundle.simplify
end

Add to the banner text shown first in the –help output. You may call this more than once; each call adds another line of text to the banner.

Any type of argument may have banner text.

See also OptParseBuilder#banner



110
111
112
 
# File 'lib/opt_parse_builder/argument_builder.rb', line 110

def banner(line)
  @banner_lines << line
end

#default(v) ⇒ Object

Set the argument’s default value. This it the value an argument has before parsing, or if parsing does not set the value.

If an argument’s default value is not explicitly set, then the default value is ‘nil`.



31
32
33
 
# File 'lib/opt_parse_builder/argument_builder.rb', line 31

def default(v)
  @default = v
end

#handler(&block) ⇒ Object

Set a handler, a proc that will will process the argument’s value. The proc takes two arguments:

  • The Argument

  • The value

If no handler is set, it defaults to

`->(argument, value) { argument.value = value }

Applies to these argument types:

  • Simple option

  • Option with value

Example:

arg = OptParseBuilder.build_argument do |arg|
  arg.key :square
  arg.on "-v", "Increase verbosity (can give more than once)"
  arg.handler do |argument, _value|
    argument.value += 1
  end
end



99
100
101
 
# File 'lib/opt_parse_builder/argument_builder.rb', line 99

def handler(&block)
  @handler = block
end

#key(v) ⇒ Object

Set the argument’s key. Accepts either a string or a symbol.



22
23
24
 
# File 'lib/opt_parse_builder/argument_builder.rb', line 22

def key(v)
  @key = v.to_sym
end

#on(*option_args) ⇒ Object

Declares the argument to be an option that is handled by OptParse. The arguments are passed to OptParse exactly as you give them, except that the string DEFAULT is replaced with the argument’s default value.

Simple example:

arg = OptParseBuilder.build_argument do |arg|
  arg.key :quiet
  arg.on "-q", "Be very very quiet", "We're hunting rabbit!"
end

You may split up a long argument list by calling this method more than once. This is equivalent to the above:

arg = OptParseBuilder.build_argument do |arg|
  arg.key :quiet
  arg.on "-q", "Be very very quiet",
  arg.on "We're hunting rabbit!"
end

So that the option’s help may print the default without having to duplicate it, the string DEFAULT is replaced with the argument’s default value:

arg = OptParseBuilder.build_argument do |arg|
  arg.key :size
  arg.default 1024
  arg.on "--size=N", Integer,
  arg.on "Size in bytes (default _DEFAULT_)"
end

When the ‘–help` text for this argument is printed, it will read:

--size-N               Size in bytes (default 1024)



71
72
73
 
# File 'lib/opt_parse_builder/argument_builder.rb', line 71

def on(*option_args)
  @on.concat(option_args)
end

#optional_operand(help_name: nil) ⇒ Object

Declare the operand to be an optional operand. An optional operand consumes one argument. If the argument is not present, value is either the default (if provided), or nil (if no default was provided).



129
130
131
132
133
 
# File 'lib/opt_parse_builder/argument_builder.rb', line 129

def optional_operand(help_name: nil)
  check_operand_class_not_set
  @operand_class = OptionalOperandArgument
  @operand_help_name = help_name
end

#required_operand(help_name: nil) ⇒ Object

Declare the operand to be a required operand. A required operand consumes one argument, generating an error if there is not one.



138
139
140
141
142
 
# File 'lib/opt_parse_builder/argument_builder.rb', line 138

def required_operand(help_name: nil)
  check_operand_class_not_set
  @operand_class = RequiredOperandArgument
  @operand_help_name = help_name
end

#separator(line) ⇒ Object

Add to the separator text shown last in the –help output. You may call this more than once; each call adds another line of text to the separator.

Any type of argument may have separator text.

See also OptParseBuilder#separator



121
122
123
 
# File 'lib/opt_parse_builder/argument_builder.rb', line 121

def separator(line)
  @separator_lines << line
end

#splat_operand(help_name: nil) ⇒ Object

Declare the argument to be a “splat” operand. A splat operand consumes all remaining arguments.



146
147
148
149
150
 
# File 'lib/opt_parse_builder/argument_builder.rb', line 146

def splat_operand(help_name: nil)
  check_operand_class_not_set
  @operand_class = SplatOperandArgument
  @operand_help_name = help_name
end