Module: ParseArgv

Defined in:
lib/parse-argv.rb,
lib/parse-argv/version.rb,
lib/parse-argv/conversion.rb

Overview

ParseArgv uses a help text of a command line interface (CLI) to find out how to parse a command line. It takes care that required command line arguments are given and optional arguments are consumed.

With a given help text and a command line it produces a Result which contains all values and meta data (ParseArgv.from). The Result::Values support type Conversion and contextual error handling (Result::Value#as).

For some debugging and test purpose it can also serialize a given help text to a informational format (ParseArgv.parse).

For details about the help text syntax see syntax.

Examples:

require 'parse-argv'

args = ParseArgv.from <<~HELP
  usage: test [options] <infile> [<outfile>]

  This is just a demonstration.

  options:
    -f, --format <format>   specify the format
    --verbose               enable verbose mode
    -h, --help              print this help text
HELP

args.verbose?
#=> true, when "--verbose" argument was specified
#=> false, when "--verbose" argument was not specified

args[:infile].as(File, :readable)
#=> file name

args.outfile?
#=> true, when second argument was specified
args.outfile
#=> second argument or nil when not specified

Defined Under Namespace

Modules: Conversion Classes: Error, Result

Constant Summary collapse

VERSION =

current version

'0.1.2'

Class Method Summary collapse

Class Method Details

.from(help_text, argv = ARGV) ⇒ Result

Parses the given +help_text+ and command line +argv+ to create an Result.

Parameters:

  • help_text (String) —

    help text describing all sub-commands, parameters and options in human readable format

  • argv (Array<String>) (defaults to: ARGV) —

    command line arguments

Returns:

  • (Result) —

    the arguments parsed from +argv+ related to the given +help_text+.



53
54
55
56
57
58
 
# File 'lib/parse-argv.rb', line 53

def self.from(help_text, argv = ARGV)
  result = Result.new(*Assemble[help_text, argv])
  block_given? ? yield(result) : result
rescue Error => e
  @on_error&.call(e) or raise
end

.on_error(function) ⇒ ParseArgv .on_error(&block) ⇒ ParseArgv

Defines custom error handler which will be called with the detected Error.

By default the error handler writes the ParseArgv::Error#message prefixed with related ParseArgv::Error#command name to $std_err and terminates the application with the suggested ParseArgv::Error#code.

Overloads:

  • .on_error(function) ⇒ ParseArgv

    Uses the given call back function to handle all parsing errors.

    Examples:

    ParseArgv.on_error ->(e) { $stderr.puts e or exit e.code }

    Parameters:

    • func (Proc) —

      call back function which receives the Error

  • .on_error(&block) ⇒ ParseArgv

    Uses the given +block+ to handle all parsing errors.

    Examples:

    ParseArgv.on_error do |e|
  $stderr.puts(e)
  exit(e.code)
end

Returns:



99
100
101
102
103
 
# File 'lib/parse-argv.rb', line 99

def self.on_error(function = nil, &block)
  function ||= block or return @on_error
  @on_error = function == :raise ? nil : function
  self
end

.parse(help_text) ⇒ Array<Hash>

Parses the given +help_text+ and returns descriptive information about the commands found.

This method can be used to test a +help_text+.

Parameters:

  • help_text (String) —

    help text describing all sub-commands, parameters and options in human readable format

Returns:

  • (Array<Hash>) —

    descriptive information

Raises:

  • (ArgumentError) —

    when the help text contains invalid information



71
72
73
 
# File 'lib/parse-argv.rb', line 71

def self.parse(help_text)
  Assemble.commands(help_text).map!(&:to_h)
end