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



277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
 
# File 'lib/toys/arg_parser.rb', line 277

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



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

def active_flag_def
  @active_flag_def
end

#data ⇒ Hash (readonly)

The collected tool data from parsed arguments.

Returns:

  • (Hash) 


330
331
332
 
# File 'lib/toys/arg_parser.rb', line 330

def data
  @data
end

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

An array of parse error messages.

Returns:



336
337
338
 
# File 'lib/toys/arg_parser.rb', line 336

def errors
  @errors
end

#parsed_args ⇒ Array<String> (readonly)

All command line arguments that have been parsed.

Returns:

  • (Array<String>) 


306
307
308
 
# File 'lib/toys/arg_parser.rb', line 306

def parsed_args
  @parsed_args
end

#tool ⇒ Toys::ToolDefinition (readonly)

The tool definition governing this parser.

Returns:



300
301
302
 
# File 'lib/toys/arg_parser.rb', line 300

def tool
  @tool
end

#unmatched_args ⇒ Array<String> (readonly)

All args that were not matched.

Returns:

  • (Array<String>) 


324
325
326
 
# File 'lib/toys/arg_parser.rb', line 324

def unmatched_args
  @unmatched_args
end

#unmatched_flags ⇒ Array<String> (readonly)

Flags that were not matched.

Returns:

  • (Array<String>) 


318
319
320
 
# File 'lib/toys/arg_parser.rb', line 318

def unmatched_flags
  @unmatched_flags
end

#unmatched_positional ⇒ Array<String> (readonly)

Extra positional args that were not matched.

Returns:

  • (Array<String>) 


312
313
314
 
# File 'lib/toys/arg_parser.rb', line 312

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) 


407
408
409
410
411
412
413
414
 
# File 'lib/toys/arg_parser.rb', line 407

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) 


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

def finished?
  @finished
end

#flags_allowed? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

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.



368
369
370
 
# File 'lib/toys/arg_parser.rb', line 368

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) 


378
379
380
381
382
383
384
385
386
387
 
# File 'lib/toys/arg_parser.rb', line 378

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