Class: CommandBuilder

Inherits:
Object
  • Object
show all
Defined in:
lib/command-builder.rb

Overview

Represents one command line command with arguments and parameters.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(command, separators = ["-", " ", "--", "="]) ⇒ CommandBuilder

Constructor.

Parameters:

  • command (String, Symbol) —

    target command

  • separators (Array) (defaults to: ["-", " ", "--", "="]) —

    separators matrix

See Also:



65
66
67
68
69
 
# File 'lib/command-builder.rb', line 65

def initialize(command, separators = ["-", " ", "--", "="])
    @command = command
    @separators = separators
    self.reset!
end

Instance Attribute Details

#args ⇒ Array

Holds arguments array. Each item is array pair with argument name and value.

Returns:

  • (Array) —

    array of argument pairs



48
49
50
 
# File 'lib/command-builder.rb', line 48

def args
  @args
end

#command ⇒ String, Symbol

Holds command name.

Returns:

  • (String, Symbol) —

    command body



20
21
22
 
# File 'lib/command-builder.rb', line 20

def command
  @command
end

#separators ⇒ Array

Holds separators matrix. It’s four-items array:

  • short argument separator,

  • short argument name/value separator,

  • long argument separator,

  • short argument name/value separator.

Here is some example in the same order as in command:

# ["-", " ", "--", "="]
command -s something --long=something

Returns:

  • (Array) —

    separators matrix



38
39
40
 
# File 'lib/command-builder.rb', line 38

def separators
  @separators
end

Instance Method Details

#[](name) ⇒ Array

Returns array of argument pairs with given name.

Parameters:

  • name (String, Symbol) —

    argument name

Returns:

  • (Array) —

    array of array pairs with this name



110
111
112
 
# File 'lib/command-builder.rb', line 110

def [](name)
    @args.select { |k, v| name == k }
end

#add(option) ⇒ Object #add(options) ⇒ Object #add(option, value = nil) ⇒ Object Also known as: <<

Adds an item to command. If option is Symbol or value isn’t nil, it will apply the item as an argument, in otherwise, it will treat as an symbol.

Examples:

cmd = Command::new(:jpegoptim)
cmd << :preserve    # will be rendered as 'jpegoptim --preserve'
cmd << "file.jpg"   # will be rendered as 'jpegoptiom --preserve file.jpg'

Overloads:

  • #add(option) ⇒ Object

    Adds parameter.

    Parameters:

    • option (Object) —

      parameter value

    See Also:

  • #add(options) ⇒ Object

    Adds parameters

    Parameters:

    • options (Array) —

      parameters values

    See Also:

  • #add(option, value = nil) ⇒ Object

    Adds argument.

    Parameters:

    • option (Symbol) —

      argument name

    • value (Object) (defaults to: nil) —

      argument value

    See Also:



176
177
178
179
180
181
182
183
184
 
# File 'lib/command-builder.rb', line 176

def add(option, value = nil)
    if option.kind_of? Symbol or not value.nil?
        self.argument(option, value)
    elsif option.kind_of? Array
        self.parameters(option)
    else
        self.parameter(option)
    end
end

#argument(name, value = nil) ⇒ Object Also known as: arg, []=

Adds argument to command.

One-letter arguments will be treated as “short” arguments for the syntax purposes, other as “long”. See #separators.

Examples:

with default set of #separators

cmd = Command::new(:jpegoptim)
@cmd.argument(:p)           # will be rendered as 'jpegoptim -p'
@cmd.argument(:preserve)    # will be rendered as 'jpegoptim -p --preserve'
@cmd.argument(:m, 2)        # will be rendered as 'jpegoptim -p --preserve -m 2'
@cmd.argument(:max, 2)      # will be rendered as 'jpegoptim -p --preserve -m 2 --max=2'

with array-like call

cmd = Command::new(:jpegoptim)
@cmd[:m] = 2                # will be rendered as 'jpegoptim -m 2'
@cmd[:max] = 2              # will be rendered as 'jpegoptim -m 2 --max=2'

