gorillib 0.4.0pre → 0.4.1pre

data/lib/gorillib/model/factories.rb

@@ -12,25 +12,35 @@ module Gorillib
 
     def self.receive(type)
       case
-      when type.is_a?(Proc) || type.is_a?(Method) then return Gorillib::Factory::ApplyProcFactory.new(type)
-      when type.respond_to?(:receive)             then return type
       when factories.include?(type)               then return factories[type]
+      when type.respond_to?(:receive)             then return type
+      when type.is_a?(Proc) || type.is_a?(Method) then return Gorillib::Factory::ApplyProcFactory.new(type)
       when type.is_a?(String)                     then
-        return Gorillib::Inflector.constantize(Gorillib::Inflector.camelize(type.gsub(/\./, '/')))
+        return( factories[type] = Gorillib::Inflector.constantize(Gorillib::Inflector.camelize(type.gsub(/\./, '/'))) )
       else raise ArgumentError, "Don't know which factory makes a #{type}"
       end
     end
 
+    # Manufactures objects from their raw attributes hash
+    #
+    # A hash with a value for `:_type` is dispatched to the corresponding factory
+    # Everything else is returned directly
+    def self.make(obj)
+      if obj.respond_to?(:has_key?) && (obj.has_key?(:_type) || obj.has_key?('_type'))
+        factory = Gorillib::Factory(attrs[:_type])
+        factory.receive(obj)
+      else
+        obj
+      end
+    end
+
     private
     def self.factories
-      @factories ||= Gorillib::Collection.new.tap{|f| f.key_method = :name }
+      @factories ||= Hash.new
     end
     public
 
-    def self.register_factory(factory, *typenames)
-      if typenames.blank?
-        typenames = [factory.typename, factory.product]
-      end
+    def self.register_factory(factory, typenames)
       typenames.each{|typename| factories[typename] = factory }
     end
 
@@ -38,42 +48,27 @@ module Gorillib
       # [Class] The type of objects produced by this factory
       class_attribute :product
 
-      # [Array<Symbol>] methods that can be redefined by passing a block to an
-      # instance No not add to your superclass' value in-place; instead, use
-      # `self.redefinable_methods += [...]`.
-      # @see #redefine
-      class_attribute :redefinable_methods, :instance_writer => false
-      self.redefinable_methods = Set.new([:blankish?, :convert])
-
-      # [Array<Object>] objects considered to be equivalent to `nil`
-      class_attribute :blankish_vals
-      self.blankish_vals = Set.new([ nil, "" ]) # note: [] {} and false are NOT blankish by default
-
       def initialize(options={})
-        @product       = options.delete(:product)       if options.has_key?(:product)
-        @blankish_vals = options.delete(:blankish_vals) if options.has_key?(:blankish_vals)
-        options.extract!(*redefinable_methods).each do |meth, value_or_block|
-          redefine(meth, value_or_block)
+        @product       = options.delete(:product){ self.class.product }
+        if options[:blankish]
+          define_singleton_method(:blankish, options.delete(:blankish))
         end
+        redefine(:convert, options.delete(:convert)) if options.has_key?(:convert)
         warn "Unknown options #{options.keys}" unless options.empty?
       end
 
       def self.typename
-        Gorillib::Inflector.underscore(product.name).to_sym
+        @typename ||= Gorillib::Inflector.underscore(product.name).to_sym
       end
       def typename ; self.class.typename ; end
 
-      def self.receive(*args, &block)
-        self.new.receive(*args, &block)
-      end
-
       # A `native` object does not need any transformation; it is accepted directly.
       # By default, an object is native if it `is_a?(product)`
       #
       # @param   [Object]      obj the object to convert and receive
       # @return [true, false] true if the item does not need conversion
       def native?(obj)
-        obj.is_a?(product)
+        obj.is_a?(@product)
       end
       def self.native?(obj) self.new.native?(obj) ; end
 
@@ -82,12 +77,15 @@ module Gorillib
       # @param   [Object]      obj the object to convert and receive
       # @return [true, false] true if the item is equivalent to a nil value
       def blankish?(obj)
