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),
  :infinite   => false
}

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.



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

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]
  @infinite   = opts[:infinite]
end

Instance Attribute Details

#defaultObject (readonly)

Returns the value of attribute default.



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

def default
  @default
end

#nameObject (readonly)

Returns the value of attribute name.



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

def name
  @name
end

#typeObject (readonly)

Returns the value of attribute type.



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

def type
  @type
end

Instance Method Details

#choice_strString

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.



115
116
117
118
119
120
121
122
123
124
125
126
127
128
# File 'lib/clive/argument.rb', line 115

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.



171
172
173
174
# File 'lib/clive/argument.rb', line 171

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

#infinite?Boolean

Returns Whether the argument is infinite.

Returns:

  • (Boolean)

    Whether the argument is infinite.



104
105
106
# File 'lib/clive/argument.rb', line 104

def infinite?
  @infinite
end

#inspectObject



130
131
132
# File 'lib/clive/argument.rb', line 130

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

#optional?Boolean

Returns Whether the argument is optional.

Returns:

  • (Boolean)

    Whether the argument is optional.



99
100
101
# File 'lib/clive/argument.rb', line 99

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.



146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
# File 'lib/clive/argument.rb', line 146

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_sString

Returns String representation for the argument.

Returns:

  • (String)

    String representation for the argument.



109
110
111
# File 'lib/clive/argument.rb', line 109

def to_s
  (optional? ? "[<#@name>]" : "<#@name>") + (infinite? ? '...' : '')
end