gearbox 0.1.0

data/lib/examples/person.rb

@@ -0,0 +1,29 @@
+module Gearbox
+  class Person
+    
+    attr_accessor :name
+    attr_accessor :twitter_account
+    attr_accessor :email
+    attr_accessor :website
+    attr_accessor :phone
+    attr_accessor :resource
+    
+  end
+end
+
+
+#     Person
+#       name
+#       tweet account | email | website | phone
+
+# it "has a people association" do
+#   subject.person_source = OpenStruct.public_method(:new)
+#   name = "George Q. Cannon"
+#   twitter_account = "gcannon"
+#   person = subject.add_person(:name => name, :twitter_account => twitter_account)
+#   subject.people[0].must_equal person
+#   person.resource.must_equal subject
+#   person.name.must_equal name
+#   person.twitter_account.must_equal twitter_account
+# end
+

data/lib/examples/reference.rb

@@ -0,0 +1,38 @@
+module Gearbox
+  class Reference
+    attr_accessor :location
+    attr_accessor :audience
+
+    attr_writer :person_source
+    attr_writer :theme_source
+    
+    def add_person(hash={})
+      new_person = person_source.call(hash.merge(:reference => self))
+      people << new_person
+      new_person
+    end
+    
+    def people
+      @people ||= []
+    end
+    
+    def add_theme(hash={})
+      new_theme = theme_source.call(hash.merge(:reference => self))
+      themes << new_theme
+      new_theme
+    end
+    
+    def themes
+      @themes ||= []
+    end
+    
+    private
+      def person_source
+        @person_source ||= Person.public_method(:new)
+      end
+      
+      def theme_source
+        @theme_source ||= Theme.public_method(:new)
+      end
+  end
+end

data/lib/examples/theme.rb

@@ -0,0 +1,8 @@
+module Gearbox
+  class Theme
+
+    attr_accessor :name
+    attr_accessor :tally
+
+  end
+end

data/lib/gearbox.rb

@@ -0,0 +1,40 @@
+# ================
+# = Dependencies =
+# ================
+require 'uuid'
+require 'linkeddata'
+require 'ostruct'
+
+module Gearbox
+  
+  # ========================
+  # = Helper Utility: path =
+  # ========================
+  # @private
+  def path(path)
+    File.expand_path("../gearbox/#{path}", __FILE__)
+  end
+  private :path
+  module_function :path
+  
+  # =======================
+  # = Loading the Library =
+  # =======================
+  autoload :AttributeCollection, path('attribute_collection')
+  autoload :RDFCollection, path('rdf_collection')
+
+  autoload :AdHocProperties, path('mixins/ad_hoc_properties')
+  autoload :Resource, path('mixins/resource')
+  autoload :SemanticAccessors, path('mixins/semantic_accessors')
+  
+  # ============
+  # = Examples =
+  # ============
+  
+  # Will separate these after things get to a solid 0.1 state.
+  autoload :Audience, path('../examples/audience')
+  autoload :Person, path('../examples/person')
+  autoload :Reference, path('../examples/reference')
+  autoload :Theme, path('../examples/theme')
+  
+end

data/lib/gearbox/attribute_collection.rb

@@ -0,0 +1,42 @@
+module Gearbox
+  
+  ##
+  # Collects attributes in a hash-like format.  Serializes the attributes in an OpenStruct.
+  ##
+  class AttributeCollection
+    
+    # Build a new AttributeCollection with an optional Hash.  
+    # Note: this class normalizes the keys and creates OpenStructs for values.
+    # @param [Hash] default A hash with normalized keys and OpenStruct values
+    def initialize(default={})
+      raise ArgumentError, "Must provide a hash for the defaults" unless default.is_a?(Hash)
+      @default = default
+      @source = {}
+    end
+    
+    # Set one attribute in the collection.
+    # @param [String, Symbol] key
+    # @param [Hash] hash
+    # @return [OpenStruct] The hash, converted into an OpenStruct
+    def []=(key, hash)
+      raise ArgumentError, "Must provide a hash for the value" unless hash.is_a?(Hash)
+      @source[normalize_key(key)] = OpenStruct.new(@default.merge(hash))
+    end
+    
+    # Get one attribute from the collection.
+    # @param [String, Symbol] key
+    # @return [OpenStruct, nil] Returns the attribute OpenStruct, if found.
+    def [](key)
+      @source[normalize_key(key)]
+    end
+    
+    private
+      # Normalizes the key.  Converts to a lower case symbol with non-alpha-numerics
+      # replaced by underscores, removing trailing and preceding underscores.
+      # @private
+      def normalize_key(obj)
+        obj.to_s.downcase.gsub(/[^A-Za-z0-9_]+/, '_').gsub(/(_$)|(^_)/, '').to_sym
+      end
+    
+  end
+end

data/lib/gearbox/mixins/ad_hoc_properties.rb