-        blankish_vals.include?(obj)
+        obj.nil? || (obj == "")
       end
-      def self.blankish?(obj) self.new.blankish?(obj) ; end
+      def self.blankish?(obj)
+        obj.nil? || (obj == "")
+      end
+
+    protected
 
       def redefine(meth, *args, &block)
-        raise ArgumentError, "Cannot redefine #{meth} -- only #{redefinable_methods.inspect} are redefinable" unless redefinable_methods.include?(meth)
         if args.present?
           val = args.first
           case
@@ -100,8 +98,6 @@ module Gorillib
         self
       end
 
-    protected
-
       # Raises a FactoryMismatchError.
       def mismatched!(obj, message=nil, *args)
         message ||= "item cannot be converted to #{product}"
@@ -109,8 +105,9 @@ module Gorillib
         raise FactoryMismatchError, message, *args
       end
 
-      def self.register_factory!(*args)
-        Gorillib::Factory.register_factory(self, *args)
+      def self.register_factory!(*typenames)
+        typenames = [typename, product] if typenames.empty?
+        Gorillib::Factory.register_factory(self.new, typenames)
       end
     end
 
@@ -139,14 +136,13 @@ module Gorillib
     # throws a mismatch error for anything else.
     #
     # @example
-    #   ff = Gorillib::Factory::NonConvertingFactory.new(:product => String, :blankish_vals => [nil])
+    #   ff = Gorillib::Factory::NonConvertingFactory.new(:product => String, :blankish => ->(obj){ obj.nil? })
     #   ff.receive(nil)    #=> nil
     #   ff.receive("bob")  #=> "bob"
     #   ff.receive(:bob)   #=> Gorillib::Factory::FactoryMismatchError: must be an instance of String, got 3
     #
     class NonConvertingFactory < BaseFactory
-      self.blankish_vals = [nil]
-
+      def blankish?(obj) obj.nil? ; end
       def receive(obj)
         return nil  if blankish?(obj)
         return obj  if native?(obj)
@@ -156,17 +152,20 @@ module Gorillib
       end
     end
 
-    class IdenticalFactory < BaseFactory
-      self.redefinable_methods = []
-      self.blankish_vals       = []
+    class ::Whatever < BaseFactory
+      def initialize(options={})
+        options.slice!(:convert, :blankish)
+        super(options)
+      end
       def native?(obj)   true  ; end
       def blankish?(obj) false ; end
-      def receive(obj)
+      def receive(obj)   obj   ; end
+      def self.receive(obj)
         obj
       end
-      register_factory!(:identical, :whatever)
+      Gorillib::Factory.register_factory(self, [self, :identical, :whatever])
     end
-    ::Whatever = IdenticalFactory unless defined?(Whatever)
+    IdenticalFactory = ::Whatever unless defined?(IdenticalFactory)
 
     # __________________________________________________________________________
     #
@@ -175,7 +174,7 @@ module Gorillib
 
     class StringFactory < ConvertingFactory
       self.product = String
-      self.blankish_vals -= [""]
+      def blankish?(obj)    obj.nil? ; end
       def native?(obj)      obj.respond_to?(:to_str)  end
       def convert(obj)      obj.to_s                  end
       register_factory!
@@ -262,13 +261,13 @@ module Gorillib
 
     class NilFactory    < NonConvertingFactory
       self.product       = NilClass
-      self.blankish_vals = []
+      def blankish?(obj) false ; end
       register_factory!(:nil, NilClass)
     end
 
     class BooleanFactory < ConvertingFactory
       self.product       = [TrueClass, FalseClass]
-      self.blankish_vals = [nil]
+      def blankish?(obj)    obj.nil? ; end
       def native?(obj)     obj.equal?(true) || obj.equal?(false) ; end
       def convert(obj)     (obj.to_s == "false") ? false : true ; end
       register_factory!(:boolean)
@@ -282,20 +281,18 @@ module Gorillib
     class EnumerableFactory < ConvertingFactory
       # [#receive] factory for converting items
       attr_reader :items_factory
