rprogram 0.0.9 → 0.1.0

data/History.txt

@@ -1,3 +1,12 @@
+== 0.1.0 / 2008-01-17
+
+* Removed redundent methods in Program:
+ * +Program.find_by_name+
+ * +Program.find_by_names+
+* Added Program#create.
+* Made Program Nameable by default.
+* Prevented arbitrary command-injection in Program#run.
+
 == 0.0.9 / 2008-01-09
 
 * Initial release.

data/README.txt

@@ -24,7 +24,7 @@ system.
 
 The MIT License
 
-Copyright (c) 2008 Hal Brodigan
+Copyright (c) 2007-2008 Hal Brodigan
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/Rakefile

@@ -8,7 +8,7 @@ Hoe.new('rprogram', RProgram::VERSION) do |p|
   p.rubyforge_name = 'rprogram'
   p.author = 'Postmodern Modulus III'
   p.email = 'postmodern.mod3@gmail.com'
-  p.summary = 'RProgram is a library for creating ruby wrappers around command-line programs'
+  p.summary = 'RProgram is a library for creating Rubyful wrappers around command-line programs'
   p.description = p.paragraphs_of('README.txt', 2..5).join("\n\n")
   p.url = p.paragraphs_of('README.txt', 0).first.split(/\n/)[1..-1]
   p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")

data/lib/rprogram/nameable.rb

@@ -5,27 +5,44 @@ module RProgram
   module Nameable
     def self.included(base)
       base.metaclass_eval do
+        #
+        # Returns the name of the program.
+        #
         def program_name
-          @program_name
-        end
-
-        def program_name=(name)
-          @program_name = name.to_s
+          @program_name ||= nil
         end
 
+        #
+        # Returns an Array of the program's aliases.
+        #
         def program_aliases
           @program_aliases ||= []
         end
 
-        def program_aliases=(aliases)
-          @program_aliases = aliases.to_a.map { |name| name.to_s }
+        #
+        # Returns an Array of all names the program is known by, combining
+        # both program_name and program_aliases.
+        #
+        def program_names
+          ([program_name] + program_aliases).compact
         end
 
-        def find_program
-          names = self.program_aliases
-          names.unshift(self.program_name) if self.program_name
+        #
+        # Sets the program name for a class to the specified _name_.
+        #
+        #   name_program 'ls'
+        #
+        def name_program(name)
+          @program_name = name.to_s
+        end
 
-          return Compat.find_program_by_names(*names)
+        #
+        # Sets the program aliases for a class to the specified _aliases_.
+        #
+        #   alias_program 'vim', 'vi'
+        #
+        def alias_program(*aliases)
+          @program_aliases = aliases.map { |name| name.to_s }
         end
       end
     end
@@ -43,25 +60,5 @@ module RProgram
     def program_aliases
       self.class.program_aliases
     end
-
-    protected
-
-    #
-    # Sets the program name for a class to the specified _name_.
-    #
-    #   name_program 'ls'
-    #
-    def Object.name_program(name)
-      self.program_name = name
-    end
-
-    #
-    # Sets the program aliases for a class to the specified _aliases_.
-    #
-    #   name_program 'vim', 'vi'
-    #
-    def Object.alias_program(*aliases)
-      self.program_aliases = aliases
-    end
   end
 end

data/lib/rprogram/non_option.rb

@@ -13,12 +13,24 @@ module RProgram
     # Can the argument be specified multiple times
     attr_reader :multiple
 
-    def initialize(opts={:name => nil, :leading => false, :tailing => false, :multiple => false})
-      @name = opts[:name]
-
-      @leading = opts[:leading] || false
-      @tailing = opts[:tailing] || true
-      @multiple = opts[:multiple] || false
+    #
+    # Creates a new NonOption object with the specified _options_.
+    #
+    # _options_ may contain the following keys:
+    # <tt>:name</tt>:: The name of the non-option.
+    # <tt>:leading</tt>:: Implies the non-option is a leading non-option.
+    #                     Defaults to +false+, if not given.
+    # <tt>:tailing</tt>:: Implies the non-option is a tailing non-option.
+    #                     Defaults to +true+, if not given.
+    # <tt>:multiple</tt>:: Implies the non-option maybe given an Array
+    #                      of values. Defaults to +false+, if not given.
+    #
+    def initialize(options={})
+      @name = options[:name]
+
+      @leading = options[:leading] || false
+      @tailing = options[:tailing] || true
+      @multiple = options[:multiple] || false
     end
 
     def arguments(value)

