doodle 0.1.8 → 0.1.9

data/lib/doodle/app.rb

@@ -0,0 +1,445 @@
+# -*- mode: ruby; -*-
+# command line option handling DSL implemented using Doodle
+# Sean O'Halpin, 2008-09-29
+
+=begin
+
+to do:
+- add file mode to filename (or have separate file type)
+- use PathName?
+- sort out lists of things (with types)
+- apply match ~before~ from
+- handle config files
+
+=end
+
+require 'doodle'
+require 'doodle/datatypes'
+require 'time'
+require 'date'
+require 'pp'
+
+# note that all the datatypes within doodle do ... end blocks are
+# doodle/datatypes - I then go on to define specialized option types
+# with many of the same names but they are not the same - could be
+# confusing :)
+
+class Doodle
+  class App < Doodle
+    # specialised classes for handling attributes
+    def self.tidy_dir(path)
+      path.to_s.gsub(Regexp.new("^#{ Dir.pwd }/"), './')
+    end
+
+    # generic option 
+    class Option < Doodle::DoodleAttribute
+      doodle do
+        string :flag, :max => 1, :doc => "one character abbreviation" do
+          init {
+            mf = name.to_s[0].chr
+            attrs = doodle_owner.doodle.attributes.map{ |k, v| v}
+            chk_attrs = attrs.reject{ |v|
+              v.name == name
+            }
+            # note: cannot check v.flag inside default clause because that
+            # causes an infinite regress (yes, I found out the hard way! :)
+            if chk_attrs.any?{|v|
+                v.respond_to?(:flag) && v.flag == mf
+              }
+              ""
+            else
+              mf
+            end
+          }
+        end
+        integer :arity, :default => 1, :doc => "how many arguments are expected"
+        has :values, :default => [], :doc => "valid values for this option"
+        has :match, :default => nil, :doc => "regex to match against"
+      end
+    end
+    # specialied Filename attribute
+    class Filename < Option
+      doodle do
+        boolean :existing, :default => false, :doc => "set to true if file must exist"
+      end
+    end
+
+    RX_ISODATE = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(\.\d+)? ?Z$/
+    
+    # App directives
+    class << self
+      public
+      
+      has :script_name, :default => File.basename($0)
+      has :doc, :default => $0
+      has :usage do
+        default { "./#{script_name} #{required_args.map{ |a| %[-#{ a.flag } #{format_kind(a.kind)}]}.join(' ')}" + ((required_args.size - doodle.attributes.size) > 0 ? " [OPTIONS]" : '') }
+      end
+      has :examples, :default => nil
+      alias :example :examples
+
+      def required
+        @optional = false
+      end
+      def optional
+        @optional = true
+      end
+      def optional?
+        instance_variable_defined?("@optional") ? @optional : false
+      end
+      def required_args
+        doodle.attributes.select{ |k, v| v.required?}.map{ |k,v| v}
+      end
+      alias :options :optional
+
+      # the generic option - can be any type
+      def option(*args, &block)
+        #p [:option, args, :optional, optional?]
+        key_values, args = args.partition{ |x| x.kind_of?(Hash)}
+        key_values = key_values.inject({ }){ |hash, kv| hash.merge(kv)}
+        
+        errors = []
+
+        # handle optional/required flipflop
+        if optional?
+          required = { :default => nil }
+          if key_values.delete(:required)
+            if key_values.key?(:optional)
+              errors << "Can't specify both :required and :optional"
+            end
+            if key_values.key?(:default)
+              errors << "Can't specify both :required and :default"
+            end
+            required = { }
+          elsif key_values.delete(:optional) && !key_values.key?(:default)
+            required = { :default => nil }
+          end
+        else
+          key_values.delete(:required)
+          required = { }
+        end        
+        args = [{ :using => Option }.merge(required).merge(key_values), *args]
+        da = has(*args, &block)
+        if errors.size > 0
+          raise ArgumentError, "#{da.name}: #{errors.join(', ')}", [caller[-1]]
+        end
+        da.instance_eval do
+          #p [:checking_values, values, values.class]
+          if da.values.kind_of?(Range)
+            must "be in range #{da.values}" do |s|
+              da.values.include?(s)
+            end
+          elsif da.values.respond_to?(:size) && da.values.size > 0
+            must "be one of #{da.values.join(', ')}" do |s|
+              da.values.include?(s)
+            end
+          end
+          if da.match
+            must "match pattern #{da.match.inspect}" do |s|
+              #p [:matching, s, da.match.inspect]
+              s.to_s =~ da.match
+            end
+          end
+        end
+        da
+      end
+      # expect string
+      def string(*args, &block)
+        args = [{ :using => Option, :kind => String }, *args]
+        da = option(*args, &block)
+      end
+      # expect symbol
+      def symbol(*args, &block)
+        args = [{ :using => Option, :kind => Symbol }, *args]
+        da = option(*args, &block)
+        da.instance_eval do
+          from String do |s|
+            s.to_sym
+          end
+        end
+      end
+      # expect filename
+      #   filename :input, :existing => true, :flag => "i", :doc => "input file name"
+      def filename(*args, &block)
+        args = [{ :using => Filename, :kind => String }, *args ]
+        da = option(*args, &block)
+        da.instance_eval do
+          if da.existing
+            must "exist" do |s|
+              File.exist?(s)
+            end
+          end
+        end
+      end
+      # expect on/off flag, e.g. -b
+      # doesn't take any arguments (mere presence sets it to true)
+      # booleans are false by default
+      def boolean(*args, &block)
+        args = [{ :using => Option, :default => false, :arity => 0}, *args]
+        da = option(*args, &block)
+        da.instance_eval do
+          kind FalseClass, TrueClass
+          from NilClass do
+            false
+          end
+          from Numeric do |n|
+            n == 0 ? false : true
+          end
+          from String do |s|
+            case s
+            when "on", "true", "yes", "1"
+              true
+            when "off", "false", "no", "0"
+              false
+            else
+              raise Doodle::ValidationError, "unknown value for boolean: #{s}"
+            end
+          end
+        end
+      end
+      # whole number, e.g. -n 10
+      # you can use, e.g. :values => [1,2,3] or :values => (0..99) to restrict valid values
+      def integer(*args, &block)
+        args = [{ :using => Option, :kind => Integer }, *args]
+        da = option(*args, &block)
+        da.instance_eval do
+          from String do |s|
+            s =~ /^\d+$/ or raise "must be a whole number"
+            s.to_i
+          end
+        end
+      end
+      # date: -d 2008-09-28
+      def date(*args, &block)
+        args = [{ :using => Option, :kind => Date }, *args]
+        da = option(*args, &block)
+        da.instance_eval do
+          from String do |s|
+            Date.parse(s)
+          end
+        end
+      end
+      # time: -d 2008-09-28T18:00:00
+      def time(*args, &block)
+        args = [{ :using => Option, :kind => Time }, *args]
+        da = option(*args, &block)
+        da.instance_eval do
+          from String do |s|
+            Time.parse(s)
+          end
+        end
+      end
+      # utcdate: -d 2008-09-28T21:41:29Z
+      # actually uses Time (so restricted range)
+      def utcdate(*args, &block)
+        args = [{ :using => Option, :kind => Time }, *args]
+        da = option(*args, &block)
+        da.instance_eval do
+          from String do |s|
+            if s !~ RX_ISODATE
+              raise ArgumentError, "date must be in ISO format (YYYY-MM-DDTHH:MM:SS, e.g. #{Time.now.utc.xmlschema})"
+            end
+            Time.parse(s)
+          end
+        end
+      end
+
+      # use this to include 'standard' flags
+      def std_flags
+        boolean :help, :flag => "h", :doc => "display this help"
+        boolean :verbose, :flag => "v", :doc => "verbose output"
+        boolean :debug, :flag => "D", :doc => "turn on debugging"
+      end
+
+      has :exit_status, :default => 0
+      
+      # call App.run to start your application (calls instance.run)
+      def run(argv = ARGV)
+        begin
+          app = from_argv(argv)
+          if app.help
+            puts help_text
+          else
+            app.run
+          end
+        rescue Object => e
+          if exit_status == 0
+            exit_status 1
+          end
+          puts "\nERROR: #{e}"
+          puts
+          puts help_text
+        ensure
+          exit(exit_status)
+        end
+      end
+
+      private
+      
+      # helpers
+      def flag_to_attribute(flag)
+        a = doodle.attributes.select do |key, attr|
+          (key.to_s == flag.to_s) || (attr.respond_to?(:flag) && attr.flag.to_s == flag.to_s)
+        end
+        if a.size == 0
+          raise ArgumentError, "Unknown option: #{flag}"
+        elsif a.size > 1
+          #raise ArgumentError, "More than one option matches: #{flag}"
+        end
+        a.first
+      end
+      def key_value(arg, argv)
+        value = nil
+        if arg[0] == ?-
+          # got flag
+          #p [:a, 1, arg]
+          if arg[1] == ?-
+            # got --flag
+            # --key value
+            key = arg[2..-1]
+            #p [:a, 2, arg, key]
+            if key == ""
+              key = "--"
+            end
+          else
+            key = arg[1].chr
+            #p [:a, 4, key]
+            if arg[2]
+              # -kvalue
+              value = arg[2..-1]
+              #p [:a, 5, key, value]
+            end
+          end
+          pkey, attr = flag_to_attribute(key)
+          if pkey.nil?
+            raise Exception, "Internal error: #{key} does not match attribute"
+          end
+          #p [:flag_to_attribute, key, value, pkey, attr]
+          if value.nil?
+            if attr.arity == 0
+              value = true
+            else
+              #p [:args, 5, :getting_args, attr.arity]
+              value = []
+              1.upto(attr.arity) do
+                a = argv.shift
+                break if a.nil?
+                #p [:a, 6, key, value]
+                if a =~ /^-/
+                  # got a switch - break? (what should happen here?)
+                  #p [:a, 7, key, value]
+                  argv.unshift a
+                  break
+                else
+                  value << a
+                end
+              end
+              if attr.arity == 1
+                value = *value
+              end
+            end
+          end
+          if key.size == 1
+            #p [:finding, key]
+            #p [:found, pkey, attr]
+            key = pkey.to_s
+          end
+        end
+        [key, value]
+      end
+      def params_args(argv)
+        argv = argv.dup
+        params = { }
+        args = []
+        while arg = argv.shift
+          key, value = key_value(arg, argv)
+          if key.nil?
+            args << arg
+          else
+            #p [:setting, key,  value]
+            params[key] = value
+          end
+        end
+        [params, args]
+      end
+      def from_argv(argv)
+        params, args = params_args(argv)
+        args << params
+        #pp [:args, args]
+        new(*args)
+      end
+      def format_values(values)
+        case values
+        when Array
+          values.map{ |s| s.to_s }.join(', ')
+        when Range
+          values.inspect
+        else
+          values.inspect
+        end
+      end
+      def format_doc(attr)
+        #p [:doc, attr.doc]
+        doc = attr.doc
+        if doc.kind_of?(Doodle::DeferredBlock)
+          doc = doc.block
+        end
+        if doc.kind_of?(Proc)
+          doc = attr.instance_eval(&doc)
+        end
+        if doc.respond_to?(:call)
+          doc = doc.call
+        end
+        doc = doc.to_s
+        if attr.respond_to?(:values) && (attr.values.kind_of?(Range) || attr.values.size > 0)
+          doc = "#{doc} [#{format_values(attr.values)}]"
+        end
+        doc
+      end
+      def format_kind(kind)
+        if (kind & [TrueClass, FalseClass, NilClass]).size > 0
+          "Boolean"
+        else
+          kind.map{ |k| k.to_s }.join(', ')
+        end.upcase
+      end
+      def help_attributes
+        options, args = doodle.attributes.partition { |key, attr| attr.respond_to?(:flag)}
+        args = args.map { |key, attr|
+          [
+           '',
+           '',
+           format_doc(attr),
+           attr.required?,
+           format_kind(attr.kind),
+          ]
+        }
+        options = options.map { |key, attr|
+          [
+           "--#{key}",
+           attr.flag.to_s.size > 0 ? "-#{attr.flag}," : '',
+           format_doc(attr),
+           attr.required?,
+           format_kind(attr.kind),
+          ]
+        }
+        args + options
+      end
+      public
+      def help_text
+        format_block = proc {|key, flag, doc, required, kind|
+          sprintf("  %-3s %-14s %-10s %s %s", flag, key, kind, doc, required ? '(REQUIRED)' : '')
+        }
+        required, options = help_attributes.partition{ |a| a[3]}
+        [
+         self.doc,
+         "\n",
+         self.usage ? ["Usage: " + self.usage, "\n"] : [],
+         required.size > 0 ? ["Required args:", required.map(&format_block), "\n"] : [],
+         options.size > 0 ? ["Options:", options.map(&format_block), "\n"] : [],
+         (self.examples && self.examples.size > 0) ? "Examples:\n" + "  " + self.examples.join("\n  ") : [],
+        ]
+      end
+    end
+  end
+end