@@ -0,0 +1,41 @@
+module Gearbox
+  ##
+  # Allows a model instance to add a new property at runtime.  
+  # This is a (small) tip of the hat towards the flexibility
+  # offered by using a graph instead of a schema to govern
+  # the data store.  
+  ##
+  module AdHocProperties
+
+    # Getter and setter for an id property.
+    # Will be adjusted when I decide whether to mixin ActiveModel
+    attr_accessor :id
+    
+    # Stored attributes
+    # @return [RDFCollection]
+    def attributes_list
+      @attributes_list ||= RDFCollection.new
+    end
+    
+    # Generates or gets a blank node, based on the id.
+    # Will be replaced by subject.
+    # @return [RDF::Node] 
+    def bnode
+      return @bnode if @bnode
+      self.id ||= UUID.generate
+      safe_id = "#{self.class.name}_#{id}".gsub(/[^A-Za-z0-9\-_]/, '_')
+      @bnode = RDF::Node(safe_id)
+    end
+    
+    # Add a property without defining it on the class.
+    # This will stay, will use the subject, and the regular infrastructure.
+    # @param [Symbol] accessor, the new field being created.
+    # @param [RDF::Statement] predicate, the predicate for the new field.
+    # @param [Any] The value to store
+    def add_property(accessor, predicate, object)
+      new_property = RDF::Statement.new(bnode, predicate, object)
+      attributes_list[accessor] = new_property
+    end
+    
+  end
+end

data/lib/gearbox/mixins/resource.rb

@@ -0,0 +1,17 @@
+module Gearbox
+  ##
+  # The main mixin for any model.  
+  # TODO: include an example file.
+  ##
+  module Resource
+
+    # ============
+    # = Behavior =
+    # ============
+    include AdHocProperties
+    include SemanticAccessors
+    include RDF::Mutable
+    include RDF::Queryable
+    
+  end
+end

data/lib/gearbox/mixins/semantic_accessors.rb

@@ -0,0 +1,118 @@
+module Gearbox
+  
+  ##
+  # The attributes to add to a model.
+  # TODO: Add example from file.
+  ##
+  module SemanticAccessors
+
+    # Treat this as a bundle of class methods and instance methods.
+    # @private
+    def self.included(base)
+      base.extend ClassMethods
+      base.send :include, InstanceMethods
+    end
+
+    ##
+    # Class methods for the model.
+    ##
+    module ClassMethods
+      
+      # Add an attribute or a field to a model.  Takes a field name.  
+      # Defines both a getter and a setter on the object.
+      # Requires a predicate option.  Options are:
+      # * :predicate => RDF::URI
+      # * :reverse => Boolean store as value, predicate, subject
+      # * :index => Boolean maintain a full-text search index on this attribute
+      # @param [String, Symbol] getter_name, the field that is being created.
+      # @param [Hash] options
+      def attribute(getter_name, options={})
+        
+        raise ArgumentError, "A predicate must be defined" unless options[:predicate]
+        
+        send(attributes_source)[getter_name] = options
+
+        # Define a getter on the object
+        define_method(getter_name) do
+          self.class.yield_attr(getter_name, self)
+        end
+
+        # Define a setter on the object
+        define_method("#{getter_name}=") do |value|
+          self.class.store_attr(getter_name, self, value)
+          # attribute = send(self.class.attributes_source)[getter_name]
+        end
+
+      end
+      
+      # Sets the attributes_source, where to store the attributes
+      attr_writer :attributes_source
+      
+      # Gets the attributes_source...
+      def attributes_source
+        @attributes_source ||= :attribute_collection
+      end
+
+      def attribute_collection
+        @attribute_collection ||= AttributeCollection.new
+      end
+      
+      def yield_attr(getter_name, instance)
+        if statement = instance.rdf_collection[getter_name]
+          # TODO: Deserialize object
+          return statement.object.to_s
+        else
+          attribute_options = send(attributes_source)[getter_name]
+          attribute_options ? attribute_options.default : nil
+        end
+      end
+      
+      def store_attr(getter_name, instance, value)
+        attribute_options = send(attributes_source)[getter_name]
+        # TODO: serialize value
+        statement = RDF::Statement.new(instance.subject, attribute_options.predicate, value)
+        instance.rdf_collection[getter_name] = statement
+      end
+
+    end
+    
+    module InstanceMethods
+      # We collect triples inside the models in order to query them, filter them
+      # and handle the bridge between domain models and the graph we're building.
+      def rdf_collection
+        @rdf_collection ||= RDFCollection.new
+      end
+      
+      def subject
+        "1"
+      end
+      
+      # An initialization strategy for all occasions.
+      def initialize(obj=nil)
+        case obj
+        when Hash
+          merge_hash_values(obj)
+        when RDFCollection
+          merge_rdf_collection(obj)
+        end
+      end
+      
+      private
+      
+        def merge_hash_values(hash)
+          # TODO: work with associations here...
+          hash.each do |getter_name, value|
+            setter_name = "#{getter_name}="
+            send(setter_name, value) if respond_to?(setter_name)
+            # What to do with the others?
+          end
+        end
+        
+        def merge_rdf_collection(collection)
+          rdf_collection.merge!(collection)
+        end
+      
+    end # InstanceMethods
+    
+  end # SemanticAccessors
+end # Gearbox

data/lib/gearbox/rdf_collection.rb

