Class: RProgram::Program

Inherits:
Object
  • Object
show all
Defined in:
lib/rprogram/program.rb

Direct Known Subclasses

Sudo

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(path) {|prog| ... } ⇒ Program

Creates a new Program object.

Examples:

Program.new('/usr/bin/ls')

Parameters:

  • path (String) —

    The full-path of the program.

Yields:

  • (prog) —

    If a block is given, it will be passed the newly created Program object.

Yield Parameters:

  • prog (Program) —

    The newly created program object.

Raises:



35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/rprogram/program.rb', line 35

def initialize(path,&block)
  path = File.expand_path(path)

  unless File.file?(path)
    raise(ProgramNotFound,"program #{path.dump} does not exist",caller)
  end

  @path = path
  @name = File.basename(path)

  block.call(self) if block
end

Instance Attribute Details

#name ⇒ Object (readonly)

Name of the program



14
15
16
 
# File 'lib/rprogram/program.rb', line 14

def name
  @name
end

#path ⇒ Object (readonly)

Path to the program



11
12
13
 
# File 'lib/rprogram/program.rb', line 11

def path
  @path
end

Class Method Details

.alias_program(*aliases) ⇒ Object

Sets the program aliases for the class.

Examples:

alias_program 'vim', 'vi'

Parameters:

  • aliases (Array) —

    The new program aliases.



96
97
98
 
# File 'lib/rprogram/program.rb', line 96

def self.alias_program(*aliases)
  @program_aliases = aliases.map { |name| name.to_s }
end

.find(*arguments) {|prog| ... } ⇒ Program

Finds and creates the program using it's program_names.

Examples:

Program.find
# => Program
MyProgram.find('stuff','here') do |prog|
  # ...
end

Parameters:

  • arguments (Array) —

    Additional arguments to initialize the program object with.

Yields:

  • (prog) —

    If a block is given, it will be passed the newly created Program object.

Yield Parameters:

  • prog (Program) —

    The newly created program object.

Returns:

  • (Program) —

    The newly created program object.

Raises:

  • (ProgramNotFound) —

    Non of the program_names represented valid programs on the system.



227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/rprogram/program.rb', line 227

def self.find(*arguments,&block)
  path = self.path
  path ||= System.find_program_by_names(*self.program_names)

  unless path
    names = self.program_names.map { |name| name.dump }.join(', ')

    raise(ProgramNotFound,"programs #{names} were not found",caller)
  end

  return self.new(path,*arguments,&block)
end

.find_with_path(path, *arguments) {|prog| ... } ⇒ Program?

Creates a new program object.

Examples:

Program.find_with_path('/bin/cd')
# => Program
Program.find_with_path('/obviously/fake')
# => nil

Parameters:

  • path (String) —

    The full-path of the program.

  • arguments (Array) —

    Additional arguments to initialize the program with.

Yields:

  • (prog) —

    If a block is given, it will be passed the newly created Program object.

Yield Parameters:

  • prog (Program) —

    The newly created program object.

Returns:

  • (Program, nil) —

    Returns the newly created Program object. If the given path was not a valid file, nil will be returned.



157
158
159
 
# File 'lib/rprogram/program.rb', line 157

def self.find_with_path(path,*arguments,&block)
  self.new(path,*arguments,&block) if File.file?(path)
end

.find_with_paths(paths, *arguments) {|prog| ... } ⇒ Program?

Creates a new program object with the specified paths, if a path within paths is a valid file. Any given arguments or a given block will be used in creating the new program.

Examples:

Program.find_with_paths(['/bin/cd','/usr/bin/cd'])
# => Program
Program.find_with_paths(['/obviously/fake','/bla'])
# => nil

Parameters:

  • paths (Array) —

    The Array of paths to search for the program.

  • arguments (Array) —

    Additional arguments to initialize the program with.

Yields:

  • (prog) —

    If a block is given, it will be passed the newly created Program object.

Yield Parameters:

  • prog (Program) —

    The newly created program object.

Returns:

  • (Program, nil) —

    Returns the newly created Program object. If none of the given paths were valid files, nil will be returned.



191
192
193
194
195
196
197
 
# File 'lib/rprogram/program.rb', line 191

def self.find_with_paths(paths,*arguments,&block)
  paths.each do |path|
    if File.file?(path)
      return self.new(path,*arguments,&block)
    end
  end
end

.name_program(name) ⇒ Object

Sets the program name for the class.

Examples:

name_program 'ls'

Parameters:

  • name (String, Symbol) —

    The new program name.



83
84
85
 
# File 'lib/rprogram/program.rb', line 83

def self.name_program(name)
  @program_name = name.to_s
end

.path ⇒ String?

The default path of the program.

Returns:

  • (String, nil) —

    The path to the program.

Since:

  • 0.2.0



108
109
110
 
# File 'lib/rprogram/program.rb', line 108

def self.path
  @program_path
end

.path=(new_path) ⇒ String?

Sets the default path to the program.

Parameters:

  • new_path (String) —

    The new path to the program.

Returns:

  • (String, nil) —

    The path to the program.

Since:

  • 0.2.0



123
124
125
126
127
 
# File 'lib/rprogram/program.rb', line 123

def self.path=(new_path)
  @program_path = if new_path
                    File.expand_path(new_path)
                  end
end

.program_aliases ⇒ Array