data/lib/doodle/datatypes.rb

@@ -3,7 +3,6 @@ $:.unshift(File.join(File.dirname(__FILE__), '.'))
 
 require 'doodle'
 
-### user code
 require 'date'
 require 'uri'
 require 'rfc822'
@@ -11,28 +10,82 @@ require 'rfc822'
 # note: this doesn't have to be in Doodle namespace
 class Doodle
   module DataTypes
+    class DataType < Doodle::DoodleAttribute
+      doodle do
+        has :values, :default => [], :doc => "valid values for this option"
+        has :match, :default => nil, :doc => "regex to match against"
+      end
+    end
+    def datatype(name, params, block, type_params, &type_block)
+      define name, params, block, { :using => DataType }.merge(type_params) do
+        #p [:self, __doodle__.__inspect__]
+        #p [:checking_values, values, values.class]
+        if respond_to?(:values)
+          if values.kind_of?(Range)
+            must "be in range #{values}" do |s|
+              values.include?(s)
+            end
+            # array of values
+          elsif values.respond_to?(:size) && values.size > 0
+            must "be one of #{values.join(', ')}" do |s|
+              values.include?(s)
+            end
+          end
+        end
+        if respond_to?(:match) && match
+          must "match pattern #{match.inspect}" do |s|
+            #p [:matching, s, da.match.inspect]
+            s.to_s =~ match
+          end
+        end
+        instance_eval(&type_block) if type_block
+      end
+    end
+
     def integer(name, params = { }, &block)
