doodle 0.1.8 → 0.1.9

data/History.txt

@@ -1,3 +1,55 @@
+== 0.1.9 / 2008-08-13
+- Features:
+  - to_hash
+  - doodle do .. end blocks now support #has, #from, #must and
+    #arg_order
+  - will now initialize a setter from a block by calling kind.new if
+    kind is specified and kind is a Doodle or a Proc, e.g.
+
+    class Animal
+      has :species
+    end
+    
+    class Barn
+      has :animals, :collect => Animal
+    end
+    
+    class Farm
+      has Barn
+    end
+    
+    farm = Farm do
+      # this is new - will call Barn.new(&block)
+      barn do
+        animal 'chicken'
+        animal 'pig'
+      end
+    end
+    
+    Will not try this for an attribute with :abstract => true
+    
+  - attributes now have :doc option
+  - attributes now have :abstract option - will not try to
+    auto-instantiate an object from this class
+  - attributes now have a :readonly attribute - will not allow setting
+    outside initialization
+  - Doodle::Utils
+    - deep_copy(obj)
+    - normalize_keys!(hash, recursive = false, method = :to_sym),
+      optionally recurse into child hashes
+    - symbolize_keys!(hash, recursive = false)
+    - stringify_keys!(hash, recursive = false)
+    
+- Experimental:
+  - Doodle::App for handlng command line application options
+  - doodle/datatypes - added more datatypes
+  
+- Bug fixes:
+  - fixed reversion in 0.1.8 which enabled full backtrace from within
+    doodle.rb
+  - fixed bug where required attributes defined after attributes with
+    default values were not being validated (had 'break' instead of 'next')
+
 == 0.1.8 / 2008-05-13
 - Features:
   - now applies instance level conversions (class level #from) to

data/Manifest.txt

@@ -23,6 +23,7 @@ examples/test-datatypes.rb
 examples/yaml-example.rb
 examples/yaml-example2.rb
 lib/doodle.rb
+lib/doodle/app.rb
 lib/doodle/datatypes.rb
 lib/doodle/rfc822.rb
 lib/doodle/utils.rb

data/examples/mail-datatypes.rb

@@ -60,6 +60,7 @@ class Mail < Doodle
   end
 end
 
+require 'rubygems'
 require 'highline/import'
 def prompt_for_password
   ask("Enter your password:  ") { |q| q.echo = '*' }

data/examples/mail.rb

@@ -78,7 +78,7 @@ end
 m = Mail do
   subject subject + ': Hi!'
   if rcpt = prompt
-    to      rcpt
+    to rcpt
   end
   body "Hello, world!\n"
 end

data/examples/profile-options.rb

@@ -2,7 +2,7 @@ $:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 require 'doodle'
 
 module CommandLine
-  class Base < Doodle::Base
+  class Base < Doodle
     has :name
     singleton_class do
       has :doc

data/lib/doodle.rb

@@ -1,4 +1,5 @@
 # doodle
+# -*- mode: ruby; ruby-indent-level: 2; tab-width: 2 -*- vim: sw=2 ts=2
 # Copyright (C) 2007-2008 by Sean O'Halpin
 # 2007-11-24 first version
 # 2008-04-18 latest release 0.0.12
@@ -7,13 +8,56 @@
 $:.unshift(File.dirname(__FILE__)) unless
   $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
-require 'molic_orderedhash'  # todo[replace this with own (required functions only) version]
+if RUBY_VERSION < '1.9.0'
+  require 'molic_orderedhash'  # todo[replace this with own (required functions only) version]
+else
+  # 1.9+ hashes are ordered by default
+  class Doodle
+    OrderedHash = ::Hash
+  end
+end
 
 # require Ruby 1.8.6 or higher
 if RUBY_VERSION < '1.8.6'
   raise Exception, "Sorry - doodle does not work with versions of Ruby below 1.8.6"
 end
 
+#
+# instance_exec for ruby 1.8 by Mauricio Fernandez
+# http://eigenclass.org/hiki.rb?bounded+space+instance_exec
+# thread-safe and handles frozen objects in bounded space
+#
+# (tag "ruby instance_exec")
+#
+if !Object.respond_to?(:instance_exec)
+  class Object
+    module InstanceExecHelper; end
+    include InstanceExecHelper
+    def instance_exec(*args, &block)
+      begin
+        old_critical, Thread.critical = Thread.critical, true
+        n = 0
+        methods = InstanceExecHelper.instance_methods
+        # this in order to make the lookup O(1), and name generation O(n) on the
+        # number of nested/concurrent instance_exec calls instead of O(n**2)
+        table = Hash[*methods.zip(methods).flatten]
+        n += 1 while table.has_key?(mname="__instance_exec#{n}")
+      ensure
+        Thread.critical = old_critical
+      end
+      InstanceExecHelper.module_eval{ define_method(mname, &block) }
+      begin
+        ret = send(mname, *args)
+      ensure
+        InstanceExecHelper.module_eval{ remove_method(mname) } rescue nil
+      end
+      ret
+    end
+  end
+end
+
+require 'yaml'
+
 # *doodle* is my attempt at an eco-friendly metaprogramming framework that does not
 # have pollute core Ruby objects such as Object, Class and Module.
 #
@@ -30,6 +74,9 @@ class Doodle
     def context
       Thread.current[:doodle_context] ||= []
     end
+    def parent
+      context[-1]
+    end
   end
 
   # debugging utilities
@@ -56,27 +103,90 @@ class Doodle
       end
       # from facets/string/case.rb, line 80
       def snake_case(camel_cased_word)
-        camel_cased_word.gsub(/([A-Z]+)([A-Z])/,'\1_\2').gsub(/([a-z])([A-Z])/,'\1_\2').downcase
+        camel_cased_word.to_s.gsub(/([A-Z]+)([A-Z])/,'\1_\2').gsub(/([a-z])([A-Z])/,'\1_\2').downcase
       end
       # resolve a constant of the form Some::Class::Or::Module
       def const_resolve(constant)
         constant.to_s.split(/::/).reject{|x| x.empty?}.inject(Object) { |prev, this| prev.const_get(this) }
       end
-      # convert keys to symbols - updates target hash
-      def symbolize_keys!(hash)
+      # deep copy of object (unlike shallow copy dup or clone)
+      def deep_copy(obj)
+        Marshal.load(Marshal.dump(obj))
+      end
+      # normalize hash keys using method (e.g. :to_sym, :to_s)
+      # - updates target hash
+      # - optionally recurse into child hashes
+      def normalize_keys!(hash, recursive = false, method = :to_sym)
         hash.keys.each do |key|
-          sym_key = key.respond_to?(:to_sym) ? key.to_sym : key
-          hash[sym_key] = hash.delete(key)
+          normalized_key = key.respond_to?(method) ? key.send(method) : key
+          v = hash.delete(key)
+          if recursive
+            if v.kind_of?(Hash)
+              v = normalize_keys!(v, recursive, method)
+            elsif v.kind_of?(Array)
+              v = v.map{ |x| normalize_keys!(x, recursive, method) }
+            end
+          end
+          hash[normalized_key] = v
         end
         hash
       end
+      # normalize hash keys using method (e.g. :to_sym, :to_s)
+      # - returns copy of hash
+      # - optionally recurse into child hashes
+      def normalize_keys(hash, recursive = false, method = :to_sym)
+        if recursive
+          h = deep_copy(hash)
+        else
+          h = hash.dup
+        end
+        normalize_keys!(h, recursive, method)
+      end
       # convert keys to symbols
-      def symbolize_keys(hash)
-        symbolize_keys(hash.dup)
+      # - updates target hash in place
+      # - optionally recurse into child hashes
+      def symbolize_keys!(hash, recursive = false)
+        normalize_keys!(hash, recursive, :to_sym)
+      end
+      # convert keys to symbols
+      # - returns copy of hash
+      # - optionally recurse into child hashes
+      def symbolize_keys(hash, recursive = false)
+        normalize_keys(hash, recursive, :to_sym)
+      end
+      # convert keys to strings
+      # - updates target hash in place
+      # - optionally recurse into child hashes
+      def stringify_keys!(hash, recursive = false)
+        normalize_keys!(hash, recursive, :to_s)
+      end
+      # convert keys to strings
+      # - returns copy of hash
+      # - optionally recurse into child hashes
+      def stringify_keys(hash, recursive = false)
+        normalize_keys(hash, recursive, :to_s)
+      end
+      # simple (!) pluralization - if you want fancier, override this method
+      def pluralize(string)
+        s = string.to_s
+        if s =~ /s$/
+          s + 'es'
+        else
+          s + 's'
+        end
+      end
+
+      # caller
+      def doodle_caller
+        if $DEBUG
+          caller
+        else
+          [caller[-1]]
+        end
       end
     end
   end
-  
+
   # error handling
   @@raise_exception_on_error = true
   def self.raise_exception_on_error
@@ -101,6 +211,9 @@ class Doodle
   # raised when arg_order called with incorrect arguments
   class InvalidOrderError < Exception
   end
+  # raised when try to set a readonly attribute after initialization
+  class ReadOnlyError < Exception
+  end
 
   # provides more direct access to the singleton class and a way to
   # treat singletons, Modules and Classes equally in a meta context
@@ -150,7 +263,7 @@ class Doodle
           #p [:embrace, :inherited, klass]
           klass.__send__(:embrace, other)       # n.b. closure
           klass.__send__(:include, Factory)     # is there another way to do this? i.e. not in embrace
-          super(klass) if defined?(super)
+          #super(klass) if defined?(super)
         end
       }
       sc.module_eval(&block) if block_given?
