ladder 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8707de1da44b6fb2a49b9e1ddf36be993201e812
-  data.tar.gz: 9629dc901be61cd1bfa50fa6af34b3e667143e87
+  metadata.gz: 94262dd2e8eb69badfa00eeb2671a19f8637614c
+  data.tar.gz: 0d2b3f22370d591e2c0aa12ccb803156c9712ba6
 SHA512:
-  metadata.gz: 21d4977c566c56b2b33c613c015b6db8a34772b9d96b7532edcbcb9579766002c9ee3f567ad1f697671eff87b2c57d3a0ecd2e8966e2ef3f3c3e61f3c1d1dc3b
-  data.tar.gz: d877c3834d31420eca16bf1f774867caa40ecf3d3460bfcd2bd4dbe09ecbfb4d8e685e42c55606d22fc8bd5fb10c5dfd407c30fc6b002e0d1dc2aa8474227abe
+  metadata.gz: f8afcec27c1a5f503137ebbfba804f7392fed957a62058d2d1c2a3632121b72607cfb96bc2ef44ebc55049666fe55bc45620de08f93fc1b2b308303191ae51fe
+  data.tar.gz: 2c7025c69534858a30b0c5717bf4575a98f3800f85b92111100f28185b6a891394066eab0bbd75f348658e837d836edcf18b5b58e5b188036878d9366adf4459

data/.gitignore

@@ -12,4 +12,7 @@
 *.o
 *.a
 mkmf.log
-*.gem
+*.gem
+.rubocop_todo.yml
+.rubocop.yml
+.ruby-version

data/.semver

@@ -0,0 +1,5 @@
+---
+:major: 0
+:minor: 3
+:patch: 2
+:special: ''

data/Gemfile

@@ -1,3 +1,3 @@
 source 'https://rubygems.org'
 
-gemspec
+gemspec

data/README.md

@@ -64,7 +64,7 @@ end
 
 steve = Person.new(first_name: 'Steve', description: 'Funny-looking')
 => #<Person _id: 542f0c124169720ea0000000, first_name: {"en"=>"Steve"}, description: {"en"=>"Funny-looking"}>
