doodle 0.1.9 → 0.2.0

data/lib/doodle/app.rb

@@ -1,14 +1,14 @@
 # -*- mode: ruby; -*-
-# command line option handling DSL implemented using Doodle
 # Sean O'Halpin, 2008-09-29
 
 =begin
 
-to do:
+TODO:
 - add file mode to filename (or have separate file type)
 - use PathName?
 - sort out lists of things (with types)
 - apply match ~before~ from
+  - add match to core doodle (as 'pattern' a la XMLSchema?)
 - handle config files
 
 =end
@@ -25,13 +25,16 @@ require 'pp'
 # confusing :)
 
 class Doodle
+  # command line option handling DSL implemented using Doodle
   class App < Doodle
     # specialised classes for handling attributes
+
+    # replace the full directory path with ./ where appropriate
     def self.tidy_dir(path)
-      path.to_s.gsub(Regexp.new("^#{ Dir.pwd }/"), './')
+      path.to_s.gsub(Regexp.new("^#{ Regexp.escape(Dir.pwd) }/"), './')
     end
 
-    # generic option 
+    # class representing a generic option
     class Option < Doodle::DoodleAttribute
       doodle do
         string :flag, :max => 1, :doc => "one character abbreviation" do
@@ -58,18 +61,20 @@ class Doodle
       end
     end
     # specialied Filename attribute
+    # - :existing => true|false (default = false)
     class Filename < Option
       doodle do
         boolean :existing, :default => false, :doc => "set to true if file must exist"
       end
     end
 
+    # regular expression for ISO date
     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
@@ -97,7 +102,7 @@ class Doodle
         #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
@@ -117,7 +122,7 @@ class Doodle
         else
           key_values.delete(:required)
           required = { }
-        end        
+        end
         args = [{ :using => Option }.merge(required).merge(key_values), *args]
         da = has(*args, &block)
         if errors.size > 0
@@ -143,12 +148,12 @@ class Doodle
         end
         da
       end
-      # expect string
+      # expect a string
       def string(*args, &block)
         args = [{ :using => Option, :kind => String }, *args]
         da = option(*args, &block)
       end
-      # expect symbol
+      # expect a symbol (and convert from String)
       def symbol(*args, &block)
         args = [{ :using => Option, :kind => Symbol }, *args]
         da = option(*args, &block)
@@ -158,7 +163,7 @@ class Doodle
           end
         end
       end
-      # expect filename
+      # expect a filename - set <tt>:existing => true</tt> to specify that the file must exist
       #   filename :input, :existing => true, :flag => "i", :doc => "input file name"
       def filename(*args, &block)
         args = [{ :using => Filename, :kind => String }, *args ]
@@ -171,9 +176,9 @@ class Doodle
           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
+      # expect an 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)
@@ -198,7 +203,7 @@ class Doodle
         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
+      # - you can use, e.g. :values => [1,2,3] or :values => (0..99) to restrict the range of valid values
       def integer(*args, &block)
         args = [{ :using => Option, :kind => Integer }, *args]
         da = option(*args, &block)
@@ -230,7 +235,7 @@ class Doodle
         end
       end
       # utcdate: -d 2008-09-28T21:41:29Z
-      # actually uses Time (so restricted range)
+      # - actually uses Time (so restricted range)
       def utcdate(*args, &block)
         args = [{ :using => Option, :kind => Time }, *args]
         da = option(*args, &block)
@@ -244,7 +249,7 @@ class Doodle
         end
       end
 
-      # use this to include 'standard' flags
+      # use this to include 'standard' flags: help (-h, --help), verbose (-v, --verbose) and debug (-d, --debug)
       def std_flags
         boolean :help, :flag => "h", :doc => "display this help"
         boolean :verbose, :flag => "v", :doc => "verbose output"
@@ -252,7 +257,7 @@ class Doodle
       end
 
       has :exit_status, :default => 0
-      
+
       # call App.run to start your application (calls instance.run)
       def run(argv = ARGV)
         begin
@@ -267,15 +272,13 @@ class Doodle
             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|
@@ -426,6 +429,7 @@ class Doodle
         args + options
       end
       public