@@ -164,8 +277,11 @@ class Doodle
       arg_block = block if block_given?
       @block = arg_block
     end
+    def call(*a, &b)
+      block.call(*a, &b)
+    end
   end
-  
+
   # A Validation represents a validation rule applied to the instance
   # after initialization. Generated using the Doodle::BaseMethods#must directive.
   class Validation
@@ -182,6 +298,7 @@ class Doodle
 
   # place to stash bookkeeping info
   class DoodleInfo
+    attr_accessor :this
     attr_accessor :local_attributes
     attr_accessor :local_validations
     attr_accessor :local_conversions
@@ -192,15 +309,20 @@ class Doodle
 
     def initialize(object)
       @this = object
-      @local_attributes = OrderedHash.new
+      @local_attributes = Doodle::OrderedHash.new
       @local_validations = []
       @validation_on = true
       @local_conversions = {}
       @arg_order = []
       @errors = []
-      @parent = nil
+      #@parent = nil
+      @parent = Doodle.parent
     end
     # hide from inspect
+    m = instance_method(:inspect)
+    define_method :__inspect__ do
+      m.bind(self).call
+    end
     def inspect
       ''
     end
@@ -215,7 +337,7 @@ class Doodle
         raise(*args)
       end
     end
-    
+
     # provide an alternative inheritance chain that works for singleton
     # classes as well as modules, classes and instances
     def parents
