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.
464 465 466 |
# File 'lib/toys/flag.rb', line 464 def acceptor @acceptor end |
#default ⇒ Object (readonly)
Returns the default value, which may be nil
.
470 471 472 |
# File 'lib/toys/flag.rb', line 470 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.
487 488 489 |
# File 'lib/toys/flag.rb', line 487 def desc @desc end |
#display_name ⇒ String (readonly)
The display name of this flag.
564 565 566 |
# File 'lib/toys/flag.rb', line 564 def display_name @display_name end |
#flag_completion ⇒ Proc, Toys::Completion::Base (readonly)
The proc that determines shell completions for the flag.
518 519 520 |
# File 'lib/toys/flag.rb', line 518 def flag_completion @flag_completion end |
#flag_syntax ⇒ Array<Toys::Flag::Syntax> (readonly)
Returns an array of Flag::Syntax for the flags.
458 459 460 |
# File 'lib/toys/flag.rb', line 458 def flag_syntax @flag_syntax end |
#flag_type ⇒ :boolean, :value (readonly)
The type of flag.
532 533 534 |
# File 'lib/toys/flag.rb', line 532 def flag_type @flag_type end |
#group ⇒ Toys::FlagGroup (readonly)
Returns the flag group containing this flag
446 447 448 |
# File 'lib/toys/flag.rb', line 446 def group @group end |
#handler ⇒ Proc (readonly)
The handler for setting/updating the value.
512 513 514 |
# File 'lib/toys/flag.rb', line 512 def handler @handler end |
#key ⇒ Symbol (readonly)
Returns the key.
452 453 454 |
# File 'lib/toys/flag.rb', line 452 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.
506 507 508 |
# File 'lib/toys/flag.rb', line 506 def long_desc @long_desc end |
#sort_str ⇒ String (readonly)
A string that can be used to sort this flag
570 571 572 |
# File 'lib/toys/flag.rb', line 570 def sort_str @sort_str end |
#value_completion ⇒ Proc, Toys::Completion::Base (readonly)
The proc that determines shell completions for the value.
524 525 526 |
# File 'lib/toys/flag.rb', line 524 def value_completion @value_completion end |
#value_delim ⇒ String? (readonly)
The value delimiter, which may be ""
, " "
, or "="
.
558 559 560 |
# File 'lib/toys/flag.rb', line 558 def value_delim @value_delim end |
#value_label ⇒ String? (readonly)
The string label for the value as it should display in help.
550 551 552 |
# File 'lib/toys/flag.rb', line 550 def value_label @value_label end |
#value_type ⇒ :required, ... (readonly)
The type of value.
543 544 545 |
# File 'lib/toys/flag.rb', line 543 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.
434 435 436 437 438 439 440 |
# File 'lib/toys/flag.rb', line 434 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.
634 635 636 |
# File 'lib/toys/flag.rb', line 634 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.
669 670 671 672 |
# File 'lib/toys/flag.rb', line 669 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.
625 626 627 |
# File 'lib/toys/flag.rb', line 625 def canonical_syntax_strings @canonical_syntax_strings ||= flag_syntax.map(&:canonical_str) end |
#effective_flags ⇒ Array<String>
The list of all effective flags used.
592 593 594 |
# File 'lib/toys/flag.rb', line 592 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.
584 585 586 |
# File 'lib/toys/flag.rb', line 584 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.
604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 |
# File 'lib/toys/flag.rb', line 604 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.
576 577 578 |
# File 'lib/toys/flag.rb', line 576 def short_flag_syntax @short_flag_syntax ||= flag_syntax.find_all { |ss| ss.flag_style == :short } end |