-	
+
 steve.as_document
 => {"_id"=>BSON::ObjectId('542f0c124169720ea0000000'),
  "first_name"=>{"en"=>"Steve"},
@@ -190,7 +190,7 @@ class Place
 
   property :city, predicate: RDF::VCARD.locality
   property :country, predicate: RDF::VCARD.send('country-name')
-  
+
   embedded_in :resident, class_name: 'Person', inverse_of: :address
   property :resident, predicate: RDF::VCARD.agent
 end
@@ -448,8 +448,8 @@ results = Person.search 'shay'
  # #<Elasticsearch::Model::Searching::SearchRequest:0x007fa2ca830a58
  #  @definition={:index=>"people", :type=>"person", :q=>"Shay"},
  #  @klass=[PROXY] Person,
- #  @options={}>>
- 
+ #  @params={}>>
+
 results.count
 => 1
 
@@ -677,8 +677,8 @@ results = OCR.search 'Moomintroll'
  # #<Elasticsearch::Model::Searching::SearchRequest:0x007fa2ca830a58
  #  @definition={:index=>"ocrs", :type=>"ocr", :q=>"Moomintroll"},
  #  @klass=[PROXY] OCR,
- #  @options={}>>
- 
+ #  @params={}>>
+
 results.count
 => 1
 
@@ -708,8 +708,8 @@ results = OCR.search 'Moomintroll', fields: '*'
  # #<Elasticsearch::Model::Searching::SearchRequest:0x007fc36cadab10
  #  @definition={:index=>"ocrs", :type=>"ocr", :body=>{:query=>{:query_string=>{:query=>"Moomintroll"}}, :fields=>"*"}},
  #  @klass=[PROXY] OCR,
- #  @options={}>>
- 
+ #  @params={}>>
+
 results.count
 => 1
 
@@ -734,8 +734,8 @@ results = OCR.search query: { query_string: { query: 'his' } }, highlight: { fie
  #  @definition={:index=>"ocrs", :type=>"ocr", :body=>{:query=>{:query_string=>"Moomintroll"},
  #  :highlight=>{:fields=>{:file=>{}}}}},
  #  @klass=[PROXY] OCR,
- #  @options={}>>
- 
+ #  @params={}>>
+
 results.count
 => 1
 
@@ -760,7 +760,7 @@ class OCR
 end
 
  # ...
- 
+
 class Person
   include Ladder::Resource
   include Ladder::Searchable::Background

data/Rakefile

@@ -1,2 +1 @@
-require "bundler/gem_tasks"
-
+require 'bundler/gem_tasks'

data/ladder.gemspec

@@ -4,33 +4,36 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'ladder/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "ladder"
+  spec.name          = 'ladder'
   spec.version       = Ladder::VERSION
   spec.platform      = Gem::Platform::RUBY
-  spec.authors       = "MJ Suhonos"
-  spec.email         = "mj@suhonos.ca"
-  spec.summary       = %q{ActiveModel Linked Data framework.}
-  spec.description   = %q{Dynamic framework for Linked Data modelling, persistence, and full-text indexing.}
-  spec.homepage      = "https://github.com/ladder/ladder"
-  spec.license       = "APACHE2"
+  spec.authors       = 'MJ Suhonos'
+  spec.email         = 'mj@suhonos.ca'
+  spec.summary       = 'ActiveModel Linked Data framework.'
+  spec.description   = 'Dynamic framework for Linked Data modelling, persistence, and full-text indexing.'
+  spec.homepage      = 'https://github.com/ladder/ladder'
+  spec.license       = 'APACHE2'
   spec.required_ruby_version = '>= 2.0.0'
 
   spec.files         = `git ls-files -z`.split("\x0")
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
+  spec.executables   = spec.files.grep(/^bin/) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(/^(test|spec|features)/)
+  spec.require_paths = ['lib']
 
-  spec.add_dependency "active-triples", "~> 0.6"
-  spec.add_dependency "activejob", "~> 4.2"
-  spec.add_dependency "elasticsearch-model", "~> 0.1"
-  spec.add_dependency "mongoid", "~> 4.0"
-  spec.add_dependency "mongoid-grid_fs", "~> 2.1"
+  spec.add_dependency 'active-triples', '~> 0.6'
+  spec.add_dependency 'activejob', '~> 4.2'
+  spec.add_dependency 'elasticsearch-model', '~> 0.1'
+  spec.add_dependency 'mongoid', '~> 4.0'
+  spec.add_dependency 'mongoid-grid_fs', '~> 2.1'
 
-  spec.add_development_dependency "bundler", "~> 1.7"
-  spec.add_development_dependency "mimemagic", "~> 0.2"
-  spec.add_development_dependency "pry", "~> 0.10"
-  spec.add_development_dependency "rspec", "~> 3.1"
-  spec.add_development_dependency "simplecov", "~> 0.9"
-  spec.add_development_dependency "wirble", "~> 0.1"
-  spec.add_development_dependency "yard", "~> 0.8"
-end
+  spec.add_development_dependency 'awesome_print', '~> 1.6'
+  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'mimemagic', '~> 0.2'
+  spec.add_development_dependency 'pry', '~> 0.10'
+  spec.add_development_dependency 'rspec', '~> 3.2'
+  spec.add_development_dependency 'rubocop', '~> 0.29'
+  spec.add_development_dependency 'semver', '~> 1.0'
+  spec.add_development_dependency 'simplecov', '~> 0.9'
+  spec.add_development_dependency 'wirble', '~> 0.1'
+  spec.add_development_dependency 'yard', '~> 0.8'
+end

data/lib/ladder.rb

@@ -1,4 +1,4 @@
-require "ladder/version"
+require 'ladder/version'
 
 module Ladder
   autoload :File,       'ladder/file'

data/lib/ladder/file.rb

@@ -1,62 +1,71 @@
 require 'mongoid/grid_fs'
 require 'active_triples'
 
-module Ladder::File
-  extend ActiveSupport::Concern
+module Ladder
+  module File
+    extend ActiveSupport::Concern
 
-  include Mongoid::Document
-  include ActiveTriples::Identifiable
+    include Mongoid::Document
+    include ActiveTriples::Identifiable
 
-  included do
-    configure base_uri: RDF::URI.new(LADDER_BASE_URI) / name.underscore.pluralize if defined? LADDER_BASE_URI
+    included do
+      configure base_uri: RDF::URI.new(LADDER_BASE_URI) / name.underscore.pluralize if defined? LADDER_BASE_URI
 
-    store_in collection: "#{ grid.prefix }.files"
+      store_in collection: "#{ grid.prefix }.files"
 
-    # Define accessor methods for attributes
-    define_method(:content_type) { read_attribute(:contentType) }
+      # Define accessor methods for attributes
+      define_method(:content_type) { read_attribute(:contentType) }
 
-    grid::File.fields.keys.map(&:to_sym).each do |attr|
-      define_method(attr) { read_attribute(attr) }
+      grid::File.fields.keys.map(&:to_sym).each do |attr|
+        define_method(attr) { read_attribute(attr) }
+      end
+
+      around_save :save_file
     end
 
-    around_save :save_file
-  end
+    attr_accessor :file
 
-  attr_accessor :file
-  
-  ##
-  # Output content of object from stored file or readable input
-  def data
-    @grid_file ||= self.class.grid.get(id) if persisted?
-    return @grid_file.data if @grid_file
+    ##
+    # Output content of object from stored file or readable input
+    #
+    # @return [String] string-encoded copy of binary data
+    def data
+      @grid_file ||= self.class.grid.get(id) if persisted?
+      return @grid_file.data if @grid_file
 
-    file.rewind if file.respond_to? :rewind
-    file.read
-  end
-  
-  ##
-  # Return an empty ActiveTriples resource for serializing related resources
-  def update_resource
-    resource
-  end
-  
-  private
+      file.rewind if file.respond_to? :rewind
+      file.read
+    end
+
+    ##
+    # Return an empty ActiveTriples resource for serializing related resources
+    #
+    # @return [ActiveTriples::Resource] resource for the object
+    def update_resource
+      resource
+    end
+
+    private
 
     ##
     # Make save behave like Mongoid::Document as much as possible
-    def save_file(&block)
+    #
+    # @return result of #run_callbacks, @see ActiveSupport::Callbacks
+    def save_file
       attributes[:content_type] = file.content_type if file.respond_to? :content_type
-      @grid_file ? @grid_file.save : !! @grid_file = self.class.grid.put(file, attributes.symbolize_keys)
+      @grid_file ? @grid_file.save : @grid_file = self.class.grid.put(file, attributes.symbolize_keys)
 
       persisted? ? run_callbacks(:update) : run_callbacks(:create)
     end
 
-  module ClassMethods
-    ##
-    # Create a namespaced GridFS module for this class
-    def grid
-     @grid ||= Mongoid::GridFs.build_namespace_for name
+    module ClassMethods
+      ##
+      # Create a namespaced GridFS module for this class
+      #
+      # @return [Module] a Mongoid::GridFs module for this class
+      def grid
+        @grid ||= Mongoid::GridFs.build_namespace_for name
+      end
     end
   end
-
-end
+end

data/lib/ladder/resource.rb

@@ -1,56 +1,112 @@
 require 'mongoid'
 require 'active_triples'
 
-module Ladder::Resource
-  autoload :Dynamic, 'ladder/resource/dynamic'
-  autoload :Serializable, 'ladder/resource/serializable'
+module Ladder
+  module Resource
+    autoload :Dynamic, 'ladder/resource/dynamic'
+    autoload :Serializable, 'ladder/resource/serializable'
 
-  extend ActiveSupport::Concern
+    extend ActiveSupport::Concern
 
-  include Mongoid::Document
-  include ActiveTriples::Identifiable
-  include Ladder::Resource::Serializable
+    include Mongoid::Document
+    include ActiveTriples::Identifiable
+    include Ladder::Resource::Serializable
 
-  included do
-    configure base_uri: RDF::URI.new(LADDER_BASE_URI) / name.underscore.pluralize if defined? LADDER_BASE_URI
-  end
+    included do
+      configure base_uri: RDF::URI.new(LADDER_BASE_URI) / name.underscore.pluralize if defined? LADDER_BASE_URI
+    end
 
-  delegate :rdf_label, to: :update_resource
+    delegate :rdf_label, to: :update_resource
 
-  ##
-  # Populate resource properties from ActiveModel
-  def update_resource(opts = {})
-    resource_class.properties.each do |name, property|
-      value = update_from_field(name) if fields[name]
-      value = update_from_relation(name, opts) if relations[name]
+    ##
+    # Update the delegated ActiveTriples::Resource from
+    # ActiveModel properties & relations
+    #
+    # @param [Hash] opts options to pass to Mongoid / ActiveTriples
+    # @option opts [Boolean] :related whether to include related resources
+    # @return [ActiveTriples::Resource] resource for the object
+    def update_resource(opts = {})
+      resource_class.properties.each do |field_name, property|
+        value = update_from_field(field_name) if fields[field_name]
+        value = update_from_relation(field_name, opts[:related]) if relations[field_name]
+
+        resource.set_value(property.predicate, value) # if value
+      end
 
-      resource.set_value(property.predicate, value) #if value
+      resource
     end
 
-    resource
-  end
+    ##
+    # Push an RDF::Statement into the object
+    #
+    # @param [RDF::Statement, Hash, Array] statement @see RDF::Statement#from
+    # @return [void]
+    def <<(statement)
+      # ActiveTriples::Resource expects: RDF::Statement, Hash, or Array
+      statement = RDF::Statement.from(statement) unless statement.is_a? RDF::Statement
+
+      # Only push statement if the statement's predicate is defined on the class
+      field_name = field_from_predicate(statement.predicate)
+      return unless field_name
+
+      # If the object is a URI, see if it is a retrievable model object
+      value = Ladder::Resource.from_uri(statement.object) if statement.object.is_a? RDF::URI
+
+      # TODO: tidy this code
+      # subject (RDF::Term) - A symbol is converted to an interned Node.
+      # predicate (RDF::URI)
+      # object (RDF::Resource) - if not a Resource, it is coerced to Literal or Node
+      #                depending on if it is a symbol or something other than a Term.
+      value = yield if block_given?
+      value ||= statement.object.to_s
+
+      enum = send(field_name)
+
+      if enum.is_a?(Enumerable)
+        enum.send(:push, value) unless enum.include? value
+      else
+        send("#{field_name}=", value)
+      end
+    end
 
-  ##
-  # Push RDF statement into resource
-  def <<(data)
-    # ActiveTriples::Resource expects: RDF::Statement, Hash, or Array
-    data = RDF::Statement.from(data) unless data.is_a? RDF::Statement
+    ##
+    # Retrieve the class for a relation, based on its defined RDF predicate
+    #
+    # @param [RDF::URI] predicate a URI for the RDF::Term
+    # @return [Ladder::Resource, Ladder::File, nil] related class
+    def klass_from_predicate(predicate)
+      field_name = field_from_predicate(predicate)
+      return unless field_name
 
-    # Only push statement if the statement's predicate is defined on the class
-    if resource_class.properties.values.map(&:predicate).include? data.predicate
-      field_name = resource_class.properties.select { |name, term| term.predicate == data.predicate }.keys.first.to_sym
+      relation = relations[field_name]
+      return unless relation
 
-      # Set the value in Mongoid
-      value = data.object.is_a?(RDF::Literal) ? data.object.object : data.object.to_s
-      self.send("#{field_name}=", value)
+      relation.class_name.constantize
     end
-  end
 
-  private
+    private
+
+    ##
+    # Retrieve the attribute name for a field or relation,
+    # based on its defined RDF predicate
+    #
+    # @param [RDF::URI] predicate a URI for the RDF::Term
+    # @return [String, nil] name for the attribute
+    def field_from_predicate(predicate)
+      defined_prop = resource_class.properties.find { |_field_name, term| term.predicate == predicate }
+      return unless defined_prop
+
+      defined_prop.first
+    end
 
-    def update_from_field(name)
-      if fields[name].localized?
-        localized_hash = read_attribute(name)
+    ##
+    # Update the delegated ActiveTriples::Resource from a field
+    #
+    # @param [String] field_name ActiveModel attribute name for the field
+    # @return [void]
+    def update_from_field(field_name)
+      if fields[field_name].localized?
+        localized_hash = read_attribute(field_name)
 
         unless localized_hash.nil?
           localized_hash.map do |lang, value|
@@ -59,20 +115,26 @@ module Ladder::Resource
           end
         end
       else
-        self.send(name)
+        send(field_name)
       end
     end
-    
-    def update_from_relation(name, opts = {})
-      objects = self.send(name).to_a
 
-      if opts[:related] or embedded_relations[name]
+    ##
+    # Update the delegated ActiveTriples::Resource from a relation
+    #
+    # @param [String] field_name ActiveModel attribute name for the relation
+    # @param [Boolean] related whether to include related objects
+    # @return [void]
+    def update_from_relation(field_name, related = false)
+      objects = send(field_name).to_a
+
+      if related || embedded_relations[field_name]
         # Force autosave of related documents to ensure correct serialization
-        methods.select{|i| i[/autosave_documents/] }.each{|m| send m}
+        methods.select { |i| i[/autosave_documents/] }.each { |m| send m }
 
         # update inverse relation properties
-        relation_def = relations[name]
-        objects.each { |object| object.resource.set_value(relation_def.inverse, self.rdf_subject) } if relation_def.inverse
+        relation_def = relations[field_name]
+        objects.each { |object| object.resource.set_value(relation_def.inverse, rdf_subject) } if relation_def.inverse
         objects.map(&:update_resource)
       else
         # remove inverse relation properties
@@ -81,26 +143,108 @@ module Ladder::Resource
       end
     end
 
-  public
+    public
+
+    module ClassMethods
+      ##
+      # Define a Mongoid field/relation on the class as well as
+      # an RDF property on the delegated resource
+      #
+      # @see ActiveTriples::Resource#property
+      # @see ActiveTriples::Properties
+      #
+      # @param [String] field_name ActiveModel attribute name for the field
+      # @param [Hash] opts options to pass to Mongoid / ActiveTriples
+      # @return [ActiveTriples::Resource] a modified resource
+      def property(field_name, opts = {})
+        if opts[:class_name]
+          mongoid_opts = { autosave: true, index: true }.merge(opts.except(:predicate, :multivalue))
+          has_and_belongs_to_many(field_name, mongoid_opts) unless relations.keys.include? field_name.to_s
+        else
+          mongoid_opts = { localize: true }.merge(opts.except(:predicate, :multivalue))
+          field(field_name, mongoid_opts) unless fields[field_name.to_s]
+        end
+
+        opts.except!(*mongoid_opts.keys)
+
+        super
+      end
+
+      ##
+      # Create a new instance of this class, populated with values
+      # and related objects from a given RDF::Graph for this model.
+      #
+      # By default, the graph will be traversed starting with the first
+      # node that matches the same RDF.type as this class; however, an
+      # optional RDF::Queryable pattern can be provided, @see RDF::Queryable#query
+      #
+      # As nodes are traversed in the graph, the instantiated objects
+      # will be added to a Hash that is passed recursively, in order to
+      # prevent infinite traversal in the case of cyclic graphs.
+      #
+      # @param [RDF::Graph] graph an RDF::Graph to traverse
+      # @param [Hash] objects a keyed Hash of already-created objects in the graph
+      # @param [RDF::Query, RDF::Statement, Array(RDF::Term), Hash] pattern a query pattern
+      # @return [Ladder::Resource, nil] an instance of this class
+      def new_from_graph(graph, objects = {}, pattern = nil)
+        # Default to getting the first object in the graph with the same RDF type as this class
+        pattern ||= [nil, RDF.type, resource_class.type]
+
+        root_subject = graph.query(pattern).first_subject
+        return unless root_subject
+
+        # If the subject is an existing model, just retrieve it
+        new_object = Ladder::Resource.from_uri(root_subject) if root_subject.is_a? RDF::URI
+        new_object ||= new
+
+        # Add object to stack for recursion
+        objects[root_subject] = new_object
+
+        graph.query([root_subject]).each_statement do |statement|
+          next if objects[statement.object]
+
+          # TODO: If the object is a list, process members individually
+          # list = RDF::List.new statement.object, graph
+          # binding.pry unless list.empty?
+
+          # If the object is a BNode, dereference the relation
+          if statement.object.is_a? RDF::Node
+            klass = new_object.klass_from_predicate(statement.predicate)
+            next unless klass
+
+            object = klass.new_from_graph(graph, objects)
+            next unless object
+
+            objects[statement.object] = object
+            new_object.send(:<<, statement) { object }
+          else
+            new_object << statement
+          end
+        end # end each_statement
+
+        new_object
+      end
+    end
 
-  module ClassMethods
-    
     ##
-    # Overload ActiveTriples #property
+    # Return a persisted instance of a Ladder::Resource from its
+    # RDF subject URI, without knowing the resource class.
+    #
+    # If there is no persisted instance for the URI, but the class
+    # is identifiable, then return a new instance of that class
     #
-    # @see ActiveTriples::Properties
-    def property(name, opts={})
-      if class_name = opts[:class_name]
-        mongoid_opts = {autosave: true, index: true}.merge(opts.except(:predicate, :multivalue))
-        opts.except! *mongoid_opts.keys
+    # @param [RDF::URI] uri RDF subject URI for the resource
+    # @return [Ladder::Resource] a resource instance
+    def self.from_uri(uri)
+      klasses = ActiveTriples::Resource.descendants.select(&:name)
+      klass = klasses.find { |k| uri.to_s.include? k.base_uri.to_s }
 
-        has_and_belongs_to_many(name, mongoid_opts) unless relations.keys.include? name.to_s
-      else
-        field(name, localize: true) unless fields[name.to_s]
-      end
+      if klass
+        object_id = uri.to_s.match(/[0-9a-fA-F]{24}/).to_s
 
-      super
+        # Retrieve the object if it's persisted, otherwise return a new one (eg. embedded)
+        return klass.parent.where(id: object_id).exists? ? klass.parent.find(object_id) : klass.parent.new
+      end
     end
   end
-
-end
+end