-      self.redefinable_methods += [:empty_product]
-      self.blankish_vals = Set.new([ nil ])
 
       def initialize(options={})
-        @items_factory = Gorillib::Factory.receive( options.delete(:items){ IdenticalFactory.new } )
+        @items_factory = Gorillib::Factory.receive( options.delete(:items){ Gorillib::Factory(:identical) } )
+        redefine(:empty_product, options.delete(:empty_product)) if options.has_key?(:empty_product)
         super(options)
       end
 
-      def native?(obj)
-        false
-      end
+      def blankish?(obj)    obj.nil? ; end
+      def native?(obj)      false    ; end
 
       def empty_product
-        product.new
+        @product.new
       end
 
       def convert(obj)
@@ -323,7 +320,7 @@ module Gorillib
       self.product = Hash
 
       def initialize(options={})
-        @keys_factory = Gorillib::Factory( options.delete(:keys){ Whatever.new } )
+        @keys_factory = Gorillib::Factory( options.delete(:keys){ Gorillib::Factory(:identical) } )
         super(options)
       end
 
@@ -339,7 +336,7 @@ module Gorillib
 
     class RangeFactory < NonConvertingFactory
       self.product       = Range
-      self.blankish_vals = [ nil, [] ]
+      def blankish?(obj)    obj.nil? || obj == [] ; end
       register_factory!
     end
 
@@ -347,7 +344,6 @@ module Gorillib
 
     class ApplyProcFactory < ConvertingFactory
       attr_reader :callable
-      self.blankish_vals = Set.new([nil])
 
       def initialize(callable=nil, options={}, &block)
         if block_given?
@@ -357,9 +353,8 @@ module Gorillib
         @callable = callable
         super(options)
       end
-      def native?(val)
-        false
-      end
+      def blankish?(obj)    obj.nil? ; end
+      def native?(val)      false    ; end
       def convert(obj)
         callable.call(obj)
       end

data/lib/gorillib/model/lint.rb

@@ -0,0 +1,24 @@
+module Gorillib
+  module Model
+    #
+    # A set of guards for good behavior:
+    #
+    # * checks that fields given to read_attribute, write_attribute, etc are defined
+    #
+    module Lint
+      def read_attribute(field_name, *)  check_field(field_name) ; super ; end
+      def write_attribute(field_name, *) check_field(field_name) ; super ; end
+      def unset_attribute(field_name, *) check_field(field_name) ; super ; end
+      def attribute_set?(field_name, *)  check_field(field_name) ; super ; end
+
+    protected
+      # @return [true] if the field exists
+      # @raise [UnknownFieldError] if the field is missing
+      def check_field(field_name)
+        return true if self.class.has_field?(field_name)
+        raise UnknownFieldError, "unknown field: #{field_name} for #{self}"
+      end
+
+    end
+  end
+end

data/lib/gorillib/model/serialization.rb

@@ -1,17 +1,27 @@
+
+class Array
+  def to_tsv
+    join("\t")
+  end
+end
+
 module Gorillib
   module Model
-
     def to_wire(options={})
       attributes.merge(:_type => self.class.typename).inject({}) do |acc, (key,attr)|
         acc[key] = attr.respond_to?(:to_wire) ? attr.to_wire(options) : attr
         acc
       end
     end
+    def as_json(*args) to_wire(*args) ; end
 
     def to_json(options={})
       MultiJson.dump(to_wire(options), options)
     end
-    alias_method(:as_json, :to_wire)
+
+    def to_tsv
+      attribute_values.map(&:to_s).join("\t")
+    end
 
     module ClassMethods
       def from_tuple(*vals)

data/lib/gorillib/model/validate.rb

@@ -9,9 +9,9 @@ module Gorillib
         raise ArgumentError, "Name must start with [A-Za-z_] and subsequently contain only [A-Za-z0-9_]", caller unless name =~ VALID_NAME_RE
       end
 
