Class: Toys::ArgParser

Inherits:
Object
  • Object
show all
Defined in:
core-docs/toys/arg_parser.rb

Overview

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 in the toys-core gem

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(tool, loader, common_data: {}, require_exact_flag_match: false) ⇒ ArgParser

Create an argument parser for a particular tool.

Parameters:

  • tool (Toys::ToolDefinition) —

    The tool defining the argument format.

  • loader (Toys::Loader) —

    The loader, used to generate suggestions for unrecognized arguments.

  • common_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.



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

def initialize(tool, loader, common_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



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

def active_flag_def
  @active_flag_def
end

#data ⇒ Hash (readonly)

The collected tool data from parsed arguments.

Returns:

  • (Hash) 


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

def data
  @data
end

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

An array of parse error messages.

Returns:



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

def errors
  @errors
end

#parsed_args ⇒ Array<String> (readonly)

All command line arguments that have been parsed.

Returns:

  • (Array<String>) 


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

def parsed_args
  @parsed_args
end

#tool ⇒ Toys::ToolDefinition (readonly)

The tool definition governing this parser.

Returns:



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

def tool
  @tool
end

#unmatched_args ⇒ Array<String> (readonly)

All args that were not matched.

Returns:

  • (Array<String>) 


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

def unmatched_args
  @unmatched_args
end

#unmatched_flags ⇒ Array<String> (readonly)

Flags that were not matched.

Returns:

  • (Array<String>) 


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

def unmatched_flags
  @unmatched_flags
end

#unmatched_positional ⇒ Array<String> (readonly)

Extra positional args that were not matched.

Returns:

  • (Array<String>) 


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

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, and are thus reflected in #data under Context::Key::USAGE_ERRORS.

After this method is called, this object is locked down, and no additional arguments may be parsed.

Returns:

  • (self) 


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

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

#finished? ⇒ boolean

Determine if this parser is finished

Returns:

  • (boolean) 


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

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) 


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

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.



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

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) 


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

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