SamovarSourceSamovarOptions

class Options

Represents a collection of command-line options.

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

Definitions

def self.parse(*arguments, **options, &block)

Parse and create an options collection from a block.

Signature

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.

Implementation

def self.parse(*arguments, **options, &block)
	options = self.new(*arguments, **options)
	
	options.instance_eval(&block) if block_given?
	
	return options.freeze
end

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

Parse options from the input.

Signature

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.

Implementation

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		# Generate a string representation for usage output.

def initialize(title = "Options", key: :options)

Initialize a new options collection.

Signature

parameter title String

The title for this options group in usage output.

parameter key Symbol

The key to use for storing parsed options.

Implementation

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

def initialize_dup(source)

Initialize a duplicate of this options collection.

Signature

parameter source Options

The source options to duplicate.

Implementation

def initialize_dup(source)
	super
	
	@ordered = @ordered.dup
	@keyed = @keyed.dup
	@defaults = @defaults.dup
end

attr :title

The title for this options group in usage output.

Signature

attribute String

attr :ordered

The ordered list of options.

Signature

attribute Array(Option)

attr :key

The key to use for storing parsed options.

Signature

attribute Symbol

attr :defaults

The default values for options.

Signature

attribute Hash

def freeze

Freeze this options collection.

Signature

returns Options

The frozen options collection.

Implementation

def freeze
	return self if frozen?
	
	@ordered.freeze
	@keyed.freeze
	@defaults.freeze
	
	@ordered.each(&:freeze)
	
	super
end

def each(&block)

Iterate over each option.

Signature

yields {|option| ...}

Each option in the collection.

Implementation

def each(&block)
	@ordered.each(&block)
end

def empty?

Check if this options collection is empty.

Signature

returns Boolean

True if there are no options.

Implementation

def empty?
	@ordered.empty?
end

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

Define a new option in this collection.

Signature

parameter arguments Array

The arguments for the option.

parameter options Hash

Additional options.

yields {|value| ...}

An optional block to transform the parsed value.

Implementation

def option(*arguments, **options, &block)
	self << Option.new(*arguments, **options, &block)
end

def merge!(options)

Merge another options collection into this one.

Signature

parameter options Options

The options to merge.

Implementation

def merge!(options)
	options.each do |option|
		self << option
	end
end

def <<(option)

Add an option to this collection.

Signature

parameter option Option

The option to add.

Implementation

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

def to_s

Signature

returns String

The usage string.

Implementation

def to_s
	@ordered.collect(&:to_s).join(" ")
end

def usage(rows)

Generate usage information for this options collection.

Signature

parameter rows Output::Rows

The rows to append usage information to.

Implementation

def usage(rows)
	@ordered.each do |option|
		rows << option
	end
end