class Git::Commands::Arguments::Bound

Bound arguments object returned by {Arguments#bind}

Provides accessor methods for all defined options and positional arguments, with automatic normalization of aliases to their canonical names.

For every ‘flag_option`, both a plain accessor (e.g. `bound.force`) and a `?`-suffixed predicate alias (e.g. `bound.force?`) are generated, following Ruby convention for boolean predicates. Plain accessors are kept for backward compatibility. `value_option` fields only receive plain accessors.

**Reserved-name exception:** if the ‘?`-suffixed name conflicts with a name in {RESERVED_NAMES} (e.g. `nil?`, `frozen?`), the predicate alias is not generated to avoid overriding built-in `Object` methods. Use hash-style access (`bound`) when the flag name is reserved.

@example Accessing bound arguments

args_def = Arguments.define do
  flag_option :force
  flag_option :remotes, as: ['-r', '--remotes']
  operand :branch_names, repeatable: true
end
bound = args_def.bind('branch1', 'branch2', force: true, remotes: true)
bound.force          # => true
bound.force?         # => true   # ? alias for flag_option
bound.remotes        # => true
bound.remotes?       # => true   # ? alias for flag_option
bound.branch_names   # => ['branch1', 'branch2']

@example Splatting for command execution

args_def = Arguments.define do
  flag_option :force
  operand :file
end
bound = args_def.bind('test.txt', force: true)
bound.to_a  # => ['--force', 'test.txt']

@example Hash-style access for reserved names

args_def = Arguments.define do
  value_option :hash
end
bound = args_def.bind(hash: 'abc123')
bound[:hash]  # => 'abc123'

@api private

Constants

EMPTY_EXECUTION_OPTIONS

Canonical frozen empty hash returned by {#execution_options} when no non-nil execution options are present.

@return [Hash{Symbol => Object}] frozen empty execution options hash

RESERVED_NAMES

Names that cannot have accessor methods defined (would override Object methods)

Attributes

execution_options [R]

Execution options and values for command execution.

Includes only options declared via {Arguments#execution_option} and excludes options with nil values.

@return [Hash{Symbol => Object}] frozen hash of execution option values

Public Class Methods

new (args_array, options, positionals, execution_option_names = [], flag_names = [])

Source

# File lib/git/commands/arguments.rb, line 4037
def initialize(args_array, options, positionals, execution_option_names = [], flag_names = [])
  @args_array = args_array.freeze
  @options = options.freeze
  @positionals = positionals.freeze
  @execution_options = build_execution_options(execution_option_names)

  # Define accessor methods (skip reserved names)
  @options.each_key { |name| define_accessor(name, @options) }
  @positionals.each_key { |name| define_accessor(name, @positionals) }
  define_flag_predicate_accessors(flag_names)

  freeze
end

Initialize a new frozen Bound object with accessor methods for all defined arguments

@param args_array [Array<String>] the CLI argument array (frozen)

@param options [Hash{Symbol => Object}] normalized options hash (frozen)

@param positionals [Hash{Symbol => Object}] positional arguments hash (frozen)

@param execution_option_names [Array<Symbol>] option names declared via {Arguments#execution_option}

@param flag_names [Array<Symbol>] option names declared via {Arguments#flag_option}

@option options [Object] :“option_name” bound value for any registered option name

Public Instance Methods

[] (key)

Source

# File lib/git/commands/arguments.rb, line 4082
def [](key)
  return @options[key] if @options.key?(key)
  return @positionals[key] if @positionals.key?(key)

  nil
end

Hash-style access to option and positional values

Use this for reserved names (like :hash, :class) that cannot have accessor methods defined.

@param key [Symbol] the option or positional name

@return [Object, nil] the value, or nil if not found

to_a ()

Source

# File lib/git/commands/arguments.rb, line 4070
def to_a
  @args_array
end

Returns the CLI arguments array for splatting

Ruby’s splat operator in array literals uses ‘to_a` for expansion. This enables: `[’git’, ‘branch’, *bound_args]‘.

Operands declared with ‘skip_cli: true` are intentionally excluded.

@return [Array<String>] the CLI arguments

to_ary ()

Source

# File lib/git/commands/arguments.rb, line 4058
def to_ary
  @args_array
end

Returns the CLI arguments array for splatting

This enables direct splatting: ‘command(*bound_args)`.

Operands declared with ‘skip_cli: true` are intentionally excluded.

@return [Array<String>] the CLI arguments

Private Instance Methods

build_execution_options (execution_option_names)

Source

# File lib/git/commands/arguments.rb, line 4098
def build_execution_options(execution_option_names)
  result = execution_option_names.each_with_object({}) do |name, values|
    value = @options[name]
    values[name] = value unless value.nil?
  end

  result.empty? ? EMPTY_EXECUTION_OPTIONS : result.freeze
end

Build the execution_options hash from the given option names

@param execution_option_names [Array<Symbol>] option names declared as execution options

@return [Hash{Symbol => Object}] frozen hash of non-nil execution option values

@api private

define_accessor (name, source)

Source

# File lib/git/commands/arguments.rb, line 4116
def define_accessor(name, source)
  return if RESERVED_NAMES.include?(name)

  define_singleton_method(name) { source[name] }
end

Define an accessor method for the given name

For ‘flag_option` names, a `?`-suffixed predicate alias is also defined by {#initialize} after all plain accessors have been set up.

@param name [Symbol] the option or positional name

@param source [Hash] the hash to read from (@options or @positionals)

define_flag_predicate_accessors (flag_names)

Source

# File lib/git/commands/arguments.rb, line 4129
def define_flag_predicate_accessors(flag_names)
  flag_names.each do |name|
    predicate_name = :"#{name}?"
    next if RESERVED_NAMES.include?(predicate_name)

    define_singleton_method(predicate_name) { flag_predicate?(@options[name]) }
  end
end

Define ‘?`-suffixed predicate aliases for each flag option

Skips any name whose ‘?` form appears in {RESERVED_NAMES} and skips names that are not present in the options hash.

@param flag_names [Array<Symbol>] flag option names

flag_predicate? (value)

Source

# File lib/git/commands/arguments.rb, line 4145
def flag_predicate?(value)
  return value.positive? if value.is_a?(Integer)

  value == true
end

Return true if a flag value represents a truthy flag state

@param value [Boolean, Integer, nil] the flag value

@return [Boolean] true if the flag value represents an enabled flag

@api private