@@ -232,7 +354,7 @@ class Doodle
       anc.select{|x| x.kind_of?(Class)}
     end
 
-    # send message to all doodle_parents and collect results 
+    # send message to all doodle_parents and collect results
     def collect_inherited(message)
       result = []
       parents.each do |klass|
@@ -247,14 +369,14 @@ class Doodle
 
     def handle_inherited_hash(tf, method)
       if tf
-        collect_inherited(method).inject(OrderedHash.new){ |hash, item|
-          hash.merge(OrderedHash[*item])
+        collect_inherited(method).inject(Doodle::OrderedHash.new){ |hash, item|
+          hash.merge(Doodle::OrderedHash[*item])
         }.merge(@this.doodle.__send__(method))
       else
         @this.doodle.__send__(method)
       end
     end
-    
+
     # returns array of Attributes
     # - if tf == true, returns all inherited attributes
     # - if tf == false, returns only those attributes defined in the current object/class
@@ -269,10 +391,10 @@ class Doodle
 
     # return class level attributes
     def class_attributes
-      attrs = OrderedHash.new
+      attrs = Doodle::OrderedHash.new
       if @this.kind_of?(Class)
-        attrs = collect_inherited(:class_attributes).inject(OrderedHash.new){ |hash, item|
-          hash.merge(OrderedHash[*item])
+        attrs = collect_inherited(:class_attributes).inject(Doodle::OrderedHash.new){ |hash, item|
+          hash.merge(Doodle::OrderedHash[*item])
         }.merge(@this.singleton_class.doodle.respond_to?(:attributes) ? @this.singleton_class.doodle.attributes : { })
         attrs
       else
@@ -287,7 +409,7 @@ class Doodle
         # as an array), whereas attributes and conversions are keyed
         # by name and kind respectively, so only the most recent
         # applies
-        
+
         local_validations + collect_inherited(:local_validations)
       else
         local_validations
@@ -311,12 +433,11 @@ class Doodle
       handle_inherited_hash(tf, :local_conversions)
     end
 
-    # fixme: move
     def initial_values(tf = true)
       attributes(tf).select{|n, a| a.init_defined? }.inject({}) {|hash, (n, a)|
         #p [:initial_values, a.name]
         hash[n] = case a.init
-                  when NilClass, TrueClass, FalseClass, Fixnum, Float, Bignum
+                  when NilClass, TrueClass, FalseClass, Fixnum, Float, Bignum, Symbol
                     # uncloneable values
                     #p [:initial_values, :special, a.name, a.init]
                     a.init
@@ -333,7 +454,7 @@ class Doodle
                     begin
                       a.init.clone
                     rescue Exception => e
-                      warn "tried to clone #{a.init.class} in :init option"
+                      warn "tried to clone #{a.init.class} in :init option (#{e})"
                       #p [:initial_values, :exception, a.name, e]
                       a.init
                     end
@@ -341,10 +462,9 @@ class Doodle
         hash
       }
     end
-    
+
     # turn off validation, execute block, then set validation to same
     # state as it was before +defer_validation+ was called - can be nested
-    # fixme: move
     def defer_validation(&block)
       old_validation = self.validation_on
       self.validation_on = false
@@ -360,12 +480,12 @@ class Doodle
 
     # helper function to initialize from hash - this is safe to use
     # after initialization (validate! is called if this method is
-    # called after initialization) 
+    # called after initialization)
     def initialize_from_hash(*args)
-      #!p [:doodle_initialize_from_hash, :args, *args]
+      # p [:doodle_initialize_from_hash, :args, *args]
       defer_validation do
         # hash initializer
-        # separate into array of hashes of form [{:k1 => v1}, {:k2 => v2}] and positional args 
+        # separate into array of hashes of form [{:k1 => v1}, {:k2 => v2}] and positional args
         key_values, args = args.partition{ |x| x.kind_of?(Hash)}
         #DBG: Doodle::Debug.d { [self.class, :doodle_initialize_from_hash, :key_values, key_values, :args, args] }
         #!p [self.class, :doodle_initialize_from_hash, :key_values, key_values, :args, args]
@@ -373,7 +493,7 @@ class Doodle
         # set up initial values with ~clones~ of specified values (so not shared between instances)
         #init_values = initial_values
         #!p [:init_values, init_values]
-        
+
         # match up positional args with attribute names (from arg_order) using idiom to create hash from array of assocs
         #arg_keywords = init_values.merge(Hash[*(Utils.flatten_first_level(self.class.arg_order[0...args.size].zip(args)))])
         arg_keywords = Hash[*(Utils.flatten_first_level(self.class.arg_order[0...args.size].zip(args)))]
@@ -390,7 +510,7 @@ class Doodle
         Doodle::Utils.symbolize_keys!(key_values)
         #DBG: Doodle::Debug.d { [self.class, :doodle_initialize_from_hash, :key_values2, key_values, :args2, args] }
         #!p [self.class, :doodle_initialize_from_hash, :key_values3, key_values]
-        
+
         # create attributes
         key_values.keys.each do |key|
           #DBG: Doodle::Debug.d { [self.class, :doodle_initialize_from_hash, :setting, key, key_values[key]] }
@@ -399,19 +519,20 @@ class Doodle
             __send__(key, key_values[key])
           else
             # raise error if not defined
-            __doodle__.handle_error key, Doodle::UnknownAttributeError, "unknown attribute '#{key}' #{key_values[key].inspect}", (caller)
+            __doodle__.handle_error key, Doodle::UnknownAttributeError, "unknown attribute '#{key}' => #{key_values[key].inspect} for #{self} #{doodle.attributes.map{ |k,v| k.inspect}.join(', ')}", Doodle::Utils.doodle_caller
           end
         end
         # do init_values after user supplied values so init blocks can depend on user supplied values
         #p [:getting_init_values, instance_variables]
         __doodle__.initial_values.each do |key, value|
           if !key_values.key?(key) && respond_to?(key)
+            #p [:initial_values, key, value]
             __send__(key, value)
           end
         end
       end
     end
-    
+
   end
 
   # what it says on the tin :) various hacks to hide @__doodle__ variable
@@ -432,6 +553,7 @@ class Doodle
     end
   end
 
+  # implements the #doodle directive
   class DataTypeHolder
     attr_accessor :klass
     def initialize(klass, &block)
@@ -445,8 +567,23 @@ class Doodle
         td
       }
     end
+    def has(*args, &block)
+      @klass.class_eval { has(*args, &block) }
+    end
+    def must(*args, &block)
+      @klass.class_eval { must(*args, &block) }
+    end
+    def from(*args, &block)
+      @klass.class_eval { from(*args, &block) }
+    end
+    def arg_order(*args, &block)
+      @klass.class_eval { arg_order(*args, &block) }
+    end
+    def doc(*args, &block)
+      @klass.class_eval { doc(*args, &block) }
+    end
   end
-  
+
   # the core module of Doodle - however, to get most facilities
   # provided by Doodle without inheriting from Doodle, include
   # Doodle::Core, not this module
@@ -483,7 +620,7 @@ class Doodle
         dh.instance_eval(&block)
       end
     end
-    
+
     # helper for Marshal.dump
     def marshal_dump
       # note: perhaps should also dump singleton attribute definitions?
@@ -500,6 +637,7 @@ class Doodle
     # (using args and/or block)
     # fixme: move
     def getter_setter(name, *args, &block)
+      #p [:getter_setter, name]
       name = name.to_sym
       if block_given? || args.size > 0
         #!p [:getter_setter, :setter, name, *args]
@@ -525,7 +663,7 @@ class Doodle
         # (e.g. arrays that disappear when you go out of scope)
         att = __doodle__.lookup_attribute(name)
         # special case for class/singleton :init
-        if att.optional?
+        if att && att.optional?
           optional_value = att.init_defined? ? att.init : att.default
           #p [:optional_value, optional_value]
           case optional_value
@@ -543,31 +681,81 @@ class Doodle
           v
         else
           # This is an internal error (i.e. shouldn't happen)
-          __doodle__.handle_error name, NoDefaultError, "'#{name}' has no default defined", (caller)
+          __doodle__.handle_error name, NoDefaultError, "'#{name}' has no default defined", Doodle::Utils.doodle_caller
         end
       end
     end
     private :_getter
 
+    def after_update(params)
+    end
+
+    def ivar_set(name, *args)
+      ivar = "@#{name}"
+      if instance_variable_defined?(ivar)
+        old_value = instance_variable_get(ivar)
+      else
+        old_value = nil
+      end
+      instance_variable_set(ivar, *args)
+      new_value = instance_variable_get(ivar)
+      if new_value != old_value
+        #pp [Doodle, :after_update, { :instance => self, :name => name, :old_value => old_value, :new_value => new_value }]
+        after_update :instance => self, :name => name, :old_value => old_value, :new_value => new_value
+      end
+    end
+    private :ivar_set
+
     # set an attribute by name - apply validation if defined
     # fixme: move
     def _setter(name, *args, &block)
       ##DBG: Doodle::Debug.d { [:_setter, name, args] }
       #p [:_setter, name, *args]
-      ivar = "@#{name}"
+      #ivar = "@#{name}"
+      att = __doodle__.lookup_attribute(name)
+      if att && doodle.validation_on && att.readonly
+        raise Doodle::ReadOnlyError, "Trying to set a readonly attribute: #{att.name}", Doodle::Utils.doodle_caller
+      end
       if block_given?
-        args.unshift(DeferredBlock.new(block))
+        # if a class has been defined, let's assume it can take a
+        # block initializer (test that it's a Doodle or Proc)
+        if att.kind && !att.abstract && klass = att.kind.first
+          if [Doodle, Proc].any?{ |c| klass <= c }
+            # p [:_setter, '# 1 converting arg to value with kind ' + klass.to_s]
+            args = [klass.new(*args, &block)]
+          else
+            __doodle__.handle_error att.name, ArgumentError, "#{klass} #{att.name} does not take a block initializer", Doodle::Utils.doodle_caller
+          end
+        else
+          # this is used by init do ... block
+          args.unshift(DeferredBlock.new(block))
+        end
+        #elsif
       end
-      if att = __doodle__.lookup_attribute(name)
-        ##DBG: Doodle::Debug.d { [:_setter, name, args] }
+      if att # = __doodle__.lookup_attribute(name)
+        if att.kind && !att.abstract && klass = att.kind.first
+          if !args.first.kind_of?(klass) && [Doodle].any?{ |c| klass <= c }
+            #p [:_setter, "#2 converting arg #{att.name} to value with kind #{klass.to_s}"]
+            #p [:_setter, args]
+            begin
+              args = [klass.new(*args, &block)]
+            rescue Object => e
+              __doodle__.handle_error att.name, e.class, e.to_s, Doodle::Utils.doodle_caller
+            end
+          end
+        end
+        #  args = [klass.new(*args, &block)]        ##DBG: Doodle::Debug.d { [:_setter, name, args] }
         #p [:_setter, :got_att1, name, ivar, *args]
-        v = instance_variable_set(ivar, att.validate(self, *args))
+        #        v = instance_variable_set(ivar, att.validate(self, *args))
+        v = ivar_set(name, att.validate(self, *args))
+
         #p [:_setter, :got_att2, name, ivar, :value, v]
         #v = instance_variable_set(ivar, *args)
       else
         #p [:_setter, :no_att, name, *args]
         ##DBG: Doodle::Debug.d { [:_setter, "no attribute"] }
-        v = instance_variable_set(ivar, *args)
+        #        v = instance_variable_set(ivar, *args)
+        v = ivar_set(name, *args)
       end
       validate!(false)
       v
@@ -590,41 +778,36 @@ class Doodle
 
     # add a validation
     def must(constraint = 'be valid', &block)
-      if block.nil?
-        # is this really useful? do I really want it?
-        __doodle__.local_validations << Validation.new(constraint, &proc { |v| v.instance_eval(constraint) })
-      else
-        __doodle__.local_validations << Validation.new(constraint, &block)
-      end
+      __doodle__.local_validations << Validation.new(constraint, &block)
     end
 
     # add a validation that attribute must be of class <= kind
     def kind(*args, &block)
-      @kind ||= []
       if args.size > 0
         @kind = [args].flatten
         # todo[figure out how to handle kind being specified twice?]
         if @kind.size > 2
-          kind_text = "a kind of #{ @kind[0..-2].map{ |x| x.to_s }.join(', ') } or #{@kind[-1].to_s}" # => 
+          kind_text = "be a kind of #{ @kind[0..-2].map{ |x| x.to_s }.join(', ') } or #{@kind[-1].to_s}" # =>
         else
-          kind_text = "a kind of #{@kind.to_s}"
+          kind_text = "be a kind of #{@kind.to_s}"
         end
         __doodle__.local_validations << (Validation.new(kind_text) { |x| @kind.any? { |klass| x.kind_of?(klass) } })
       else
-        @kind
+        @kind ||= []
       end
     end
 
     # convert a value according to conversion rules
     # fixme: move
     def convert(owner, *args)
-      #!p [:convert, 1, owner, args, __doodle__.conversions]
+      #pp( { :convert => 1, :owner => owner, :args => args, :conversions => __doodle__.conversions } )
       begin
         args = args.map do |value|
           #!p [:convert, 2, value]
           if (converter = __doodle__.conversions[value.class])
-            #!p [:convert, 3, value]
-            value = converter[*args]
+            #p [:convert, 3, value, self, caller]
+            value = converter[value]
+            #value = instance_exec(value, &converter)
             #!p [:convert, 4, value]
           else
             #!p [:convert, 5, value]
@@ -641,22 +824,24 @@ class Doodle
               #!p [:convert, 10, converter_class]
               if converter = __doodle__.conversions[converter_class]
                 #!p [:convert, 11, converter]
-                value = converter[*args]
+                value = converter[value]
+                #value = instance_exec(value, &converter)
                 #!p [:convert, 12, value]
               end
             else
-              #!p [:convert, 13, :kind, kind, name, value] 
+              #!p [:convert, 13, :kind, kind, name, value]
               mappable_kinds = kind.select{ |x| x <= Doodle::Core }
-              #!p [:convert, 13.1, :kind, kind, mappable_kinds] 
+              #!p [:convert, 13.1, :kind, kind, mappable_kinds]
               if mappable_kinds.size > 0
                 mappable_kinds.each do |mappable_kind|
-                  #!p [:convert, 14, :kind_is_a_doodle, value.class, mappable_kind, mappable_kind.doodle.conversions, args] 
+                  #!p [:convert, 14, :kind_is_a_doodle, value.class, mappable_kind, mappable_kind.doodle.conversions, args]
                   if converter = mappable_kind.doodle.conversions[value.class]
-                    #!p [:convert, 15, value, mappable_kind, args] 
-                    value = converter[*args]
+                    #!p [:convert, 15, value, mappable_kind, args]
+                    value = converter[value]
+                    #value = instance_exec(value, &converter)
                     break
                   else
-                    #!p [:convert, 16, :no_conversion_for, value.class] 
+                    #!p [:convert, 16, :no_conversion_for, value.class]
                   end
                 end
               else
@@ -668,7 +853,7 @@ class Doodle
           value
         end
       rescue Exception => e
-        owner.__doodle__.handle_error name, ConversionError, "#{e.message}", (caller)
+        owner.__doodle__.handle_error name, ConversionError, "#{e.message}", Doodle::Utils.doodle_caller
       end
       if args.size > 1
         args
@@ -681,26 +866,26 @@ class Doodle
     # fixme: move
     def validate(owner, *args)
       ##DBG: Doodle::Debug.d { [:validate, self, :owner, owner, :args, args ] }
-      #!p [:validate, 1, args]
+      #p [:validate, 1, args]
       begin
         value = convert(owner, *args)
       rescue Exception => e
-        owner.__doodle__.handle_error name, ConversionError, "#{owner.kind_of?(Class) ? owner : owner.class}.#{ name } - #{e.message}", (caller)
+        owner.__doodle__.handle_error name, ConversionError, "#{owner.kind_of?(Class) ? owner : owner.class}.#{ name } - #{e.message}", Doodle::Utils.doodle_caller
       end
-      #!p [:validate, 2, args, :becomes, value]
+      #p [:validate, 2, args, :becomes, value]
       __doodle__.validations.each do |v|
         ##DBG: Doodle::Debug.d { [:validate, self, v, args, value] }
         if !v.block[value]
-          owner.__doodle__.handle_error name, ValidationError, "#{owner.kind_of?(Class) ? owner : owner.class}.#{ name } must #{ v.message } - got #{ value.class }(#{ value.inspect })", (caller)
+          owner.__doodle__.handle_error name, ValidationError, "#{owner.kind_of?(Class) ? owner : owner.class}.#{ name } must #{ v.message } - got #{ value.class }(#{ value.inspect })", Doodle::Utils.doodle_caller
         end
       end
-      #!p [:validate, 3, value]
+      #p [:validate, 3, value]
       value
     end
 
     # define a getter_setter
     # fixme: move
-    def define_getter_setter(name, *args, &block)      
+    def define_getter_setter(name, params = { }, &block)
       # need to use string eval because passing block
       sc_eval "def #{name}(*args, &block); getter_setter(:#{name}, *args, &block); end", __FILE__, __LINE__
       sc_eval "def #{name}=(*args, &block); _setter(:#{name}, *args); end", __FILE__, __LINE__
@@ -717,6 +902,16 @@ class Doodle
     end
     private :define_getter_setter
 
+    # +doc+ add docs to doodle class or attribute
+    def doc(*args, &block)
+      if args.size > 0
+        @doc = *args
+      else
+        @doc
+      end
+    end
+    alias :doc= :doc
+
     # +has+ is an extended +attr_accessor+
     #
     # simple usage - just like +attr_accessor+:
@@ -738,33 +933,33 @@ class Doodle
     #      default { Date.today }
     #    end
     #  end
-    #    
+    #
     def has(*args, &block)
       #DBG: Doodle::Debug.d { [:has, self, self.class, args] }
-      
+
       params = DoodleAttribute.params_from_args(self, *args)
       # get specialized attribute class or use default
       attribute_class = params.delete(:using) || DoodleAttribute
 
       # could this be handled in DoodleAttribute?
       # define getter setter before setting up attribute
-      define_getter_setter params[:name], *args, &block
+      define_getter_setter params[:name], params, &block
       #p [:attribute, attribute_class, params]
-      __doodle__.local_attributes[params[:name]] = attribute_class.new(params, &block)
+      attr = __doodle__.local_attributes[params[:name]] = attribute_class.new(params, &block)
     end
-    
+
     # define order for positional arguments
     def arg_order(*args)
       if args.size > 0
         begin
           args = args.uniq
           args.each do |x|
-            __doodle__.handle_error :arg_order, ArgumentError, "#{x} not a Symbol", (caller) if !(x.class <= Symbol)
-            __doodle__.handle_error :arg_order, NameError, "#{x} not an attribute name", (caller) if !doodle.attributes.keys.include?(x)
+            __doodle__.handle_error :arg_order, ArgumentError, "#{x} not a Symbol", Doodle::Utils.doodle_caller if !(x.class <= Symbol)
+            __doodle__.handle_error :arg_order, NameError, "#{x} not an attribute name", Doodle::Utils.doodle_caller if !doodle.attributes.keys.include?(x)
           end
           __doodle__.arg_order = args
         rescue Exception => e
-          __doodle__.handle_error :arg_order, InvalidOrderError, e.to_s, (caller)
+          __doodle__.handle_error :arg_order, InvalidOrderError, e.to_s, Doodle::Utils.doodle_caller
         end
       else
         __doodle__.arg_order + (__doodle__.attributes.keys - __doodle__.arg_order)
@@ -799,29 +994,29 @@ class Doodle
             # if all == true, reset values so conversions and
             # validations are applied to raw instance variables
             # e.g. when loaded from YAML
-            if all
+            if all && !att.readonly
               ##DBG: Doodle::Debug.d { [:validate!, :sending, att.name, instance_variable_get(ivar_name) ] }
               __send__("#{att.name}=", instance_variable_get(ivar_name))
             end
           elsif att.optional?   # treat default/init as special case
             ##DBG: Doodle::Debug.d { [:validate!, :optional, name ]}
-            break
+            next
           elsif self.class != Class
-            __doodle__.handle_error name, Doodle::ValidationError, "#{self} missing required attribute '#{name}'", (caller)
+            __doodle__.handle_error name, Doodle::ValidationError, "#{self} missing required attribute '#{name}'", Doodle::Utils.doodle_caller
           end
         end
-        
+
         # now apply instance level validations
-        
+
         ##DBG: Doodle::Debug.d { [:validate!, "validations", doodle_validations ]}
         __doodle__.validations.each do |v|
           ##DBG: Doodle::Debug.d { [:validate!, self, v ] }
           begin
             if !instance_eval(&v.block)
-              __doodle__.handle_error self, ValidationError, "#{ self.class } must #{ v.message }", (caller)
+              __doodle__.handle_error self, ValidationError, "#{ self.class } must #{ v.message }", Doodle::Utils.doodle_caller
             end
           rescue Exception => e
-            __doodle__.handle_error self, ValidationError, e.to_s, (caller)
+            __doodle__.handle_error self, ValidationError, e.to_s, Doodle::Utils.doodle_caller
           end
         end
       end
@@ -837,13 +1032,29 @@ class Doodle
         super
       end
       __doodle__.validation_on = true
-      __doodle__.parent = Doodle.context[-1]
+      #p [:doodle_parent, Doodle.parent, caller[-1]]
       Doodle.context.push(self)
       __doodle__.defer_validation do
         doodle.initialize_from_hash(*args)
         instance_eval(&block) if block_given?
       end
       Doodle.context.pop
+      #p [:doodle, __doodle__.__inspect__]
+      #p [:doodle, __doodle__.attributes]
+      #p [:doodle_parent, __doodle__.parent]
+    end
+
+    # create 'pure' hash of scalars only from attributes - hacky but works fine
+    def to_hash
+      Doodle::Utils.symbolize_keys!(YAML::load(to_yaml.gsub(/!ruby\/object:.*$/, '')) || { }, true)
+      #begin
+      #  YAML::load(to_yaml.gsub(/!ruby\/object:.*$/, '')) || { }
+      #rescue Object => e
+      #  doodle.attributes.inject({}) {|hash, (name, attribute)| hash[name] = send(name); hash}
+      #end
+    end
+    def to_string_hash
+      Doodle::Utils.stringify_keys!(YAML::load(to_yaml.gsub(/!ruby\/object:.*$/, '')) || { }, true)
     end
 
   end
@@ -856,10 +1067,10 @@ class Doodle
   # As the notion of a factory function is somewhat contentious [xref
   # ruby-talk], you need to explicitly ask for them by including Factory
   # in your base class:
-  #   class Base < Doodle::Root
+  #   class Animal < Doodle
   #     include Factory
   #   end
-  #   class Dog < Base
+  #   class Dog < Animal
   #   end
   #   stimpy = Dog(:name => 'Stimpy')
   # etc.
@@ -880,8 +1091,8 @@ class Doodle
                            rescue Object
                              false
                            end
-          
-          if name =~ Factory::RX_IDENTIFIER && !method_defined && !klass.respond_to?(name) && !eval("respond_to?(:#{name})", TOPLEVEL_BINDING) 
+
+          if name =~ Factory::RX_IDENTIFIER && !method_defined && !klass.respond_to?(name) && !eval("respond_to?(:#{name})", TOPLEVEL_BINDING)
             eval("def #{ name }(*args, &block); ::#{name}.new(*args, &block); end", ::TOPLEVEL_BINDING, __FILE__, __LINE__)
           end
         else
@@ -915,11 +1126,9 @@ class Doodle
       }
     end
   end