data/lib/rprogram/option.rb

@@ -10,15 +10,32 @@ module RProgram
     # Can the option be specified multiple times
     attr_reader :multiple
 
-    def initialize(opts={:flag => nil, :equals => false, :multiple => false},&block)
-      @flag = opts[:flag]
+    #
+    # Creates a new Option object with the specified _options_. If a _block_
+    # is given it will be used for the custom formating of the option. If a
+    # _block_ is not given, the option will use the default_format when
+    # generating the arguments.
+    #
+    # _options_ may contain the following keys:
+    # <tt>:flag</tt>:: The command-line flag to use.
+    # <tt>:equals</tt>:: Implies the option maybe formated as '--flag=value'.
+    #                    Defaults to +falue+, if not given.
+    # <tt>:multuple</tt>:: Implies the option maybe given an Array of
+    #                      values. Defaults to +false+, if not given.
+    #
+    def initialize(options={},&block)
+      @flag = options[:flag]
 
-      @equals = opts[:equals] || false
-      @multiple = opts[:multiple] || false
+      @equals = options[:equals] || false
+      @multiple = options[:multiple] || false
 
       @formating = block
     end
 
+    #
+    # Returns an +Array+ of the arguments for the option with the specified
+    # _value_.
+    #
     def arguments(value)
       return [@flag] if value==true
       return [] if (value==nil || value==false)
@@ -41,12 +58,20 @@ module RProgram
 
     protected
 
+    #
+    # Returns an Array of the flag and the specified _value_ in argument
+    # form.
+    #
     def default_format(value)
       return [@flag] + value if value.kind_of?(Array)
       return ["#{flag}=#{value}"] if @equals
       return [@flag, value]
     end
 
+    #
+    # Formats specified _value_ with the option flag using
+    # either the custom formating or the default_format.
+    #
     def format(value)
       if @formating
         return @formating.call(@flag,value).to_a

data/lib/rprogram/options.rb

@@ -6,10 +6,17 @@ module RProgram
   module Options
     def self.included(base)
       base.metaclass_eval do
+        #
+        # Returns a Hash of all defined non-options.
+        #
         def non_options
           @non_options ||= {}
         end
 
+        #
+        # Returns +true+ if the non-option with the specified _name_ was
+        # defined, returns +false+ otherwise.
+        #
         def has_non_option?(name)
           name = name.to_sym
 
@@ -22,6 +29,9 @@ module RProgram
           return false
         end
 
+        #
+        # Returns the non-option known by _name_, returns +nil+ otherwise.
+        #
         def get_non_option(name)
           name = name.to_sym
 
@@ -34,10 +44,17 @@ module RProgram
           return nil
         end
 
+        #
+        # Returns a Hash of all defined options.
+        #
         def options
           @options ||= {}
         end
 
+        #
+        # Returns +true+ if an option with the specified _name_ was defined,
+        # returns +false+ otherwise.
+        #
         def has_option?(name)
           name = name.to_sym
 
@@ -50,6 +67,10 @@ module RProgram
           return false
         end
 
+        #
+        # Returns the option with the specified _name_, returns +nil+
+        # otherwise.
+        #
         def get_option(name)
           name = name.to_sym
 
@@ -64,18 +85,33 @@ module RProgram
       end
     end
 
+    #
+    # Returns +true+ if the non-option with the specified _name_ was
+    # defined, returns +false+ otherwise.
+    #
     def has_non_option?(name)
       self.class.has_non_option?(name)
     end
 
+    #
+    # Returns the non-option known by _name_, returns +nil+ otherwise.
+    #
     def get_non_option(name)
       self.class.get_non_option(name)
     end
 
+    #
+    # Returns +true+ if an option with the specified _name_ was defined,
+    # returns +false+ otherwise.
+    #
     def has_option?(name)
       self.class.has_option?(name)
     end
 
+    #
+    # Returns the option with the specified _name_, returns +nil+
+    # otherwise.
+    #
     def get_option(name)
       self.class.get_option(name)
     end

data/lib/rprogram/program.rb

@@ -1,10 +1,15 @@
 require 'rprogram/compat'
 require 'rprogram/task'
+require 'rprogram/nameable'
 require 'rprogram/exceptions/program_not_found'
 
+require 'open3'
+
 module RProgram
   class Program
 
+    include Nameable
+
     # Path to the program
     attr_reader :path
 
@@ -12,62 +17,76 @@ module RProgram
     attr_reader :name
 
     #
