optout 0.0.1 → 0.0.2

data/README.rdoc

@@ -20,7 +20,7 @@ arguments and define validation rules that must be met before the command line a
    :gem => "rake",
    :os => "mswin",
    :version => "0.9.2",
-   :user => true
+   :user => truep	
  }
 
  exec "gem", *optout.argv(options)
@@ -68,13 +68,30 @@ in a different format. +Optout+ accepts various configuration options that can r
   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
 
+Options can be grouped into required and optional:
+
+  Optout.options :arg_separator => "=" do 
+    required do 
+      on :in, "if"
+      on :out, "of"
+    end
+
+    optional do 
+      on :size, "size"
+      on :count, "count"
+    end
+  end
+
+  optout.shell(:in => "/dev/zero", :out => "/var/log/secure")
+  # Returns: in='/dev/zero' out='/var/log/secure'
+ 
 == Validating Options
 
 +Optout+ can validate your options too. Just specify the validation rule after the option's key or switch:
@@ -85,7 +102,7 @@ in a different format. +Optout+ accepts various configuration options that can r
   end
 
   optout = Optout.options do 
-    # Must be true, false, or nil
+    # Must be true, false, or nil (add :required => true to allow only true or false)
     on :path, "-p", Optout::Boolean
   end
 
@@ -95,20 +112,24 @@ in a different format. +Optout+ accepts various configuration options that can r
   end
 
   optout = Optout.options do 
-    # Must be a diretory under "/sshaw" and have user write permission
-    on :path, Optout::Dir.under("/home").permissions("w")
+    # Must be a diretory under "/home" and have user read and write permissions
+    on :path, Optout::Dir.under("/home").permissions("rw")
   end
 
   optout.shell(:path => "/root")
   # Raises: Optout::OptionInvalid
 
