data_bindings 0.0.1

data/.gitignore

@@ -0,0 +1,5 @@
+Gemfile.lock
+.yardoc
+doc
+Gemfile.lock
+.DS_Store

data/Gemfile

@@ -0,0 +1,4 @@
+source :rubygems
+
+gemspec
+gem 'hashie', :git => 'https://github.com/intridea/hashie.git'

data/README.md

@@ -0,0 +1,167 @@
+# Data bindings
+
+There are many ways to represent data. For instance, XML, JSON and YAML are all very similar while having different representations.
+Data bindings attempts to unify these various representations by allowing the creation of representation-free schemas which can be used to valiate a document. As well,
+it provides adapters to normalize access across these various types.
+
+Data bindings has four central concepts. *Adapters* provide normal access independent of representation. *Readers* allow you to define adapter-independent ways of reading data. *Writers* allows you define adapter-independent ways of writing data.*Validations* allow you to define a schema for your document.
+
+## 5 minute demo
+
+Start by loading from a JSON object
+
+    a = DataBindings.from_json('{"name":"Proust","books":[{"published":1913,"title":"Swan\'s Way"},{"published":1923,"title":"The Prisoner"}]}')
+
+(You could also load from YAML, XML BSON, etc by using `#from_yaml`, `#from_xml`, `#from_bson` and so forth)
+
+We can go ahead and access that like we nomrally would
+
+    a[:name]
+    # "proust"
+    a[:name][0][:title]
+    # "Swan's Way"
+
+Great, now let's get a validated copy of that object
+
+    b = a.bind {
+      property :name, String
+      property :books, [] {
+        property :published, Integer
+        property :title, String
+      }
+    }
+
+Is it okay?
+
+    b.valid?
+    # => true
+
+How about we represent it in YAML!
+
+    b.convert_to_yaml
+    # => "---\nname: Proust\nbooks:\n- published: 1913\n  title: Swan's Way\n- published: 1923\n  title: The Prisoner\n" 
+
+Or, right out to a YAML file
+
+    b.convert_to_yaml_file("/tmp/proust.yaml")
+
+And load it back
+
+    from_file = DataBindings.from_yaml_file("/tmp/proust.yaml")
+    from_file.bind(a) # Use the binding from above
+
+We can also define the types independently so that we can associate them with Ruby constructors later.
+
+    DataBindings.type(:book) {
+      property :published, Integer
+      property :title, String
+    }
+
+    DataBindings.type(:person) {
+      property :name
+      property :books, [:book]
+    }
+
+    proust = DataBindings.from_yaml_file('/tmp/proust.yaml').bind(:person)
+    p proust[:name]
+    # => "Proust" 
+    p proust[:books][1]
+    # => {"published"=>1923, "title"=>"The Prisoner"}
+
+Maybe we also want to create a Ruby object out of person, let's do that.
+
+    class Person
+      attr_reader :name, :books
+
+      def initialize(name, books)
+        @name = name
+        @books = books
+      end
+
+      def proust?
+        name.downcase == 'proust'
+      end
+    end
+
+    class Book
+      attr_reader :published, :title
+
+      def initialize(published, title)
+        @published, @title = published, title
+      end
+
+      def published_before?(year)
+        published < year
+      end
+    end
+
+    DataBindings.for_native(:person) { |attrs| Person.new(attrs[:name], attrs[:books]) }
+    DataBindings.for_native(:book) { |attrs| Book.new(attrs[:published], attrs[:title]) }
+
+    proust = DataBindings.from_yaml_file('/tmp/proust.yaml').bind!(:person).to_native
+    proust.proust?
+    # => true
+    proust.books[0].published_before?(2011)
+    # => true
+	proust.books[0].published_before?(1800)
+	# => false
+
+## Adapters
+
+Adapters have a simple contract. They must be a module. They must define a method #from_* where * is a type. For example, the JSONAdapter provides `#from_json`. They must also provide a singleton method #construct that can serialize an object into it's target representation. They may provide other methods to your base generator; they are included into it and thus can access any of it's internals. They are typically expected to return a ruby hash or array. For instance:
+
+    a = DataBindings.from_json('{"Hello":"World"}')
+	# => {"Hello"=>"World"} 
+	a.class
+    # => DataBindings::Adapters::Ruby::RubyObjectAdapter 
+
+## Binding
+
+Bindings provide a mechanism to validate certain properties of a Hash.
+
+To create a type, define it from your generator. For example:
+
+	DataBindings.type(:person) do
+	  property :name, String
+	  property :age, Integer
+	end
+
+Would define a type for `:person`. This object would have two properties `name` and `age`. The types available are String, Integer, Float, DataBindings::Boolean. As well, you can refer to any of the types you've defined previously. You can refer to an implicit array of values by putting the type in `[]`. For example, you could have
+
+	DataBindings.type(:person) do
+	  property :name, String
+	  property :age, Integer
+	  property :lottery_numbers, [Integer]
+	end
+
+## Readers
+
+Readers provide an adapter-indepedent way of reading data from other sources. By default, we are also dealing with a String representation of the data. For instance:
+
+    DataBindings.from_json('{"Hello":"World"}')
+
+would create a JSON representation. You could provide file access by adding a `file` reader.
+
+	DataBindings.reader(:file) { |f| File.read(f) }
+
+Now, we could load the above JSON from disk by using
+
+    DataBindings.from_json_file('/tmp/file.json')
+
+The `#from_json_file` method is synthesized into your generator by adding a `:file` reader. By default, there are readers for files, io, and http.
+
+## Writers
+
+Writers provide an adapter-indepedent way of writing data to other sources. By default, we emit our representation of the data as a String. For instance:
+
+    DataBindings.from_ruby({"Hello" => "World"}).convert_to_yaml
+
+would create a YAML representation. You could provide file writing by adding a `file` writer.
+
+	DataBindings.reader(:file) { |obj, f| File.open(f, 'w') { |h| h << obj } }
+
+Now, if you wanted to write the above JSON to disk as YAML, you could do the following:
+
+	DataBindings.from_ruby({"Hello" => "World"}).convert_to_file(:yaml, "/tmp/out.yaml")
+
+The `#convert_to_file` method that would be synthesized into your generator. By default, there are writers for files, io, and http.

