optout 0.0.1

data/README.rdoc

@@ -0,0 +1,123 @@
+= Optout
+
+Optout helps you write code that will call +exec+ and +system+ like functions. It allows you to map hash keys to command line 
+arguments and define validation rules that must be met before the command line arguments are created.
+
+== Overview
+
+ require "optout"
+
+ # Create options for `gem`
+ optout = Optout.options do
+   on :gem, "install", :required => true
+   on :os, "--platform", %w(mswin cygwin mingw)
+   on :version, "-v", /\A\d+(\.\d+)*\z/
+   on :user, "--user-install"
+   on :location, "-i", Optout::Dir.exists.under(ENV["HOME"])
+ end
+
+ options = {
+   :gem => "rake",
+   :os => "mswin",
+   :version => "0.9.2",
+   :user => true
+ }
+
+ exec "gem", *optout.argv(options)
+ # Returns: ["install", "rake", "--platform", "mswin", "-v", "0.9.2", "--user-install"]
+
+ `gem #{optout.shell(options)}`
+ # Returns: "'install' 'rake' --platform 'mswin' -v '0.9.2' --user-install"
+
+== Install
+
+<code>gem install optout</code>
+
+== Defining Options
+
+Inorder to turn the incoming option hash into something useful you must tell +Optout+ a bit about your options. This is done by calling <code>Optout#on</code> and passing it the name of a key in the option hash. The simplest case is an option with no switch:
+
+  optout = Optout.options do 
+    on :path
+  end
+
+  optout.shell(:path => "/home/sshaw")
+  # Returns: '/home/sshaw'
+
+Key names can be a +Symbol+ or a +String+, +Optout+ will check for both in the option hash. 
+
+If the option has a switch it can be given after the option's key:
+
+  optout = Optout.options do 
+    on :path, "-p"
+  end
+
+  optout.shell(:path => "/home/sshaw")
+  # Returns: -p '/home/sshaw'
+
+Some programs can be finicky about the space between the switch and the value, or require options 
+in a different format. +Optout+ accepts various configuration options that can remdy this:
+
+  optout = Optout.options do 
+    on :path, "-p", :arg_separator => ""
+  end
+
+  optout.shell(:path => "/home/sshaw")
+  # Returns: -p'/home/sshaw'
+
+  optout = Optout.options do 
+    on :path, "--path", :arg_separator => "=", :required => true
+  end
+
+  optout.shell(:path => "/home/sshaw")
+  # Returns: --path='/home/sshaw'
+
+  optout.shell({})
+  # Raises: Optout::OptionRequired
+
+== Validating Options
+
++Optout+ can validate your options too. Just specify the validation rule after the option's key or switch:
+
+  optout = Optout.options do 
+    # Must match [a-z]
+    on :path, "-p", /[a-z]/
+  end
+
+  optout = Optout.options do 
+    # Must be true, false, or nil
+    on :path, "-p", Optout::Boolean
+  end
+
+  optout = Optout.options do 
+    # Must be in the given set
+    on :path, %w(/home/sshaw /Users/gatinha /Users/fofinha)
+  end
+
+  optout = Optout.options do 
+    # Must be a diretory under "/sshaw" and have user write permission
+    on :path, Optout::Dir.under("/home").permissions("w")
+  end
+
+  optout.shell(:path => "/root")
+  # Raises: Optout::OptionInvalid
+
+There are plenty of other features, see {the RDoc}[http://rubydoc.info/github/sshaw/optout/frames].
+
+== More Info
+
+=== RDoc
+
+http://rubydoc.info/github/sshaw/optout/frames
+
+=== Bugs
+
+https://github.com/sshaw/optout/issues
+
+== Author
+
+Skye Shaw [sshaw AT lucas.cis.temple.edu]
+
+== License
+
+Released under the MIT License: http://www.opensource.org/licenses/MIT

data/lib/optout.rb

@@ -0,0 +1,596 @@
+require "rbconfig"
+require "pathname"
+
+class Optout
+  VERSION = "0.0.1"
+
+  class OptionError < StandardError
+    attr :key
+    def initialize(key, message)
+      super(message)
+      @key = key
+    end
+  end
+
+  class OptionRequired < OptionError
+    def initialize(key)
+      super(key, "option required: '#{key}'")
+    end
+  end
+
+  class OptionUnknown < OptionError
+    def initialize(key)
+      super(key, "option unknown: '#{key}'")
+    end
+  end
+
+  class OptionInvalid < OptionError
+    def initialize(key, message)
+      super(key, "option invalid: #{key}; #{message}")
+    end
+  end
+
+  class << self
+    ##
+    # Define a set of options to validate and create. 
+    #
+    # === Parameters
+    #
+    # [config     (Hash)] Configuration options
+    # [definition (Proc)] Option definitions
+    #
+    # === Configuration Options
+    #
+    # [:arg_separator] Set the default for all subsequent options defined via +on+. See Optout#on@Options.
+    # [:check_keys]    If +true+ an <code>Optout::OptionUnknown</code> error will be raised when the incoming option hash contains a key that has not been associated with an option.
+    #                  Defaults to +true+.
+    # [:multiple]      Set the default for all subsequent options defined via +on+. See Optout#on@Options.
+    # [:required]      Set the default for all subsequent options defined via +on+. See Optout#on@Options.
+    #
+    # === Errors
+    #
+    # [ArgumentError] Calls to +on+ from inside a block can raise an +ArgumentError+.
+    #
+    # === Examples
+    #
+    #  optz = Optout.options do
+    #    on :all,  "-a"
+    #    on :size, "-b", /\A\d+\z/, :required => true
+    #    on :file, Optout::File.under("/home/sshaw"), :default => "/home/sshaw/tmp"
+    #  end
+    #
+    #  optz.shell(:all => true, :size => 1024, :file => "/home/sshaw/some file")
+    #  # Creates: "-a -b '1024' '/home/sshaw/some file'
+    #
+    #  optz = Optout.options :required => true, :check_keys => false do
+    #    on :lib, :index => 2
+    #    on :prefix, "--prefix" , %w{/sshaw/lib /sshaw/usr/lib}, :arg_separator => "="
+    #  end
+    #
+    #  optz.argv(:lib      => "libssl2",
+    #            :prefix   => "/sshaw/usr/lib",
+    #            :bad_key  => "No error raised because of moi")
+    #  # Creates: ["--prefix='/sshaw/usr/lib'", "libssl2"]
+    #
+
+    def options(config = {}, &block)
+      optout = new(config)
+      optout.instance_eval(&block) if block_given?
+      optout
+    end
+
+    alias :keys :options
+  end
+
+  def initialize(args = {})
+    @options = {}
+    @check_keys = args.include?(:check_keys) ? args[:check_keys] : true
+    #@opt_seperator = args[:opt_seperator]
+    @default_opt_options = {
+      :required => args[:required],
+      :multiple => args[:multiple],
+      :arg_separator => args[:arg_separator]
+    }
+  end
+
+  ##
+  # Define an option. 
+  #
+  # === Parameters
+  #
+  # [key     (Symbol)] The key of the option in the option hash that will passed to +shell+ or +argv+.
+  # [switch  (String)] Optional. The option's command line switch. If no switch is given only the option's value is output.
+  # [rule    (Object)] Optional. Validation rule, see {Validating}[rdoc-ref:#on@Validating].
+  # [options   (Hash)] Additional option configuration, see {Options}[rdoc-ref:#on@Options]. 
+  #
+  # === Options
+  #
+  # [:arg_separator] The +String+ used to separate the option's switch from its value. Defaults to <code>" "</code> (space).
+  # [:default]  The option's default value. This will be used if the option is +nil+ or +empty?+. 
+  # [:index]    The index of the option in the resulting +String+ or +Array+.
+  # [:multiple] If +true+ the option will accept multiple values. If +false+ an <code>Optout::OptionInvalid</code> error will be raised if the option 
+  # 		contains multiple values. If +true+ multiple values are joined on a comma, you can set this to a +String+ 
+  #		to join on that string instead. Defaults to +false+.
+  # [:required] If +true+ the option must contian a value i.e., it must not be +false+ or +nil+ else an <code>Optout::OptionRequired</code> error will be raised. 
+  #		Defaults to +false+.
+  # [:validator] An additional validation rule, see Validating.
+  #
+  # === Validating
+  #
+  # A Validator will only be applied if there's a value. If the option is required pass <code>:required => true</code>
+  # to +on+ when defining the option. Validation rules can be in one of the following forms:
+  #
+  # [Regular Expresion] A pattern to match the option's value against. 
+  # [An Array]  Restrict the option's value(s) to item(s) contained in the given array.
+  # [Class]  Restrict the option's value to instances of the given class. 
+  # [Optout::Boolean] Restrict the option's value to something boolean, i.e., +true+, +false+, or +nil+. 
+  # [Optout::File] The option's value must be a file. Note that the file does not have to exist. <code>Optout::File</code> has several methods that can be used to tune validation, see Optout::File.
+  # [Optout::Dir] The option's value must be a directory. <code>Optout::Dir</code> has several methods that can be used to tune validation, see Optout::Dir.
+  #  
+  # === Errors
+  #
+  # [ArgumentError] An +ArgumentError+ is raised if +key+ is +nil+ or +key+ has already been defined
+
+  def on(*args)
+    key = args.shift
+
+    # switch is optional, this could be a validation rule
+    switch = args.shift if String === args[0]
+    raise ArgumentError, "option key required" if key.nil?
+    raise ArgumentError, "option already defined: '#{key}'" if @options[key]
+
+    opt_options = Hash === args.last ? @default_opt_options.merge(args.pop) : @default_opt_options.dup
+    opt_options[:index] ||= @options.size
+    opt_options[:validator] = args.shift
+
+    @options[key] = Option.create(key, switch, opt_options)
+  end
+
+  ##
+  # Create an argument string that can be to passed to a +system+ like function.
+  #
+  # === Parameters
+  # [options (Hash)] The option hash used to construct the argument string.
+  #
+  # === Returns
+  # [String] The argument string.
+  #
+  # === Errors
+  # See Optout#argv@Errors
+  def shell(options = {})
+    create_options(options).map { |opt| opt.to_s }.join " "
+  end
+
+  ##
+  # Create an +argv+ array that can be to passed to an +exec+ like function.
+  #
+  # === Parameters
+  # [options (Hash)] The options hash used to construct the +argv+ array. 
+  #
+  # === Returns
+  # [Array] The +argv+ array, each element is a +String+
+  #
+  # === Errors
+  # [Optout::OptionRequired] The option hash is missing a required value.
+  # [Optout::OptionUnknown] The option hash contains an unknown key.
+  # [Optout::OptionInvalid] The option hash contains a value the does not conform to the defined specification.
+  
+  def argv(options = {})
+    create_options(options).map { |opt| opt.to_a }.flatten
+  end
+
+  private
+  def create_options(options = {})
+    argv = []
+    options = options.dup
+
+    @options.each do |key, klass|
+      value = options.delete(key) || options.delete(key.to_s)
+      opt = klass.new(value)
+      opt.validate!
+      argv << opt
+    end
+
+    if @check_keys && options.any?
+      raise OptionUnknown, options.keys[0]
+    end
+
+    argv.select  { |opt| !opt.empty? }.
+         sort_by { |opt| opt.index }
+  end
+
+  class Option
+    attr :key
+    attr :value
+    attr :index
+
+    ##
+    # Creates a subclass of +Option+ 
+    #
+    # === Parameters
+    #
+    # [key     (Symbol)] The hash key that will be used to lookup and create this option.
+    # [switch  (String)] Optional. 
+    # [config    (Hash)] Describe how to validate and create the option.
+    #
+    # === Examples
+    #
+    #  MyOption = Optout::Option.create(:quality, "-q", :arg_separator => "=", :validator => Fixnum)
+    #  opt = MyOption.new(75)
+    #  opt.empty? # false
+    #  opt.validate!
+    #  opt.to_s   # "-q='75'"
+    #
+    def self.create(key, *args)
+      options = Hash === args.last ? args.pop : {}
+      switch  = args.shift
+
+      Class.new(Option) do
+        define_method(:initialize) do |*v|
+          @key    = key
+          @switch = switch
+          @value  = v.shift || options[:default]
+          @joinon = String === options[:multiple] ? options[:multiple] : ","
+          @index  = options[:index].to_i
+          @separator = options[:arg_separator] || " "
+          
+          @validators = []
+          @validators << Validator::Required.new(options[:required])
+          @validators << Validator::Multiple.new(options[:multiple])
+
+          # Could be an Array..?
+          @validators << Validator.for(options[:validator]) if options[:validator]
+        end
+      end
+    end
+
+    ##
+    # Turn the option into a string that can be to passed to a +system+ like function.
+    # This _does not_ validate the option. You must call <code>validate!</code>.
+    #
+    # === Examples
+    #
+    #  MyOption = Optout::Option.create(:level, "-L", %w(fatal info warn debug))
+    #  MyOption.new("debug").to_s
+    #  # Returns: "-L 'debug'"
+    #
+    def to_s
+      opt = create_opt_array
+      if opt.any?
+        if opt.size == 1
+          opt[0] = quote(opt[0]) unless @switch
+        else
+          opt[1] = quote(opt[1])
+        end
+      end
+      opt.join(@separator)
+    end
+
+    ##
+    # Turn the option into an array that can be passed to an +exec+ like function.
+    # This _does not_ validate the option. You must call <code>validate!</code>.
+    #
+    # === Examples
+    #
+    #  MyOption = Optout::Option.create(:level, "-L", %w(fatal info warn debug))
+    #  MyOption.new("debug").to_a
+    #  # Returns: [ "-L", "debug" ]
+    #
+    def to_a
+      opt = create_opt_array
+      opt = [ opt.join(@separator) ] unless @separator =~ /\A\s+\z/
+      opt
+    end
+
+    ##
+    # Check if the option contains a value
+    #
+    # === Returns
+    #
+    # +false+ if the option's value is +false+, +nil+, or an empty +String+, +true+ otherwise.
+    #
+    def empty?
+      !@value || @value.to_s.empty?
+    end
+
+    ##
+    # Validate the option
+    #
+    # === Errors
+    #
+    # [OptionRequired] The option is missing a required value
+    # [OptionUnknown] The option contains an unknown key
+    # [OptionInvalid] The option contains a value the does not conform to the defined specification
+    #
+    def validate!
+      @validators.each { |v| v.validate!(self) }
+    end
+
+    private
+    def create_opt_array
+      opt = []
+      opt << @switch if @switch && @value
+      opt << normalize(@value) if !empty? && @value != true       # Only include @value for non-boolean options
+      opt
+    end
+
+    def quote(value)
+      if unix?
+        sprintf "'%s'", value.gsub("'") { "'\\''" }
+      else
+        # TODO: Real cmd.exe quoting
+        %|"#{value}"|
+      end
+    end
+
+    def unix?
+      RbConfig::CONFIG["host_os"] !~ /mswin|mingw/i
+    end
+
+    def normalize(value)
+      value.respond_to?(:entries) ? value.entries.join(@joinon) : value.to_s.strip
+    end
+  end
+
+  module Validator	#:nodoc: all
+    def self.for(setting)
+      if setting.respond_to?(:validate!)
+        setting
+      else
+        # Load validator based on the setting's name or the name of its class
+        validator = setting.class.name
+        if validator == "Class"
+          name = setting.name.split("::", 2)
+          validator = name[1] if name[1] && name[0] == "Optout"
+        end
+
+        # Support 1.8 and 1.9, avoid String/Symbol and const_defined? differences 
+        if !constants.include?(validator) && !constants.include?(validator.to_sym)
+          raise ArgumentError, "don't know how to validate with #{setting}"
+        end
+
+        const_get(validator).new(setting)
+      end
+    end
+
+    Base = Struct.new :setting
+
+    # Check for multiple values
+    class Multiple < Base  
+      def validate!(opt)
+        if !opt.empty? && opt.value.respond_to?(:entries) && opt.value.entries.size > 1 && !multiple_values_allowed?
+          raise OptionInvalid.new(opt.key, "multiple values are not allowed")
+        end
+      end
+
+      private
+      def multiple_values_allowed?
+        !!setting
+      end
+    end
+
+    class Required < Base
+      def validate!(opt)
+        if opt.empty? && option_required?
+          raise OptionRequired, opt.key
+        end
+      end
+
+      private
+      def option_required?
+        !!setting
+      end
+    end
+
+    class Array < Base
+      def validate!(opt)
+        values = [opt.value].flatten
+        values.each do |e|
+          if !setting.include?(e)
+            raise OptionInvalid.new(opt.key, "value '#{e}' must be one of (#{setting.join(", ")})")
+          end
+        end
+      end
+    end
+
+    class Regexp < Base
+      def validate!(opt)
+        if !opt.empty? && opt.value.to_s !~ setting
+          raise OptionInvalid.new(opt.key, "value '#{opt.value}' does not match pattern #{setting}")
+        end
+      end
+    end
+
+    class Class < Base
+      def validate!(opt)
+        if !(setting === opt.value)
+          raise OptionInvalid.new(opt.key, "value '#{opt.value}' must be type #{setting}")
+        end
+      end
+    end
+
+    class Boolean < Base
+      def validate!(opt)
+        if !(opt.value == true || opt.value == false || opt.value.nil?)
+          raise OptionInvalid.new(opt.key, "does not accept an argument")
+        end
+      end
+    end
+
+    class File < Base
+      RULES = %w|under named permissions|;
+      MODES = { "x" => :executable?, "r" => :readable?, "w" => :writable? }
+
+      RULES.each do |r|
+        define_method(r) do |arg|
+          instance_variable_set("@#{r}", arg)
+          self
+        end
+      end
+
+      def exists(wanted = true)
+        @exists = wanted
+        self
+      end
+
+      def validate!(opt)
+        return if opt.empty?
+
+        @file = Pathname.new(opt.value.to_s)
+        what  = self.class.name.split("::")[-1].downcase
+        error = case
+                when !under?
+                  "#{what} must be under '#{@under}'"
+                when !named?
+                  "#{what} name must match '#{@named}'"
+                when !permissions?
+                  "#{what} must have user permission of #{@permissions}"
+                when !exists?
+                  "#{what} '#{@file}' does not exist"
+                when !creatable?
+                  # TODO: Why can't it be created!?
+                  "can't create a #{what} at '#{@file}'"
+                end
+        raise OptionInvalid.new(opt.key, error) if error
+      end
+
+      protected
+      def correct_type?
+        @file.file?
+      end
+
+      def permissions?
+        !@permissions ||
+        exists? &&
+        @permissions.split(//).inject(true) { |can, m| can && MODES[m] && @file.send(MODES[m]) }
+      end
+
+      def exists?
+        !@exists || @file.exist? && correct_type?
+      end
+
+      def named?
+        basename = @file.basename.to_s
+        !@named ||
+        (::Regexp === @named ?
+          basename =~ @named :
+          basename == @named)
+      end
+
+      def under?
+        !@under ||
+        exists? &&
+        (::Regexp === @under ?
+          @file.parent.to_s =~ @under :
+          @file.parent.expand_path.to_s == ::File.expand_path(@under))
+      end
+
+      def creatable?
+       @file.exist? && correct_type? ||
+       !@file.exist? && @file.parent.exist? && @file.parent.writable?
+      end
+    end
+
+    class Dir < File
+      protected
+      def correct_type?
+        @file.directory?
+      end
+    end
+  end
+
+  
+  #
+  # These are shortcuts and/or marker classes used by the public interface so Validator.for()
+  # can load the equivalent validation class
+  #
+
+  ##
+  # <code>Optout::File</code> is a validaton rule that can be used to check that an option's value is a path to a file.
+  # By default <code>Optout::File</code> *does* *not* *check* that the file exists. Instead, it checks that the file's parent directory 
+  # exists. This is done so that you can validate a path that _will_ be created by the program the options are for. 
+  # If you _do_ want the file to exist just call the +exists+ method. 
+  #
+  # Validation rules can be combined:
+  #
+  #  Optout.options do 
+  #    on :path, "--path", Optout::File.exists.under("/home").named(/\.txt$/)
+  #  end
+  #
+  class File
+    class << self
+      Validator::File::RULES.each do |r|
+        define_method(r) { |arg| proxy_for.new.send(r, arg) }
+      end
+
+      ##
+      # :singleton-method: under
+      # :call-seq: 
+      #   under(path)
+      #   under(Regexp)
+      #
+      # The option must be under the given path.
+      #
+      # === Parameters
+      #
+      # This can be a +String+ denoting the parent directory or a +Regexp+ to match the parent directory against. 
+
+
+      ##
+      # :singleton-method: named
+      # :call-seq: 
+      #   named(basename)
+      #   named(Regexp)
+      #  
+      # The option's basename must match the given basename.
+      #
+      # === Parameters
+      #
+      # A +String+ denoting the basename or a +Regexp+ to match the basename against. 
+
+
+      ##
+      # :singleton-method: permissions
+      # :call-seq:
+      #  permissions(symbolic_mode)
+      #
+      # The option's user permissions must match the given permission(s).
+      #
+      # === Parameters
+      #
+      # A +String+ denoting the desired permission. Any combination of <code>"r"</code>, <code>"w"</code> and <code>"x"</code> is supported. 
+
+      ##
+      #
+      # If +wanted+ is true the file must exist. 
+      #
+      def exists(wanted = true) 
+        proxy_for.new.exists(wanted)
+      end
+
+      def proxy_for #:nodoc:
+        Validator::File
+      end
+    end
+  end
+
+  ##
+  # <code>Optout::Dir</code> is a validaton rule that can be used to check that an option's value is a path to a directory.
+  # Validation rules can be combined:
+  #
+  #  Optout.options do 
+  #    on :path, "--path", Optout::Dir.exists.under("/tmp").named(/\d$/)
+  #  end
+  #
+  # See Optout::File for a list of methods.
+  #
+  class Dir < File
+    def self.proxy_for #:nodoc:
+      Validator::Dir
+    end
+  end
+
+  class Boolean  #:nodoc:
+  end
+end
+

data/spec/optout_spec.rb

@@ -0,0 +1,380 @@
+require "optout"
+require "tempfile"
+require "fileutils"
+require "rbconfig"
+
+def create_optout(options = {})
+  Optout.options(options) do 
+    on :x, "-x" 
+    on :y, "-y"
+  end
+end
+
+def optout_option(*options)
+  Optout.options { on :x, "-x", *options }
+end
+
+class Optout
+  class Option
+    def unix?
+      true
+    end
+  end
+end
+
+shared_examples_for "something that validates files" do
+  before(:all) { @tmpdir = Dir.mktmpdir }
+  after(:all) { FileUtils.rm_rf(@tmpdir) }
+
+  def options
+    { :x => @file }
+  end
+
+  it "should not raise an exception if a file does not exist but its directory does" do          
+    file = File.join(@tmpdir, "__bad__")
+    optout = optout_option(@validator)
+    proc { optout.argv(:x => file) }.should_not raise_exception
+  end
+
+  describe "permissions" do 
+    # Only some chmod() modes work on Win
+    if RbConfig::CONFIG["host_os"] !~ /mswin|mingw/i
+      it "should raise an exception when user permissions don't match" do 
+        FileUtils.chmod(0100, @file)    
+        optout = optout_option(@validator.permissions("r"))
+        proc { optout.argv(options) }.should raise_exception(Optout::OptionInvalid, /user permission/)
+      end
+      
+      it "should not raise an exception when user permissions match" do 
+        checker = proc do |validator| 
+          proc { optout_option(validator).argv(options) }.should_not raise_exception
+        end
+        
+        FileUtils.chmod(0100, @file)
+        checker.call(@validator.permissions("x"))
+        
+        FileUtils.chmod(0200, @file)
+        checker.call(@validator.permissions("w"))
+        
+        FileUtils.chmod(0400, @file)
+        checker.call(@validator.permissions("r"))
+        
+        FileUtils.chmod(0700, @file)
+        checker.call(@validator.permissions("rwx"))
+      end
+    end
+  end
+
+  describe "exists" do 
+    it "should raise an exception if the file does not exist" do
+      optout = optout_option(@validator.exists)
+      proc { optout.argv(:x => @file + "no_file") }.should raise_exception(Optout::OptionInvalid, /does not exist/)
+      proc { optout.argv(options) }.should_not raise_exception
+    end  
+  end
+
+  describe "under a directory" do 
+    it "should raise an exception if not under the given directory" do 
+      optout = optout_option(@validator.under(File.join("wrong", "path")))
+      proc { optout.argv(options) }.should raise_exception(Optout::OptionInvalid, /must be under/)
+      
+      optout = optout_option(@validator.under(@tmpdir))
+      proc { optout.argv(options) }.should_not raise_exception
+    end
+    
+    it "should raise an exception if the parent directory does not match the given pattern" do       
+      # We need to respect the @file's type to ensure other validation rules implicitly applied by the @validator pass.
+      # First create parent dirs to validate against
+      tmp = File.join(@tmpdir, "a1", "b1")
+      FileUtils.mkdir_p(tmp)
+
+      # Then copy the target of the validation (file or directory) under the parent dir. 
+      FileUtils.cp_r(@file, tmp)
+
+      # And create the option's value
+      tmp = File.join(tmp, File.basename(@file))
+      options = { :x => tmp }
+
+      optout = optout_option(@validator.under(/X$/))
+      proc { optout.argv(options) }.should raise_exception(Optout::OptionInvalid, /must be under/)
+
+      [ %r|(/[a-z]\d){2}|, %r|[a-z]\d$| ].each do |r|
+        optout = optout_option(@validator.under(r))
+        proc { optout.argv(options) }.should_not raise_exception      
+      end
+    end
+  end
+  
+  describe "basename" do
+    it "should raise an exception if it does not equal the given value" do 
+      optout = optout_option(@validator.named("__bad__"))
+      proc { optout.argv(options) }.should raise_exception(Optout::OptionInvalid, /name must match/)
+      
+      optout = optout_option(@validator.named(File.basename(@file)))
+      proc { optout.argv(options) }.should_not raise_exception
+    end
+    
+    it "should raise an exception if it does not match the given pattern" do    
+      optout = optout_option(@validator.named(/\A-_-_-_/))
+      proc { optout.argv(options) }.should raise_exception(Optout::OptionInvalid, /name must match/)
+
+      ends_with = File.basename(@file)[/.{2}\z/]
+      optout = optout_option(@validator.named(/#{Regexp.quote(ends_with)}\z/))
+      proc { optout.argv(options) }.should_not raise_exception    
+    end
+  end
+end
+
+describe Optout do
+  describe "defining options" do
+    before(:each) { @optout = Optout.new }
+
+    it "should require the option's key" do
+      proc { @optout.on }.should raise_exception(ArgumentError, /option key required/)
+      proc { Optout.options { on } }.should raise_exception(ArgumentError, /option key required/)
+    end
+    
+    it "should not allow an option to be defined twice" do
+      @optout.on :x
+      proc { @optout.on :x }.should raise_exception(ArgumentError, /already defined/)
+      proc do
+        Optout.options do
+          on :x
+          on :x
+        end
+      end.should raise_exception(ArgumentError, /already defined/)
+    end
+  end
+
+  describe "creating options" do
+    before(:each) { @optout = create_optout }
+
+    context "as a string" do	
+      it "should only output the option's value if there's no switch" do
+        optout = Optout.options { on :x }
+        optout.shell(:x => "x").should eql("'x'")
+      end
+
+      it "should output an empty string if the option hash is empty" do
+        @optout.shell({}).should be_empty
+      end
+
+      it "should only output the option's switch if its value if true" do        
+        @optout.shell(:x => true, :y => true).should eql("-x -y")
+      end
+
+      it "should not output the option if its value is false" do        
+        @optout.shell(:x => false, :y => true).should eql("-y")
+      end
+
+      it "should only output the options that have a value" do        
+        @optout.shell(:x => "x", :y => nil).should eql("-x 'x'")
+      end
+      
+      it "should output all of the options" do        
+        @optout.shell(:x => "x", :y => "y").should eql("-x 'x' -y 'y'")
+      end
+
+      it "should escape the single quote char" do        
+        @optout.shell(:x => "' a'b'c '").should eql(%q|-x ''\'' a'\''b'\''c '\'''|)
+      end
+
+      it "should not separate switches from their value" do 
+        optout = create_optout(:arg_separator => "")
+        optout.shell(:x => "x", :y => "y").should eql("-x'x' -y'y'")
+      end
+      
+      it "should seperate all switches from their value with a '='" do
+        optout = create_optout(:arg_separator => "=")
+        optout.shell(:x => "x", :y => "y").should eql("-x='x' -y='y'")
+      end      
+
+      it "should join all options with multiple values on a delimiter" do         
+        optout = create_optout(:multiple => true)
+        optout.shell(:x => %w|a b c|, :y => "y").should eql("-x 'a,b,c' -y 'y'")
+      end
+
+      it "should join all options with multiple values on a ':'" do         
+        optout = create_optout(:multiple => ":")
+        optout.shell(:x => %w|a b c|, :y => "y").should eql("-x 'a:b:c' -y 'y'")
+      end     
+    end
+
+    context "as an array" do
+      it "should only output the option's value if there's no switch" do
+        optout = Optout.options { on :x }
+        optout.argv(:x => "x").should eql(["x"])
+      end
+
+      it "should output an empty array if the option hash is empty" do
+        @optout.argv({}).should be_empty
+      end
+
+      it "should only output the option's switch if its value if true" do
+        @optout.argv(:x => true, :y => true).should eql(["-x", "-y"])
+      end
+
+      it "should not output the option if its value is false" do
+        @optout.argv(:x => false, :y => true).should eql(["-y"])
+      end
+
+      it "should only output the options that have a value" do        
+        @optout.argv(:x => "x", :y => nil).should eql(["-x", "x"])
+      end
+
+      it "should output all of the options" do
+        @optout.argv(:x => "x", :y => "y").should eql(["-x", "x", "-y", "y"])
+      end
+
+      it "should not escape the single quote char" do        
+        @optout.argv(:x => "' a'b'c '").should eql(["-x", "' a'b'c '"])
+      end
+
+      it "should not separate switches from their value" do 
+        optout = create_optout(:arg_separator => "")
+        optout.argv(:x => "x", :y => "y").should eql(["-xx", "-yy"])
+      end
+
+      it "should seperate all of switches from their value with a '='" do
+        optout = create_optout(:arg_separator => "=") 
+        optout.argv(:x => "x", :y => "y").should eql(["-x=x", "-y=y"])
+      end
+
+      it "should join all options with multiple values on a delimiter" do         
+        optout = create_optout(:multiple => true)
+        optout.argv(:x => %w|a b c|, :y => "y").should eql(["-x", "a,b,c", "-y", "y"])
+      end
+
+      it "should join all options with multiple values on a ':'" do      
+        optout = create_optout(:multiple => ":")
+        optout.argv(:x => %w|a b c|, :y => "y").should eql(["-x", "a:b:c", "-y", "y"])
+      end     
+    end
+  end
+
+  # TODO: Check exception.key
+  describe "validation rules" do 
+    it "should raise an exception if the option hash contains an unknown key" do
+      optout = create_optout
+      proc { optout.argv(:bad => 123) }.should raise_exception(Optout::OptionUnknown)
+    end
+
+    it "should not raise an exception if the option hash contains an unknown key" do
+      optout = create_optout(:check_keys => false)
+      proc { optout.argv(:bad => 123) }.should_not raise_exception
+    end
+
+    it "should raise an exception if an option is missing" do
+      optout = create_optout(:required => true) 
+      proc { optout.argv(:x => 123) }.should raise_exception(Optout::OptionRequired, /'y'/)
+    end
+
+    it "should raise an exception if a required option is missing" do
+      optout = Optout.options do
+        on :x
+        on :y, :required => true
+      end
+
+      [ { :x => 123 }, { :x => 123, :y => false } ].each do |options|
+        proc { optout.argv(options) }.should raise_exception(Optout::OptionRequired, /'y'/)
+      end
+    end
+
+    it "should raise an exception if any option contains multiple values" do
+      optout = create_optout(:multiple => false) 
+
+      [ { :x => 123, :y => %w|a b c| },
+        { :x => 123, :y => { :a => "b", :b => "c" }} ].each do |options|
+        proc { optout.argv(options) }.should raise_exception(Optout::OptionInvalid)
+      end
+
+      # An Array with 1 value is OK
+      proc { optout.argv(:x => 123, :y => %w|a|) }.should_not raise_exception(Optout::OptionInvalid)    
+    end
+
+    it "should raise an exception if a single value option contains multiple values" do 
+      optout = Optout.options do 
+        on :x
+        on :y, :multiple => false
+      end
+
+      proc { optout.argv(:x => "x", :y => %w|a b c|) }.should raise_exception(Optout::OptionInvalid, /\by\b/)
+    end
+
+    it "should check the option's type" do
+      optout = optout_option(Float)
+      proc { optout.argv(:x => 123) }.should raise_exception(Optout::OptionInvalid, /type Float/)
+      proc { optout.argv(:x => 123.0) }.should_not raise_exception(Optout::OptionInvalid)      
+    end
+
+    it "should raise an exception if the option's value is not in the given set" do 
+      optout = optout_option(%w|sshaw skye|, :multiple => true)
+
+      [ "bob", [ "jack", "jill" ] ].each do |v|
+        proc { optout.argv(:x => v) }.should raise_exception(Optout::OptionInvalid)
+      end
+
+      [ "sshaw", [ "sshaw", "skye" ] ].each do |v|
+        proc { optout.argv(:x => v) }.should_not raise_exception
+      end
+    end
+
+    it "should raise an exception if the option's value does not match the given pattern" do 
+      optout = optout_option(/X\d{2}/)
+      proc { optout.argv(:x => "X7") }.should raise_exception(Optout::OptionInvalid, /match pattern/)
+      proc { optout.argv(:x => "X21") }.should_not raise_exception
+    end
+
+    it "should raise an exception if the option has a non-boolean value" do 
+      optout = optout_option(Optout::Boolean)
+      proc { optout.argv(:x => "x") }.should raise_exception(Optout::OptionInvalid, /does not accept/)
+      [ false, true, nil ].each do |v|
+        proc { optout.argv(:x => v) }.should_not raise_exception
+      end
+    end
+    
+    it "should call a custom validator" do
+      klass = Class.new do
+        def validate!(opt)
+          raise "raise up!"
+        end
+      end
+
+      optout = optout_option(klass.new)
+      proc { optout.argv(:x => "x") }.should raise_exception(RuntimeError, "raise up!")
+    end
+
+    it "should raise an exception if an unknown validation rule is used" do 
+      optout = optout_option("whaaaaa")
+      proc { optout.argv(:x => "x") }.should raise_exception(ArgumentError, /don't know how to validate/)
+    end
+
+    context "when validating a file" do 
+      it_should_behave_like "something that validates files"      
+
+      before(:all) do
+        @file = Tempfile.new("", @tmpdir).path
+        @validator = Optout::File
+      end
+
+      it "should raise an exception if it's not a file" do
+        optout = optout_option(@validator)
+        proc { optout.argv(:x => @tmpdir) }.should raise_exception(Optout::OptionInvalid, /can't create a file/)
+      end      
+    end
+
+    context "when validating a directory" do 
+      it_should_behave_like "something that validates files"      
+
+      before(:all) do
+        @file = Dir.mktmpdir(nil, @tmpdir)
+        @validator = Optout::Dir
+      end     
+
+      it "should raise an exception if it's not a directory" do
+        optout = optout_option(@validator)
+        proc { optout.argv(:x => Tempfile.new("", @tmpdir).path) }.should raise_exception(Optout::OptionInvalid) 
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification 
+name: optout
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Skye Shaw
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-01-04 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 59
+        segments: 
+        - 0
+        - 9
+        - 0
+        version: 0.9.0
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  type: :development
+  version_requirements: *id002
+description: "    Optout helps you write code that will call exec() and system() like functions. It allows you to map hash keys to command line \n    arguments and define validation rules that must be me before the command line options are created. \n"
+email: sshaw@lucas.cis.temple.edu
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- lib/optout.rb
+- spec/optout_spec.rb
+- README.rdoc
+homepage: http://github.com/sshaw/optout
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: "The opposite of getopt(): validate an option hash and turn it into something appropriate for exec() and system() like functions"
+test_files: 
+- spec/optout_spec.rb