rprogram 0.2.3 → 0.3.0

data/ChangeLog.md

@@ -1,14 +1,36 @@
+### 0.3.0 / 2011-04-08
+
+* Merged `RProgram::Nameable` into {RProgram::Program}.
+* Merged `RProgram::Options` into {RProgram::Task}.
+* Renamed `RProgram::Compat` to {RProgram::System}.
+* Added {RProgram::System.arch}.
+* Added {RProgram::System.platform}.
+* Added {RProgram::System.windows?}.
+* Added {RProgram::System.ruby_1_8?}.
+* Added {RProgram::System.jruby?}.
+* Added {RProgram::System.sudo_path}.
+* Added {RProgram::System.sudo_path=}.
+* Added {RProgram::System.sudo?}.
+* Added {RProgram::Sudo}.
+* Added {RProgram::SudoTask}.
+* Allow passing tailing [exec-options](http://rubydoc.info/stdlib/core/1.9.2/Kernel#spawn-instance_method)
+  to {RProgram::System.run} (only supported on Ruby 1.9).
+* Allow using `IO.popen` in {RProgram::System.run} if the `:popen` option
+  is specified (only available on Ruby 1.9).
+* Allow specifying the environment variables in {RProgram::System.run}
+  if the `:env` option is specified (only available on Ruby 1.9).
+
 ### 0.2.3 / 2011-03-30
 
 * Require env ~> 0.1, >= 0.1.2.
 * Automatically search for programs with a `.exe` suffix, when running on
   Windows.
-* {RProgram::Compat.find_program} and {RProgram::Compat.find_program_by_names}
+* `RProgram::Compat.find_program` and `RProgram::Compat.find_program_by_names`
   now return a `Pathname` object.
 
 ### 0.2.2 / 2011-01-22
 
-* Deprecated {RProgram::Compat.platform}.
+* Deprecated `RProgram::Compat.platform`.
 * Use `File::PATH_SEPARATOR` to separate the `PATH` environment variable
   in `RProgram::Compat.paths`.
 
@@ -18,19 +40,19 @@
 
 ### 0.2.0 / 2010-10-03
 
-* Added {RProgram::Nameable::ClassMethods}.
-* Added {RProgram::Options::ClassMethods}.
-* Added {RProgram::Nameable::ClassMethods#path}:
+* Added `RProgram::Nameable::ClassMethods`.
+* Added `RProgram::Options::ClassMethods`.
+* Added `RProgram::Nameable::ClassMethods#path`:
   * {RProgram::Program.find} will default to
-    {RProgram::Nameable::ClassMethods#path} if set.
+    `RProgram::Nameable::ClassMethods#path` if set.
 
 ### 0.1.8 / 2009-12-24
  
 * Allow Program to run commands under sudo:
-  * Added {RProgram::Compat.sudo}.
-  * Added {RProgram::Task#sudo}.
-  * Added {RProgram::Task#sudo=}.
-  * Added {RProgram::Task#sudo?}.
+  * Added `RProgram::Compat.sudo`.
+  * Added `RProgram::Task#sudo`.
+  * Added `RProgram::Task#sudo=`.
+  * Added `RProgram::Task#sudo?`.
   * Added {RProgram::Program#sudo}.
 
 ### 0.1.7 / 2009-09-21
@@ -46,7 +68,7 @@
 
 * Use Hoe 2.2.0.
 * Removed requirement for 'open3'.
-* Renamed PRogram::Compat.PATHS to `RProgram::Compat.paths`.
+* Renamed `PRogram::Compat.PATHS` to `RProgram::Compat.paths`.
 * Refactored {RProgram::Option#arguments}.
 * Removed `RProgram::Option#format`.
 * Refactored {RProgram::NonOption#arguments}.

data/README.md

@@ -2,7 +2,7 @@
 
 * [Source](http://github.com/postmodern/rprogram)
 * [Issues](http://github.com/postmodern/rprogram/issues)
-* [Documentation](http://rubydoc.info/gems/rprogram)
+* [Documentation](http://rubydoc.info/gems/rprogram/frames)
 * [Email](mailto:postmodern.mod3 at gmail.com)
 
 ## Description
@@ -14,8 +14,12 @@ system.
 
 ## Features
 
-* Uses Kernel.system for safe execution of individual programs and their
-  separate command-line arguments.
+* Safely executes individual programs and their separate command-line
+  arguments, to prevent command or option injection.
+* Supports using Ruby 1.9 [exec options](http://rubydoc.info/stdlib/core/1.9.2/Kernel#spawn-instance_method).
+* Supports specifying environment variables of a process
+  (only available on Ruby 1.9).
+* Allows running programs with `IO.popen` (only available on Ruby 1.9).
 * Allows running programs under `sudo`.
 * Provides cross-platform access to the `PATH` environment variable.
 * Supports leading/tailing non-options.

data/lib/rprogram/program.rb

@@ -1,14 +1,12 @@
 require 'rprogram/rprogram'
-require 'rprogram/compat'
+require 'rprogram/system'
 require 'rprogram/task'
-require 'rprogram/nameable'
+require 'rprogram/sudo_task'
 require 'rprogram/exceptions/program_not_found'
 
 module RProgram
   class Program
 
-    include Nameable
-
     # Path to the program
     attr_reader :path
 
@@ -47,6 +45,87 @@ module RProgram
       block.call(self) if block
     end
 
+    #
+    # @return [String]
+    #   The name of the program.
+    #
+    def self.program_name
+      @program_name ||= nil
+    end
+
+    #
+    # @return [Array]
+    #   The program's aliases.
+    #
+    def self.program_aliases
+      @program_aliases ||= []
+    end
+
+    #
+    # Combines program_name with program_aliases.
+    #
+    # @return [Array]
+    #   Names the program is known by.
+    #
+    def self.program_names
+      ([program_name] + program_aliases).compact
+    end
+
+    #
+    # Sets the program name for the class.
+    #
+    # @param [String, Symbol] name
+    #   The new program name.
+    #
+    # @example
+    #   name_program 'ls'
+    #
+    def self.name_program(name)
+      @program_name = name.to_s
+    end
+
+    #
+    # Sets the program aliases for the class.
+    #
+    # @param [Array] aliases
+    #   The new program aliases.
+    #
+    # @example
+    #   alias_program 'vim', 'vi'
+    #
+    def self.alias_program(*aliases)
+      @program_aliases = aliases.map { |name| name.to_s }
+    end
+
+    #
+    # The default path of the program.
+    #
+    # @return [String, nil]
+    #   The path to the program.
+    #
+    # @since 0.2.0
+    #
+    def self.path
+      @program_path
+    end
+
+    #
+    # Sets the default path to the program.
+    #
+    # @param [String] new_path
+    #   The new path to the program.
+    #
+    # @return [String, nil]
+    #   The path to the program.
+    #
+    # @since 0.2.0
+    #
+    def self.path=(new_path)
+      @program_path = if new_path
+                        File.expand_path(new_path)
+                      end
+    end
+
     #
     # Creates a new program object.
     #
@@ -76,7 +155,7 @@ module RProgram
     #   # => nil
     #
     def self.find_with_path(path,*arguments,&block)
-      return self.new(path,*arguments,&block) if File.file?(path)
+      self.new(path,*arguments,&block) if File.file?(path)
     end
 
     #
@@ -111,7 +190,9 @@ module RProgram
     #
     def self.find_with_paths(paths,*arguments,&block)
       paths.each do |path|
-        return self.new(path,*arguments,&block) if File.file?(path)
+        if File.file?(path)
+          return self.new(path,*arguments,&block)
+        end
       end
     end
 
@@ -145,7 +226,7 @@ module RProgram
     #
     def self.find(*arguments,&block)
       path = self.path
-      path ||= Compat.find_program_by_names(*self.program_names)
+      path ||= System.find_program_by_names(*self.program_names)
 
       unless path
         names = self.program_names.map { |name| name.dump }.join(', ')
@@ -156,11 +237,54 @@ module RProgram
       return self.new(path,*arguments,&block)
     end
 
+    #
+    # @return [String]
+    #   The program name of the class.
+    #
+    def program_name
+      self.class.program_name
+    end
+
+    #
+    # @return [Array]
+    #   The program aliases of the class.
+    #
+    def program_aliases
+      self.class.program_aliases
+    end
+
+    #
+    # @return [Array]
+    #   The program names of the class.
+    #
+    def program_names
+      self.class.program_names
+    end
+
     #
     # Runs the program.
     #
-    # @param [Array] args
-    #   Addition arguments to run the program with.
+    # @overload run(*arguments)
+    #   Run the program with the given arguments.
+    #
+    #   @param [Array] arguments
+    #     Additional arguments to run the program with.
+    #
+    # @overload run(*arguments,options)
+    #   Run the program with the given arguments and options.
+    #
+    #   @param [Array] arguments
+    #     Additional arguments to run the program with.
+    #
+    #   @param [Hash] options
+    #     Additional options to execute the program with.
+    #
+    #   @option options [Hash{String => String}] :env
+    #     Environment variables to execute the program with.
+    #
+    #   @option options [String] :popen
+    #     Specifies to run the program using `IO.popen` with the given
+    #     IO mode.
     #
     # @return [true, false]
     #   Specifies the exit status of the program.
@@ -171,17 +295,34 @@ module RProgram
     #   # hello
     #   # => true
     #
-    # @see Kernel.system
+    # @see http://rubydoc.info/stdlib/core/1.9.2/Kernel#spawn-instance_method
+    #   For acceptable options.
     #
-    def run(*args)
-      Compat.run(@path,*args)
+    def run(*arguments)
+      System.run(@path,*arguments)
     end
 
     #
     # Runs the program under sudo.
     #
-    # @param [Array] args
-    #   Additional arguments to run the program with.
+    # @overload sudo(*arguments)
+    #   Run the program under `sudo` with the given arguments.
+    #
+    #   @param [Array] arguments
+    #     Additional arguments to run the program with.
+    #
+    # @overload sudo(*arguments,options)
+    #   Run the program under `sudo` with the given arguments
+    #   and options.
+    #
+    #   @param [Array] arguments
+    #     Additional arguments to run the program with.
+    #
+    #   @param [Hash] options
+    #     Additional options to execute the program with.
+    #
+    #   @option options [Hash{Symbol => Object}] :sudo
+    #     Additional `sudo` options.
     #
     # @return [Boolean]
     #   Specifies whether the program exited successfully.
@@ -191,27 +332,76 @@ module RProgram
     #
     # @since 0.1.8
     #
-    def sudo(*args)
-      Compat.sudo(@path,*args)
+    # @see http://rubydoc.info/stdlib/core/1.9.2/Kernel#spawn-instance_method
+    #   For acceptable options.
+    #
+    # @see SudoTask
+    #   For valid `:sudo` options.
+    #
+    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
 
     #
     # Runs the program with the arguments from the given task.
     #
-    # @param [Task] task
+    # @param [Task, #to_a] task
     #   The task who's arguments will be used to run the program.
     #
+    # @param [Hash] options
+    #   Additional options to execute the program with.
+    #
     # @return [true, false]
     #   Specifies the exit status of the program.
     #
-    # @see Kernel.system
+    # @see #run
     #
-    def run_task(task)
-      if task.sudo?
-        return sudo(*(task.arguments))
-      else
-        return run(*(task.arguments))
-      end
+    def run_task(task,options={})
+      arguments = task.arguments
+      arguments << options unless options.empty?
+
+      return run(*arguments)
+    end
+
+    #
+    # Runs the program under `sudo` with the arguments from the given task.
+    #
+    # @param [Task, #to_a] task
+    #   The task who's arguments will be used to run the program.
+    #
+    # @param [Hash] options
+    #   Spawn options for the program to be ran.
+    #
+    # @yield [sudo]
+    #   If a block is given, it will be passed the sudo task.
+    #
+    # @yieldparam [SudoTask] sudo
+    #   The sudo tasks.
+    #
+    # @return [true, false]
+    #   Specifies the exit status of the program.
+    #
+    # @see #sudo
+    #
+    # @since 0.3.0
+    #
+    def sudo_task(task,options={},&block)
+      arguments = task.arguments
+      arguments << options unless options.empty?
+
+      return sudo(*arguments,&block)
     end
 
     #

data/lib/rprogram/sudo.rb

@@ -0,0 +1,14 @@
+require 'rprogram/program'
+
+module RProgram
+  #
+  # Represents the `sudo` executable.
+  #
+  # @since 0.3.0
+  #
+  class Sudo < Program
+
+    name_program 'sudo'
+
+  end
+end

data/lib/rprogram/sudo_task.rb

@@ -0,0 +1,68 @@
+require 'rprogram/task'
+
+module RProgram
+  #
+  # Represents the options for `sudo`.
+  #
+  # ## Sudo options:
+  #
+  # * `-A` - `sudo.ask_password`
+  # * `-b` - `sudo.background`
+  # * `-C` - `sudo.close_from`
+  # * `-E` - `sudo.preserve_env`
+  # * `-e` - `sudo.edit`
+  # * `-g` - `sudo.group`
+  # * `-H` - `sudo.home`
+  # * `-h` - `sudo.help`
+  # * `-i` - `sudo.simulate_initial_login`
+  # * `-k` - `sudo.kill`
+  # * `-K` - `sudo.sure_kill`
+  # * `-L` - `sudo.list_defaults`
+  # * `-l` - `sudo.list`
+  # * `-n` - `sudo.non_interactive`
+  # * `-P` - `sudo.preserve_group`
+  # * `-p` - `sudo.prompt`
+  # * `-r` - `sudo.role`
+  # * `-S` - `sudo.stdin`
+  # * `-s` - `sudo.shell`
+  # * `-t` - `sudo.type`
+  # * `-U` - `sudo.other_user`
+  # * `-u` - `sudo.user`
+  # * `-V` - `sudo.version`
+  # * `-v` - `sudo.validate`
+  #
+  # * `[command]` - `sudo.command`
+  #
+  # @since 0.3.0
+  #
+  class SudoTask < Task
+
+    short_option :name => :ask_password, :flag => '-A'
+    short_option :name => :background, :flag => '-b'
+    short_option :name => :close_from, :flag => '-C'
+    short_option :name => :preserve_env, :flag => '-E'
+    short_option :name => :edit, :flag => '-e'
+    short_option :name => :group, :flag => '-g'
+    short_option :name => :home, :flag => '-H'
+    short_option :name => :help, :flag => '-h'
+    short_option :name => :simulate_initial_login, :flag => '-i'
+    short_option :name => :kill, :flag => '-k'
+    short_option :name => :sure_kill, :flag => '-K'
+    short_option :name => :list_defaults, :flag => '-L'
+    short_option :name => :list, :flag => '-l'
+    short_option :name => :non_interactive, :flag => '-n'
+    short_option :name => :preserve_group, :flag => '-P'
+    short_option :name => :prompt, :flag => '-p'
+    short_option :name => :role, :flag => '-r'
+    short_option :name => :stdin, :flag => '-S'
+    short_option :name => :shell, :flag => '-s'
+    short_option :name => :type, :flag => '-t'
+    short_option :name => :other_user, :flag => '-U'
+    short_option :name => :user, :flag => '-u'
+    short_option :name => :version, :flag => '-V'
+    short_option :name => :validate, :flag => '-v'
+
+    non_option :tailing => true, :name => :command
+
+  end
+end