data/Rakefile

@@ -0,0 +1,13 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+require 'yard'
+
+task :test do
+  Rake::TestTask.new do |t|
+    Dir['test/**/*_test.rb'].each{|f| require File.expand_path(f)}
+  end
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']   # optional
+end

data/data_bindings.gemspec

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "data_bindings/version"
+
+Gem::Specification.new do |s|
+  s.name        = "data_bindings"
+  s.version     = DataBindings::VERSION
+  s.authors     = ["Joshual Hull"]
+  s.email       = ["joshbuddy@gmail.com"]
+  s.homepage    = "http://github.com/joshbuddy/data_bindings"
+  s.summary     = %q{Bind data to and from things}
+  s.description = %q{Bind data to and from things.}
+
+  s.rubyforge_project = "data_bindings"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency 'hashie', '= 2.0.0.beta'
+
+  # specify any dependencies here; for example:
+  s.add_development_dependency 'bson'
+  s.add_development_dependency 'multi_json'
+  s.add_development_dependency 'nokogiri'
+  s.add_development_dependency 'builder'
+  s.add_development_dependency 'httparty'
+  s.add_development_dependency "minitest"
+  s.add_development_dependency "rake"
+  s.add_development_dependency "fakeweb"
+  s.add_development_dependency "yard"
+  s.add_development_dependency "redcarpet"
+  s.add_development_dependency "tnetstring"
+end

data/lib/data_bindings/adapters/bson.rb

