tripod 0.0.2 → 0.0.3

data/README.md

@@ -1,7 +1,13 @@
 # Tripod
 
-Active Model style Ruby ORM for RDF data, inspired by http://github.com/mongoid/mongoid
+ActiveModel-style Ruby ORM for RDF data.
 
-Warning: Work still in progress / experimental. Not production ready!
+    gem install tripod
 
-Copyright (c) 2012 Swirrl IT Limited. http://swirrl.com. Released under MIT License
+[Documentation](http://rubydoc.info/github/Swirrl/tripod/master/frames)
+
+__Warning: Work still in progress / experimental. Not production ready!__
+
+Heavily inspired by [Durran Jordan's](https://github.com/durran) excellent [Mongoid](http://mongoid.org/en/mongoid/) ORM for [MongoDB](http://www.mongodb.org/).
+
+Copyright (c) 2012 [Swirrl IT Limited](http://swirrl.com). Released under MIT License

data/lib/tripod.rb

@@ -60,6 +60,7 @@ module Tripod
 
 end
 
+require "tripod/extensions"
 require "tripod/sparql_client"
 
 require "tripod/attributes"

data/lib/tripod/attributes.rb

@@ -58,12 +58,8 @@ module Tripod::Attributes
   # Append the statement-values for a single predicate in this resource's in-memory repository. Basically just adds a new statement for this ((resource's uri)+predicate)
   #
   # @example Write the attribute.
-  #   person.append_attribute('http://title', "Mrs.")
-  #   person.append_attribute('http://title', "Ms.")
-  #
-  # @example Write the attribute (alternate syntax.)
-  #   person['http://title'] << "Mrs."
-  #   person['http://title'] << "Ms."
+  #   person.append_to_attribute('http://title', "Mrs.")
+  #   person.append_to_attribute('http://title', "Ms.")
   #
   # @param [ String, RDF::URI ] predicate_uri The uri of the attribute to update.
   # @param [ Object ] value The values to append for the attribute. Should compatible with RDF::Terms
@@ -76,5 +72,6 @@ module Tripod::Attributes
       @repository.delete( statement )
     end
   end
+  alias :delete :remove_attribute
 
 end

data/lib/tripod/extensions.rb

@@ -0,0 +1,2 @@
+# encoding: utf-8
+require "tripod/extensions/module"

data/lib/tripod/extensions/module.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+module Tripod::Extensions
+  module Module
+
+    # Redefine the method. Will undef the method if it exists or simply
+    # just define it.
+    #
+    # @example Redefine the method.
+    #   Object.re_define_method("exists?") do
+    #     self
+    #   end
+    #
+    # @param [ String, Symbol ] name The name of the method.
+    # @param [ Proc ] block The method body.
+    #
+    # @return [ Method ] The new method.
+    def re_define_method(name, &block)
+      undef_method(name) if method_defined?(name)
+      define_method(name, &block)
+    end
+  end
+end
+
+::Module.__send__(:include, Tripod::Extensions::Module)

data/lib/tripod/fields.rb

@@ -1,7 +1,175 @@
 # encoding: utf-8
+require "tripod/fields/standard"
 
  # This module defines behaviour for fields.
 module Tripod::Fields
   extend ActiveSupport::Concern
 
+  included do
+    class_attribute :fields
+    self.fields = {}
+  end
+
+  module ClassMethods
+
+    # Defines all the fields that are accessible on the Resource
+    # For each field that is defined, a getter and setter will be
+    # added as an instance method to the Resource.
+    #
+    # @example Define a field.
+    #   field :name, :predicate => 'http://name'
+    #
+    # @param [ Symbol ] name The name of the field.
+    # @param [ String, RDF::URI ] predicate The predicate for the field.
+    # @param [ Hash ] options The options to pass to the field.
+    #
+    # @option options [ String, RDF::URI ] datatype The uri of the datatype for the field (will be used to create an RDF::Literal of the right type on the way in only).
+    # @option options [ Boolean ] multivalued Is this a multi-valued field? Default is false.
+    #
+    # @return [ Field ] The generated field
+    def field(name, predicate, options = {})
+      named = name.to_s
+      # TODO: validate the field params/options here..
+      add_field(named, predicate, options)
+    end
+
+
+    def new_value_for_field(value, field)
+      if field.datatype
+        RDF::Literal.new(value, :datatype => field.datatype)
+      else
+        value
+      end
+    end
+
+    protected
+
+    # Define a field attribute for the +Resource+.
+    #
+    # @example Set the field.
+    #   Person.add_field(:name, :predicate => 'http://myfield')
+    #
+    # @param [ Symbol ] name The name of the field.
+    # @param [ String, RDF::URI ] predicate The predicate for the field.
+    # @param [ Hash ] options The hash of options.
+    def add_field(name, predicate, options = {})
+      # create a field object and store it in our hash
+      field = field_for(name, predicate, options)
+      fields[name] = field
+
+      # set up the accessors for the fields
+      create_accessors(name, name, options)
+      field
+    end
+
+    # Create the field accessors.
+    #
+    # @example Generate the accessors.
+    #   Person.create_accessors(:name, "name")
+    #   person.name #=> returns the field
+    #   person.name = "" #=> sets the field
+    #   person.name? #=> Is the field present?
+    #
+    # @param [ Symbol ] name The name of the field.
+    # @param [ Symbol ] meth The name of the accessor.
+    # @param [ Hash ] options The options.
+    def create_accessors(name, meth, options = {})
+      field = fields[name]
+
+      create_field_getter(name, meth, field)
+      create_field_setter(name, meth, field)
+      create_field_check(name, meth, field)
+    end
+
+    # Create the getter method for the provided field.
+    #
+    # @example Create the getter.
+    #   Model.create_field_getter("name", "name", field)
+    #
+    # @param [ String ] name The name of the attribute.
+    # @param [ String ] meth The name of the method.
+    # @param [ Field ] field The field.
+    def create_field_getter(name, meth, field)
+      generated_methods.module_eval do
+        re_define_method(meth) do
+
+          attr_values = read_attribute(field.predicate)
+
+          # We always return strings on way out.
+          # If the field is multivalued, return an array of the results
+          # If it's not multivalued, return the first (should be only) result.
+          if field.multivalued
+            attr_values.map(&:to_s)
+          else
+            attr_values.first.to_s
+          end
+        end
+      end
+    end
+
+    # Create the setter method for the provided field.
+    #
+    # @example Create the setter.
+    #   Model.create_field_setter("name", "name")
+    #
+    # @param [ String ] name The name of the attribute.
+    # @param [ String ] meth The name of the method.
+    # @param [ Field ] field The field.
+    def create_field_setter(name, meth, field)
+      generated_methods.module_eval do
+        re_define_method("#{meth}=") do |value|
+          if value.kind_of?(Array)
+            if field.multivalued
+              new_val = []
+              value.each do |v|
+                new_val << self.class.new_value_for_field(v, field)
+              end
+            else
+              new_val = self.class.new_value_for_field(value.first, field)
+            end
+          else
+            new_val = self.class.new_value_for_field(value, field)
+          end
+
+          write_attribute(field.predicate, new_val)
+        end
+      end
+    end
+
+    # Create the check method for the provided field.
+    #
+    # @example Create the check.
+    #   Model.create_field_check("name", "name")
+    #
+    # @param [ String ] name The name of the attribute.
+    # @param [ String ] meth The name of the method.
+    def create_field_check(name, meth, field)
+      generated_methods.module_eval do
+        re_define_method("#{meth}?") do
+          attr = read_attribute(field.predicate)
+          attr == true || attr.present?
+        end
+      end
+    end
+
+     # Include the field methods as a module, so they can be overridden.
+    #
+    # @example Include the fields.
+    #   Person.generated_methods
+    #
+    # @return [ Module ] The module of generated methods.
+    def generated_methods
+      @generated_methods ||= begin
+        mod = Module.new
+        include(mod)
+        mod
+      end
+    end
+
+
+    # instantiates and returns a new standard field
+    def field_for(name, predicate, options)
+      Tripod::Fields::Standard.new(name, predicate, options)
+    end
+  end
 end

data/lib/tripod/fields/standard.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+module Tripod::Fields
+  # Defines the behaviour for defined fields in the resource.
+  class Standard
+
+    # Set readers for the instance variables.
+    attr_accessor :name, :predicate, :options, :datatype, :multivalued
+
+    # Create the new field with a name and optional additional options.
+    #
+    # @example Create the new field.
+    #   Field.new(:name, 'http://foo', opts)
+    #
+    # @param [ String ] name The field name.
+    # @param [ String, RDF::URI ] predicate The field's predicate.
+    # @param [ Hash ] options The field options.
+    #
+    # @option options [ String, RDF::URI ] datatype The uri of the datatype for the field (will be used to create an RDF::Literal of the right type on the way in only).
+    # @option options [ Boolean ] multivalued Is this a multi-valued field? Default is false.
+    def initialize(name, predicate, options = {})
+      @name = name
+      @options = options
+      @predicate = RDF::URI.new(predicate.to_s)
+      @datatype = RDF::URI.new(options[:datatype].to_s) if options[:datatype]
+      @multivalued = options[:multivalued] || false
+    end
+
+  end
+end

data/lib/tripod/finders.rb

@@ -14,7 +14,7 @@ module Tripod::Finders
     #
     # @param [ String, RDF::URI ] uri The uri of the resource to find
     #
-    # @raise [ Errors::DocumentNotFound ] If no document found.
+    # @raise [ Tripod::Errors::ResourceNotFound ] If no resource found.
     #
     # @return [ Resource ] A single resource
     def find(uri)

data/lib/tripod/persistence.rb

@@ -29,6 +29,16 @@ module Tripod::Persistence
     end
   end
 
+  # Save the resource, and raise an exception if it fails.
+  # Note: As with save(), regardless of whether it's a new_record or not, we always make the
+  # db match the contents of this resource's statements.
+  #
+  # @example Save the resource.
+  #   resource.save
+  #
+  # @raise [Tripod::Errors::Validations] if invalid
+  #
+  # @return [ true ] True is success.
   def save!()
     # try to save
     unless self.save()

data/lib/tripod/repository.rb

@@ -13,7 +13,7 @@ module Tripod::Repository
   #   person.hydrate!
   #
   # @example Hydrate the resource from a passed in graph
-  #   person.hydrate!(my_graph)
+  #   person.hydrate!(my_graph)
   #
   # @return [ RDF::Repository ] A reference to the repository for this instance.
   def hydrate!(graph = nil)

data/lib/tripod/sparql_client.rb

@@ -5,14 +5,12 @@ module Tripod::SparqlClient
 
   module Query
 
-
     # Runs a +sparql+ query against the endpoint. Returns a RestClient response object.
     #
     # @example Run a query
-    #   Tripload::Sparql.query('SELECT * WHERE {?s ?p ?o}')
+    #   Tripod::SparqlClient::Query.query('SELECT * WHERE {?s ?p ?o}')
     #
     # @return [ RestClient::Response ]
-
     def self.query(sparql, format='json', headers = {})
 
       begin
@@ -44,7 +42,7 @@ module Tripod::SparqlClient
     # @param [ String ] raw_format valid formats are: 'json', 'text', 'csv', 'xml'
     #
     # @example Run a SELECT query
-    #   Triploid::Sparql.select('SELECT * WHERE {?s ?p ?o}')
+    #   Tripod::SparqlClient::Query.select('SELECT * WHERE {?s ?p ?o}')
     #
     # @return [ Hash, String ]
     def self.select(query, raw_format=nil)
@@ -60,7 +58,7 @@ module Tripod::SparqlClient
     # Executes the +query+ and returns ntriples by default
     #
     # @example Run a DESCRIBE query
-    #  Triploid::Sparql.select('DESCRIBE <http://foo>')
+    #   Tripod::SparqlClient::Query.select('DESCRIBE <http://foo>')
     #
     # @param [ String ] query The query to run
     # @param [ String ] accept_header The header to pass to the database.
@@ -74,6 +72,12 @@ module Tripod::SparqlClient
 
   module Update
 
+    # Runs a +sparql+ update against the endpoint. Returns true if success.
+    #
+    # @example Run a query
+    #   Tripod::SparqlClient::Update.update('DELETE {?s ?p ?o} WHERE {?s ?p ?o};')
+    #
+    # @return [ true ]
     def self.update(sparql)
 
       begin
@@ -83,7 +87,7 @@ module Tripod::SparqlClient
           :timeout => Tripod.timeout_seconds,
           :payload => {:update => sparql}
         )
-        return true
+        true
       rescue RestClient::BadRequest => e
         body = e.http_body
         if body.start_with?('Error 400: Parse error:')

data/lib/tripod/state.rb

@@ -21,7 +21,7 @@ module Tripod::State
   end
 
   # Checks if the resource has been saved to the database. Returns false
-  # if the document has been destroyed.
+  # if the resource has been destroyed.
   #
   # @example Is the resource persisted?
   #   person.persisted?

data/lib/tripod/version.rb

@@ -1,3 +1,3 @@
 module Tripod
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/spec/app/models/person.rb

@@ -2,4 +2,9 @@ class Person
 
   include Tripod::Resource
 
+  field :name, 'http://name'
+  field :aliases, 'http://alias', :multivalued => true
+  field :age, 'http://age', :datatype => RDF::XSD.integer
+  field :important_dates, 'http://importantdates', :datatype => RDF::XSD.date, :multivalued => true
+
 end

data/spec/tripod/fields_spec.rb

@@ -0,0 +1,87 @@
+require "spec_helper"
+
+describe Tripod::Fields do
+
+  describe ".field" do
+
+    let(:barry) do
+      b = Person.new('http://barry')
+      b['http://name'] = 'Barry'
+      b['http://alias'] = ['Basildon', 'Baz']
+      b['http://age'] = 54
+      b['http://importantdates'] = [Date.new(2010,01,01), Date.new(2012,01,01)]
+      b
+    end
+
+    context "with no options" do
+
+      it "creates a getter for the field, which accesses data for the predicate, returning a single String" do
+        barry.name.should == "Barry"
+      end
+
+      it "creates a setter for the field, which sets data for the predicate" do
+        barry.name = "Basildon"
+        barry.name.should == "Basildon"
+        barry['http://name'].should == [RDF::Literal.new("Basildon")]
+      end
+
+    end
+
+    context "with multivalued option" do
+
+      it "creates a getter for the field, which accesses data for the predicate, returning an array of Strings" do
+        barry.aliases.should == ['Basildon', 'Baz']
+      end
+
+      it "creates a setter for the field, which sets data for the predicate" do
+        barry.aliases = ['Basildon', 'Baz', 'B-man']
+        barry.aliases.should == ['Basildon', 'Baz', 'B-man']
+        barry['http://alias'].should == [RDF::Literal.new("Basildon"),RDF::Literal.new("Baz"),RDF::Literal.new("B-man")]
+      end
+
+      context 'with data type' do
+
+        it "creates a getter for the field, which accesses data for the predicate, returning an array of Strings" do
+          barry.important_dates.class.should == Array
+          barry.important_dates.should == ["2010-01-01Z", "2012-01-01Z"]
+        end
+
+        it "creates a setter for the field, which sets data for the predicate, using the right data type" do
+          barry.important_dates = [Date.new(2010,01,02),Date.new(2010,01,03)]
+          barry['http://importantdates'].should == [ RDF::Literal.new(Date.new(2010,01,02)), RDF::Literal.new(Date.new(2010,01,03)) ]
+          barry['http://importantdates'].map(&:datatype).should == [RDF::XSD.date,RDF::XSD.date]
+        end
+
+      end
+
+    end
+
+    context 'with data type' do
+
+      it "creates a getter for the field, which accesses data for the predicate, returning a single String" do
+        barry.age.should == "54"
+      end
+
+      it "creates a setter for the field, which sets data for the predicate, using the right data type" do
+        barry.age = 57
+        barry.age.should == '57'
+        barry['http://age'] = [ RDF::Literal.new(57) ]
+        barry['http://age'].first.datatype = RDF::XSD.integer
+      end
+
+    end
+
+    context 'with no data type specified' do
+
+      it "creates the right kind of literals when setting values." do
+        barry.name == 100 # set an integer
+        barry['http://name'] = [ RDF::Literal.new(100) ]
+        barry['http://name'].first.datatype = RDF::XSD.integer
+      end
+
+
+    end
+
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tripod
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-27 00:00:00.000000000 Z
+date: 2012-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
-  requirement: &70292958584520 !ruby/object:Gem::Requirement
+  requirement: &70124707968440 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70292958584520
+  version_requirements: *70124707968440
 - !ruby/object:Gem::Dependency
   name: activemodel
-  requirement: &70292958583980 !ruby/object:Gem::Requirement
+  requirement: &70124707967900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: '3.1'
   type: :runtime
   prerelease: false
-  version_requirements: *70292958583980
+  version_requirements: *70124707967900
 - !ruby/object:Gem::Dependency
   name: equivalent-xml
-  requirement: &70292958583560 !ruby/object:Gem::Requirement
+  requirement: &70124707967480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70292958583560
+  version_requirements: *70124707967480
 - !ruby/object:Gem::Dependency
   name: rdf
-  requirement: &70292958583020 !ruby/object:Gem::Requirement
+  requirement: &70124707966940 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +54,10 @@ dependencies:
         version: '0.3'
   type: :runtime
   prerelease: false
-  version_requirements: *70292958583020
+  version_requirements: *70124707966940
 - !ruby/object:Gem::Dependency
   name: rdf-rdfxml
-  requirement: &70292958582600 !ruby/object:Gem::Requirement
+  requirement: &70124707966520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70292958582600
+  version_requirements: *70124707966520
 - !ruby/object:Gem::Dependency
   name: rdf-n3
-  requirement: &70292958582140 !ruby/object:Gem::Requirement
+  requirement: &70124707966060 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70292958582140
+  version_requirements: *70124707966060
 - !ruby/object:Gem::Dependency
   name: rdf-json
-  requirement: &70292958581720 !ruby/object:Gem::Requirement
+  requirement: &70124707965640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,7 +87,7 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70292958581720
+  version_requirements: *70124707965640
 description: RDF ruby ORM
 email:
 - ric@swirrl.com
@@ -107,7 +107,10 @@ files:
 - lib/tripod/errors/resource_not_found.rb
 - lib/tripod/errors/uri_not_set.rb
 - lib/tripod/errors/validations.rb
+- lib/tripod/extensions.rb
+- lib/tripod/extensions/module.rb
 - lib/tripod/fields.rb
+- lib/tripod/fields/standard.rb
 - lib/tripod/finders.rb
 - lib/tripod/persistence.rb
 - lib/tripod/repository.rb
@@ -118,6 +121,7 @@ files:
 - spec/app/models/person.rb
 - spec/spec_helper.rb
 - spec/tripod/attributes_spec.rb
+- spec/tripod/fields_spec.rb
 - spec/tripod/finders_spec.rb
 - spec/tripod/persistence_spec.rb
 - spec/tripod/repository_spec.rb
@@ -152,6 +156,7 @@ test_files:
 - spec/app/models/person.rb
 - spec/spec_helper.rb
 - spec/tripod/attributes_spec.rb
+- spec/tripod/fields_spec.rb
 - spec/tripod/finders_spec.rb
 - spec/tripod/persistence_spec.rb
 - spec/tripod/repository_spec.rb