-    # Creates a new Program object from _path_. If _block_ is given, it will
-    # be passed the newly created Program.
+    # Creates a new Program object from _path_. If _path_ is not a valid
+    # file, a ProgramNotFound exception will be thrown. If a _block_ is
+    # given, it will be passed the newly created Program.
     #
     #   Program.new('/usr/bin/ls')
     #
     def initialize(path,&block)
-      @path = File.expand_path(path)
-      @name = File.basename(@path)
-    end
+      path = File.expand_path(path)
 
-    #
-    # Finds the program with the specified _name_ and returns a new
-    # Program object. If no programs could be found with the matching _name_,
-    # a ProramNotFound exception will be raised.
-    #
-    #   Program.find_by_name('cat') # => Program
-    #
-    def self.find_by_name(name)
-      path = Compat.find_program(name)
-      unless path
-        raise(ProgramNotFound,"program '#{name}' could not be found",caller)
+      unless File.file?(path)
+        raise(ProgramNotFound,"program #{path.dump} does not exist",caller)
       end
 
-      return self.new(path)
-    end
-
-    def self.find_by_names(*names)
-      path = Compat.find_program_by_names(*names)
-
-      unless path
-        names = names.map { |name| name.dump }.join(', ')
+      @path = path
+      @name = File.basename(path)
 
-        raise(ProgramNotFound,"programs #{names} were not be found",caller)
-      end
-
-      return self.new(path)
+      block.call(self) if block
     end
 
     #
-    # Creates a new Program object with the specified _path_,
-    # if _path_ is a valid file.
+    # Creates a new program object with the specified _path_, if _path_
+    # is a valid file. Any given _args_ or a given _block_ will be used
+    # in creating the new program.
     #
     #   Program.create_from_path('/bin/cd') # => Program
     #
     #   Program.create_from_path('/obviously/fake') # => nil
     #
-    def self.create_from_path(path)
-      return self.new(path) if File.file?(path)
+    def self.create_from_path(path,*args,&block)
+      return self.new(path,*args,&block) if File.file?(path)
     end
 
-    def self.create_from_paths(*paths)
+    #
+    # Creates a new program object with the specified _paths_,
+    # if a path within _paths_ is a valid file. Any given _args_ or
+    # a given _block_ will be used in creating the new program.
+    #
+    #   Program.create_from_paths(['/bin/cd','/usr/bin/cd']) # => Program
+    #
+    #   Program.create_from_paths(['/obviously/fake','/bla']) # => nil
+    #
+    def self.create_from_paths(paths,*args,&block)
       paths.each do |path|
-        return self.new(path) if File.file?(path)
+        return self.new(path,*args,&block) if File.file?(path)
       end
     end
 
+    #
+    # Finds and creates the program using it's +program_names+ and returns
+    # a new Program object. If the program cannot be found by any of it's
+    # +program_names+, a ProramNotFound exception will be raised. Any given
+    # _args_ or a given _block_ will be used in creating the new program.
+    #
+    #   Program.create # => Program
+    #
+    #   MyProgram.create('stuff','here') do |prog|
+    #     ...
+    #   end
+    #
+    def self.create(*args,&block)
+      path = Compat.find_program_by_names(program_names)
+      unless path
+        names = program_names.map { |name| name.dump }.join(', ')
+
+        raise(ProgramNotFound,"programs #{names} were not found",caller)
+      end
+
+      return self.new(path,*args,&block)
+    end
+
     #
     # Runs the program with the specified _args_ and returns
     # an Array of the programs output.
@@ -76,17 +95,17 @@ module RProgram
     #   echo.run("hello") # => ["hello\n"]
     #
     def run(*args)
-      command = [@path] + args
+      args = args.map { |arg| arg.to_s }
 
-      IO.popen(command.join(' ')) do |process|
-        return process.readlines
+      Open3.popen3(@path,*args) do |stdin,stdout,stderr|
+        return stdout.readlines
       end
     end
 
     #
     # Runs the program with the specified _task_ object.
     #
-    def run_task(task)
+    def run_with_task(task)
       run(*(task.arguments))
     end
 

data/lib/rprogram/task.rb

@@ -10,7 +10,10 @@ module RProgram
     # given, it is passed the newly created Task object.
     #
     #   Task.new(:test => 'example', :count => 2, :verbose => true)
-    #   Task.new(:help => true) { |task| ... }
+    #
+    #   Task.new(:help => true) do |task|
+    #     ...
+    #   end
     #
     def initialize(options={},&block)
       @subtasks = {}