-      define name, params, block, { :kind => Integer } do
+      if params.key?(:max)
+        max = params.delete(:max)
+      end
+      if params.key?(:min)
+        min = params.delete(:min)
+      end
+      datatype name, params, block, { :kind => Integer } do
         from Float do |n|
           n.to_i
         end
         from String do |n|
-          n =~ /[0-9]+(.[0-9]+)?/ or raise ArgumentError, "#{name} must be numeric"
+          n =~ /[0-9]+(.[0-9]+)?/ or raise ArgumentError, "#{name} must be numeric", [caller[-1]]
           n.to_i
         end
+        if max
+          must "be <= #{max}" do |s|
+            s.size <= max
+          end
+        end
+        if min
+          must "be >= #{min}" do |s|
+            s.size >= min
+          end
+        end
       end
     end
 
     def boolean(name, params = { }, &block)
-      define name, params, block, { } do
+      datatype name, params, block, { :default => true } do
         must "be true or false" do |v|
           [true, false].include?(v)
         end
+        from NilClass do |v|
+          false
+        end
+        from Integer do |v|
+          v == 0 ? false : true
+        end
         from String, Symbol do |v|
           case v.to_s
-          when /^(yes|true|on)$/
+          when /^(yes|true|on|1)$/
             true
-          when /^(no|false|off)$/
+          when /^(no|false|off|0)$/
             false
           else
             v
