Class: Toys::ArgParser

Inherits:
Object
  • Object
show all
Defined in:
lib/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 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::Tool) —

    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.



298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
 
# File 'lib/toys/arg_parser.rb', line 298

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

Returns:

  • (Toys::Flag) —

    The pending flag definition

  • (nil) —

    if there is no pending flag



365
366
367
 
# File 'lib/toys/arg_parser.rb', line 365

def active_flag_def
  @active_flag_def
end

#data ⇒ Hash (readonly)

The collected tool data from parsed arguments.

Returns:

  • (Hash) 


351
352
353
 
# File 'lib/toys/arg_parser.rb', line 351

def data
  @data
end

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

An array of parse error messages.

Returns:



357
358
359
 
# File 'lib/toys/arg_parser.rb', line 357

def errors
  @errors
end

#parsed_args ⇒ Array<String> (readonly)

All command line arguments that have been parsed.

Returns:

  • (Array<String>) 


327
328
329
 
# File 'lib/toys/arg_parser.rb', line 327

def parsed_args
  @parsed_args
end

#tool ⇒ Toys::Tool (readonly)

The tool definition governing this parser.

Returns:



321
322
323
 
# File 'lib/toys/arg_parser.rb', line 321

def tool
  @tool
end

#unmatched_args ⇒ Array<String> (readonly)

All args that were not matched.

Returns:

  • (Array<String>) 


345
346
347
 
# File 'lib/toys/arg_parser.rb', line 345

def unmatched_args
  @unmatched_args
end

#unmatched_flags ⇒ Array<String> (readonly)

Flags that were not matched.

Returns:

  • (Array<String>) 


339
340
341
 
# File 'lib/toys/arg_parser.rb', line 339

def unmatched_flags
  @unmatched_flags
end

#unmatched_positional ⇒ Array<String> (readonly)

Extra positional args that were not matched.

Returns:

  • (Array<String>) 


333
334
335
 
# File 'lib/toys/arg_parser.rb', line 333

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) 


428
429
430
431
432
433
434
435
 
# File 'lib/toys/arg_parser.rb', line 428

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

Returns:

  • (Boolean) 


379
380
381
 
# File 'lib/toys/arg_parser.rb', line 379

def finished?
  @finished
end

#flags_allowed? ⇒ Boolean

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

Returns:

  • (Boolean) 


371
372
373
 
# File 'lib/toys/arg_parser.rb', line 371

def flags_allowed?
  @flags_allowed
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.



389
390
391
 
# File 'lib/toys/arg_parser.rb', line 389

def next_arg_def
  @arg_defs[@arg_def_index]
end

#parse(args) ⇒ self

Incrementally parse a single string or an array of strings

Parameters:

  • args (String, Array<String>)

Returns:

  • (self) 


399
400
401
402
403
404
405
406
407
408
 
# File 'lib/toys/arg_parser.rb', line 399

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