-  # deprecated
-  Helper = Core
 
-  # deprecated
-  class Base
+  # wierd 1.9 shit
+  class IAmNotUsedBut1_9GoesIntoAnInfiniteRegressInInspectIfIAmNotDefined
     include Core
   end
   include Core
@@ -934,6 +1143,7 @@ class Doodle
   class DoodleAttribute < Doodle
     # note: using extend with a module causes an infinite loop in 1.9
     # hence the inline
+
     class << self
       # rewrite rules for the argument list to #has
       def params_from_args(owner, *args)
@@ -953,15 +1163,15 @@ class Doodle
         params = key_values.inject(params){ |acc, item| acc.merge(item)}
         #DBG: Doodle::Debug.d { [:has, self, self.class, params] }
         if !params.key?(:name)
-          __doodle__.handle_error name, ArgumentError, "#{self.class} must have a name", (caller)
+          __doodle__.handle_error name, ArgumentError, "#{self.class} must have a name", Doodle::Utils.doodle_caller
           params[:name] = :__ERROR_missing_name__
         else
           # ensure that :name is a symbol
           params[:name] = params[:name].to_sym
         end
         name = params[:name]
-        __doodle__.handle_error name, ArgumentError, "#{self.class} has too many arguments", (caller) if positional_args.size > 0
-        
+        __doodle__.handle_error name, ArgumentError, "#{self.class} has too many arguments", Doodle::Utils.doodle_caller if positional_args.size > 0
+
         if collector = params.delete(:collect)
           if !params.key?(:using)
             if params.key?(:key)
