Class: Clive::Option

Inherits:
Object
  • Object
show all
Extended by:
Type::Lookup
Includes:
Comparable
Defined in:
lib/clive/option.rb,
lib/clive/option/runner.rb

Overview

An option saves a value to the state or triggers a block if given when used. They can have a long, --opt, and/or short, -o and can take arguments which can be constricted by passing various parameters.

class CLI < Clive
  VERSION = '0.0.1'

  desc 'Name of the person'
  opt :name, arg: '<first> [<middle>] <last>'

  opt :v, :version do
    puts CLI::VERSION
  end
end

You can also have boolean options, created with the bool or boolean method which are simply Options with :boolean set to true. You can pass the option name as normal to set them to true or prepend --no- to the name to set them to false.

class CLI
  bool :auto, 'Auto regenerate person on change'
end

Direct Known Subclasses

Command

Defined Under Namespace

Classes: InvalidNamesError, Runner

Constant Summary collapse

DEFAULTS =

Default values to use for config. These are also the config options that an Option takes, see #initialize for details.

{
  :boolean => false,
  :group   => nil,
  :head    => false,
  :tail    => false,
  :runner  => Clive::Option::Runner
}

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(names = [], description = "", config = {}, &block) ⇒ Option

Returns a new instance of Option.

Examples:


Option.new(
  [:N, :new],
  "Add a new thing",
  {:args => "<dir> [<size>]", :matches => [/^\//], :types => [nil, Integer]}
)

Parameters:

  • names (Array<Symbol>) (defaults to: []) —

    Names for this option

  • description (String) (defaults to: "") —

    Description of the option.

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

Options Hash (config):

  • :head (true, false) —

    If option should be at top of help list

  • :tail (true, false) —

    If option should be at bottom of help list

  • :args (String) —

    Arguments that the option takes. See Argument.

  • :as (Type, Array[Type]) —

    The class the argument(s) should be cast to. See Type.

  • :match (#match, Array[#match]) —

    Regular expression that the argument(s) must match

  • :in (#include?, Array[#include?]) —

    Collection that argument(s) must be in

  • :default (Object) —

    Default value that is used if argument is not given

  • :group (Object) —

    Name of the group this option belongs to



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

def initialize(names=[], description="", config={}, &block)
  @names = names.sort_by {|i| i.to_s.size }

  # @return [Symbol, nil] Short name from the names (ie. +:a+)
  def @names.short
    find {|i| i.to_s.size == 1 }
  end

  # @return [Symbol, nil] Long name from the names (ie. +:abc+)
  def @names.long
    find {|i| i.to_s.size > 1 }
  end

  @description  = description
  @block = block

  @args = Arguments.create( get_subhash(config, Arguments::Parser::KEYS.keys) )
  @config = DEFAULTS.merge( get_subhash(config, DEFAULTS.keys) || {} )
end

Instance Attribute Details

#args ⇒ Arguments (readonly)

Returns List of arguments this Option can take when ran.

Returns:

  • (Arguments) —

    List of arguments this Option can take when ran



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

def args
  @args
end

#config ⇒ Hash{Symbol=>Object} (readonly)

Returns Config options passed to #initialize using defaults when not given.

Returns:

  • (Hash{Symbol=>Object}) —

    Config options passed to #initialize using defaults when not given



39
40
41
 
# File 'lib/clive/option.rb', line 39

def config
  @config
end

#description ⇒ String (readonly)

Returns Description of the Option.

Returns:

  • (String) —

    Description of the Option



43
44
45
 
# File 'lib/clive/option.rb', line 43

def description
  @description
end

#names ⇒ Array<Symbol> (readonly)

Returns List of names this Option can be called.

Returns:

  • (Array<Symbol>) —

    List of names this Option can be called



36
37
38
 
# File 'lib/clive/option.rb', line 36

def names
  @names
end

Class Method Details

.long ⇒ Symbol?

Returns Long name from the names (ie. :abc).

Returns:

  • (Symbol, nil) —

    Long name from the names (ie. :abc)



96
97
98
 
# File 'lib/clive/option.rb', line 96

def @names.long
  find {|i| i.to_s.size > 1 }
end

.short ⇒ Symbol?

Returns Short name from the names (ie. :a).

Returns:

  • (Symbol, nil) —

    Short name from the names (ie. :a)



91
92
93
 
# File 'lib/clive/option.rb', line 91

def @names.short
  find {|i| i.to_s.size == 1 }
end

Instance Method Details

#<=>(other) ⇒ Integer

Compare based on the size of #name, makes sure tails go to the bottom and heads go to the top. If both are head or tail then sorts based on the names.

Parameters:

  • other (Option) —

    Option to compare with

Returns:

  • (Integer) —

    Either -1, 0 or 1



170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/clive/option.rb', line 170

def <=>(other)
  if (config[:tail] && !other.config[:tail]) ||
      (other.config[:head] && !config[:head])
    1
  elsif (other.config[:tail] && !config[:tail]) ||
      (config[:head] && !other.config[:head])
    -1
  else
    self.name.to_s <=> other.name.to_s
  end
end

#block? ⇒ Boolean

Returns Whether a block was given.

Returns:

  • (Boolean) —

    Whether a block was given.



132
133
134
 
# File 'lib/clive/option.rb', line 132

def block?
  @block != nil
end

#inspect ⇒ String

Returns:



127
128
129
 
# File 'lib/clive/option.rb', line 127

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

#name ⇒ Symbol

Returns The longest name given.

Returns:

  • (Symbol) —

    The longest name given



108
109
110
 
# File 'lib/clive/option.rb', line 108

def name
  @names.long || @names.short
end

#run(state, args = [], scope = nil) ⇒ Hash

Runs the Option’s block with the current state and arguments passed.

Parameters:

  • state (Hash) —

    Local state for parser, this may be modified!

  • args (Array) (defaults to: []) —

    Arguments for the block which is run

  • scope (Command) (defaults to: nil) —

    Scope of the state to use

Returns:

  • (Hash) —

    the state which may have been modified!



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

def run(state, args=[], scope=nil)
  mapped_args = if @config[:boolean] == true
    [[:truth, args.first]]
  else
    @args.zip(args).map {|k,v| [k.name, (k.infinite? ? v.first : v)] }
  end

  if block?
    if scope
      state = @config[:runner]._run(mapped_args, state[scope.name], @block)
    else
      state = @config[:runner]._run(mapped_args, state, @block)
    end
  else
    state = set_state(state, args.flatten(1), scope)
  end

  state
end

#to_s ⇒ String

Returns String representaion of the Option.

Returns:

  • (String) —

    String representaion of the Option



113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/clive/option.rb', line 113

def to_s
  r = ""
  r << "-#{@names.short}" if @names.short
  if @names.long
    r << ", " if @names.short
    r << "--"
    r << "[no-]" if @config[:boolean] == true
    r << @names.long.to_s.gsub('_', '-')
  end

  r
end