@@ -40,18 +93,18 @@ class Doodle
         end
       end
     end
-    
+
     def symbol(name, params = { }, &block)
-      define name, params, block, { :kind => Symbol } do
+      datatype name, params, block, { :kind => Symbol } do
         from String do |s|
           s.to_sym
         end
       end
     end
-    
+
     def string(name, params = { }, &block)
       # must extract non-standard attributes before processing with
-      # define otherwise causes UnknownAttribute error in Attribute definition
+      # datatype otherwise causes UnknownAttribute error in Attribute definition
       if params.key?(:max)
         max = params.delete(:max)
       end
@@ -60,7 +113,7 @@ class Doodle
         # size should be a Range
         size.kind_of?(Range) or raise ArgumentError, "#{name}: size should be a Range", [caller[-1]]
       end
-      define name, params, block, { :kind => String } do
+      datatype name, params, block, { :kind => String } do
         from String do |s|
           s
         end
@@ -84,7 +137,7 @@ class Doodle
     end
 
     def uri(name, params = { }, &block)
-      define name, params, block, { :kind => URI } do
+      datatype name, params, block, { :kind => URI } do
         from String do |s|
           URI.parse(s)
         end
@@ -100,9 +153,9 @@ class Doodle
         end
       end
     end
-    
+
     def date(name, params = { }, &block)
