class Samovar::Options

Represents a collection of command-line options.

Options provide a DSL for defining multiple option flags in a single block.

Attributes

defaults [R]

The default values for options.

@attribute [Hash]

key [R]

The key to use for storing parsed options.

@attribute [Symbol]

ordered [R]

The ordered list of options.

@attribute [Array(Option)]

title [R]

The title for this options group in usage output.

@attribute [String]

Public Class Methods

new (title = "Options", key: :options)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/options.rb, line 31
def initialize(title = "Options", key: :options)
        @title = title
        @ordered = []
        
        # We use this flag to option cache to improve parsing performance:
        @keyed = {}
        
        @key = key
        
        @defaults = {}
end

Initialize a new options collection.

@parameter title [String] The title for this options group in usage output. @parameter key [Symbol] The key to use for storing parsed options.

parse (*arguments, **options, &block)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/options.rb, line 19
def self.parse(*arguments, **options, &block)
        options = self.new(*arguments, **options)
        
        options.instance_eval(&block) if block_given?
        
        return options.freeze
end

Parse and create an options collection from a block.

@parameter arguments [Array] The arguments for the options collection. @parameter options [Hash] Additional options. @yields {|…| …} A block that defines options using {#option}. @returns [Options] The frozen options collection.

Public Instance Methods

<< (option)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/options.rb, line 124
def << option
        @ordered << option
        option.flags.each do |flag|
                @keyed[flag.prefix] = option
                
                flag.alternatives.each do |alternative|
                        @keyed[alternative] = option
                end
        end
        
        if default = option.default
                @defaults[option.key] = option.default
        end
end

Add an option to this collection.

@parameter option [Option] The option to add.

each (&block)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/options.rb, line 92
def each(&block)
        @ordered.each(&block)
end

Iterate over each option.

@yields {|option| …} Each option in the collection.

empty? ()

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/options.rb, line 99
def empty?
        @ordered.empty?
end

Check if this options collection is empty.

@returns [Boolean] True if there are no options.

freeze ()

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/options.rb, line 77
def freeze
        return self if frozen?
        
        @ordered.freeze
        @keyed.freeze
        @defaults.freeze
        
        @ordered.each(&:freeze)
        
        super
end

Freeze this options collection.

@returns [Options] The frozen options collection.

Calls superclass method

initialize_dup (source)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/options.rb, line 46
def initialize_dup(source)
        super
        
        @ordered = @ordered.dup
        @keyed = @keyed.dup
        @defaults = @defaults.dup
end

Initialize a duplicate of this options collection.

@parameter source [Options] The source options to duplicate.

Calls superclass method

merge! (options)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/options.rb, line 115
def merge!(options)
        options.each do |option|
                self << option
        end
end

Merge another options collection into this one.

@parameter options [Options] The options to merge.

option (*arguments, **options, &block)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/options.rb, line 108
def option(*arguments, **options, &block)
        self << Option.new(*arguments, **options, &block)
end

Define a new option in this collection.

@parameter arguments [Array] The arguments for the option. @parameter options [Hash] Additional options. @yields {|value| …} An optional block to transform the parsed value.

parse (input, parent = nil, default = nil)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/options.rb, line 145
def parse(input, parent = nil, default = nil)
        values = (default || @defaults).dup
        
        while option = @keyed[input.first]
                # prefix = input.first
                result = option.parse(input)
                if result != nil
                        values[option.key] = result
                end
        end
        
        # Validate required options
        @ordered.each do |option|
                if option.required && !values.key?(option.key)
                        raise MissingValueError.new(parent, option.key)
                end
        end
        
        return values
end

Parse options from the input.

@parameter input [Array(String)] The command-line arguments. @parameter parent [Command | Nil] The parent command. @parameter default [Hash | Nil] Default values to use. @returns [Hash] The parsed option values.

to_s ()

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/options.rb, line 167
def to_s
        @ordered.collect(&:to_s).join(" ")
end

@returns [String] The usage string.

usage (rows)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/options.rb, line 174
def usage(rows)
        @ordered.each do |option|
                rows << option
        end
end

Generate usage information for this options collection.

@parameter rows [Output::Rows] The rows to append usage information to.