@@ -1035,6 +1245,15 @@ class Doodle
     # special case - not an attribute
     define_getter_setter :doodle_owner
 
+    # temporarily fake existence of abstract attribute - later has
+    # :abstract overrides this
+    def abstract
+      @abstract = false
+    end
+    def readonly
+      false
+    end
+
     # name of attribute
     has :name, :kind => Symbol do
       from String do |s|
@@ -1048,13 +1267,21 @@ class Doodle
     # initial value
     has :init, :default => nil
 
+    # documentation
+    has :doc, :default => ""
+
+    # don't try to initialize from this class
+    remove_method(:abstract) # because we faked it earlier - remove to avoid redefinition warning
+    has :abstract, :default => false
+    remove_method(:readonly) # because we faked it earlier - remove to avoid redefinition warning
+    has :readonly, :default => false
   end
 
   # base class for attribute collector classes
   class AttributeCollector < DoodleAttribute
     has :collector_class
     has :collector_name
-    
+
     def resolve_collector_class
       if !collector_class.kind_of?(Class)
         self.collector_class = Doodle::Utils.const_resolve(collector_class)
@@ -1074,7 +1301,7 @@ class Doodle
       define_collection
       from Hash do |hash|
         resolve_collector_class
-        hash.inject({ }) do |h, (key, value)|
+        hash.inject(self.init.clone) do |h, (key, value)|
           h[key] = resolve_value(value)
           h
         end
@@ -1085,12 +1312,13 @@ class Doodle
       end
     end
     def post_process(results)
-      results
+      self.init.clone.replace(results)
     end
   end
 
   # define collector methods for array-like attribute collectors
   class AppendableAttribute < AttributeCollector
+    #    has :init, :init => DoodleArray.new
     has :init, :init => []
 
     # define a collector for appendable collections
@@ -1113,16 +1341,17 @@ class Doodle
                         end", __FILE__, __LINE__)
       end
     end
-    
+
   end
 
   # define collector methods for hash-like attribute collectors
   class KeyedAttribute < AttributeCollector
+    #    has :init, :init => DoodleHash.new
     has :init, :init => { }
     has :key
 
     def post_process(results)
-      results.inject({ }) do |h, result|
+      results.inject(self.init.clone) do |h, result|
         h[result.send(key)] = result
         h
       end