rprogram 0.1.8 → 0.2.0

data/.gitignore

@@ -0,0 +1,9 @@
+doc
+pkg
+tmp/*
+.DS_Store
+.yardoc
+*.db
+*.log
+*.swp
+*~

data/.specopts

@@ -0,0 +1 @@
+--colour --format specdoc

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title 'RProgram Documentation' --protected --files ChangeLog.md,LICENSE.txt

data/ChangeLog.md

@@ -0,0 +1,103 @@
+### 0.2.0 / 2010-10-03
+
+* 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.
+
+### 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::Program#sudo}.
+
+### 0.1.7 / 2009-09-21
+
+* Require Hoe >= 2.3.3.
+* Require YARD >= 0.2.3.5.
+* Require RSpec >= 1.2.8.
+* Use 'hoe/signing' for signed RubyGems.
+* Moved to YARD based documentation.
+* All specs pass on JRuby 1.3.1.
+
+### 0.1.6 / 2009-06-30
+
+* Use Hoe 2.2.0.
+* Removed requirement for 'open3'.
+* Renamed PRogram::Compat.PATHS to {RProgram::Compat.paths}.
+* Refactored {RProgram::Option#arguments}.
+* Removed `RProgram::Option#format`.
+* Refactored {RProgram::NonOption#arguments}.
+* Renamed `RProgram::NonOption#leading` to {RProgram::NonOption#leading?}.
+* Removed `RProgram::NonOption#tailing`.
+* Added {RProgram::NonOption#tailing?}.
+* Added specs.
+* All specs pass on Ruby 1.9.1-p0 and 1.8.6-p287.
+
+### 0.1.5 / 2009-01-14
+
+* Use Kernel.system in {RProgram::Program#run}, instead of Open3.popen3:
+  * popen3 is not well supported on Windows.
+  * win32-open3 does not allow for the execution of single programs with
+    separate command-line arguments. Instead, it merely executes a command
+    string in command.com. This seems to allow arbitrary command injection
+    via command-line arguments.
+  * {RProgram::Program#run} will now return either `true` or `false`,
+    depending on the exit status of the program.
+* Added some missing documentation.
+
+### 0.1.4 / 2009-01-07
+
+* Added `lib/rprogram/rprogram.rb` to the Manifest.
+* Added more documentation.
+
+### 0.1.3 / 2008-01-27
+
+* Renamed `RProgram::Program.create_from_path` to
+  {RProgram::Program.find_with_path}.
+* Renamed `RProgram::Program.create_from_paths` to
+  {RProgram::Program.find_with_paths}.
+* Renamed `RProgram::Program.create` to {RProgram::Program.find}.
+* Renamed `RProgram::Program.run_with_task` to {RProgram::Program#run_task}.
+
+### 0.1.2 / 2008-01-18
+
+* DRYed up lib/rprogram/task.
+  * Added {RProgram::Task.define_option}.
+* Added OptionList so that Option may contain sub-options.
+* Touched up documenation.
+
+### 0.1.1 / 2008-01-18
+
+* Added support for the {RProgram::Option} argument separators.
+
+        #
+        # Creates arguments of the form:
+        #
+        #   ["-opts","value1:value2:value3"]
+        #
+        long_option :flag => '-opts', :separator => ':'
+
+* Fixed the `lib/rprogram.rb` file.
+
+### 0.1.0 / 2008-01-17
+
+* Removed redundent methods in {RProgram::Program}:
+  * `RProgram::Program.find_by_name`
+  * `RProgram::Program.find_by_names`
+* Added `RProgram::Program#create`.
+* Made {RProgram::Program} nameable by default.
+* Prevented arbitrary command-injection in {RProgram::Program#run}.
+
+### 0.0.9 / 2008-01-09
+
+* Initial release.
+* Provides cross-platform access to the `PATH` environment variable.
+* Supports mapping long and short options.
+* Supports mapping leading and tailing non-options.
+* Supports custom formating of options.
+

data/LICENSE.txt

@@ -1,23 +1,22 @@
 
+Copyright (c) 2007-2010 Hal Brodigan
 
-The MIT License
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
 
-Copyright (c) 2007-2008 Hal Brodigan
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.

data/README.md

@@ -0,0 +1,101 @@
+# RProgram
+
+* [github.com/postmodern/rprogram](http://github.com/postmodern/rprogram)
+* [github.com/postmodern/rprogram/issues](http://github.com/postmodern/rprogram/issues)
+* Postmodern (postmodern.mod3 at gmail.com)
+
+## Description
+  
+RProgram is a library for creating wrappers around command-line programs.
+RProgram provides a Rubyful interface to programs and all their options
+or non-options. RProgram can also search for programs installed on a
+system.
+
+## Features
+
+* Uses Kernel.system for safe execution of individual programs and their
+  separate command-line arguments.
+* Allows running programs under `sudo`.
+* Provides cross-platform access to the PATH variable.
+* Supports leading/tailing non-options.
+* Supports long-options and short-options.
+* Supports custom formating of options.
+
+## Examples
+
+First, create the class to represent the options of the program, using
+{RProgram::Task} as the base class:
+
+    require 'rprogram/task'
+
+    class MyProgTask < RProgram::Task
+
+      # map in the short-options
+      short_option :flag => '-o', :name => :output
+      short_option :flag => '-oX', :name => :xml_output
+
+      # map in long options
+      long_option :flag => '--no-resolv', :name => :disable_resolv
+
+      # long_option can infer the :name option, based on the :flag
+      long_option :flag => '--mode'
+
+      # options can also take multiple values
+      long_option :flag => '--includes', :multiple => true
+
+      # options with multiple values can have a custom separator character
+      long_option :flag => '--ops',
+                  :multiple => true,
+                  :separator => ','
+
+      # define any non-options (aka additional arguments)
+      non_option :tailing => true, :name => :files
+
+    end
+
+Next, create the class to represent the program you wish to interface with,
+using {RProgram::Program} as the base class:
+
+    require 'my_prog_task'
+
+    require 'rprogram/program'
+
+    class MyProg < RProgram::Program
+
+      # identify the file-name of the program
+      name_program 'my_prg'
+
+      # add a top-level method which finds and runs your program.
+      def self.my_run(options={},&block)
+        self.find.my_run(options,&block)
+      end
+
+      # add a method which runs the program with MyProgTask.
+      def my_run(options={},&block)
+        run_task(MyProgTask.new(options,&block))
+      end
+
+    end
+
+Finally, run your program with options or a block:
+
+    MyProgram.my_run(:mode => :fast, :files => ['test1'])
+    # => true
+
+    MyProgram.my_run do |my_prog|
+      my_prog.includes = ['one', 'two', 'three']
+      my_prog.mode == :safe
+
+      my_prog.output = 'output.txt'
+      my_prog.files = ['test1.txt', 'test2.txt']
+    end
+    # => true
+
+## Install
+
+    $ sudo gem install rprogram
+
+## License
+
+See {file:LICENSE.txt} for license information.
+

data/Rakefile

@@ -1,22 +1,43 @@
-# -*- ruby -*-
-
 require 'rubygems'
-require 'hoe'
-require 'hoe/signing'
-require './tasks/spec.rb'
-require './tasks/yard.rb'
+require 'rake'
+require './lib/rprogram/version.rb'
 
-Hoe.spec('rprogram') do
-  self.rubyforge_name = 'rprogram'
-  self.developer('Postmodern', 'postmodern.mod3@gmail.com')
-  self.remote_rdoc_dir = ''
+begin
+  gem 'jeweler', '~> 1.4.0'
+  require 'jeweler'
 
-  self.extra_dev_deps = [
-    ['rspec', '>=1.2.8'],
-    ['yard', '>=0.5.2']
-  ]
+  Jeweler::Tasks.new do |gem|
+    gem.name = 'rprogram'
+    gem.version = RProgram::VERSION
+    gem.summary = %Q{A library for creating wrappers around command-line programs.}
+    gem.description = %Q{RProgram is a library for creating wrappers around command-line programs. RProgram provides a Rubyful interface to programs and all their options or non-options. RProgram can also search for programs installed on a system.}
+    gem.email = 'postmodern.mod3@gmail.com'
+    gem.homepage = 'http://github.com/postmodern/rprogram'
+    gem.authors = ['Postmodern']
+    gem.add_development_dependency 'rspec', '>= 1.3.0'
+    gem.add_development_dependency 'yard', '>= 0.5.3'
+    gem.has_rdoc = 'yard'
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
 
-  self.spec_extras = {:has_rdoc => 'yard'}
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs += ['lib', 'spec']
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+  spec.spec_opts = ['--options', '.specopts']
 end
 
-# vim: syntax=Ruby
+task :spec => :check_dependencies
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yard do
+    abort "YARD is not available. In order to run yard, you must: gem install yard"
+  end
+end

data/lib/rprogram/compat.rb

@@ -16,10 +16,10 @@ module RProgram
     end
 
     #
-    # Determines the contents of the +PATH+ environment variable.
+    # Determines the contents of the `PATH` environment variable.
     #
     # @return [Array]
-    #   The contents of the +PATH+ environment variable.
+    #   The contents of the `PATH` environment variable.
     #
     # @example
     #   Compat.paths #=> ["/bin", "/usr/bin"]
@@ -109,7 +109,7 @@ module RProgram
     #   Specifies whether the program exited successfully.
     #
     # @raise [ProgramNotFound]
-    #   Indicates that the +sudo+ program could not be located.
+    #   Indicates that the `sudo` program could not be located.
     #
     # @since 0.1.8
     #

data/lib/rprogram/nameable/class_methods.rb

@@ -0,0 +1,84 @@
+module RProgram
+  module Nameable
+    module ClassMethods
+      #
+      # @return [String]
+      #   The name of the program.
+      #
+      def program_name
+        @program_name ||= nil
+      end
+
+      #
+      # @return [Array]
+      #   The program's aliases.
+      #
+      def program_aliases
+        @program_aliases ||= []
+      end
+
+      #
+      # Combines program_name with program_aliases.
+      #
+      # @return [Array]
+      #   Names the program is known by.
+      #
+      def 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 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 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 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 path=(new_path)
+        @program_path = (File.expand_path(new_path) if new_path)
+      end
+    end
+  end
+end

data/lib/rprogram/nameable/nameable.rb

@@ -0,0 +1,34 @@
+require 'rprogram/nameable/class_methods'
+require 'rprogram/compat'
+
+module RProgram
+  module Nameable
+    def self.included(base)
+      base.send :extend, ClassMethods
+    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
+  end
+end

data/lib/rprogram/nameable.rb

@@ -1,86 +1,2 @@
-require 'rprogram/extensions/meta'
-require 'rprogram/compat'
-
-module RProgram
-  module Nameable
-    def self.included(base)
-      base.metaclass_eval do
-        #
-        # @return [String]
-        #   The name of the program.
-        #
-        def program_name
-          @program_name ||= nil
-        end
-
-        #
-        # @return [Array]
-        #   The program's aliases.
-        #
-        def program_aliases
-          @program_aliases ||= []
-        end
-
-        #
-        # Combines program_name with program_aliases.
-        #
-        # @return [Array]
-        #   Names the program is known by.
-        #
-        def 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 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 alias_program(*aliases)
-          @program_aliases = aliases.map { |name| name.to_s }
-        end
-      end
-    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
-  end
-end
+require 'rprogram/nameable/class_methods'
+require 'rprogram/nameable/nameable'

data/lib/rprogram/option.rb

@@ -29,14 +29,14 @@ module RProgram
     #   The command-line flag to use.
     #
     # @option options [true, false] :equals (false)
-    #   Implies the option maybe formated as <tt>"--flag=value"</tt>.
+    #   Implies the option maybe formated as `--flag=value`.
     #
     # @option options [true, false] :multiple (false)
     #   Specifies the option maybe given an Array of values.
     #
     # @option options [String] :separator
     #   The separator to use for formating multiple arguments into one
-    #   +String+. Cannot be used with the +:multiple+ option.
+    #   `String`. Cannot be used with the `:multiple` option.
     #
     # @option options [true, false] :sub_options (false)
     #   Specifies that the option contains sub-options.

data/lib/rprogram/options/class_methods.rb

@@ -0,0 +1,112 @@
+module RProgram
+  module Options
+    module ClassMethods
+      #
+      # @return [Hash]
+      #   All defined non-options of the class.
+      #
+      def non_options
+        @non_options ||= {}
+      end
+
+      #
+      # Searches for the non-option with the matching name in the class
+      # and it's ancestors.
+      #
+      # @param [Symbol, String] name
+      #   The name to search for.
+      #
+      # @return [true, false]
+      #   Specifies whether the non-option with the matching name was
+      #   defined.
+      #
+      def has_non_option?(name)
+        name = name.to_sym
+
+        ancestors.each do |base|
+          if base.include?(RProgram::Options)
+            return true if base.non_options.include?(name)
+          end
+        end
+
+        return false
+      end
+
+      #
+      # Searches for the non-option with the matching name in the class
+      # and it's ancestors.
+      #
+      # @param [Symbol, String] name
+      #   The name to search for.
+      #
+      # @return [NonOption]
+      #   The non-option with the matching name.
+      #
+      def get_non_option(name)
+        name = name.to_sym
+
+        ancestors.each do |base|
+          if base.include?(RProgram::Options)
+            if base.non_options.has_key?(name)
+              return base.non_options[name]
+            end
+          end
+        end
+
+        return nil
+      end
+
+      #
+      # @return [Hash]
+      #   All defined options for the class.
+      #
+      def options
+        @options ||= {}
+      end
+
+      #
+      # Searches for the option with the matching name in the class and
+      # it's ancestors.
+      #
+      # @param [Symbol, String] name
+      #   The name to search for.
+      #
+      # @return [true, false]
+      #   Specifies whether the option with the matching name was defined.
+      #
+      def has_option?(name)
+        name = name.to_sym
+
+        ancestors.each do |base|
+          if base.include?(RProgram::Options)
+            return true if base.options.has_key?(name)
+          end
+        end
+
+        return false
+      end
+
+      #
+      # Searches for the option with the matching name in the class and
+      # it's ancestors.
+      #
+      # @param [Symbol, String] name
+      #   The name to search for.
+      #
+      # @return [Option]
+      #   The option with the matching name.
+      #
+      def get_option(name)
+        name = name.to_sym
+
+        ancestors.each do |base|
+          if base.include?(RProgram::Options)
+            return base.options[name] if base.options.has_key?(name)
+          end
+        end
+
+        return nil
+      end
+    end
+  end
+end