Class: Toys::ArgParser

Inherits:
Object
  • Object
show all
Defined in:
core-docs/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

Instance Method Summary collapse

Constructor Details

#initialize(cli, tool, default_data: {}, require_exact_flag_match: false) ⇒ ArgParser

Create an argument parser for a particular tool.

Parameters:

  • cli (Toys::CLI) —

    The CLI in effect.

  • tool (Toys::ToolDefinition) —

    The tool defining the argument format.

  • default_data (Hash) (defaults to: {}) —

    Additional initial data (such as verbosity).

  • require_exact_flag_match (boolean) (defaults to: false) —

    Whether to require flag matches be exact (not partial). Default is false.



297
298
299
 
# File 'core-docs/toys/arg_parser.rb', line 297

def initialize(cli, tool, default_data: {}, require_exact_flag_match: false)
  # Source available in the toys-core gem
end

Instance Attribute Details

#active_flag_def ⇒ Toys::Flag? (readonly)

The current flag definition whose value is still pending

Returns:

  • (Toys::Flag) —

    The pending flag definition

  • (nil) —

    if there is no pending flag



349
350
351
 
# File 'core-docs/toys/arg_parser.rb', line 349

def active_flag_def
  @active_flag_def
end

#data ⇒ Hash (readonly)

The collected tool data from parsed arguments.

Returns:

  • (Hash) 


335
336
337
 
# File 'core-docs/toys/arg_parser.rb', line 335

def data
  @data
end

#errors ⇒ Array<Toys::ArgParser::UsageError> (readonly)

An array of parse error messages.

Returns:



341
342
343
 
# File 'core-docs/toys/arg_parser.rb', line 341

def errors
  @errors
end

#parsed_args ⇒ Array<String> (readonly)

All command line arguments that have been parsed.

Returns:

  • (Array<String>) 


311
312
313
 
# File 'core-docs/toys/arg_parser.rb', line 311

def parsed_args
  @parsed_args
end

#tool ⇒ Toys::ToolDefinition (readonly)

The tool definition governing this parser.

Returns:



305
306
307
 
# File 'core-docs/toys/arg_parser.rb', line 305

def tool
  @tool
end

#unmatched_args ⇒ Array<String> (readonly)

All args that were not matched.

Returns:

  • (Array<String>) 


329
330
331
 
# File 'core-docs/toys/arg_parser.rb', line 329

def unmatched_args
  @unmatched_args
end

#unmatched_flags ⇒ Array<String> (readonly)

Flags that were not matched.

Returns:

  • (Array<String>) 


323
324
325
 
# File 'core-docs/toys/arg_parser.rb', line 323

def unmatched_flags
  @unmatched_flags
end

#unmatched_positional ⇒ Array<String> (readonly)

Extra positional args that were not matched.

Returns:

  • (Array<String>) 


317
318
319
 
# File 'core-docs/toys/arg_parser.rb', line 317

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.

Returns:

  • (self) 


405
406
407
 
# File 'core-docs/toys/arg_parser.rb', line 405

def finish
  # Source available in the toys-core gem
end

#finished? ⇒ boolean

Determine if this parser is finished

Returns:

  • (boolean) 


363
364
365
 
# File 'core-docs/toys/arg_parser.rb', line 363

def finished?
  # Source available in the toys-core gem
end

#flags_allowed? ⇒ boolean

Whether flags are currently allowed. Returns false after -- is received.

Returns:

  • (boolean) 


355
356
357
 
# File 'core-docs/toys/arg_parser.rb', line 355

def flags_allowed?
  # Source available in the toys-core gem
end

#next_arg_def ⇒ Toys::PositionalArg?

The argument definition that will be applied to the next argument.

Returns:

  • (Toys::PositionalArg) —

    The next argument definition.

  • (nil) —

    if all arguments have been filled.



373
374
375
 
# File 'core-docs/toys/arg_parser.rb', line 373

def next_arg_def
  # Source available in the toys-core gem
end

#parse(args) ⇒ self

Incrementally parse a single string or an array of strings

Parameters:

  • args (String, Array<String>)

Returns:

  • (self) 


383
384
385
 
# File 'core-docs/toys/arg_parser.rb', line 383

def parse(args)
  # Source available in the toys-core gem
end