# But be warn, it pushes to arguments array as you can se, so
# already existing values will not be replaced!

Parameters:

  • name (String, Symbol) —

    of the argument

  • value (Object) (defaults to: nil) —

    of the argument



95
96
97
98
 
# File 'lib/command-builder.rb', line 95

def argument(name, value = nil)
    @args << [name, value]
    @order << :argument
end

#empty? ⇒ Boolean

Returns whether this command has any either arguments or parameters set.

Returns:

  • (Boolean) 


281
282
283
 
# File 'lib/command-builder.rb', line 281

def empty?
  @args.empty? and @params.empty?
end

#execute(&block) ⇒ String Also known as: exec, exec!, execute!

Executes the command. If block given, takes it output of the command and runs it asynchronously using EventMachine.

Parameters:

  • block (Proc) —

    if asynchronous run

Returns:

  • (String) —

    output of the command or nil if asynchronous

See Also:



221
222
223
224
225
226
227
228
229
230
 
# File 'lib/command-builder.rb', line 221

def execute(&block)
    callback = nil
    if not block.nil?
        callback = Proc::new do |out|
            block.call(out, out.strip.empty?)
        end
    end

    Pipe::run(self.to_s, &callback)
end

#parameter(value) ⇒ Object Also known as: param

Adds parameter to command.

Parameters:

  • value (Object) —

    value of the prameter convertable to String.



119
120
121
122
 
# File 'lib/command-builder.rb', line 119

def parameter(value)
    @params << value
    @order << :parameter
end

#parameters ⇒ Array #parameters(values) ⇒ Object Also known as: params

Adds multiple parameters to command at once. If no values are given, returns the current parameters array.

Overloads:

  • #parameters ⇒ Array

    Returns current parameters array.

    Returns:

    • (Array) —

      current parameters array

  • #parameters(values) ⇒ Object

    Adds multiple parameters at once.

    Parameters:

    • values (Array) —

      array of values

    See Also:



139
140
141
142
143
144
145
146
147
 
# File 'lib/command-builder.rb', line 139

def parameters(values = nil)
    if values.nil?
        return @params
    else
        @params += values
        orders = [:parameter] * values.length
        @order.push(*orders)
    end
end

#quote(value) ⇒ String

Quotes value for use in command line.

Uses some heuristic for setting the right quotation. If both “ and ‘ are found, escapes ’ by \ and quotes by ”. If only one of them found, escapes by the second one. If space found in the string, quotes by “ too.

Examples:

cmd = Command::new(:jpegoptim)
cmd.escape("hello 'something' world")   # will result to < "hello 'something' world" >
cmd.escape('hello "something" world')   # will result to < 'hello "something" world' >
cmd.escape('hello "som\'thing" world')  # will result to < "hello \"som'thing\" world" >
cmd.escape('hello something world')     # will result to < "hello something world" >

Parameters:

  • value (String) —

    string for escaping

Returns:

  • (String) —

    quoted value



207
208
209
210
 
# File 'lib/command-builder.rb', line 207

def quote(value)
    value = value.to_s
    Shellwords::escape(value)
end

#reset! ⇒ CommandBuilder Also known as: reset

Resets the arguments and parameters so prepares it for new build.

Returns:

Since:

  • 0.1.1



266
267
268
269
270
271
 
# File 'lib/command-builder.rb', line 266

def reset!
    @args = [ ]
    @params = [ ]
    @order = [ ]
    self
end

#to_s ⇒ String

Converts command to string.

Returns:

  • (String) —

    command in string form



241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/command-builder.rb', line 241

def to_s
    cmd = @command.to_s.gsub(" ", "\\ ")
    args = @args.dup
    params = @params.dup

    @order.each do |type|
        if type == :argument
            name, value = args.shift
            __add_arg(cmd, name, value)
        else
            param = params.shift
            cmd << " " << self.quote(param.to_s)
        end
    end

    return cmd
end