-      def hashlike!(desc, val)
+      def hashlike!(val)
         return true if val.respond_to?(:[]) && val.respond_to?(:has_key?)
-        raise ArgumentError, "#{desc} should be something that behaves like a hash: #{val.inspect}", caller
+        raise ArgumentError, "#{block_given? ? yield : 'value'} should be something that behaves like a hash: #{val.inspect}", caller
       end
 
       def included_in!(desc, val, colxn)

data/lib/gorillib/pathname.rb

@@ -9,15 +9,21 @@ module Gorillib
 
     def register_path(handle, *pathsegs)
       ArgumentError.arity_at_least!(pathsegs, 1)
-      ROOT_PATHS[handle] = pathsegs
+      ROOT_PATHS[handle.to_sym] = pathsegs
     end
 
-    def register_paths(pairs = {})
-      pairs.each_pair{ |handle, pathsegs| register_path(handle, *pathsegs) }
+    def register_paths(handle_paths = {})
+      handle_paths.each_pair{|handle, pathsegs| register_path(handle, *pathsegs) }
     end
 
-    def unregister_path handle
-      ROOT_PATHS.delete handle
+    def register_default_paths(handle_paths = {})
+      handle_paths.each_pair do |handle, pathsegs|
+        register_path(handle, *pathsegs) unless ROOT_PATHS.has_key?(handle.to_sym)
+      end
+    end
+
+    def unregister_path(handle)
+      ROOT_PATHS.delete handle.to_sym
     end
 
     # Expand a path with late-evaluated segments.
@@ -59,8 +65,13 @@ module Gorillib
     def relative_path_to(*pathsegs)
       ArgumentError.arity_at_least!(pathsegs, 1)
       pathsegs = pathsegs.map{|ps| expand_pathseg(ps) }.flatten
-      new(File.join(*pathsegs)).cleanpath(true)
+      self.new(File.join(*pathsegs)).cleanpath(true)
     end
+    def relpath_to(*args) relative_path_to(*args) ; end
+
+    # def make_pathname(*args)
+    #   Pathname.new(*args)
+    # end
 
   protected
     # Recursively expand a path handle
@@ -75,4 +86,8 @@ end
 
 class Pathname
   extend Gorillib::Pathref
+  class << self ; alias_method :new_pathname, :new ; end
+
+  # FIXME: find out if this is dangerous
+  alias_method :to_str, :to_path
 end

data/lib/gorillib/some.rb

@@ -5,6 +5,8 @@ require 'pathname'
 
 require 'gorillib/base'
 
+require 'gorillib/logger/log'
+
 require 'gorillib/pathname'
 require 'gorillib/string/simple_inflector'
 require 'gorillib/string/inflections'

data/lib/gorillib/type/extended.rb

@@ -9,8 +9,6 @@ class ::Guid      < ::String  ; end
 class ::IpAddress < ::String  ; end
 class ::Hostname  < ::String  ; end
 
-class ::Url       < ::String  ; end
-
 # require 'gorillib/metaprogramming/delegation'
 #
 # class ::Boolean < ::Object

data/lib/gorillib/type/url.rb

@@ -0,0 +1,9 @@
+require 'addressable/uri'
+
+class ::Url < Addressable::URI ; end
+
+class UrlFactory < Gorillib::Factory::ConvertingFactory
+  self.product = ::Url
+  def convert(obj)      product.parse(obj) ; end
+  register_factory!
+end

data/lib/gorillib/utils/console.rb

@@ -36,6 +36,9 @@ class ItsATrap < BasicObject
   alias_method :pretty_inspect, :inspect
   def methods() @obj.methods ; end
 
+  # @returns the proxied object
+  def __obj__ ; @obj ; end
+
   # These are defined on BasicObject, delegate them along with the rest
   #   BasicObject.instance_methods
   #   => [:==, :equal?, :!, :!=, :instance_eval, :instance_exec, :__send__, :__id__]
@@ -58,7 +61,7 @@ private
   end
 
   def __describe_and_send__(meth, *args, &block)