@@ -108,7 +111,7 @@ module RProgram
     # the tasks leading non_options, options and tailing non-options.
     #
     def arguments
-      leading_non_options + options + ['--'] + tailing_non_options
+      leading_non_options + options + tailing_non_options
     end
 
     protected
@@ -118,7 +121,7 @@ module RProgram
     #
     #   subtask :extra, ExtraTask
     #
-    def Object.subtask(name,task)
+    def self.subtask(name,task)
       class_eval %{
         def #{name}(options={},&block)
           if @subtasks[#{name.dump}]
@@ -141,7 +144,7 @@ module RProgram
     #
     #   non_option :name => 'file', :tailing => true, :multiple => true
     #
-    def Object.non_option(opts={})
+    def self.non_option(opts={})
       name = opts[:name].to_sym
 
       self.non_options[name] = NonOption.new(opts)
@@ -166,7 +169,7 @@ module RProgram
     #
     #   long_option :flag => '-f', :name => :file
     #
-    def Object.long_option(opts={},&block)
+    def self.long_option(opts={},&block)
       flag = opts[:flag].to_s
       method_name = (opts[:name] || Task.flag_namify(flag)).to_sym
 
@@ -190,7 +193,7 @@ module RProgram
     #
     #   short_option :flag => '-c', :name => :count
     #
-    def Object.short_option(opts={},&block)
+    def self.short_option(opts={},&block)
       method_name = opts[:name].to_sym
 
       self.options[method_name] = Option.new(opts,&block)
@@ -211,7 +214,7 @@ module RProgram
     #
     # Converts a long-option flag to a Ruby method name.
     # 
-    #   Task.flag_namify('--output-file')  #=> "output_files"
+    #   Task.flag_namify('--output-file')  # => "output_file"
     #
     def Task.flag_namify(flag)
       flag = flag.to_s

data/lib/rprogram/version.rb

@@ -1,3 +1,3 @@
 module RProgram
-  VERSION = '0.0.9'
+  VERSION = '0.1.0'
 end

metadata

@@ -1,33 +1,36 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.9.4
-specification_version: 1
 name: rprogram
 version: !ruby/object:Gem::Version 
-  version: 0.0.9
-date: 2008-01-09 00:00:00 -08:00
-summary: RProgram is a library for creating ruby wrappers around command-line programs
-require_paths: 
-- lib
-email: postmodern.mod3@gmail.com
-homepage: "    by Postmodern Modulus III"
-rubyforge_project: rprogram
-description: "== FEATURES/PROBLEMS:  * Provides cross-platform access to the PATH variable. * Supports leading/tailing non-options. * Supports long-options and short-options. * Supports custom formating of options.  == INSTALL:  $ sudo gem install rprogram  == LICENSE:"
-autorequire: 
-default_executable: 
-bindir: bin
-has_rdoc: true
-required_ruby_version: !ruby/object:Gem::Version::Requirement 
-  requirements: 
-  - - ">"
-    - !ruby/object:Gem::Version 
-      version: 0.0.0
-  version: 
+  version: 0.1.0
 platform: ruby
-signing_key: 
-cert_chain: 
-post_install_message: 
 authors: 
 - Postmodern Modulus III
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-01-17 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.4.0
+    version: 
+description: "== FEATURES/PROBLEMS:  * Provides cross-platform access to the PATH variable. * Supports leading/tailing non-options. * Supports long-options and short-options. * Supports custom formating of options.  == INSTALL:  $ sudo gem install rprogram  == LICENSE:"
+email: postmodern.mod3@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
 files: 
 - History.txt
 - Manifest.txt
@@ -48,28 +51,32 @@ files:
 - lib/rprogram/nameable.rb
 - lib/rprogram/program.rb
 - test/test_rprogram.rb
-test_files: 
-- test/test_rprogram.rb
+has_rdoc: true
+homepage: "    by Postmodern Modulus III"
+post_install_message: 
 rdoc_options: 
 - --main
 - README.txt
-extra_rdoc_files: 
-- History.txt
-- Manifest.txt
-- README.txt
-executables: []
-
-extensions: []
-
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
 requirements: []
 
-dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: hoe
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Version::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: 1.4.0
-    version: 
+rubyforge_project: rprogram
+rubygems_version: 1.0.1
+signing_key: 
+specification_version: 2
+summary: RProgram is a library for creating Rubyful wrappers around command-line programs
+test_files: 
+- test/test_rprogram.rb