# Class: Cri::Parser

Inherits:
  Object
  - Object
  - Cri::Parser
  show all

Defined in:
  lib/cri/parser.rb

## Overview

Cri::Parser is used for parsing command-line options and arguments.

## Defined Under Namespace

Classes: IllegalOptionError, IllegalOptionValueError, OptionRequiresAnArgumentError

## Instance Attribute Summary collapse

- #delegate ⇒ #option_added, #argument_added

  The delegate to which events will be sent.

- #options ⇒ Hash readonly

  The options that have already been parsed.

- #unprocessed_arguments_and_options ⇒ Array readonly

  The options and arguments that have not yet been processed.

## Instance Method Summary collapse

- #gen_argument_list ⇒ Cri::ArgumentList

  The list of arguments that have already been parsed, excluding the -- separator.

- #initialize(arguments_and_options, option_defns, param_defns, explicitly_no_params) ⇒ Parser constructor

  Creates a new parser with the given options/arguments and definitions.

- #run ⇒ Cri::Parser

  Parses the command-line arguments into options and arguments.

- #running? ⇒ Boolean

  True if the parser is running, false otherwise.

- #stop ⇒ void

  Stops the parser.

## Constructor Details

### #initialize(arguments_and_options, option_defns, param_defns, explicitly_no_params) ⇒ `Parser`

Creates a new parser with the given options/arguments and definitions.

Parameters:

- arguments_and_options (`Array<String>`) —

  An array containing the command-line arguments (will probably be `ARGS` for a root command)

- option_defns (`Array<Cri::OptionDefinition>`) —

  An array of option definitions

- param_defns (`Array<Cri::ParamDefinition>`) —

  An array of parameter definitions

    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74

    # File 'lib/cri/parser.rb', line 63

    def initialize(arguments_and_options, option_defns, param_defns, explicitly_no_params)
      @unprocessed_arguments_and_options = arguments_and_options.dup
      @option_defns = option_defns
      @param_defns = param_defns
      @explicitly_no_params = explicitly_no_params

      @options       = {}
      @raw_arguments = []

      @running = false
      @no_more_options = false
    end

## Instance Attribute Details

### #delegate ⇒ `#option_added`, `#argument_added`

The delegate to which events will be sent. The following methods will be send to the delegate:

- `option_added(key, value, cmd)`
- `argument_added(argument, cmd)`

Returns:

- (`#option_added`, `#argument_added`) —

  The delegate

    36
    37
    38

    # File 'lib/cri/parser.rb', line 36

    def delegate
      @delegate
    end

### #options ⇒ `Hash` (readonly)

The options that have already been parsed.

If the parser was stopped before it finished, this will not contain all options and `unprocessed_arguments_and_options` will contain what is left to be processed.

Returns:

- (`Hash`) —

  The already parsed options.

    45
    46
    47

    # File 'lib/cri/parser.rb', line 45

    def options
      @options
    end

### #unprocessed_arguments_and_options ⇒ `Array` (readonly)

The options and arguments that have not yet been processed. If the parser wasn’t stopped (using #stop), this list will be empty.

Returns:

- (`Array`) —

  The not yet parsed options and arguments.

    51
    52
    53

    # File 'lib/cri/parser.rb', line 51

    def unprocessed_arguments_and_options
      @unprocessed_arguments_and_options
    end

## Instance Method Details

### #gen_argument_list ⇒ `Cri::ArgumentList`

Returns The list of arguments that have already been parsed, excluding the -- separator.

Returns:

- (`Cri::ArgumentList`) —

  The list of arguments that have already been parsed, excluding the -- separator.

    126
    127
    128

    # File 'lib/cri/parser.rb', line 126

    def gen_argument_list
      ArgumentList.new(@raw_arguments, @explicitly_no_params, @param_defns)
    end

### #run ⇒ `Cri::Parser`

Parses the command-line arguments into options and arguments.

During parsing, two errors can be raised:

Returns:

- (`Cri::Parser`) —

  The option parser self

Raises:

- IllegalOptionError if an unrecognised option was encountered, i.e. an option that is not present in the list of option definitions

- OptionRequiresAnArgumentError if an option was found that did not have a value, even though this value was required.

    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122

    # File 'lib/cri/parser.rb', line 100

    def run
      @running = true

      while running?
        # Get next item
        e = @unprocessed_arguments_and_options.shift
        break if e.nil?

        if e == '--'
          handle_dashdash(e)
        elsif e =~ /^--./ && !@no_more_options
          handle_dashdash_option(e)
        elsif e =~ /^-./ && !@no_more_options
          handle_dash_option(e)
        else
          add_argument(e)
        end
      end

      self
    ensure
      @running = false
    end

### #running? ⇒ `Boolean`

Returns true if the parser is running, false otherwise.

Returns:

- (`Boolean`) —

  true if the parser is running, false otherwise.

    77
    78
    79

    # File 'lib/cri/parser.rb', line 77

    def running?
      @running
    end

### #stop ⇒ `void`

This method returns an undefined value.

Stops the parser. The parser will finish its current parse cycle but will not start parsing new options and/or arguments.

    85
    86
    87

    # File 'lib/cri/parser.rb', line 85

    def stop
      @running = false
    end