Class: Clive::Argument

Inherits:
Object
  • Object
show all
Defined in:
lib/clive/argument.rb

Overview

An Argument represents an argument for an Option or Command, it can be optional and can also be constricted by various other values, see #initialize.

Defined Under Namespace

Classes: AlwaysTrue

Constant Summary collapse

DEFAULTS =

An Argument will have these traits by default.

{
  :optional   => false,
  :type       => Type::Object,
  :match      => AlwaysTrue.for(:match),
  :within     => AlwaysTrue.for(:include?),
  :default    => nil,
  :constraint => AlwaysTrue.for(:call)
}

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, opts = {}) ⇒ Argument

A new instance of Argument.

Examples:


Argument.new(:arg, :optional => true, :type => Integer, :constraint => :odd?)

Parameters:

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :name (#to_sym) —

    Name of the argument.

  • :optional (Boolean) —

    Whether this argument is optional. An optional argument does not have to be given and will pass :default to the block instead.

  • :type (Type) —

    Type that the matching argument should be cast to. See Type and the various subclasses for details. Each Type defines something that the argument must match in addition to the :match argument given.

  • :match (#match) —

    Regular expression the argument must match.

  • :within (#include?) —

    Collection that the argument should be in. This will be checked against the string argument and the cast object (see :type). So for instance if :type is set to Integer you can set :within to be an array of integers, [1,2,3], or an array of strings, %w(1 2 3), and get the same result.

  • :default (Object) —

    Default value the argument takes. This is only set or used if the Option or Command is actually called.

  • :constraint (#call, #to_proc) —

    Proc which is passed the found argument and should return true if the value is ok and false if not. If the object responds to #to_proc this will be called and the resulting Proc object saved for later use. This allows you to pass method symbols.



82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/clive/argument.rb', line 82

def initialize(name, opts={})
  @name = name.to_sym

  opts[:constraint] = opts[:constraint].to_proc if opts[:constraint].respond_to?(:to_proc)
  opts = DEFAULTS.merge(opts)

  @optional   = opts[:optional]
  @type       = Type.find_class(opts[:type].to_s) rescue opts[:type]
  @match      = opts[:match]
  @within     = opts[:within]
  @default    = opts[:default]
  @constraint = opts[:constraint]
end

Instance Attribute Details

#default ⇒ Object (readonly)

Returns the value of attribute default.



40
41
42
 
# File 'lib/clive/argument.rb', line 40

def default
  @default
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



40
41
42
 
# File 'lib/clive/argument.rb', line 40

def name
  @name
end

#type ⇒ Object (readonly)

Returns the value of attribute type.



40
41
42
 
# File 'lib/clive/argument.rb', line 40

def type
  @type
end

Instance Method Details

#choice_str ⇒ String

Returns Choices or range of choices that can be made, for the help string.

Returns:

  • (String) —

    Choices or range of choices that can be made, for the help string.



108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/clive/argument.rb', line 108

def choice_str
  if @within
    case @within
    when Array
      '(' + @within.join(', ') + ')'
    when Range
      '(' + @within.to_s + ')'
    else
      ''
    end
  else
    ''
  end
end

#coerce(str) ⇒ Object

Converts the given String argument to the correct type determined by the :type passed to #initialize.



164
165
166
167
 
# File 'lib/clive/argument.rb', line 164

def coerce(str)
  return str unless str.is_a?(String)
  @type.typecast(str)
end

#inspect ⇒ Object 



123
124
125
 
# File 'lib/clive/argument.rb', line 123

def inspect
  "#<#{self.class} #{to_s}>"
end

#optional? ⇒ Boolean

Returns Whether the argument is optional.

Returns:

  • (Boolean) —

    Whether the argument is optional.



97
98
99
 
# File 'lib/clive/argument.rb', line 97

def optional?
  @optional
end

#possible?(obj) ⇒ Boolean

Determines whether the object given can be this argument. Checks whether it is valid based on the options passed to #initialize.

Parameters:

Returns:

  • (Boolean) —

    Whether obj could be this argument.



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/clive/argument.rb', line 139

def possible?(obj)
  return false if obj.is_a?(String) && !@type.valid?(obj)
  return false unless @match.match(obj.to_s)

  coerced = coerce(obj)

  unless @within.include?(obj.to_s) || @within.include?(coerced)
    return false
  end

  begin
    return false unless @constraint.call(obj.to_s)
  rescue
    begin
      return false unless @constraint.call(coerced)
    rescue
      return false
    end
  end

  true
end

#to_s ⇒ String

Returns String representation for the argument.

Returns:

  • (String) —

    String representation for the argument.



102
103
104
 
# File 'lib/clive/argument.rb', line 102

def to_s
  optional? ? "[<#@name>]" : "<#@name>"
end