@@ -0,0 +1,32 @@
+module DataBindings
+  module Adapters
+    module BSON
+      include Ruby
+      include DataBindings::GemRequirement
+      
+      # Constructs a wrapped object from a JSON string
+      # @param [String] str The JSON object
+      # @return [RubyObjectAdapter, RubyArrayAdapter] The wrapped object
+      def from_bson(str)
+        from_ruby(::BSON.deserialize(str.unpack("C*")))
+      end
+      gentle_require_gem :from_bson, 'bson'
+
+      module Convert
+        include ConverterHelper
+        include DataBindings::GemRequirement
+
+        # Creates a String repsentation of a Ruby Hash or Array.
+        # @param [Generator] generator The generator that invokes this constructor
+        # @param [Symbol] name The name of the binding used on this object
+        # @param [Array, Hash] obj The object to be represented in JSON
+        # @return [String] The JSON representation of this object
+        def force_convert_to_bson
+          ::BSON.serialize(self).to_s
+        end
+        gentle_require_gem :force_convert_to_bson, 'bson'
+        standard_converter :convert_to_bson
+      end
+    end
+  end
+end

data/lib/data_bindings/adapters/json.rb

@@ -0,0 +1,32 @@
+module DataBindings
+  module Adapters
+    module JSON
+      include Ruby
+      include DataBindings::GemRequirement
+
+      # Constructs a wrapped object from a JSON string
+      # @param [String] str The JSON object
+      # @return [RubyObjectAdapter, RubyArrayAdapter] The wrapped object
+      def from_json(str)
+        from_ruby(MultiJson.decode(str))
+      end
+      gentle_require_gem :from_json, 'multi_json'
+
+      module Convert
+        include ConverterHelper
+        include DataBindings::GemRequirement
+
+        # Creates a String repsentation of a Ruby Hash or Array.
+        # @param [Generator] generator The generator that invokes this constructor
+        # @param [Symbol] name The name of the binding used on this object
+        # @param [Array, Hash] obj The object to be represented in JSON
+        # @return [String] The JSON representation of this object
+        def force_convert_to_json
+          MultiJson.encode(self)
+        end
+        gentle_require_gem :force_convert_to_json, 'multi_json'
+        standard_converter :convert_to_json
+      end
+    end
+  end
+end

data/lib/data_bindings/adapters/native.rb

@@ -0,0 +1,50 @@
+module DataBindings
+  module Adapters
+    module Native
+      # Constructs a wrapped object from a native Ruby object. This object is expected
+      # to respond to calls similar to those defined by #attr_accessor
+      # @param [Object] obj The object to be wrapped
+      # @return [NativeArrayAdapter, NativeObjectAdapter] The wrapped object
+      def from_native(obj)
+        binding_class(NativeAdapter).new(self, obj)
+      end
+
+      class NativeAdapter
+        include Unbound
+
+        def initialize(generator, object)
+          @generator, @object = generator, object
+        end
+
+        def pre_convert
+          raise DataBindings::UnboundError unless @name
+        end
+
+        def type
+          @object.is_a?(Array) ? :array : :hash
+        end
+
+        def [](idx)
+          val = @object.respond_to?(:[]) ? @object[idx] : @object.send(idx)
+          if DataBindings.primitive_value?(val)
+            val
+          else
+            binding_class(NativeAdapter).new(@generator, val)
+          end
+        end
+
+        def []=(idx, value)
+          @object.respond_to?(:[]=) ? @object[idx] = value : @object.send("#{idx}=", value)
+        end
+
+        def key?(name)
+          @object.respond_to?(name)
+        end
+
+        def to_hash
+          raise UnboundError
+        end
+      end
+    end
+  end
+end

data/lib/data_bindings/adapters/params.rb