-There are plenty of other features, see {the RDoc}[http://rubydoc.info/github/sshaw/optout/frames].
+== TODOs
+
+* Proper <code>cmd.exe</code> quoting 
+* Mutually exclusive options
+* Split options i.e., <code>:jvm => %w[A B C]</code> would be created as <code>-XA -XB -XC</code>
 
 == More Info
 
 === RDoc
 
-http://rubydoc.info/github/sshaw/optout/frames
+http://rubydoc.info/github/sshaw/optout/frames (with RDoc -> YARD incompatibilities :)
 
 === Bugs
 
@@ -120,4 +141,6 @@ Skye Shaw [sshaw AT lucas.cis.temple.edu]
 
 == License
 
-Released under the MIT License: http://www.opensource.org/licenses/MIT
+Copyright (c) 2011-2012 Skye Shaw
+
+Released under the MIT License: http://www.opensource.org/licenses/MIT

data/lib/optout.rb

@@ -2,7 +2,7 @@ require "rbconfig"
 require "pathname"
 
 class Optout
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 
   class OptionError < StandardError
     attr :key
@@ -32,20 +32,26 @@ class Optout
 
   class << self
     ##
-    # Define a set of options to validate and create. 
+    # Define a set of options. 
+    # After the options are defined call Optout#argv or Optout#shell to create them.
+    # 
+    #  optz = Optout.options config do 
+    #    on :key, "-switch", ValidationRule, :multiple => false, :required => true
+    #    # ...
+    #  end        
     #
     # === Parameters
     #
     # [config     (Hash)] Configuration options
-    # [definition (Proc)] Option definitions
+    # [block      (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.
+    # [:arg_separator] Set the default argument seperator (i.e., the char used to seperate a switch from its value) for all subsequent options defined via Optout#on.
+    # [:check_keys]    If +true+ an +OptionUnknown+ error will be raised when the incoming option hash contains a key that has not been associated with an option via Optout#on.
     #                  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.
+    # [:multiple]      Set the default for all subsequent options defined via +on+. See Optout#on.
+    # [:required]      Set the default for all subsequent options defined via +on+. See Optout#on.
     #
     # === Errors
     #
@@ -59,20 +65,20 @@ class Optout
     #    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 :lib
     #    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"]
+    #  # Same as above
+    #  optz = Optout.options :check_keys => false do
+    #    required do 
+    #      on :lib
+    #      on :prefix, "--prefix" , %w{/sshaw/lib /sshaw/usr/lib}, :arg_separator => "="
+    #    end
+    #  end
     #
-
+    
     def options(config = {}, &block)
       optout = new(config)
       optout.instance_eval(&block) if block_given?
@@ -85,7 +91,8 @@ class Optout
   def initialize(args = {})
     @options = {}
     @check_keys = args.include?(:check_keys) ? args[:check_keys] : true
-    #@opt_seperator = args[:opt_seperator]
+    @required_context = option_context(:required => true)
+    @optional_context = option_context(:required => false)  
     @default_opt_options = {
       :required => args[:required],
       :multiple => args[:multiple],
@@ -98,45 +105,103 @@ class Optout
   #
   # === Parameters
   #
-  # [key     (Symbol)] The key of the option in the option hash that will passed to +shell+ or +argv+.
+  # [key     (Symbol)] The key of the option in the option hash 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]. 
+  # [rule    (Object)] Optional. Validation rule, see Optout#on@Validating.
+  # [options   (Hash)] Additional option configuration, see Optout#on@Options. 
   #
   # === Options
   #
-  # [:arg_separator] The +String+ used to separate the option's switch from its value. Defaults to <code>" "</code> (space).
+  # [:arg_separator] The +String+ used to separate the option's switch from its value. Defaults to <code>" "</code> (space). This can be set globally via Optout::options. 
   # [: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.
+  # [: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. By default multiple values are joined on a comma, you can set this to a +String+ to join on that string instead. Defaults to +false+. This can be set globally via Optout::options. 
+  # [:required] If +true+ the option must contian a value i.e., it must not be +false+ or +nil+ otherwise an <code>Optout::OptionRequired</code> exception will be raised. 
+  #		Defaults to +false+. This can be set globally via Optout::options or for a set of options via Optout#required or Optout#optional.
+  #
+  # === Errors
+  #
+  # [ArgumentError] An +ArgumentError+ is raised if +key+ is +nil+ or has already been defined
   #
   # === 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:
+  # An option's value can be restricted by a validation rule. If validation fails an Optout::OptionInvalid exception is raised. 
   #
-  # [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
+  # Validation rules will only be applied if the option hash contains a non-nil value for the given option's key.    
+  # If the option is required you must either define it in a Optout#required block or set the +:required+ option to +true+ when calling Optout#on.
   #
-  # [ArgumentError] An +ArgumentError+ is raised if +key+ is +nil+ or +key+ has already been defined
-
+  # Validation rules can be in one of the following forms:
+  #
+  # ==== Regex
+  #
+  # A pattern to match the option's value against.
+  #
+  #  on :key, /\d+/
+  #  on :key, "-switch", /\d+/
+  #
+  # ==== Array
+  #
+  # Only accept value(s) contained in the given array.
+  #
+  #  on :key, %w(item_a item_b item_c)
+  #  on :key, "-switch", %w(item_a item_b item_c)
+  #
+  # ==== Class
+  #
+  # Must be an instance of the given class. 
+  #
+  #  on :key, Fixnum
+  #  on :key, "-switch", Fixnum
+  #
+  # ==== Optout::Boolean
+  #
+  # Must be +true+ or +false+.
+  #
+  #  on :key, Optout::Boolean
+  #  on :key, "-switch", Optout::Boolean
+  #
+  # ==== Optout::File   
+  #
+  # Must be a file. Note that the file does not have to exist.
+  #
+  #  on :key, Optout::File
+  #  on :key, "-switch", Optout::File
+  #
+  # <code>Optout::File</code> has several methods that can be used to tune validation:
+  #
+  #  on :key, "-switch", Optout::File.named(/-\d{2}$/).under("/home/sshaw")
+  #
+  # In this case the file's basename must match the given regexp and exist under the given directory. See Optout::File for more info.
+  #
+  # ==== Optout::Dir
+  #
+  # Like <code>Optout::File</code> except for directories. <code>Optout::Dir</code> has several methods that can be used to tune validation, see Optout::Dir.
+  #
+  #  on :key, Optout::Dir
+  #  on :key, "-switch", Optout::Dir
+  #
+  # ==== Custom Validator
+  #
+  # A class that responds to +validate!+ and accepts a single argument containing the option (as an instance of Optout::Option).
+  #
+  #  class MyValidator
+  #    def validate!(option)
+  #      if option.empty? || option.value.size % 2 != 1
+  #        raise Optout::OptionInvalid.new(option.key, "bad option!")
+  #      end
+  #    end
+  #  end
+  # 
+  #  on :key, MyValidator.new
+  #  on :key, "-switch", MyValidator.new
+ 
   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?
+
+    key = key.to_sym
     raise ArgumentError, "option already defined: '#{key}'" if @options[key]
 
     opt_options = Hash === args.last ? @default_opt_options.merge(args.pop) : @default_opt_options.dup
@@ -146,41 +211,120 @@ class Optout
     @options[key] = Option.create(key, switch, opt_options)
   end
 
+  ##
+  # Create a set of options that are optional. This can also be set on a per option basis, see Optout#on.
+  #
+  # === Examples
+  #
+  #  optz = Optout.options do 
+  #    optional do 
+  #      on :ignore, "-i"
+  #      on :recurse, "-r"
+  #    end
+  #  end
+  #
+  #  optz.optional { on :path, Optout::File }
+
+  def optional(&block)
+    @optional_context.instance_eval(&block)
+  end
+
+  ##
+  # Create a set of options that are required. 
+  #
+  # If any +required+ option is missing from the option hash passed to Optout#argv or Optout#shell an 
+  # <code>Optout::OptionRequired</code> exception is raised. 
+  #
+  # This can also be set on a per option basis, see Optout#on.
+  #
+  # === Examples
+  #
+  #  optz = Optout.options do 
+  #    required do 
+  #      on :ignore, "-i"
+  #      on :recurse, "-r"
+  #    end
+  #  end
+  #
+  #  optz.required { on :path, Optout::File }
+  #
+
+  def required(&block)    
+    @required_context.instance_eval(&block)
+  end
+
   ##
   # Create an argument string that can be to passed to a +system+ like function.
+  # Options must first be defined via Optout#on.
   #
   # === Parameters
+  #
   # [options (Hash)] The option hash used to construct the argument string.
   #
   # === Returns
+  #
   # [String] The argument string.
   #
   # === Errors
+  #
   # See Optout#argv@Errors
+  #
+  # === Examples
+  #
+  # Create <code>"-a -b '1024' '/home/sshaw/some file'"</code>
+  #
+  #  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")
+
   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.
+  # Options must first be defined via Optout#on.
   #
   # === Parameters
+  #
   # [options (Hash)] The options hash used to construct the +argv+ array. 
   #
   # === Returns
+  #
   # [Array] The +argv+ array, each element is a +String+
   #
   # === Errors
+  #
+  # [ArgumentError] If options are not a +Hash+
   # [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.
-  
+  # 
+  # === Examples
+  #
+  # Create <code>["--prefix='/sshaw/usr/lib'", "libssl2"]</code>
+  #
+  #  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.argv(:lib      => "libssl2",
+  #            :prefix   => "/sshaw/usr/lib")
+
   def argv(options = {})
     create_options(options).map { |opt| opt.to_a }.flatten
   end
 
   private
-  def create_options(options = {})
+  def create_options(options = {})    
+    raise ArgumentError, "options must be a Hash" unless Hash === options
+
     argv = []
     options = options.dup
 
@@ -199,12 +343,24 @@ class Optout
          sort_by { |opt| opt.index }
   end
 
+  def option_context(forced_options)
+    klass = self
+    Class.new do
+      define_method(:on) do |*args|
+        options = Hash === args.last ? args.pop.dup : {}        
+        options.merge!(forced_options)
+        args << options
+        klass.on *args
+      end
+    end.new
+  end
+  
   class Option
     attr :key
     attr :value
     attr :index
 
-    ##
+    ##    
     # Creates a subclass of +Option+ 
     #
     # === Parameters
@@ -246,7 +402,7 @@ class Optout
 
     ##
     # 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>.
+    # This _does_ _not_ validate the option. You must call <code>validate!</code>.
     #
     # === Examples
     #
@@ -300,7 +456,7 @@ class Optout
     #
     # [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
+    # [OptionInvalid] The option contains a value that does not conform to the defined specification
     #
     def validate!
       @validators.each { |v| v.validate!(self) }
@@ -324,28 +480,29 @@ class Optout
     end
 
     def unix?
-      RbConfig::CONFIG["host_os"] !~ /mswin|mingw/i
+      RbConfig::CONFIG["host_os"] !~ /mswin|mingw|msys/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
+        # Note that on 1.9 calling class.name on anonymous classes (i.e., Class.new.new) returns nil
+        validator = setting.class.name.to_s  
         if validator == "Class"
-          name = setting.name.split("::", 2)
+          name = setting.name.to_s.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)
+        # Support 1.8 and 1.9, avoid String/Symbol and const_defined? differences
+        if validator.empty? || !constants.include?(validator) && !constants.include?(validator.to_sym)
           raise ArgumentError, "don't know how to validate with #{setting}"
         end
 
@@ -355,7 +512,7 @@ class Optout
 
     Base = Struct.new :setting
 
-    # Check for multiple values
+    # Checks 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?
@@ -384,6 +541,8 @@ class Optout
 
     class Array < Base
       def validate!(opt)
+        return if opt.empty?
+
         values = [opt.value].flatten
         values.each do |e|
           if !setting.include?(e)
@@ -403,7 +562,7 @@ class Optout
 
     class Class < Base
       def validate!(opt)
-        if !(setting === opt.value)
+        if !opt.empty? && !(setting === opt.value)
           raise OptionInvalid.new(opt.key, "value '#{opt.value}' must be type #{setting}")
         end
       end
@@ -412,6 +571,7 @@ class Optout
     class Boolean < Base
       def validate!(opt)
         if !(opt.value == true || opt.value == false || opt.value.nil?)
+          # TODO: Better message
           raise OptionInvalid.new(opt.key, "does not accept an argument")
         end
       end
@@ -485,6 +645,7 @@ class Optout
           @file.parent.expand_path.to_s == ::File.expand_path(@under))
       end
 
