Class: Awaaz::Utils::ShellCommandBuilder

Inherits:
Object
  • Object
show all
Defined in:
lib/awaaz/utils/shell_command_builder.rb

Overview

A utility class to construct shell commands in a safe and composable way.

This class supports chaining methods to add arguments, flags, and options, and finally output the full shell command string.

Examples:

Build a simple FFmpeg command

cmd = ShellCommandBuilder.new(:ffmpeg)
         .add_flag("-nostdin")
         .add_option("-i", "input.mp3")
         .add_option("-ar", 44100)
         .command
# => "ffmpeg -nostdin -i input.mp3 -ar 44100"

Instance Method Summary collapse

Constructor Details

#initialize(base = nil) ⇒ ShellCommandBuilder

Initializes a new shell command builder.

Parameters:

  • base (String, Symbol, nil) (defaults to: nil) —

    The base command (e.g., ‘:ffmpeg` or `“ls”`).



25
26
27
 
# File 'lib/awaaz/utils/shell_command_builder.rb', line 25

def initialize(base = nil)
  @args = [base.to_s]
end

Instance Method Details

#add_arg(arg) ⇒ ShellCommandBuilder Also known as: add_flag

Adds a positional argument to the command.

Parameters:

  • arg (String, Symbol, Numeric) —

    The argument to add.

Returns:



35
36
37
38
 
# File 'lib/awaaz/utils/shell_command_builder.rb', line 35

def add_arg(arg)
  @args << arg.to_s.strip
  self
end

#add_multiple_args(args_array) ⇒ ShellCommandBuilder

Adds multiple arguments or options at once.

Examples:

Adding multiple

builder.add_multiple_args([
  [:flag, ["-q"]],
  [:option, ["-i", "file.mp3"]],
  [:arg, ["extra"]]
])

Parameters:

  • args_array (Array<Array>) —

    An array of argument definitions. Each element should be ‘[type, args]` where:

    • ‘type` is `:arg` or `:flag` for positional arguments/flags

    • otherwise, treated as an option for #add_option

Returns:



85
86
87
88
89
90
91
92
 
# File 'lib/awaaz/utils/shell_command_builder.rb', line 85

def add_multiple_args(args_array)
  args_array.each do |shell_args|
    arg_type, args = shell_args
    arg_type = arg_type.to_sym
    i[arg flag].include?(arg_type) ? add_arg(*args) : add_option(*args)
  end
  self
end

#add_option(option, value, with_colon: false) ⇒ ShellCommandBuilder

Adds an option with a value to the command.

Examples:

Space-separated

builder.add_option("-i", "file.mp3")
# => "-i file.mp3"

Colon-separated

builder.add_option("--volume", 10, with_colon: true)
# => "--volume:10"

Parameters:

  • option (String, Symbol) —

    The option flag (e.g., ‘-i`).

  • value (String, Symbol, Numeric) —

    The value for the option.

  • with_colon (Boolean) (defaults to: false) —

    Whether to separate the option and value with a colon (‘:`) instead of a space.

Returns:



63
64
65
66
 
# File 'lib/awaaz/utils/shell_command_builder.rb', line 63

def add_option(option, value, with_colon: false)
  @args << "#{option}#{with_colon ? ":" : " "}#{value}"
  self
end

#command ⇒ String

Builds and returns the complete shell command string.

Returns:

  • (String) —

    The constructed command.



99
100
101
 
# File 'lib/awaaz/utils/shell_command_builder.rb', line 99

def command
  @args.join(" ")
end