Class: Toys::ArgParser
- Inherits:
-
Object
- Object
- Toys::ArgParser
- Defined in:
- toys-core/lib/toys/arg_parser.rb
Overview
Defined in the toys-core gem
An internal class that parses command line arguments for a tool.
Generally, you should not need to use this class directly. It is called from CLI.
Defined Under Namespace
Classes: ArgMissingError, ArgValueUnacceptableError, ExtraArgumentsError, FlagAmbiguousError, FlagGroupConstraintError, FlagUnrecognizedError, FlagValueMissingError, FlagValueNotAllowedError, FlagValueUnacceptableError, ToolUnrecognizedError, UsageError
Instance Attribute Summary collapse
-
#active_flag_def ⇒ Toys::Flag?
readonly
The current flag definition whose value is still pending.
-
#data ⇒ Hash
readonly
The collected tool data from parsed arguments.
-
#errors ⇒ Array<Toys::ArgParser::UsageError>
readonly
An array of parse error messages.
-
#parsed_args ⇒ Array<String>
readonly
All command line arguments that have been parsed.
-
#tool ⇒ Toys::ToolDefinition
readonly
The tool definition governing this parser.
-
#unmatched_args ⇒ Array<String>
readonly
All args that were not matched.
-
#unmatched_flags ⇒ Array<String>
readonly
Flags that were not matched.
-
#unmatched_positional ⇒ Array<String>
readonly
Extra positional args that were not matched.
Instance Method Summary collapse
-
#finish ⇒ self
Complete parsing.
-
#finished? ⇒ Boolean
Determine if this parser is finished.
-
#flags_allowed? ⇒ Boolean
Whether flags are currently allowed.
-
#initialize(cli, tool, default_data: {}, require_exact_flag_match: false) ⇒ ArgParser
constructor
Create an argument parser for a particular tool.
-
#next_arg_def ⇒ Toys::PositionalArg?
The argument definition that will be applied to the next argument.
-
#parse(args) ⇒ self
Incrementally parse a single string or an array of strings.
Constructor Details
#initialize(cli, tool, default_data: {}, require_exact_flag_match: false) ⇒ ArgParser
Create an argument parser for a particular tool.
301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 |
# File 'toys-core/lib/toys/arg_parser.rb', line 301 def initialize(cli, tool, default_data: {}, require_exact_flag_match: false) @require_exact_flag_match = require_exact_flag_match @loader = cli.loader @data = initial_data(cli, tool, default_data) @tool = tool @seen_flag_keys = [] @errors = [] @unmatched_args = [] @unmatched_positional = [] @unmatched_flags = [] @parsed_args = [] @active_flag_def = nil @active_flag_arg = nil @arg_defs = tool.positional_args @arg_def_index = 0 @flags_allowed = true @finished = false end |
Instance Attribute Details
#active_flag_def ⇒ Toys::Flag? (readonly)
The current flag definition whose value is still pending
368 369 370 |
# File 'toys-core/lib/toys/arg_parser.rb', line 368 def active_flag_def @active_flag_def end |
#data ⇒ Hash (readonly)
The collected tool data from parsed arguments.
354 355 356 |
# File 'toys-core/lib/toys/arg_parser.rb', line 354 def data @data end |
#errors ⇒ Array<Toys::ArgParser::UsageError> (readonly)
An array of parse error messages.
360 361 362 |
# File 'toys-core/lib/toys/arg_parser.rb', line 360 def errors @errors end |
#parsed_args ⇒ Array<String> (readonly)
All command line arguments that have been parsed.
330 331 332 |
# File 'toys-core/lib/toys/arg_parser.rb', line 330 def parsed_args @parsed_args end |
#tool ⇒ Toys::ToolDefinition (readonly)
The tool definition governing this parser.
324 325 326 |
# File 'toys-core/lib/toys/arg_parser.rb', line 324 def tool @tool end |
#unmatched_args ⇒ Array<String> (readonly)
All args that were not matched.
348 349 350 |
# File 'toys-core/lib/toys/arg_parser.rb', line 348 def unmatched_args @unmatched_args end |
#unmatched_flags ⇒ Array<String> (readonly)
Flags that were not matched.
342 343 344 |
# File 'toys-core/lib/toys/arg_parser.rb', line 342 def unmatched_flags @unmatched_flags end |
#unmatched_positional ⇒ Array<String> (readonly)
Extra positional args that were not matched.
336 337 338 |
# File 'toys-core/lib/toys/arg_parser.rb', line 336 def unmatched_positional @unmatched_positional end |
Instance Method Details
#finish ⇒ self
Complete parsing. This should be called after all arguments have been processed. It does a final check for any errors, including:
- The arguments ended with a flag that was expecting a value but wasn't provided.
- One or more required arguments were never given a value.
- One or more extra arguments were provided.
- Restrictions defined in one or more flag groups were not fulfilled.
Any errors are added to the errors array. It also fills in final values
for Context::Key::USAGE_ERRORS
and Context::Key::ARGS
.
After this method is called, this object is locked down, and no additional arguments may be parsed.
431 432 433 434 435 436 437 438 |
# File 'toys-core/lib/toys/arg_parser.rb', line 431 def finish finish_active_flag finish_arg_defs finish_flag_groups finish_special_data @finished = true self end |
#finished? ⇒ Boolean
Determine if this parser is finished
382 383 384 |
# File 'toys-core/lib/toys/arg_parser.rb', line 382 def finished? @finished end |
#flags_allowed? ⇒ Boolean
Whether flags are currently allowed. Returns false after --
is received.
374 375 376 |
# File 'toys-core/lib/toys/arg_parser.rb', line 374 def flags_allowed? @flags_allowed end |
#next_arg_def ⇒ Toys::PositionalArg?
The argument definition that will be applied to the next argument.
392 393 394 |
# File 'toys-core/lib/toys/arg_parser.rb', line 392 def next_arg_def @arg_defs[@arg_def_index] end |
#parse(args) ⇒ self
Incrementally parse a single string or an array of strings
402 403 404 405 406 407 408 409 410 411 |
# File 'toys-core/lib/toys/arg_parser.rb', line 402 def parse(args) raise "Parser has finished" if @finished Array(args).each do |arg| @parsed_args << arg unless @tool.argument_parsing_disabled? check_flag_value(arg) || check_flag(arg) || handle_positional(arg) end end self end |