+      # TODO: Should probably make correct_type? a separate check
       def creatable?
        @file.exist? && correct_type? ||
        !@file.exist? && @file.parent.exist? && @file.parent.writable?
@@ -501,22 +662,24 @@ class Optout
 
   
   #
-  # These are shortcuts and/or marker classes used by the public interface so Validator.for()
-  # can load the equivalent validation class
+  # The following are shortcuts and/or marker classes used by Optout's public. They enable Validator.for()
+  # to load the appropriate 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. 
+  # 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
-  #
+  # 
+  # To validate directories use Optout::Dir.
+  # 
   class File
     class << self
       Validator::File::RULES.each do |r|
@@ -554,11 +717,15 @@ class Optout
       # :call-seq:
       #  permissions(symbolic_mode)
       #
-      # The option's user permissions must match the given permission(s).
+      # 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. 
+      # A <code>chmod(1)</code> symbolic mode +String+ denoting the desired permission(s).
+      # Any combination of <code>"r"</code>, <code>"w"</code> and <code>"x"</code> is supported. 
+      #
+      # Note that permissions are system dependent, certain modes might not be supported by your OS. 
 
       ##
       #
@@ -576,7 +743,9 @@ class Optout
 
   ##
   # <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:
+  # This class proivdes the same functionality for directories that Optout::File provides for files. See Optout::File for more info. 
+  #
+  # Validation rules can be combined: 
   #
   #  Optout.options do 
   #    on :path, "--path", Optout::Dir.exists.under("/tmp").named(/\d$/)
@@ -590,7 +759,14 @@ class Optout
     end
   end
 
-  class Boolean  #:nodoc:
+  ##
+  # <code>Optout::Boolean</code> is a validaton rule that can be used to check that an option's value is +true+ or +false+.
+  #
+  #  Optout.options do 
+  #    on :force, "-f", Optout::Boolean
+  #  end
+
+  class Boolean
   end
 end