Class: Toys::Flag
- Inherits:
-
Object
- Object
- Toys::Flag
- Defined in:
- lib/toys/flag.rb
Overview
Representation of a formal set of flags that set a particular context key. The flags within a single Flag definition are synonyms.
Defined Under Namespace
Classes: DefaultCompletion, Resolution, Syntax
Constant Summary collapse
- SET_HANDLER =
The set handler replaces the previous value.
->(val, _prev) { val }
- PUSH_HANDLER =
The push handler pushes the given value using the
<<
operator. ->(val, prev) { prev.nil? ? [val] : prev << val }
- DEFAULT_HANDLER =
The default handler is the set handler, replacing the previous value.
SET_HANDLER
Instance Attribute Summary collapse
-
#acceptor ⇒ Toys::Acceptor::Base
readonly
Returns the effective acceptor.
-
#default ⇒ Object
readonly
Returns the default value, which may be
nil
. -
#desc ⇒ Toys::WrappableString
The short description string.
-
#display_name ⇒ String
readonly
The display name of this flag.
-
#flag_completion ⇒ Proc, Toys::Completion::Base
readonly
The proc that determines shell completions for the flag.
-
#flag_syntax ⇒ Array<Toys::Flag::Syntax>
readonly
Returns an array of Flag::Syntax for the flags.
-
#flag_type ⇒ :boolean, :value
readonly
The type of flag.
-
#group ⇒ Toys::FlagGroup
readonly
Returns the flag group containing this flag.
-
#handler ⇒ Proc
readonly
The handler for setting/updating the value.
-
#key ⇒ Symbol
readonly
Returns the key.
-
#long_desc ⇒ Array<Toys::WrappableString>
The long description strings.
-
#sort_str ⇒ String
readonly
A string that can be used to sort this flag.
-
#value_completion ⇒ Proc, Toys::Completion::Base
readonly
The proc that determines shell completions for the value.
-
#value_delim ⇒ String?
readonly
The value delimiter, which may be
""
," "
, or"="
. -
#value_label ⇒ String?
readonly
The string label for the value as it should display in help.
-
#value_type ⇒ :required, ...
readonly
The type of value.
Class Method Summary collapse
-
.create(key, flags = [], used_flags: nil, report_collisions: true, accept: nil, handler: nil, default: nil, complete_flags: nil, complete_values: nil, display_name: nil, desc: nil, long_desc: nil, group: nil) ⇒ Object
Create a flag definition.
Instance Method Summary collapse
-
#active? ⇒ Boolean
Whether this flag is active--that is, it has a nonempty flags list.
-
#append_long_desc(long_desc) ⇒ self
Append long description strings.
-
#canonical_syntax_strings ⇒ Array<String>
A list of canonical flag syntax strings.
-
#effective_flags ⇒ Array<String>
The list of all effective flags used.
-
#long_flag_syntax ⇒ Array<Flag::Syntax>
An array of Flag::Syntax including only long (double-dash) flags.
-
#resolve(str) ⇒ Toys::Flag::Resolution
Look up the flag by string.
-
#short_flag_syntax ⇒ Array<Flag::Syntax>
An array of Flag::Syntax including only short (single dash) flags.
Instance Attribute Details
#acceptor ⇒ Toys::Acceptor::Base (readonly)
Returns the effective acceptor.
127 128 129 |
# File 'lib/toys/flag.rb', line 127 def acceptor @acceptor end |
#default ⇒ Object (readonly)
Returns the default value, which may be nil
.
133 134 135 |
# File 'lib/toys/flag.rb', line 133 def default @default end |
#desc ⇒ Toys::WrappableString
The short description string.
When reading, this is always returned as a WrappableString.
When setting, the description may be provided as any of the following:
- A WrappableString.
- A normal String, which will be transformed into a WrappableString using spaces as word delimiters.
- An Array of String, which will be transformed into a WrappableString where each array element represents an individual word for wrapping.
150 151 152 |
# File 'lib/toys/flag.rb', line 150 def desc @desc end |
#display_name ⇒ String (readonly)
The display name of this flag.
227 228 229 |
# File 'lib/toys/flag.rb', line 227 def display_name @display_name end |
#flag_completion ⇒ Proc, Toys::Completion::Base (readonly)
The proc that determines shell completions for the flag.
181 182 183 |
# File 'lib/toys/flag.rb', line 181 def flag_completion @flag_completion end |
#flag_syntax ⇒ Array<Toys::Flag::Syntax> (readonly)
Returns an array of Flag::Syntax for the flags.
121 122 123 |
# File 'lib/toys/flag.rb', line 121 def flag_syntax @flag_syntax end |
#flag_type ⇒ :boolean, :value (readonly)
The type of flag.
195 196 197 |
# File 'lib/toys/flag.rb', line 195 def flag_type @flag_type end |
#group ⇒ Toys::FlagGroup (readonly)
Returns the flag group containing this flag
109 110 111 |
# File 'lib/toys/flag.rb', line 109 def group @group end |
#handler ⇒ Proc (readonly)
The handler for setting/updating the value.
175 176 177 |
# File 'lib/toys/flag.rb', line 175 def handler @handler end |
#key ⇒ Symbol (readonly)
Returns the key.
115 116 117 |
# File 'lib/toys/flag.rb', line 115 def key @key end |
#long_desc ⇒ Array<Toys::WrappableString>
The long description strings.
When reading, this is returned as an Array of WrappableString representing the lines in the description.
When setting, the description must be provided as an Array where each element may be any of the following:
- A WrappableString representing one line.
- A normal String representing a line. This will be transformed into a WrappableString using spaces as word delimiters.
- An Array of String representing a line. This will be transformed into a WrappableString where each array element represents an individual word for wrapping.
169 170 171 |
# File 'lib/toys/flag.rb', line 169 def long_desc @long_desc end |
#sort_str ⇒ String (readonly)
A string that can be used to sort this flag
233 234 235 |
# File 'lib/toys/flag.rb', line 233 def sort_str @sort_str end |
#value_completion ⇒ Proc, Toys::Completion::Base (readonly)
The proc that determines shell completions for the value.
187 188 189 |
# File 'lib/toys/flag.rb', line 187 def value_completion @value_completion end |
#value_delim ⇒ String? (readonly)
The value delimiter, which may be ""
, " "
, or "="
.
221 222 223 |
# File 'lib/toys/flag.rb', line 221 def value_delim @value_delim end |
#value_label ⇒ String? (readonly)
The string label for the value as it should display in help.
213 214 215 |
# File 'lib/toys/flag.rb', line 213 def value_label @value_label end |
#value_type ⇒ :required, ... (readonly)
The type of value.
206 207 208 |
# File 'lib/toys/flag.rb', line 206 def value_type @value_type end |
Class Method Details
.create(key, flags = [], used_flags: nil, report_collisions: true, accept: nil, handler: nil, default: nil, complete_flags: nil, complete_values: nil, display_name: nil, desc: nil, long_desc: nil, group: nil) ⇒ Object
Create a flag definition.
97 98 99 100 101 102 103 |
# File 'lib/toys/flag.rb', line 97 def self.create(key, flags = [], used_flags: nil, report_collisions: true, accept: nil, handler: nil, default: nil, complete_flags: nil, complete_values: nil, display_name: nil, desc: nil, long_desc: nil, group: nil) new(key, flags, used_flags, report_collisions, accept, handler, default, complete_flags, complete_values, desc, long_desc, display_name, group) end |
Instance Method Details
#active? ⇒ Boolean
Whether this flag is active--that is, it has a nonempty flags list.
297 298 299 |
# File 'lib/toys/flag.rb', line 297 def active? !effective_flags.empty? end |
#append_long_desc(long_desc) ⇒ self
Append long description strings.
You must pass an array of lines in the long description. See #long_desc for details on how each line may be represented.
332 333 334 335 |
# File 'lib/toys/flag.rb', line 332 def append_long_desc(long_desc) @long_desc.concat(WrappableString.make_array(long_desc)) self end |
#canonical_syntax_strings ⇒ Array<String>
A list of canonical flag syntax strings.
288 289 290 |
# File 'lib/toys/flag.rb', line 288 def canonical_syntax_strings @canonical_syntax_strings ||= flag_syntax.map(&:canonical_str) end |
#effective_flags ⇒ Array<String>
The list of all effective flags used.
255 256 257 |
# File 'lib/toys/flag.rb', line 255 def effective_flags @effective_flags ||= flag_syntax.flat_map(&:flags) end |
#long_flag_syntax ⇒ Array<Flag::Syntax>
An array of Flag::Syntax including only long (double-dash) flags.
247 248 249 |
# File 'lib/toys/flag.rb', line 247 def long_flag_syntax @long_flag_syntax ||= flag_syntax.find_all { |ss| ss.flag_style == :long } end |
#resolve(str) ⇒ Toys::Flag::Resolution
Look up the flag by string. Returns an object that indicates whether the given string matched this flag, whether the match was unique, and other pertinent information.
267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 |
# File 'lib/toys/flag.rb', line 267 def resolve(str) resolution = Resolution.new(str) flag_syntax.each do |fs| if fs.positive_flag == str resolution.add!(self, fs, false, true) elsif fs.negative_flag == str resolution.add!(self, fs, true, true) elsif fs.positive_flag.start_with?(str) resolution.add!(self, fs, false, false) elsif fs.negative_flag.to_s.start_with?(str) resolution.add!(self, fs, true, false) end end resolution end |
#short_flag_syntax ⇒ Array<Flag::Syntax>
An array of Flag::Syntax including only short (single dash) flags.
239 240 241 |
# File 'lib/toys/flag.rb', line 239 def short_flag_syntax @short_flag_syntax ||= flag_syntax.find_all { |ss| ss.flag_style == :short } end |