@@ -0,0 +1,72 @@
+module Gearbox
+  
+  ##
+  # Collects model values as RDF.  This is a key part of making SPARQL our primary
+  # filtering, finding, and extension language.  
+  ##
+  class RDFCollection
+    
+    # ============
+    # = Behavior =
+    # ============
+    include RDF::Enumerable
+    
+    def initialize
+      @source = {}
+    end
+    
+    # Enumerates on the RDF Statements.  Necessary for RDF::Enumerable to 
+    # add all of the internal and external iterator goodies available there
+    # (like each_subject and has_subject?).
+    # @param [Block] block Optional block.  Creates an external iterator if omitted.
+    # @return [nil, Enumerator] Returns either nil, or an external iterator.
+    def each(&block)
+      if block_given?
+        @source.each(&block)
+      else
+        Enumerator.new(self, :each)
+      end
+    end
+    
+    # Set RDF::Statements to the underlying collection.  Normalizes the keys.
+    # @param [String, Symbol] key
+    # @param [RDF::Statement] obj.  RDF::Statement that will be added.
+    def add_statement(key, obj)
+      @source[normalize_key(key)] = obj if obj.is_a?(RDF::Statement)
+    end
+    alias :[]= :add_statement
+    
+    # Get RDF::Statement from the underlying collection.  Normalizes the key.
+    # @param [String, Symbol] key.  Normalized.
+    # @return [RDF::Statement, nil] Found statement, if it exists.
+    def [](key)
+      @source[normalize_key(key)]
+    end
+    
+    # Lookup whether the key exists.
+    # @param [String, Symbol] key 
+    # @param [Hash, nil] opts.  :normalize => false will lookup the key as provided.
+    # @return [Boolean]
+    def has_key?(key, opts={})
+      key = normalize_key(key) if opts.fetch(:normalize, true)
+      @source.has_key?(key)
+    end
+    
+    # Merges a hash of RDF::Statements into the underlying collection.
+    # Uses the add_statement to filter the values of the hash.
+    # @param [Hash] hash.  Collection of statements.
+    # @return [nil]
+    def merge!(hash)
+      hash.each {|key, obj| add_statement(key, obj)}
+    end
+    
+    private
+      # Normalizes the key.  Converts to a lower case symbol with non-alpha-numerics
+      # replaced by underscores, removing trailing and preceding underscores.
+      # @private
+      def normalize_key(obj)
+        obj.to_s.downcase.gsub(/[^A-Za-z0-9_]+/, '_').gsub(/(_$)|(^_)/, '').to_sym
+      end
+    
+  end
+end

data/lib/gearbox/type.rb

@@ -0,0 +1,85 @@
+module Gearbox
+
+  ##
+  # This was taken wholesale from Spira.  I think Ben did a great job with that.
+  # I have nothing to add or detract from his good work.
+  # 
+  # Gearbox::Type can be included by classes to create new property types for
+  # Gearbox.  These types are responsible for serialization a Ruby value into an
+  # `RDF::Value`, and deserialization of an `RDF::Value` into a Ruby value.
+  #
+  # A simple example:
+  #
+  #     class Integer
+  #       
+  #       include Gearbox::Type
+  #       
+  #       def self.unserialize(value)
+  #         value.object
+  #       end
+  #       
+  #       def self.serialize(value)
+  #         RDF::Literal.new(value)
+  #       end
+  #       
+  #       register_alias XSD.integer
+  #     end
+  #
+  # This example will serialize and deserialize integers.  It's included with
+  # Gearbox by default.  It allows either of the following forms to declare an
+  # integer property on a Gearbox resource:
+  #
+  #     property :age, :predicate => FOAF.age, :type => Integer
+  #     property :age, :predicate => FOAF.age, :type => XSD.integer
+  #
+  # `Gearbox::Type`s include the RDF namespace and thus have all of the base RDF
+  # vocabularies available to them without the `RDF::` prefix.
+  #
+  # @see http://rdf.rubyforge.org/RDF/Value.html
+  # @see Gearbox::Resource
+  module Type
+
+    ##
+    # Make the DSL available to a child class.
+    #
+    # @private
+    def self.included(child)
+      child.extend(ClassMethods)
+      Gearbox.type_alias(child,child)
+    end
+
+    include RDF
+
+    module ClassMethods
+
+      ##
+      # Register an alias that this type can be referred to as, such as an RDF
+      # URI.  The alias can be any object, symbol, or constant.
+      #
+      # @param [Any] identifier The new alias in property declarations for this class
+      # @return [Void]
+      def register_alias(any)
+        Gearbox.type_alias(any, self)
+      end
+
+      ##
+      # Serialize a given value to RDF.
+      #
+      # @param [Any] value The Ruby value to be serialized
+      # @return [RDF::Value] The RDF form of this value
+      def serialize(value)
+        value
+      end
+
+      ##
+      # Unserialize a given RDF value to Ruby
+      #
+      # @param [RDF::Value] value The RDF form of this value
+      # @return [Any] The Ruby form of this value
+      def unserialize(value)
+        value
+      end
+    end
+
+  end
+end