Module: ParseArgv::Conversion

Defined in:

lib/parse-argv/conversion.rb

Overview

The Conversion module provides an interface to convert String arguments to different types and is used by the Result::Value#as method.

Besides the build-in defined types custom conversion functions can be defined with Conversion.define.

In general a conversion function is a Proc which gets called with a String argument, an error handler and - optional - with function-specific arguments and options.

The conversion function should convert the given String argument and return the result. When it's impossible to convert the argument the error handler have to be called with a descriptive error message.

Here is an example for a conversion function of even Integer:

ParseArgv::Conversion.define(:even_number) do |arg, &err|
  /\A-?\d+/.match?(arg) or err['argument have to be an even integer']
  result = arg.to_i
  result.even? ? result : err['not an even integer']
end

Build-In Conversion Functions

Name	Alias	Description
:integer	Integer	convert to Integer; it allows additional checks like :positive, :negative, :nonzero
:float	Float	convert to Float; it allows additional checks like :positive, :negative, :nonzero
:number	Numeric	convert to Float or Integer; it allows additional checks like :positive, :negative, :nonzero
:byte		convert to Integer; argument can have suffix kilo, Mega, Giga, Tera, Peta, Exa, Zetta and Yotta ('0.5M' == 524288)
:string	String	passes a non-empty string argument
:file_name		convert to file name; uses File#expand_path
:regexp	Regexp	convert to a Regexp
:array	Array	convert to a Array<String>
:date	Date	convert to a Date; accepts optional a Date or Time as :reference option
:time	Time	convert to a Time>; accepts optional a Date or Time as :reference option
:file	File	convert to a file name; checks if the file exists; allows additional checks like :blockdev, :chardev, :grpowned, :owned, :readable, :readable_real, :setgid, :setuid, :size, :socket, :sticky, :symlink :world_readable, :world_writeable, :writable, :writable_real, :zero
:directory	Dir	convert to a directory name; checks if the directory exists; allows additional check like the :file conversion (above)
:file_content		expects a file name and returns the file content

Class Method Summary

• .[](type) ⇒ #call

  Get a conversion function.

• .define(name, old_name = nil, &block) ⇒ Conversion

  Define a conversion function or an alias between two conversion functions.

Class Method Details

.[](type) ⇒ #call

Get a conversion function.

The requested +type+ specifies the type of returned conversion function:

• Symbol: a defined function; see define
• Class: function associated to the given Class
• Enumerable: function to pass only given strings
• Array(type): function returning converted elements of argument array
• Regexp: function which passes matching arguments

Examples:

type is a Symbol

ParseArgv::Conversion[:integer]
# => Proc which converts an argument into an Integer
ParseArgv::Conversion[:integer].call('42')
# => 42

type is a Class

ParseArgv::Conversion[Time]
# => Proc which converts an argument to a Time object
ParseArgv::Conversion[Time].call('2022-01-02 12:13 CET')
# => "2022-01-02 12:13:00 +0100"

type is a Array

ParseArgv::Conversion[%w[foo bar baz]]
# => Proc which allows only an argument 'foo', 'bar', or 'baz'
ParseArgv::Conversion[%w[foo bar baz]].call('bar')
# => "bar"

type is a Array(type)

ParseArgv::Conversion[[:number]]
# => Proc which converts an argument array to numbers
ParseArgv::Conversion[[:number]].call('42, 21.84')
# => [42, 21.84]

type is a Regexp

Conversion[/\Ate+st\z/]
# => Proc which allows only an argument matching the Regexp
Conversion[/\Ate+st\z/].call('teeeeeeest')
# => "teeeeeeest"

Parameters:

• type (Symbol, Class, Enumerable<String>, Array(type), Regexp)

Returns:

• (#call) —

  conversion function

# File 'lib/parse-argv/conversion.rb', line 168

def [](type)
  return regexp_match(type) if type.is_a?(Regexp)
  if type.is_a?(Array) && type.size == 1
    return array_of(Conversion[type[0]])
  end
  return enum_type(type) if type.is_a?(Enumerable)
  (@ll[type] || @ll[type.to_sym]) or
    raise(UnknownAttributeConverterError, type)
end

.define(name, &block) ⇒ Conversion .define(new_name, old_name) ⇒ Conversion

Define a conversion function or an alias between two conversion functions.

Overloads:

• .define(name, &block) ⇒ Conversion

  Define the conversion function for specified +name+.

  Examples:

  define the type +:odd_number+

  ParseArgv::Conversion.define(:odd_number) do |arg, &err|
    result = ParseArgv::Conversion[:number].call(arg, &err)
    result.odd? ? result : err['argument must be an odd number']
  end

  Parameters:

  • name (Symbol) —

    conversion function name

  • block (Proc) —

    conversion function

• .define(new_name, old_name) ⇒ Conversion

  Creates an alias between two conversion functions.

  Examples:

  define the alias +:odd+ for the existing type +:odd_number+

  ParseArgv::Conversion.define(:odd, :odd_number)

  Parameters:

  • new_name (Symbol) —

    new name for the handler

  • old_name (Symbol) —

    name of existing handler

Returns:

• (Conversion) —

  itself

# File 'lib/parse-argv/conversion.rb', line 203

def define(name, old_name = nil, &block)
  @ll[name] = old_name.nil? ? block : self[old_name]
  self
end