@@ -0,0 +1,91 @@
+require 'cgi'
+
+module DataBindings
+  module Adapters
+    module Params
+      include Ruby
+      
+      def from_params(str)
+        from_ruby( parse_nested_query(str) )
+      end
+      
+      
+      def parse_nested_query(qs, d = nil)
+        params = {}
+        
+        (qs || '').split(d ? /[#{d}] */n : /[&;] */n).each do |p|
+          k, v = p.split('=', 2).map { |s| CGI::unescape(s) }
+          normalize_params(params, k, v)
+        end
+        
+        return params
+      end
+      
+      private
+      def normalize_params(params, name, v = nil)
+        name =~ %r(\A[\[\]]*([^\[\]]+)\]*)
+        k = $1 || ''
+        after = $' || ''
+        
+        return if k.empty?
+        
+        if after == ""
+          params[k] = v
+        elsif after == "[]"
+          params[k] ||= []
+          raise TypeError, "expected Array (got #{params[k].class.name}) for param `#{k}'" unless params[k].is_a?(Array)
+          params[k] << v
+        elsif after =~ %r(^\[\]\[([^\[\]]+)\]$) || after =~ %r(^\[\](.+)$)
+          child_key = $1
+          params[k] ||= []
+          raise TypeError, "expected Array (got #{params[k].class.name}) for param `#{k}'" unless params[k].is_a?(Array)
+          if params[k].last.is_a?(Hash) && !params[k].last.key?(child_key)
+            normalize_params(params[k].last, child_key, v)
+          else
+            params[k] << normalize_params({}, child_key, v)
+          end
+        else
+          params[k] ||= {}
+          raise TypeError, "expected Hash (got #{params[k].class.name}) for param `#{k}'" unless params[k].is_a?(Hash)
+          params[k] = normalize_params(params[k], after, v)
+        end
+        
+        return params
+      end
+      
+      module Convert
+        include ConverterHelper
+
+        # Creates a String repsentation of a Ruby Hash or Array.
+        # @param [Generator] generator The generator that invokes this constructor
+        # @param [Symbol] name The name of the binding used on this object
+        # @param [Array, Hash] obj The object to be represented in JSON
+        # @return [String] The JSON representation of this object
+        def force_convert_to_params
+          build_nested_query(to_hash)
+        end
+        standard_converter :convert_to_params
+
+        private
+      
+        def build_nested_query(value, prefix = nil)
+          case value
+          when Array
+            index = 0
+            value.map { |v|
+              query_string = build_nested_query(v, prefix ? "#{prefix}[#{index}]" : index)
+              index += 1
+              query_string
+            }.join("&")
+          when Hash
+            value.map { |k, v|
+              build_nested_query(v, prefix ? "#{prefix}[#{CGI::escape(k)}]" : CGI::escape(k))
+            }.join("&")
+          else
+            "#{prefix}=#{CGI::escape(value.to_s)}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/data_bindings/adapters/ruby.rb

@@ -0,0 +1,44 @@
+module DataBindings
+  module Adapters
+    module Ruby
+
+      # Constructs a wrapped object from an Array or Hash
+      # @param [Array, Hash] obj The Ruby array or hash
+      # @return [RubyObjectAdapter, RubyArrayAdapter] The wrapped object
+      def from_ruby(obj)
+        case obj
+        when Array then from_ruby_array(obj)
+        when Hash  then from_ruby_hash(obj)
+        else            obj
+        end
+      end
+
+      def from_ruby_hash(h)
+        binding_class(RubyObjectAdapter).new(self, h)
+      end
+      alias_method :from_ruby_object, :from_ruby_hash
+
+      def from_ruby_array(a)
+        binding_class(RubyArrayAdapter).new(self, a)
+      end
+
+      class RubyArrayAdapter < Array
+        include Unbound
+
+        def initialize(generator, o)
+          @generator = generator
+          super o
+        end
+      end
+
+      class RubyObjectAdapter < IndifferentHash
+        include Unbound
+
+        def initialize(generator, o)
+          @generator = generator
+          replace o
+        end
+      end
+    end
+  end
+end