Class: Argy::Parser

Inherits:
Object
  • Object
show all
Defined in:
lib/argy/parser.rb

Overview

Parses command line arguments.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize {|_self| ... } ⇒ Parser

Returns a new instance of Parser.

Yields:

  • (_self)

Yield Parameters:

  • _self (Argy::Parser) —

    the object that the method was called on



26
27
28
29
30
31
32
33
34
 
# File 'lib/argy/parser.rb', line 26

def initialize
  @usage = $0
  @description = nil
  @arguments = []
  @options = []
  @flags = []
  @examples = []
  yield self if block_given?
end

Instance Attribute Details

#arguments ⇒ Array<Argument> (readonly)

The arguments that were declared

Returns:



16
17
18
 
# File 'lib/argy/parser.rb', line 16

def arguments
  @arguments
end

#examples ⇒ Array<String> (readonly)

The examples that were declared

Returns:

  • (Array<String>) 


12
13
14
 
# File 'lib/argy/parser.rb', line 12

def examples
  @examples
end

#flags ⇒ Array<Array(Array<String>, Proc)> (readonly)

The flags that were declared

Returns:

  • (Array<Array(Array<String>, Proc)>) 


24
25
26
 
# File 'lib/argy/parser.rb', line 24

def flags
  @flags
end

#options ⇒ Array<Option> (readonly)

The options that were declared

Returns:



20
21
22
 
# File 'lib/argy/parser.rb', line 20

def options
  @options
end

Instance Method Details

#argument(*args, **opts) ⇒ Object

Adds an argument

Examples:

Argy.new do |o|
  o.argument :input
end

See Also:



78
79
80
 
# File 'lib/argy/parser.rb', line 78

def argument(*args, **opts)
  @arguments << Argument.new(*args, **opts)
end

#default_values ⇒ Hash{Symbol => Object}

Build the default values for the declared paramters.

Returns:

  • (Hash{Symbol => Object}) 


119
120
121
122
123
124
 
# File 'lib/argy/parser.rb', line 119

def default_values
  parameters.reduce(unused_args: []) do |acc, opt|
    acc[opt.name] = opt.default
    acc
  end
end

#description(description = nil) ⇒ String

Gets or sets a description for your program. If the provided description is nil, the description will not change.

Examples:

Argy.new do |o|
  o.description "a really useful program"
end

Parameters:

  • description (String, nil) (defaults to: nil)

Returns:

  • (String) 


58
59
60
61
 
# File 'lib/argy/parser.rb', line 58

def description(description = nil)
  @description = description if description
  @description
end

#example(example) ⇒ Object

Adds an example

Examples:

Argy.new do |o|
  o.example "$ example foo"
end



68
69
70
 
# File 'lib/argy/parser.rb', line 68

def example(example)
  @examples << example
end

#help(**opts) ⇒ Help

Generate help for this parser.

Returns:

See Also:



113
114
115
 
# File 'lib/argy/parser.rb', line 113

def help(**opts)
  Help.new(self, **opts)
end

#on(*args, &action) ⇒ Object

Adds a flag

Examples:

Argy.new do |o|
  o.on "-v", "--version" do
    puts Example::VERSION
    exit
  end
end



100
101
102
 
# File 'lib/argy/parser.rb', line 100

def on(*args, &action)
  @flags << [args, action]
end

#option(*args, **opts) ⇒ Object

Adds an option

Examples:

Argy.new do |o|
  o.option :verbose, type: :boolean
end

See Also:



88
89
90
 
# File 'lib/argy/parser.rb', line 88

def option(*args, **opts)
  @options << Option.new(*args, **opts)
end

#parameters ⇒ Array<Argument, Option>

All parameters that are defined

Returns:



106
107
108
 
# File 'lib/argy/parser.rb', line 106

def parameters
  arguments + options
end

#parse(argv, strategy: nil) ⇒ Hash{Symbol => Object}

Build the default values for the declared paramters.

Parameters:

  • argv (Array<String>) —

    the command line arguments to parse

  • strategy (Symbol, nil) (defaults to: nil) —

    can be either :order or :permute. See OptionParser#order! and OptionParser#permute! for more info.

Returns:

  • (Hash{Symbol => Object})

Raises:

  • (ParseError) —

    when the arguments can't be parsed



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/argy/parser.rb', line 132

def parse(argv, strategy: nil)
  argv = argv.dup
  values = default_values
  parser = build_parser(values)

  case strategy
  when :order
    parser.order!(argv)
  when :permute
    parser.permute!(argv)
  else
    parser.parse!(argv)
  end

  populate_arguments(values, argv)
  Options.new validate!(values)
rescue OptionParser::ParseError => error
  raise ParseError.new(error)
end

#usage(usage = nil) ⇒ String

Gets or sets the usage for your program. If the provided usage is nil, the usage will not change.

Examples:

Argy.new do |o|
  o.usage "example [INPUT]"
end

Parameters:

  • usage (String, nil) (defaults to: nil) —

    sets the usage if not nil

Returns:

  • (String) —

    usage



44
45
46
47
 
# File 'lib/argy/parser.rb', line 44

def usage(usage = nil)
  @usage = usage if usage
  @usage
end

#validate!(values) ⇒ Hash{Symbol => Object}

Validate the values

Parameters:

  • values (Hash{Symbol => Object})

Returns:

  • (Hash{Symbol => Object})

Raises:



156
157
158
159
160
161
 
# File 'lib/argy/parser.rb', line 156

def validate!(values)
  parameters.each do |param|
    param.validate(values[param.name])
  end
  values
end