-      define name, params, block, { :kind => Date } do
+      datatype name, params, block, { :kind => Date } do
         from String do |s|
           Date.parse(s)
         end
@@ -115,8 +168,46 @@ class Doodle
       end
     end
 
+    # defaults to UTC if passed an array
+    # use :timezone => :local if you want local time
+    def time(name, params = { }, &block)
+      timezone_method = params.delete(:timezone) || :utc
+      if timezone_method == :local
+        timezone_method = :mktime
+      end
+      datatype name, params, block, { :kind => Time } do
+        from String do |s|
+          Time.parse(s)
+        end
+        from Array do |*args|
+          Time.send(timezone_method, *args)
+        end
+        # seconds since Thu Jan 01 00:00:00 UTC 1970
+        from Integer do |epoch_seconds|
+          Time.at(epoch_seconds)
+        end
+      end
+    end
+
+    RX_ISODATE = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(\.\d+)? ?Z$/
+
+    def utc(name, params = { }, &block)
+      da = time( name, { :kind => Time }.merge(params))
+      da.instance_eval do
+        # override time from String
+        from String do |s|
+          if s !~ RX_ISODATE
+            raise ArgumentError, "date must be in ISO format (YYYY-MM-DDTHH:MM:SS, e.g. #{Time.now.utc.xmlschema})"
+          end
+          Time.parse(s)
+        end
+      end
+      da.instance_eval(&block) if block_given?
+      da
+    end
+
     def version(name, params = { }, &block)
-      define name, params, block, { :kind => String } do
+      datatype name, params, block, { :kind => String } do
         must "be of form n.n.n" do |str|
           str =~ /\d+\.\d+.\d+/
         end
@@ -126,6 +217,24 @@ class Doodle
         end
       end
     end
+
+    def list(name, params = { }, &block)
+      if name.kind_of?(Class)
+        params[:collect] = name
+        name = Doodle::Utils.pluralize(Doodle::Utils.snake_case(name))
+      end
+      raise ArgumentError, "#{name} must specify what to :collect", [caller[-1]] if !params.key?(:collect)
+      datatype name, params, block, { :using => Doodle::AppendableAttribute }
+    end
+
+    def dictionary(name, params = { }, &block)
+      if name.kind_of?(Class)
+        params[:collect] = name
+        name = Doodle::Utils.pluralize(Doodle::Utils.snake_case(name))
+      end
+      raise ArgumentError, "#{name} must specify what to :collect", [caller[-1]] if !params.key?(:collect)
+      datatype name, params, block, { :using => Doodle::KeyedAttribute }
+    end
   end
 end