Class: Toys::Flag
- Inherits:
-
Object
- Object
- Toys::Flag
- Defined in:
- toys-core/lib/toys/flag.rb
Overview
Defined in the toys-core gem
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.
129 130 131 |
# File 'toys-core/lib/toys/flag.rb', line 129 def acceptor @acceptor end |
#default ⇒ Object (readonly)
Returns the default value, which may be nil
.
135 136 137 |
# File 'toys-core/lib/toys/flag.rb', line 135 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.
152 153 154 |
# File 'toys-core/lib/toys/flag.rb', line 152 def desc @desc end |
#display_name ⇒ String (readonly)
The display name of this flag.
229 230 231 |
# File 'toys-core/lib/toys/flag.rb', line 229 def display_name @display_name end |
#flag_completion ⇒ Proc, Toys::Completion::Base (readonly)
The proc that determines shell completions for the flag.
183 184 185 |
# File 'toys-core/lib/toys/flag.rb', line 183 def flag_completion @flag_completion end |
#flag_syntax ⇒ Array<Toys::Flag::Syntax> (readonly)
Returns an array of Flag::Syntax for the flags.
123 124 125 |
# File 'toys-core/lib/toys/flag.rb', line 123 def flag_syntax @flag_syntax end |
#flag_type ⇒ :boolean, :value (readonly)
The type of flag.
197 198 199 |
# File 'toys-core/lib/toys/flag.rb', line 197 def flag_type @flag_type end |
#group ⇒ Toys::FlagGroup (readonly)
Returns the flag group containing this flag
111 112 113 |
# File 'toys-core/lib/toys/flag.rb', line 111 def group @group end |
#handler ⇒ Proc (readonly)
The handler for setting/updating the value.
177 178 179 |
# File 'toys-core/lib/toys/flag.rb', line 177 def handler @handler end |
#key ⇒ Symbol (readonly)
Returns the key.
117 118 119 |
# File 'toys-core/lib/toys/flag.rb', line 117 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.
171 172 173 |
# File 'toys-core/lib/toys/flag.rb', line 171 def long_desc @long_desc end |
#sort_str ⇒ String (readonly)
A string that can be used to sort this flag
235 236 237 |
# File 'toys-core/lib/toys/flag.rb', line 235 def sort_str @sort_str end |
#value_completion ⇒ Proc, Toys::Completion::Base (readonly)
The proc that determines shell completions for the value.
189 190 191 |
# File 'toys-core/lib/toys/flag.rb', line 189 def value_completion @value_completion end |
#value_delim ⇒ String? (readonly)
The value delimiter, which may be ""
, " "
, or "="
.
223 224 225 |
# File 'toys-core/lib/toys/flag.rb', line 223 def value_delim @value_delim end |
#value_label ⇒ String? (readonly)
The string label for the value as it should display in help.
215 216 217 |
# File 'toys-core/lib/toys/flag.rb', line 215 def value_label @value_label end |
#value_type ⇒ :required, ... (readonly)
The type of value.
208 209 210 |
# File 'toys-core/lib/toys/flag.rb', line 208 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.
99 100 101 102 103 104 105 |
# File 'toys-core/lib/toys/flag.rb', line 99 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.
299 300 301 |
# File 'toys-core/lib/toys/flag.rb', line 299 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.
334 335 336 337 |
# File 'toys-core/lib/toys/flag.rb', line 334 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.
290 291 292 |
# File 'toys-core/lib/toys/flag.rb', line 290 def canonical_syntax_strings @canonical_syntax_strings ||= flag_syntax.map(&:canonical_str) end |
#effective_flags ⇒ Array<String>
The list of all effective flags used.
257 258 259 |
# File 'toys-core/lib/toys/flag.rb', line 257 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.
249 250 251 |
# File 'toys-core/lib/toys/flag.rb', line 249 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.
269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 |
# File 'toys-core/lib/toys/flag.rb', line 269 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.
241 242 243 |
# File 'toys-core/lib/toys/flag.rb', line 241 def short_flag_syntax @short_flag_syntax ||= flag_syntax.find_all { |ss| ss.flag_style == :short } end |