Class: Miniparse::Parser

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

Overview

this is the key class to the miniparse library, please find below an example of use:

require 'miniparse'

parser = Miniparse::Parser.new
parser.add_option "--debug", "activate debugging"
parser.parse ARGV

if parser.options[:debug]
  puts "DEBUG ACTIVATED!"
else
  puts "run silently"
end

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Parser) initialize

Returns a new instance of Parser



41
42
43
44
45
46
47
48
49
50
 
# File 'lib/miniparse/parser.rb', line 41

def initialize
  @commander = Commander.new
  @program_desc = nil     
  @global_broker = OptionBroker.new do
    print program_desc + "\n"    if program_desc
    print help_usage + "\n"
    print help_desc + "\n"
    exit ERR_HELP_REQ
  end
end

Instance Attribute Details

- (array) args (readonly)

Returns rest of arguments after parsing

Returns:

  • (array) —

    rest of arguments after parsing



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

def args
  @args
end

Instance Method Details

- (void) add_command(name, desc, opts = {}, &block)

This method returns an undefined value.

Returns added Command

Parameters:

  • name (symbol|string) —

    is the command name

  • desc (string|nil) —

    is a short description of the command

  • opts (hash) (defaults to: {}) —

    are the options to apply to the command, keys can be:

    • :no_options indicates the command has no command line options



80
81
82
83
 
# File 'lib/miniparse/parser.rb', line 80

def add_command(name, desc, opts={}, &block)
  args = opts.merge(spec: name, desc: desc)
  commander.add_command(args, &block)
end

- (void) add_option(spec, desc, opts = {}, &block)

This method returns an undefined value.

Returns added Option

Parameters:

  • spec (string) —

    is the option specification, similar to the option invocation in the command line (e.g. --debug or --verbose LEVEL)

  • desc (string|nil) —

    is a short description of the option

  • opts (hash) (defaults to: {}) —

    are the options to apply to the option, keys can include:

    • :default

    • :negatable (used only for switches)

    • :shortable



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

def add_option(spec, desc, opts={}, &block)
  args = opts.merge(spec: spec, desc: desc)
  current_broker.add_option(args, &block)
end

- (void) add_program_description(desc)

This method returns an undefined value.

Returns same argument

Parameters:

  • desc (string) —

    is the program description to display on help msgs



54
55
56
 
# File 'lib/miniparse/parser.rb', line 54

def add_program_description(desc)
  @program_desc = desc
end

- (array) command_args

Returns remaining command args after parsing the options for the parsed command

Returns:

  • (array) —

    remaining command args after parsing the options for the parsed command



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

def command_args; commander.parsed_args; end

- (symbol|nil) command_name

Returns name of command parsed , i.e. specified, (or nil if none)

Returns:

  • (symbol|nil) —

    name of command parsed , i.e. specified, (or nil if none)



30
 
# File 'lib/miniparse/parser.rb', line 30

def command_name; commander.parsed_command_name; end

- (hash) command_options

Returns parsed option values for the parsed command

Returns:

  • (hash) —

    parsed option values for the parsed command



33
 
# File 'lib/miniparse/parser.rb', line 33

def command_options; commander.parsed_values; end

- (symbol) current_command_name

Returns the name of the command the next #add_option will apply to

Returns:

  • (symbol) —

    the name of the command the next #add_option will apply to



39
 
# File 'lib/miniparse/parser.rb', line 39

def current_command_name; commander.current_command_name; end

- (string) help_desc

Returns a help message with the short descriptions

Returns:

  • (string) —

    a help message with the short descriptions



106
107
108
109
110
111
112
113
114
 
# File 'lib/miniparse/parser.rb', line 106

def help_desc
  text = ""
  if (global = global_broker.help_desc).size > 0
    text += "\nOptions:\n"
    text += global
  end
  text += commander.help_desc   
  text
end

- (string) help_usage

Returns a usage message

Returns:

  • (string) —

    a usage message



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/miniparse/parser.rb', line 117

def help_usage
  if Miniparse.control(:detailed_usage)
    right_text = @global_broker.help_usage
  elsif current_command_name
    right_text = "[global_options]"   
  else
    right_text = "[options]"
  end

  if current_command_name
    right_text += " <command> [command_options]"
  end
  right_text += " <args>"

  Miniparse.help_usage_format(right_text)
end

- (hash) options

Returns parsed, i.e. specified, global options

Returns:

  • (hash) —

    parsed, i.e. specified, global options



27
 
# File 'lib/miniparse/parser.rb', line 27

def options; global_broker.parsed_values; end

- (array) parse(argv)

Returns unprocessed arguments

Parameters:

  • argv —

    is like ARGV but just for this parser

Returns:

  • (array) —

    unprocessed arguments



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/miniparse/parser.rb', line 87

def parse(argv)
  if Miniparse.control(:help_cmdline_empty) && argv.empty?
    puts help_usage
    exit ERR_HELP_REQ  
  end
  try_argument do
    global_argv, cmd_name, cmd_argv = commander.split_argv(argv)
    @args = global_broker.parse_argv(global_argv)
    
    commander.parse_argv(cmd_name, cmd_argv)    if cmd_name
    if Miniparse.control(:raise_global_args) && !args.empty?
      error = current_command_name  ?  "unrecognized command"  :  "extra arguments"
      raise ArgumentError, "#{error} '#{args[0]}'"
    end
    args      
  end
end