+      # defines the help text displayed when option --help passed
       def help_text
         format_block = proc {|key, flag, doc, required, kind|
           sprintf("  %-3s %-14s %-10s %s %s", flag, key, kind, doc, required ? '(REQUIRED)' : '')

data/lib/doodle/version.rb

@@ -1,8 +1,8 @@
 class Doodle #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0
-    MINOR = 1
-    TINY  = 9
+    MINOR = 2
+    TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/lib/doodle/xml.rb

@@ -0,0 +1,175 @@
+require 'rubygems'
+# some prob with different versions of libxml on different platforms
+# begin
+#   require 'nokogiri'
+# rescue LoadError
+require 'rexml/document'
+# end
+
+class Doodle
+  module EscapeXML
+    ESCAPE = { '&' => '&amp;', '"' => '&quot;', '>' => '&gt;', '<' => '&lt;' }
+
+    def self.escape(s)
+      s.to_s.gsub(/[&"><]/) { |special| ESCAPE[special] }
+    end
+    def self.unescape(s)
+      ESCAPE.inject(s.to_s) do |str, (k, v)|
+        # don't use gsub! here - don't want to modify argument
+        str.gsub(v, k)
+      end
+    end
+  end
+
+  # adds to_xml and from_xml methods for serializing and deserializing
+  # Doodle object graphs to and from XML
+  #
+  # works for me but YMMV
+  module XML
+    include Utils
+    class Document < Doodle
+      include Doodle::XML
+    end
+
+    # adapter module for REXML
+    module REXMLAdapter
+
+      # return the parsed xml DOM
+      def parse_xml(xml)
+        REXML::Document.new(xml)
+      end
+
+      # test whether a node is a text node
+      def text_node?(node)
+        node.kind_of?(::REXML::Text)
+      end
+
+      # get the first XML element in the document
+      def get_root(doc)
+        # skip :REXML::XMLDecl
+        # REXML children does not properly implement shift (or pop)
+        root = doc.children.find { |el, i| el.kind_of?(REXML::Element) }
+        if root.nil?
+          raise ArgumentError, "XML document does not contain any elements"
+        else
+          root
+        end
+      end
+    end
+
+    # adapter module for Nokogiri
+    module NokogiriAdapter
+
+      # return the parsed xml DOM
+      def parse_xml(xml)
+        Nokogiri::XML(xml)
+      end
+
+      # test whether a node is a text node
+      def text_node?(node)
+        node.name == "text"
+      end
+
+      # get the first XML element in the document
+      def get_root(doc)
+        doc.children.first
+      end
+    end
+
+    if Object.const_defined?(:Nokogiri)
+      extend NokogiriAdapter
+    else
+      extend REXMLAdapter
+    end
+
+    class << self
+      # parse XML +str+ into a Doodle object graph, using +ctx+ as the
+      # root namespace (can be module or class)
+      #
+      # this is the entry point - most of the heavy lifting is done by
+      # +from_xml_elem+
+      def from_xml(ctx, str)
+        doc = parse_xml(str)
+        root = get_root(doc)
+        from_xml_elem(ctx, root)
+      end
+
+      # helper function to handle recursion
+      def from_xml_elem(ctx, root)
+        attributes = root.attributes.inject({ }) { |hash, (k, v)| hash[k] = EscapeXML.unescape(v.to_s); hash}
+        text, children = root.children.partition{ |x| text_node?(x) }
+        text = text.map{ |x| x.to_s}.reject{ |s| s =~ /^\s*$/}.join('')
+        oroot = Utils.const_lookup(root.name, ctx).new(text, attributes) {
+          from_xml_elem(root)
+        }
+        oroot
+      end
+      private :from_xml_elem
+    end
+
+    def from_xml_elem(parent)
+      children = parent.children.reject{ |x| XML.text_node?(x) }
+      children.each do |child|
+        text = child.children.select{ |x| XML.text_node?(x) }.map{ |x| x.to_s}.reject{ |s| s =~ /^\s*$/}.join('')
+        object = const_lookup(child.name)
+        method = Doodle::Utils.snake_case(Utils.normalize_const(child.name))
+        attributes = child.attributes.inject({ }) { |hash, (k, v)| hash[k] = EscapeXML.unescape(v.to_s); hash}
+        send(method, object.new(text, attributes) {
+               from_xml_elem(child)
+             })
+      end
+      #parent
+      self
+    end
+    private :from_xml_elem
+
+    # override this to define a tag name for output - the default is
+    # to use the classname (wthout namespacing)
+    def tag
+      #self.class.to_s.split(/::/)[-1].downcase
+      self.class.to_s.split(/::/)[-1]
+    end
+
+    # override this to define a specialised attributes format
+    def format_attributes(attributes)
+      if attributes.size > 0
+        " " + attributes.map{ |k, v| %[#{ k }="#{ v }"]}.join(" ")
+      else
+        ""
+      end
+    end
+
+    # override this to define a specialised tag format
+    def format_tag(tag, attributes, body)
+      if body.size > 0
+        ["<#{tag}#{format_attributes(attributes)}>", body, "</#{tag}>"]
+      else
+        ["<#{tag}#{format_attributes(attributes)} />"]
+      end.join('')
+    end
+
+    # output Doodle object graph as xml
+    def to_xml
+      body = []
+      attributes = []
+      self.doodle.attributes.map do |k, attr|
+        next if self.default?(k)
+        # arbitrary
+        if k == :_text_
+          body << self._text_
+          next
+        end
+        v = send(k)
+        if v.kind_of?(Doodle)
+          body << v.to_xml
+        elsif v.kind_of?(Array)
+          body << v.map{ |x| x.to_xml }
+        else
+          attributes << [k, EscapeXML.escape(v)]
+        end
+      end
+      format_tag(tag, attributes, body)
+    end
+  end
+end
+

data/spec/arg_order_spec.rb

@@ -82,7 +82,7 @@ describe 'arg_order' do
     it 'should specify order of positional arguments' do
       f = Bar.new 1
       f.value.should_be 1
-      f.name.should_be "bar"
+      f.name.should =~ /bar/
     end  
   end
 end

data/spec/block_init_spec.rb

@@ -4,7 +4,7 @@ require 'yaml'
 describe 'Doodle', 'block initialization of scalar attributes' do
   temporary_constant :Foo, :Bar, :Farm, :Barn, :Animal do
     before :each do
-      class Animal < Doodle
+      class ::Animal < Doodle
         has :species
       end
       class Barn < Doodle

data/spec/bugs_spec.rb

@@ -24,7 +24,7 @@ end
 describe 'Doodle', 'loading good data from yaml' do
   temporary_constant :Foo do
     before :each do
-      class Foo < Doodle
+      class ::Foo < Doodle
         has :date, :kind => Date do
           from String do |s|
             Date.parse(s)
@@ -57,7 +57,7 @@ end
 describe 'Doodle', 'loading bad data from yaml' do
   temporary_constant :Foo do
     before :each do
-      class Foo < Doodle
+      class ::Foo < Doodle
         has :date, :kind => Date do
           from String do |s|
             Date.parse(s)
@@ -83,7 +83,7 @@ end
 describe 'Doodle', 'loading bad data from yaml with default defined' do
   temporary_constant :Foo do
     before :each do
-      class Foo < Doodle
+      class ::Foo < Doodle
         has :date, :kind => Date do
           default Date.today
           from String do |s|
@@ -110,7 +110,7 @@ end
 describe Doodle, 'class attributes:' do
   temporary_constant :Foo do
     before :each do
-      class Foo < Doodle
+      class ::Foo < Doodle
         has :ivar
         class << self
           has :cvar
@@ -127,19 +127,20 @@ end
 describe Doodle, 'initializing from hashes and yaml' do
   temporary_constants :AddressLine, :Person do
     before :each do
-      class AddressLine < Doodle
+      class ::AddressLine < Doodle
         has :text, :kind => String
       end
 
-      class Person < Doodle
+      class ::Person < Doodle
         has :name, :kind => String
-        has :address, :collect => { :line => AddressLine }
+        has :address, :collect => { :line => ::AddressLine }
       end
     end
 
-    it 'should validate ouput from to_yaml' do
+    # TODO: this is a bit of a mess - split into separate specs and clarify what I'm expecting
+    it 'should validate output from to_yaml' do
 
-      yaml = %[
+      source_yaml = %[
 ---
 :address:
 - Henry Wood House
@@ -147,23 +148,26 @@ describe Doodle, 'initializing from hashes and yaml' do
 :name: Sean
 ]
 
-      person = Person(YAML.load(yaml))
+      person = Person(YAML.load(source_yaml))
       yaml = person.to_yaml
       # be careful here - Ruby yaml is finicky (spaces after class names)
       yaml = yaml.gsub(/\s*\n/m, "\n")
-#       yaml.should_be %[--- !ruby/object:Person
-# address:
-# - !ruby/object:AddressLine
-#   text: Henry Wood House
-# - !ruby/object:AddressLine
-#   text: London
-# name: Sean
-# ]
-
-      yaml.should_be "--- !ruby/object:Person\naddress:\n- !ruby/object:AddressLine\n  text: Henry Wood House\n- !ruby/object:AddressLine\n  text: London\nname: Sean\n"
+      #       yaml.should_be %[--- !ruby/object:Person
+      # address:
+      # - !ruby/object:AddressLine
+      #   text: Henry Wood House
+      # - !ruby/object:AddressLine
+      #   text: London
+      # name: Sean
+      # ]
+      loaded = YAML::load(source_yaml)
+      loaded[:name].should_be person.name
+      loaded[:address].should_be person.address.map{|x| x.text}
+      # want to compare yaml output with this but different order for every version of ruby, jruby, etc.
+      # "--- !ruby/object:Person\naddress:\n- !ruby/object:AddressLine\n  text: Henry Wood House\n- !ruby/object:AddressLine\n  text: London\nname: Sean\n"
       person = YAML.load(yaml)
       proc { person.validate! }.should_not raise_error
-      person.address.all?{ |x| x.kind_of? AddressLine }.should_be true
+      person.address.all?{ |x| x.kind_of?(AddressLine) }.should_be true
 
     end
   end
@@ -172,20 +176,20 @@ end
 describe 'Doodle', 'hiding @__doodle__' do
   temporary_constant :Foo, :Bar, :DString, :DHash, :DArray do
     before :each do
-      class Foo < Doodle
+      class ::Foo < Doodle
         has :var1, :kind => Integer
       end
-      class Bar
+      class ::Bar
         include Doodle::Core
         has :var2, :kind => Integer
       end
-      class DString < String
+      class ::DString < String
         include Doodle::Core
       end
-      class DHash < Hash
+      class ::DHash < Hash
         include Doodle::Core
       end
-      class DArray < Array
+      class ::DArray < Array
         include Doodle::Core
       end
     end
@@ -232,15 +236,15 @@ end
 describe 'Doodle', 'initalizing class level collectors' do
   temporary_constant :Menu, :KeyedMenu, :Item, :SubMenu do
     before :each do
-      class Item < Doodle
+      class ::Item < Doodle
         has :title
       end
-      class Menu < Doodle
+      class ::Menu < Doodle
         class << self
           has :items, :collect => Item
         end
       end
-      class KeyedMenu < Doodle
+      class ::KeyedMenu < Doodle
         class << self
           has :items, :collect => Item, :key => :title
         end
@@ -322,3 +326,31 @@ describe 'Doodle', 'validating required attributes after default attributes' do
     end
   end
 end
+
+describe Doodle, 'if default specified before required attributes, they are ignored if defined in block' do
+  temporary_constant :Address do
+    before :each do
+      class Address < Doodle
+        has :where, :default => "home"
+        has :city
+      end
+    end
+
+    it 'should raise an error that required attributes have not been set' do
+      proc {
+        Address do
+          city "London"
+        end
+      }.should_not raise_error
+    end
+
+    it 'should define required attributes' do
+      a = Address do
+        city "London"
+      end
+      a.city.should_be "London"
+    end
+  end
+
+end
+