Class: ConfigParser::Flag

Inherits:
Object
  • Object
show all
Includes:
Utils
Defined in:
lib/config_parser/flag.rb

Overview

Represents a boolean flag-style option. Flag handles the parsing of specific flags, and provides hooks for processing the various types of options (Switch, Option, List).

Direct Known Subclasses

Option, Switch

Constant Summary

Constants included from Utils

Utils::DELIMITER, Utils::LONG_FLAG, Utils::NEST, Utils::OPTION, Utils::OPTION_BREAK, Utils::SHORT_FLAG, Utils::SWITCH

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Utils

guess_hint, guess_option_type, guess_option_type_by_arg_name, guess_option_type_by_value, longify, next_arg, option?, parse_attrs, prefix_long, shortify, wrap

Constructor Details

#initialize(attrs = {}) ⇒ Flag

Returns a new instance of Flag.



40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/config_parser/flag.rb', line 40

def initialize(attrs={})
  @key       = attrs[:key]
  @nest_keys = attrs[:nest_keys]
  @default   = attrs[:default]
  @short     = shortify(attrs.has_key?(:short) ? attrs[:short] : default_short)
  @long      = longify(attrs.has_key?(:long) ? attrs[:long] : default_long)
  @desc      = attrs[:desc]
  @hint      = attrs[:hint]
  @callback  = attrs[:callback]
  reset
end

Instance Attribute Details

#assigned ⇒ Object (readonly)

A tracking flag set to true when assign is called. Useful when assign works differently for the first assignment than later assignments. See reset.



38
39
40
 
# File 'lib/config_parser/flag.rb', line 38

def assigned
  @assigned
end

#callback ⇒ Object (readonly)

A callback for processing values (must respond to call, or be nil).



33
34
35
 
# File 'lib/config_parser/flag.rb', line 33

def callback
  @callback
end

#default ⇒ Object (readonly)

The default value.



18
19
20
 
# File 'lib/config_parser/flag.rb', line 18

def default
  @default
end

#desc ⇒ Object (readonly)

The description printed by to_s.



27
28
29
 
# File 'lib/config_parser/flag.rb', line 27

def desc
  @desc
end

#hint ⇒ Object (readonly)

A hint printed by to_s, after desc.



30
31
32
 
# File 'lib/config_parser/flag.rb', line 30

def hint
  @hint
end

#key ⇒ Object (readonly)

The config key.



12
13
14
 
# File 'lib/config_parser/flag.rb', line 12

def key
  @key
end

#long ⇒ Object (readonly)

The long flag mapping to self.



24
25
26
 
# File 'lib/config_parser/flag.rb', line 24

def long
  @long
end

#nest_keys ⇒ Object (readonly)

The config nesting keys.



15
16
17
 
# File 'lib/config_parser/flag.rb', line 15

def nest_keys
  @nest_keys
end

#short ⇒ Object (readonly)

The short flag mapping to self.



21
22
23
 
# File 'lib/config_parser/flag.rb', line 21

def short
  @short
end

Instance Method Details

#assign(config, value) ⇒ Object

Assign the value to the config hash, if key is set, and flips assigned to true. Returns config.



120
121
122
123
124
125
126
127
128
 
# File 'lib/config_parser/flag.rb', line 120

def assign(config, value)
  if key
    nest_config = nest(config)
    nest_config[key] = value
  end

  @assigned = true
  config
end

#assign_default(config) ⇒ Object

Assigns the default value into config and resets the assigned flag to false, such that the next assign behaves as if self has not put a value into config. Returns config.



112
113
114
115
116
 
# File 'lib/config_parser/flag.rb', line 112

def assign_default(config)
  assign(config, default)
  reset
  config
end

#flags ⇒ Object

Returns an array of flags mapping to self (ie [long, short]).



53
54
55
 
# File 'lib/config_parser/flag.rb', line 53

def flags
  [long, short].compact
end

#inspect ⇒ Object

Returns an inspect string.



167
168
169
 
# File 'lib/config_parser/flag.rb', line 167

def inspect
  "#<#{self.class}:#{object_id} key=#{key.inspect} default=#{default.inspect} long=#{long.inspect} short=#{short.inspect}>"
end

#nest(config) ⇒ Object

Returns the nested config hash for config, as specified by nest_keys.



131
132
133
134
135
136
137
 
# File 'lib/config_parser/flag.rb', line 131

def nest(config)
  nest_keys.each do |key|
    config = (config[key] ||= {})
  end if nest_keys

  config
end

#parse(flag, value = nil, argv = [], config = {}) ⇒ Object

Parse handles the parsing of flags, which happens in three steps:

  • determine the value (occurs in parse)

  • process the value

  • assign the result into config

Flag uses !default as the value (such that the flag indicates true if the default is false) then passes the value to process, and then assign. Raises and error if provided a value directly (flags always determine their value based on the default).

– Implementation Note

The compact syntax for short flags is handled through parse by unshifting remaining shorts (ie value) back onto argv. This allows shorts that consume a value to take the remainder as needed. As an example to clarify, assume -x -y are flags where -x takes a value and -y does not. These are equivalent:

-x value -y
-xvalue -y
-y -xvalue
-yxvalue

Whereas this is not:

-xyvalue                   # x receives 'yvalue' not 'value'

Parse handles the compact short syntax splitting ‘-yxvalue’ into ‘-y’, ‘xvalue’. Then ‘-y’ determines whether or not it needs a values; if not ‘-xvalue’ gets unshifted to argv and parsing continues as if ‘-y -xvalue’ were the original arguments.



90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/config_parser/flag.rb', line 90

def parse(flag, value=nil, argv=[], config={})
  unless value.nil?
    if flag == short
      argv.unshift "-#{value}"
    else
      raise "value specified for #{flag}: #{value.inspect}"
    end
  end

  value = (default.nil? ? true : !default)
  assign(config, process(value))
end

#process(value) ⇒ Object

Process the value by calling the callback, if specified, with the value and returns the result. Returns value if no callback is specified.



105
106
107
 
# File 'lib/config_parser/flag.rb', line 105

def process(value)
  callback ? callback.call(value) : value
end

#reset ⇒ Object

Resets assigned to false.



140
141
142
 
# File 'lib/config_parser/flag.rb', line 140

def reset
  @assigned = false
end

#to_s(opts = {}) ⇒ Object

Formats self as a help string for use on the command line (deprecated for that use, see format instead).



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

def to_s(opts={})
  width     = opts[:width] || 80
  head_size = opts[:head_size] || (width * 0.45).to_i
  desc_size = width - head_size - 1

  format = "%-#{head_size}s %-#{desc_size}s"

  lines  = wrap(desc_str, desc_size)

  header = header_str
  header = header.length > head_size ? header.ljust(width) : (format % [header, lines.shift])

  if lines.empty?
    header
  else
    lines.collect! {|line| format % [nil, line] }
    "#{header}\n#{lines.join("\n")}"
  end
end