Class: Toys::Flag

Inherits:
Object
  • Object
show all
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.

Returns:

  • (Proc) 
proc { |val| val }
PUSH_HANDLER =

The push handler appends the given value, returning a new array. The previous array is not modified, so a shared or frozen default array can be used safely.

Returns:

  • (Proc) 
proc { |val, prev| prev.nil? ? [val] : prev + [val] }
DEFAULT_HANDLER =

The default handler is the set handler, which replaces the previous value.

Returns:

  • (Proc) 
SET_HANDLER

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#acceptor ⇒ Toys::Acceptor::Base (readonly)

Returns the effective acceptor.

Returns:



472
473
474
 
# File 'lib/toys/flag.rb', line 472

def acceptor
  @acceptor
end

#default ⇒ Object (readonly)

Returns the default value, which may be nil.

Returns:

  • (Object) 


478
479
480
 
# File 'lib/toys/flag.rb', line 478

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.

Returns:



495
496
497
 
# File 'lib/toys/flag.rb', line 495

def desc
  @desc
end

#display_name ⇒ String (readonly)

The display name of this flag.

Returns:

  • (String) 


572
573
574
 
# File 'lib/toys/flag.rb', line 572

def display_name
  @display_name
end

#flag_completion ⇒ Proc, Toys::Completion::Base (readonly)

The proc that determines shell completions for the flag.

Returns:



526
527
528
 
# File 'lib/toys/flag.rb', line 526

def flag_completion
  @flag_completion
end

#flag_syntax ⇒ Array<Toys::Flag::Syntax> (readonly)

Returns an array of Flag::Syntax for the flags.

Returns:



466
467
468
 
# File 'lib/toys/flag.rb', line 466

def flag_syntax
  @flag_syntax
end

#flag_type ⇒ :boolean, :value (readonly)

The type of flag.

Returns:

  • (:boolean) —

    if the flag is a simple boolean switch

  • (:value) —

    if the flag sets a value



540
541
542
 
# File 'lib/toys/flag.rb', line 540

def flag_type
  @flag_type
end

#group ⇒ Toys::FlagGroup (readonly)

Returns the flag group containing this flag

Returns:



454
455
456
 
# File 'lib/toys/flag.rb', line 454

def group
  @group
end

#handler ⇒ Proc (readonly)

The handler for setting/updating the value.

Returns:

  • (Proc) 


520
521
522
 
# File 'lib/toys/flag.rb', line 520

def handler
  @handler
end

#key ⇒ Symbol (readonly)

Returns the key.

Returns:

  • (Symbol) 


460
461
462
 
# File 'lib/toys/flag.rb', line 460

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.

Returns:



514
515
516
 
# File 'lib/toys/flag.rb', line 514

def long_desc
  @long_desc
end

#sort_str ⇒ String (readonly)

A string that can be used to sort this flag

Returns:

  • (String) 


578
579
580
 
# File 'lib/toys/flag.rb', line 578

def sort_str
  @sort_str
end

#value_completion ⇒ Proc, Toys::Completion::Base (readonly)

The proc that determines shell completions for the value.

Returns:



532
533
534
 
# File 'lib/toys/flag.rb', line 532

def value_completion
  @value_completion
end

#value_delim ⇒ String? (readonly)

The value delimiter, which may be "", " ", or "=".

Returns:

  • (String) —

    The delimiter

  • (nil) —

    if the flag type is not :value.



566
567
568
 
# File 'lib/toys/flag.rb', line 566

def value_delim
  @value_delim
end

#value_label ⇒ String? (readonly)

The string label for the value as it should display in help.

Returns:

  • (String) —

    The label

  • (nil) —

    if the flag type is not :value.



558
559
560
 
# File 'lib/toys/flag.rb', line 558

def value_label
  @value_label
end

#value_type ⇒ :required, ... (readonly)

The type of value.

Returns:

  • (:required) —

    if the flag type is :value and the value is required.

  • (:optional) —

    if the flag type is :value and the value is optional.

  • (nil) —

    if the flag type is not :value.



551
552
553
 
# File 'lib/toys/flag.rb', line 551

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.

Parameters:

  • key (String, Symbol) —

    The key to use to retrieve the value from the execution context.

  • flags (Array<String>) (defaults to: []) —

    The flags in OptionParser format. If empty, a flag will be inferred from the key.

  • accept (Object) (defaults to: nil) —

    An acceptor that validates and/or converts the value. See Acceptor.create for recognized formats. Optional. If not specified, defaults to Acceptor::DEFAULT.

  • default (Object) (defaults to: nil) —

    The default value. This is the value that will be set in the context if this flag is not provided on the command line. Defaults to nil.

  • handler (Proc, nil, :set, :push, :append) (defaults to: nil) —

    An optional handler that customizes how a value is set or updated when the flag is parsed. A handler is a proc that takes up to three arguments: the given value, the previous value, and a hash containing all the data collected so far during argument parsing. The proc must return the new value for the flag. You may also specify a predefined named handler. The :set handler (the default) replaces the previous value (effectively -> (val) { val }). The :push handler expects the previous value to be an array and pushes the given value onto it; it should be combined with setting default: [] and is intended for "multi-valued" flags. :append is an alias for :push.

  • complete_flags (Object) (defaults to: nil) —

    A specifier for shell tab completion for flag names associated with this flag. By default, a DefaultCompletion is used, which provides the flag's names as completion candidates. To customize completion, set this to a hash of options to pass to the constructor for DefaultCompletion, or pass any other spec recognized by Completion.create.

  • complete_values (Object) (defaults to: nil) —

    A specifier for shell tab completion for flag values associated with this flag. Pass any spec recognized by Completion.create.

  • report_collisions (boolean) (defaults to: true) —

    Raise an exception if a flag is requested that is already in use or marked as disabled. Default is true.

  • group (Toys::FlagGroup) (defaults to: nil) —

    Group containing this flag.

  • desc (String, Array<String>, Toys::WrappableString) (defaults to: nil) —

    Short description for the flag. See ToolDefinition#desc for a description of allowed formats. Defaults to the empty string.

  • long_desc (Array<String,Array<String>,Toys::WrappableString>) (defaults to: nil) —

    Long description for the flag. See ToolDefinition#long_desc for a description of allowed formats. Defaults to the empty array.

  • display_name (String) (defaults to: nil) —

    A display name for this flag, used in help text and error messages.

  • used_flags (Array<String>) (defaults to: nil) —

    An array of flags already in use.



442
443
444
445
446
447
448
 
# File 'lib/toys/flag.rb', line 442

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.

Returns:

  • (boolean) 


642
643
644
 
# File 'lib/toys/flag.rb', line 642

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.

Parameters:

Returns:

  • (self) 


677
678
679
680
 
# File 'lib/toys/flag.rb', line 677

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.

Returns:

  • (Array<String>) 


633
634
635
 
# File 'lib/toys/flag.rb', line 633

def canonical_syntax_strings
  @canonical_syntax_strings ||= flag_syntax.map(&:canonical_str)
end

#effective_flags ⇒ Array<String>

The list of all effective flags used.

Returns:

  • (Array<String>) 


600
601
602
 
# File 'lib/toys/flag.rb', line 600

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.

Returns:



592
593
594
 
# File 'lib/toys/flag.rb', line 592

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.

Parameters:

  • str (String) —

    Flag string to look up

Returns:



612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
 
# File 'lib/toys/flag.rb', line 612

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.

Returns:



584
585
586
 
# File 'lib/toys/flag.rb', line 584

def short_flag_syntax
  @short_flag_syntax ||= flag_syntax.find_all { |ss| ss.flag_style == :short }
end