Module: Choice

Extended by:
Choice
Included in:
Choice
Defined in:
lib/choice.rb,
lib/choice/option.rb,
lib/choice/parser.rb,
lib/choice/writer.rb,
lib/choice/version.rb,
lib/choice/lazyhash.rb

Overview

Usage of this module is lovingly detailed in the README file.

Defined Under Namespace

Modules: Parser, Version, Writer Classes: LazyHash, Option

Instance Method Summary collapse

Instance Method Details

#[](choice) ⇒ Object

Shortcut access to Choice.choices



57
58
59
 
# File 'lib/choice.rb', line 57

def [](choice)
  choices[choice]
end

#args ⇒ Object

Return the args.



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

def args #:nodoc:
  @@args
end

#args=(args) ⇒ Object

Set the args, potentially to something other than ARGV.



126
127
128
129
 
# File 'lib/choice.rb', line 126

def args=(args) #:nodoc:
  @@args = args.dup.map { |a| a + '' }
  parse if parsed?
end

#args_of(opt) ⇒ Object

Returns the arguments that follow an argument



137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/choice.rb', line 137

def args_of(opt)
  args_of_opt = []
  
  # Return an array of the arguments between opt and the next option,
  # which all start with "-"
  @@args.slice(@@args.index(opt)+1, @@args.length).select do |arg|
    if arg[0].chr != "-"
      args_of_opt << arg
    else
      break
    end
  end
  args_of_opt
end

#choices ⇒ Object

Returns a hash representing options passed in via the command line.



52
53
54
 
# File 'lib/choice.rb', line 52

def choices
  @@choices
end

#dont_exit_on_help=(val) ⇒ Object

You can choose to not kill the script after the help screen is printed.



153
154
155
 
# File 'lib/choice.rb', line 153

def dont_exit_on_help=(val) #:nodoc:
  @@exit = true
end

#exit_on_help? ⇒ Boolean

Do we want to exit on help?

Returns:

  • (Boolean) 


158
159
160
 
# File 'lib/choice.rb', line 158

def exit_on_help? #:nodoc:
  @@exit rescue false
end

#help ⇒ Object

Print the help screen by calling our Writer object



119
120
121
122
123
 
# File 'lib/choice.rb', line 119

def help #:nodoc:
  Writer.help( { :banner => @@banner, :header => @@header, 
                 :options => @@options, :footer => @@footer }, 
                 output_to, exit_on_help? )
end

#option(opt, options = {}, &block) ⇒ Object

Defines an option.



62
63
64
65
66
 
# File 'lib/choice.rb', line 62

def option(opt, options = {}, &block)
  # Notice: options is maintained as an array of arrays, the first element
  # the option name and the second the option object.
  @@options << [opt.to_s, Option.new(options, &block)]
end

#options(hash = {}, &block) ⇒ Object

The main method, which defines the options



20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/choice.rb', line 20

def options(hash = {}, &block)
  # if we are passing in a hash to define our options, use that straight
  options_from_hash(hash) unless hash.empty?

  # Setup all instance variables
  reset! if hash.empty?
  @@args ||= ARGV
  
  # Eval the passed block to define the options.
  instance_eval(&block) if block_given?

  # Parse what we've got.
  parse unless parsed?
end

#options_from_hash(options_hash) ⇒ Object

Set options from a hash, shorthand style



36
37
38
39
40
41
42
43
44
 
# File 'lib/choice.rb', line 36

def options_from_hash(options_hash)
  options_hash.each do |name, definition|
    option = Option.new
    definition.each do |key, value| 
      Array(value).each { |hit| option.send(key, hit) }
    end
    @@options << [name.to_s, option]
  end
end

#output_to(target = nil) ⇒ Object

If we want to write to somewhere other than STDOUT.



163
164
165
166
167
 
# File 'lib/choice.rb', line 163

def output_to(target = nil) #:nodoc:
  @@output_to ||= STDOUT
  return @@output_to if target.nil?
  @@output_to = target
end

#parse ⇒ Object

Parse the provided args against the defined options.



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/choice.rb', line 93

def parse #:nodoc:
  # Do nothing if options are not defined.
  return unless @@options.size > 0

  # Show help if it's anywhere in the argument list.
  if @@args.include?('--help')
    help
  else
    begin
      # Delegate parsing to our parser class, passing it our defined 
      # options and the passed arguments.
      @@choices, @@rest = Parser.parse(@@options, @@args)
      @@choices = LazyHash.new(@@choices)
    rescue Choice::Parser::ParseError
      # If we get an expected exception, show the help file.
      help
    end
  end
end

#parsed? ⇒ Boolean

Did we already parse the arguments?

Returns:

  • (Boolean) 


114
115
116
 
# File 'lib/choice.rb', line 114

def parsed? #:nodoc:
  @@choices ||= false
end

#reset! ⇒ Object

Reset all the class variables.



170
171
172
173
174
175
176
 
# File 'lib/choice.rb', line 170

def reset! #:nodoc:
  @@args    = false
  @@banner  = false
  @@header  = Array.new
  @@options = Array.new
  @@footer  = Array.new
end

#rest ⇒ Object

Return an array representing the rest of the command line arguments



47
48
49
 
# File 'lib/choice.rb', line 47

def rest
  @@rest
end

#separator(str) ⇒ Object

Separators are text displayed by –help within the options block.



69
70
71
72
73
 
# File 'lib/choice.rb', line 69

def separator(str)
  # We store separators as simple strings in the options array to maintain
  # order.  They are ignored by the parser.
  @@options << str
end