Returns The program's aliases.

Returns:

  • (Array) —

    The program's aliases.



60
61
62
 
# File 'lib/rprogram/program.rb', line 60

def self.program_aliases
  @program_aliases ||= []
end

.program_name ⇒ String

Returns The name of the program.

Returns:

  • (String) —

    The name of the program.



52
53
54
 
# File 'lib/rprogram/program.rb', line 52

def self.program_name
  @program_name ||= nil
end

.program_names ⇒ Array

Combines program_name with program_aliases.

Returns:

  • (Array) —

    Names the program is known by.



70
71
72
 
# File 'lib/rprogram/program.rb', line 70

def self.program_names
  ([program_name] + program_aliases).compact
end

Instance Method Details

#program_aliases ⇒ Array

Returns The program aliases of the class.

Returns:

  • (Array) —

    The program aliases of the class.



252
253
254
 
# File 'lib/rprogram/program.rb', line 252

def program_aliases
  self.class.program_aliases
end

#program_name ⇒ String

Returns The program name of the class.

Returns:

  • (String) —

    The program name of the class.



244
245
246
 
# File 'lib/rprogram/program.rb', line 244

def program_name
  self.class.program_name
end

#program_names ⇒ Array

Returns The program names of the class.

Returns:

  • (Array) —

    The program names of the class.



260
261
262
 
# File 'lib/rprogram/program.rb', line 260

def program_names
  self.class.program_names
end

#run(*arguments) ⇒ true, false #run(*arguments, options) ⇒ true, false

Runs the program.

Examples:

echo = Program.find_by_name('echo')
echo.run('hello')
# hello
# => true

Overloads:

  • #run(*arguments) ⇒ true, false

    Run the program with the given arguments.

    Parameters:

    • arguments (Array) —

      Additional arguments to run the program with.

  • #run(*arguments, options) ⇒ true, false

    Run the program with the given arguments and options.

    Parameters:

    • arguments (Array) —

      Additional arguments to run the program with.

    • options (Hash) —

      Additional options to execute the program with.

    Options Hash (options):

    • :env (Hash{String => String}) —

      Environment variables to execute the program with.

    • :popen (String) —

      Specifies to run the program using IO.popen with the given IO mode.

Returns:

  • (true, false) —

    Specifies the exit status of the program.

See Also:



301
302
303
 
# File 'lib/rprogram/program.rb', line 301

def run(*arguments)
  System.run(@path,*arguments)
end

#run_task(task, options = {}) ⇒ true, false

Runs the program with the arguments from the given task.

Parameters:

  • task (Task, #to_a) —

    The task who's arguments will be used to run the program.

  • options (Hash) (defaults to: {}) —

    Additional options to execute the program with.

Returns:

  • (true, false) —

    Specifies the exit status of the program.

See Also:



371
372
373
374
375
376
 
# File 'lib/rprogram/program.rb', line 371

def run_task(task,options={})
  arguments = task.arguments
  arguments << options unless options.empty?

  return run(*arguments)
end

#sudo(*arguments) ⇒ Boolean #sudo(*arguments, options) ⇒ Boolean

Runs the program under sudo.

Overloads:

  • #sudo(*arguments) ⇒ Boolean

    Run the program under sudo with the given arguments.

    Parameters:

    • arguments (Array) —

      Additional arguments to run the program with.

  • #sudo(*arguments, options) ⇒ Boolean

    Run the program under sudo with the given arguments and options.

    Parameters:

    • arguments (Array) —

      Additional arguments to run the program with.

    • options (Hash) —

      Additional options to execute the program with.

    Options Hash (options):

    • :sudo (Hash{Symbol => Object}) —

      Additional sudo options.

Returns:

  • (Boolean) —

    Specifies whether the program exited successfully.

Raises:

  • (ProgramNotFound) —

    Indicates that the sudo program could not be located.

See Also:

Since:

  • 0.1.8



341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
 
# File 'lib/rprogram/program.rb', line 341

def sudo(*arguments)
  options = if arguments.last.kind_of?(Hash)
              arguments.pop
            else
              {}
            end

  task = SudoTask.new(options.delete(:sudo) || {})
  task.command = [@path] + arguments

  arguments = task.arguments
  arguments << options unless options.empty?

  return System.sudo(*arguments)
end

#sudo_task(task, options = {}) {|sudo| ... } ⇒ true, false

Runs the program under sudo with the arguments from the given task.

Parameters:

  • task (Task, #to_a) —

    The task who's arguments will be used to run the program.

  • options (Hash) (defaults to: {}) —

    Spawn options for the program to be ran.

Yields:

  • (sudo) —

    If a block is given, it will be passed the sudo task.

Yield Parameters:

Returns:

  • (true, false) —

    Specifies the exit status of the program.

See Also:

Since:

  • 0.3.0



400
401
402
403
404
405
 
# File 'lib/rprogram/program.rb', line 400

def sudo_task(task,options={},&block)
  arguments = task.arguments
  arguments << options unless options.empty?

  return sudo(*arguments,&block)
end

#to_s ⇒ String

Converts the program to a String.

Examples:

Program.find_by_name('echo').to_s
# => "/usr/bin/echo"

Returns:

  • (String) —

    The path of the program.



417
418
419
 
# File 'lib/rprogram/program.rb', line 417

def to_s
  @path.to_s
end