-    pref         = "%-3d %-14s %-15s" % [@call_count, __id__, self.to_s[0..14]]
+    pref         = "%-3d %-14s %-15s" % [@call_count, @obj.__id__, self.to_s[0..14]]
     @call_count += 1
     $stderr.puts   "%s %-15s <-  %-30s %s -- %s" % [pref, meth.to_s[0..14], args.map(&:inspect).join(','), block, ::Kernel.caller.first]
     ret = @obj.__send__(meth, *args, &block)

data/notes/HOWTO.md

@@ -0,0 +1,22 @@
+# Walkthrough
+
+**note (2012-06): you must use the dev branch, `version_1` of Gorillib** -- https://github.com/infochimps-labs/gorillib/tree/version_1/
+
+1. Here's a set of examples of Gorillib records in action.
+  * [examples of `Gorillib::Model`](https://github.com/infochimps-labs/gorillib/tree/version_1/examples/model)
+  * see example gorillib records in the /examples directories
+  
+__________________________________________________________________________
+
+2. Walkthrough dataflow for a new customer:
+  * models to represent records in a dataflow (gorillib/examples)
+  * describe the macro dataflow (wukong/examples)
+  * simulate the dataflow at commandline
+  * project the dataflow using Flume
+  * export the dataflow using graphviz
+
+https://github.com/infochimps-labs/wukong/wiki
+https://github.com/infochimps-labs/gorillib/wiki
+Plus source files (or you can instead see the Yard Docs)
+
+3. flume event model shim

data/notes/bucket.md

@@ -0,0 +1,155 @@
+# gorillib/bucket (WIP -- NOT READY YET) -- freeform storage with definable access
+
+* A `Go::Bucket` fulfills the contract of `Go::Model`
+
+## Arbitrary read/writes with `[]/[]=`, defined access with `.foo/.foo=`
+
+Overriding `method_missing` is uncouth. It screws up your stack traces, muddies your interface and leads to unassertive code:
+
+    ```ruby
+    Settings.defcon = 3
+    # ... elsewhere ...
+    if Settings.def_con.to_i <= 1
+      WOPR.launch_nukes!
+    end
+    ```
+
+Here, mispelling `def_con` as `defcon` (along with being wussy about the attribute's type and negligent about prescribing a default value) leads to the destruction of humanity.
+
+Nonetheless, for several reasons (prudent laziness, handling configuration of an external component, etc) it's important to handle arbitrary attributes uniformly.
+
+So the rule is that you can get or set anything you like using `[]` and `[]=` respectively, no need to define it first:
+
+    Settings[:whatever] = 3
+    Settings[:whatever]       #=> 3
+
+You don't get any magic, and the ugly accessor leaves you in no doubt that you're being lazy (ain't judging, just sayin').  When you define a setting you get accessors for that attribute and all associated magic:
+
+    Settings.option :defcon, Integer, :doc => 'Current NORAD defense condition', :default => 5, :validates => { :in => 1..5 }
+    Settings.defcon           #=> 5
+    Settings.defcon = 0
+    Settings.validate!        # raises a validation exception
+
+Defined fields' magic works whichever form of access you use -- here, type-converting the value on assignment:
+
+    Settings[:defcon]     = '5'   #=> 5
+    Settings.defcon       = '5'   #=> 5
+    Settings.receive_defcon('5')  #=> 5
+
+## Keys
+
+Keys be lower-cased identifiers: they should match `/\A([a-z][a-z0-9\_]*)\z/`.
+
+## Deep Hash
+
+     Hash.new {|h,k| h[k] = Hash.new(&h.default_proc)}
+
+### Dot addressing
+
+Can retrieve keys as 'x.y.z' meaning 'foo[x][y][z]'.
+
+* On a `get`, will  
+  - return the value, if `foo[:x][:y][:z]` exists
+  - return nil, if either `foo[:x]` or `foo[:x][:y]` is *unset*. It will not create `foo[:x]` or `foo[:x][:y]`.
+  - raise an error if either `foo[:x]` or `foo[:x][:y]` is set to a value that does not respond to `[]`
+
+* On a `set`, will  
+  - raise an error if either `foo[:x]` or `foo[:x][:y]` is set to a value that doesn't respond to `[]`
+  - set and return the value; any intermediate buckets (`foo[:x]` and `foo[:x][:y]`) will be created if they don't exist.
+
+
+__________________________________________________________________________
+
+
+## Examples
+
+### how hash-like is this?
+
+* obj.deep_get(:foo, :bar, :baz) #
+* obj.deep_set(:foo, :bar, :baz, val) # sets foo bar baz.
+  - where property has a type, it uses that type
+  - otherwise it uses Mash, and calls [] on it
+
+* TD votes NO on magic recursive hash behavior
+
+
+    {
+      :buck1  => { 
+        :buck2  =>  { :k3 => 33, :ehsh => {}, :arr => [11, 12, 13] },
+        :cars   => [{ :model => 'ford', :cylinders => 8 }, { :model => 'buick', :cylinders => 6 }],
+      }
+      :buck3 => {
+        :buck4  =>  { :k4 => 44 }
+        :k5     => nil,
+      }
+      :k6       => 69
+    }
+
+* `obj[:buck3]`               # b{ :buck4=>b{ :k4=>44 },:k5=>nil } -- it's a bucket
+* `obj[:buck5] = Hash.new`
+* `obj[:buck5].class`         # Bucket -- it's converted to bucket
+* `obj[:xxx]`                 # nil -- it's not there
+* `obj[:xxx][:yyy][:zzz]`     # fails -- it doesn't try to index into the nil `obj[:xxx]` cell.
+* `obj[:xxx]`                 # nil -- it didn't create the `obj[:xxx]` object when we tried to read on the previous line.
+
+    c.options_for 'wheels', 'interior.fabric', 'interior.carpeting'
+    
+    c[:wheels]                    # c{ }
+    c[:wheels][:whitewall]        # nil
+    c[:wheels][:whitewall] = true # true
+    
+    c.interior.fabric.color 
+    
+
+* `obj[:k6][:bomb]`           # raises ArgumentError; `obj[:k6]` is not a bucket.
+  
+* `obj[:'hello-there']        # undefined; `'hello-there'` is not a valid identifier.
+
+* `obj[:buck3][:buck4][:k5] = 55` 
+  `obj[:buck3]`                    # b{ :buck4=>b{ :k4=>44 },:k5 => 55}
+* `obj[:f][:g][:h] = 7`
+  `obj[:f]`                   # b{ :g => b{ :h => 7 } }
+
+* `obj[:foo][:bar][:baz] ||= 1` -- **hard** ?I think?
+
+* `obj[:foo]`       -- nil
+* `obj[:foo][:bar]` -- raise
+* `obj[:foo][:bar] = 3`  --
+  - now obj[:foo][:bar] is 3
+  - and obj[:foo] is a ?dsl_object?? but
+
+`obj[:foo][:bar]`
+
+Suppose `obj[:foo]` is set to a
+
+Seems clear these should do the right thing:
+
+* `obj.merge`
+* `obj.reverse_merge`
+* `obj.keys`
+* `obj.values`
+* ... and a few more
+
+Also:
+
+* `obj.to_a`?
+* `obj.each`?
+* other crazy Enumerable properties?
+
+### TODO
+
+* figure out the method structure for
+  - read/write/unset of attributes when Hash vs Accessors vs Instance Variables
+  - reader/writer: raw vs. hooks, dirty, etc.
+
+## Configliere Settings
+
+
+Configliere lets you define arbitrary attributes of a param, notably:
+
+     [:description]  Documentation for the param, used in the --help message
+     [:default]      Sets a default value (applied immediately)
+     [:env_var]      Environment variable to adopt (applied immediately, and after +:default+)
+     [:type]         Converts param's value to the given type, just before the finally block is called
+     [:finally]      Block of code to postprocess settings or handle complex configuration.
+     [:required]     Raises an error if, at the end of calling resolve!, the param's value is nil.