class Samovar::Command

Represents a command in the command-line interface.

Commands are the main building blocks of Samovar applications. Each command is a class that can parse command-line arguments, options, and sub-commands.

Attributes

description [RW]

A description of the command’s purpose.

@attribute [String]

name [R]

The name of the command.

@attribute [String]

output [R]

The output stream for usage information.

@attribute [IO]

parent [R]

The parent command, if this is a nested command.

@attribute [Command | Nil]

Public Class Methods

[] (*input, **options)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/command.rb, line 59
def self.[](*input, **options)
        self.new(input, **options)
end

Create a new command instance with the given arguments.

This is a convenience method for creating command instances with explicit arguments.

@parameter input [Array(String)] The command-line arguments to parse. @parameter options [Hash] Additional options to pass to the command. @returns [Command] The command instance.

append (row)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/command.rb, line 80
def self.append(row)
        if method_defined?(row.key, false)
                raise ArgumentError, "Method for key #{row.key} is already defined!"
        end
        
        attr_accessor(row.key) if row.respond_to?(:key)
        
        self.table << row
end

Append a row to the parsing table.

@parameter row The row to append to the table.

call (input = ARGV, output: $stderr)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/command.rb, line 30
def self.call(input = ARGV, output: $stderr)
        self.parse(input).call
rescue Error => error
        error.command.print_usage(output: output) do |formatter|
                formatter.map(error)
        end
        
        return nil
end

Parse and execute the command with the given input.

This is the high-level entry point for CLI applications. It handles errors gracefully by printing usage and returning nil.

@parameter input [Array(String)] The command-line arguments to parse. @parameter output [IO] The output stream for error messages. @returns [Object | Nil] The result of the command’s call method, or nil if parsing/execution failed.

command_line (name)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/command.rb, line 153
def self.command_line(name)
        table = self.table.merged
        
        return "#{name} #{table.usage}"
end

Generate a command-line usage string.

@parameter name [String] The name of the command. @returns [String] The command-line usage string.

many (*arguments, **options)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/command.rb, line 119
def self.many(*arguments, **options)
        append Many.new(*arguments, **options)
end

Define multiple positional arguments.

@parameter arguments [Array] The arguments for the positional parameters. @parameter options [Hash] Additional options.

nested (*arguments, **options)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/command.rb, line 103
def self.nested(*arguments, **options)
        append Nested.new(*arguments, **options)
end

Define a nested sub-command.

@parameter arguments [Array] The arguments for the nested command. @parameter options [Hash] A hash mapping command names to command classes.

new (input = nil, name: File.basename($0), parent: nil, output: nil)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/command.rb, line 165
def initialize(input = nil, name: File.basename($0), parent: nil, output: nil)
        @name = name
        @parent = parent
        @output = output
        
        parse(input) if input
end

Initialize a new command instance.

@parameter input [Array(String) | Nil] The command-line arguments to parse. @parameter name [String] The name of the command (defaults to the script name). @parameter parent [Command | Nil] The parent command, if this is a nested command. @parameter output [IO | Nil] The output stream for usage information.

one (*arguments, **options)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/command.rb, line 111
def self.one(*arguments, **options)
        append One.new(*arguments, **options)
end

Define a single required positional argument.

@parameter arguments [Array] The arguments for the positional parameter. @parameter options [Hash] Additional options.

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

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/command.rb, line 95
def self.options(*arguments, **options, &block)
        append Options.parse(*arguments, **options, &block)
end

Define command-line options for this command.

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

parse (input)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/command.rb, line 48
def self.parse(input)
        self.new(input)
end

Parse the command-line input and create a command instance.

This is the low-level parsing primitive. It raises {Error} exceptions on parsing failures. For CLI applications, use {call} instead which handles errors gracefully.

@parameter input [Array(String)] The command-line arguments to parse. @returns [Command] The parsed command instance. @raises [Error] If parsing fails.

split (*arguments, **options)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/command.rb, line 127
def self.split(*arguments, **options)
        append Split.new(*arguments, **options)
end

Define a split point in the argument list (typically ‘–`).

@parameter arguments [Array] The arguments for the split. @parameter options [Hash] Additional options.

table ()

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/command.rb, line 73
def self.table
        @table ||= Table.nested(self)
end

The table of rows for parsing command-line arguments.

@returns [Table] The table of parsing rows.

usage (rows, name)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/command.rb, line 135
def self.usage(rows, name)
        rows.nested(name, self) do |rows|
                return unless table = self.table.merged
                
                table.each do |row|
                        if row.respond_to?(:usage)
                                row.usage(rows)
                        else
                                rows << row
                        end
                end
        end
end

Generate usage information for this command.

@parameter rows [Output::Rows] The rows to append usage information to. @parameter name [String] The name of the command.

Public Instance Methods

[] (*input)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/command.rb, line 206
def [](*input)
        self.dup.tap{|command| command.parse(input)}
end

Duplicate the command with additional arguments.

@parameter input [Array(String)] The additional command-line arguments to parse. @returns [Command] The duplicated command instance.

parse (input)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/command.rb, line 214
def parse(input)
        self.class.table.merged.parse(input, self)
        
        if input.empty?
                return self
        else
                raise InvalidInputError.new(self, input)
        end
end

Parse the command-line input.

@parameter input [Array(String)] The command-line arguments to parse. @returns [Command] The command instance.

print_usage (output: self.output, formatter: Output::UsageFormatter, &block)

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/command.rb, line 229
def print_usage(output: self.output, formatter: Output::UsageFormatter, &block)
        rows = Output::Rows.new
        
        self.class.usage(rows, @name)
        
        formatter.print(rows, output, &block)
end

Print usage information for this command.

@parameter output [IO] The output stream to print to. @parameter formatter [Class] The formatter class to use for output. @yields {|formatter| …} A block to customize the output.

to_s ()

Source

# File vendor/bundle/ruby/3.4.0/gems/samovar-2.4.1/lib/samovar/command.rb, line 188
def to_s
        self.class.name
end

Generate a string representation of the command.

@returns [String] The class name.