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
20
 
# 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 = []
  @footer_lines = []
end

Instance Method Details

#argument ⇒ Object

:nodoc:



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/opt_parse_builder/argument_builder.rb', line 180

def argument # :nodoc:
  check_for_build_errors
  bundle = ArgumentBundle.new
  unless @banner_lines.empty?
    bundle << BannerArgument.new(@banner_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
  unless @separator_lines.empty?
    bundle << SeparatorArgument.new(@separator_lines)
  end
  unless @footer_lines.empty?
    bundle << FooterArgument.new(@footer_lines)
  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



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

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`.



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

def default(v)
  @default = v
end

#footer(line) ⇒ Object

Add to the footer text shown at the bottom of –help output. You may call this more than once; each call adds another line of text to the footer.

This is the recommended way to add text at the bottom of help output in v1.1.0 and later.

Any type of argument may have footer text.

See also OptParseBuilder#footer



149
150
151
 
# File 'lib/opt_parse_builder/argument_builder.rb', line 149

def footer(line)
  @footer_lines << line
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



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

def handler(&block)
  @handler = block
end

#key(v) ⇒ Object

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



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

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)



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

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).



157
158
159
160
161
 
# File 'lib/opt_parse_builder/argument_builder.rb', line 157

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.



166
167
168
169
170
 
# File 'lib/opt_parse_builder/argument_builder.rb', line 166

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

#separator(line, footer: true) ⇒ 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.

The footer: parameter controls where the text appears:

  • footer: true (default in v1.x) - text appears at bottom (DEPRECATED: use footer method instead)

  • footer: false - text appears positionally between options (will be default in v2.0.0)

Any type of argument may have separator text.

See also OptParseBuilder#separator and OptParseBuilder#footer



128
129
130
131
132
133
134
135
136
137
 
# File 'lib/opt_parse_builder/argument_builder.rb', line 128

def separator(line, footer: true)
  if footer
    warn "separator with footer text is deprecated and will" +
      " become positional in v2.0.0. Use footer(line) instead or" +
      " separator(line, footer: false) for positional."
    @footer_lines << line
  else
    @separator_lines << line
  end
end

#splat_operand(help_name: nil) ⇒ Object

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



174
175
176
177
178
 
# File 'lib/opt_parse_builder/argument_builder.rb', line 174

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