ladder 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 94262dd2e8eb69badfa00eeb2671a19f8637614c
-  data.tar.gz: 0d2b3f22370d591e2c0aa12ccb803156c9712ba6
+  metadata.gz: 1f0ab0c27e81412e4f124be731b6de0abb4ce723
+  data.tar.gz: 3d3e89d64df981809eebb4fdbdc8755033676a6c
 SHA512:
-  metadata.gz: f8afcec27c1a5f503137ebbfba804f7392fed957a62058d2d1c2a3632121b72607cfb96bc2ef44ebc55049666fe55bc45620de08f93fc1b2b308303191ae51fe
-  data.tar.gz: 2c7025c69534858a30b0c5717bf4575a98f3800f85b92111100f28185b6a891394066eab0bbd75f348658e837d836edcf18b5b58e5b188036878d9366adf4459
+  metadata.gz: 6f9e6883c2d960327de40b1d82fe22d38c1e8f8b43072ac6f6bf2ed8b1646b90e4e3ebeb8ed8d8c0006a8a02072ee1f4fddbb4d3787b0c179d72346f77f0d2dd
+  data.tar.gz: f5c77d39b0890fa5a5af2ebc5ea7a361c1f24a6ae6b2e5bc05f6c8d9f5289716ae26f180f922f66c74bf7af4a93af51906b627e0b87893ab15bd85a189e065cd

data/.semver

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

data/README.md

@@ -6,7 +6,7 @@
 
 Ladder is a dynamic framework for [Linked Data](http://en.wikipedia.org/wiki/Linked_data) modelling, persistence, and full-text indexing. It is implemented as a series of Ruby modules that can be used individually and incorporated within existing ActiveModel frameworks (eg. [Project Hydra](http://projecthydra.org)), or combined as a comprehensive stack.
 
-Ladder is intended to encourage the [GLAM](http://en.wikipedia.org/wiki/GLAM_(industry_sector)) community to think less dogmatically about established (often monolithic and/or niche) tools and instead embrace a broader vision of adopting more widely-used technologies.
+Although conceptually similar to [Spira](https://github.com/ruby-rdf/spira), Ladder takes the opposite approach: instead of making RDF repositories (triple stores) behave like ActiveModel, it allows ActiveModel objects to behave like RDF resources.
 
 ### Components
 
@@ -17,7 +17,9 @@ Ladder is intended to encourage the [GLAM](http://en.wikipedia.org/wiki/GLAM_(in
 
 ## History
 
-Ladder was loosely conceived over the course of several years prior to 2011.  In early 2012, Ladder began existence as an opportunity to escape from a decade of LAMP development and become familiar with Ruby.  From 2012 to late 2013, a closed prototype was built under the auspices of [Deliberate Data](http://deliberatedata.com) as a proof-of-concept to test the feasibility of the design.  For those interested in the historical code, the original [prototype](https://github.com/ladder/ladder/tree/prototype) branch is available, as is an [experimental](https://github.com/ladder/ladder/tree/l2) branch.
+Ladder was loosely conceived over the course of several years prior to 2011 as a way to encourage the [GLAM](http://en.wikipedia.org/wiki/GLAM_(industry_sector)) community to think less dogmatically about established (often monolithic and/or niche) tools and instead embrace a broader vision of adopting more widely-used technologies.
+
+In early 2012, Ladder began existence as an opportunity to escape from a decade of LAMP development and become familiar with Ruby.  From 2012 to late 2013, a closed prototype was built under the auspices of [Deliberate Data](http://deliberatedata.com) as a proof-of-concept to test the feasibility of the design.  For those interested in the historical code, the original [prototype](https://github.com/ladder/ladder/tree/prototype) branch is available, as is an [experimental](https://github.com/ladder/ladder/tree/l2) branch.
 
 ## Installation
 
@@ -38,13 +40,13 @@ Or install it yourself as:
 ## Usage
 
 * [Resources](#resources)
-  * [Configuring Resources](#configuring-resources)
   * [Dynamic Resources](#dynamic-resources)
 * [Files](#files)
 * [Indexing](#indexing)
   * [Indexing Resources](#indexing-resources)
   * [Indexing Files](#indexing-files)
   * [Background Indexing](#background-indexing)
+* [Configuration](#configuration)
 
 ### Resources
 
@@ -89,7 +91,19 @@ steve.as_jsonld
  # }
 ```
 
-The `#property` method takes care of setting both Mongoid fields and ActiveTriples properties.  Properties with literal values are localized by default.  Properties with a supplied `class_name:` will create a has-and-belongs-to-many (HABTM) relation:
+The `#property` method takes care of setting both Mongoid fields and ActiveTriples properties.  Properties with literal values (Mongoid fields) can be localized by default.  Properties with a supplied `class_name:` will create a many-to-many relation.
+
+By default, URIs are dynamically generated based on the name of the model class and the configured base URI.  However, you can still set the base URI for a class explicitly just as you would in ActiveTriples, eg:
+
+```ruby
+Person.base_uri
+=> #<RDF::URI:0x3fecf69da274 URI:http://example.org/people>
+
+Person.configure base_uri: 'http://some.other.uri/'
+=> "http://some.other.uri/"
+```
+
+See the [configuration](#configuration) section for more information on configuring default behaviour.
 
 ```ruby
 class Person
@@ -240,20 +254,6 @@ steve.as_jsonld
 
 Note in this case that both objects are included in the RDF graph, thanks to embedded relations. This can be useful to avoid additional queries to the database for objects that are tightly coupled.
 
-#### Configuring Resources
-
-If the LADDER_BASE_URI global constant is set, base URIs are dynamically generated based on the name of the model class.  However, you can still set the base URI for a class explicitly just as you would in ActiveTriples:
-
-```ruby
-LADDER_BASE_URI = 'http://example.org'
-
-Person.resource_class.base_uri
-=> #<RDF::URI:0x3fecf69da274 URI:http://example.org/people>
-
-Person.configure base_uri: 'http://some.other.uri/'
-=> "http://some.other.uri/"
-```
-
 #### Dynamic Resources
 
 In line with ActiveTriples' [Open Model](https://github.com/ActiveTriples/ActiveTriples#open-model) design, you can define properties on any Resource instance similarly to how you would on the class:
@@ -363,7 +363,7 @@ class Image
 end
 ```
 
-Similar to Resources, using `#property` will create a has-many relation for a File by default; however, because Files must be the target of a one-way relation, the `inverse_of: nil` option is required. Note that due to the way GridFS is designed, Files **can not** be embedded.
+As with Resources, using `#property` will create a many-to-many relation for a File by default; however, because Files must be the target of a one-way relation, the `inverse_of: nil` option is required (unless the `one_sided_relations` [configuration](#configuration) option is set). Note that due to the way GridFS is designed, Files **can not** be embedded.
 
 ```ruby
 steve = Person.new(first_name: 'Steve')
@@ -779,6 +779,24 @@ ActiveJob::Base.queue_adapter = :sidekiq
 
 For more information on available queueing adapters and their features, see the [ActiveJob documentation](http://api.rubyonrails.org/classes/ActiveJob/QueueAdapters.html).
 
+### Configuration
+
+Configuration options are set using `Ladder::Config#settings`, eg:
+
+```ruby
+Ladder::Config.settings[:base_uri] = 'http://example.org'
+=> "http://example.org"
+
+Ladder::Config.settings
+=> {:base_uri=>"http://example.org", :localize_fields=>false, :one_sided_relations=>false}
+```
+
+Ladder currently supports the following configuration options (defaults in parentheses):
+
+* `:base_uri ('urn:x-ladder')`: Tells Ladder the base (root) URI to use for generating model URIs.  For a Rack-based linked data application, this will typically be the HTTP(S) URL, eg. "http://some.domain/my_application/"
+* `:localize_fields (false)`: When set to `true`, Ladder will set fields defined using `#property` to be localized by default.
+* `:one_sided_relations (false)`: When set to `true`, Ladder will set relations defined using `#property` to be [one-sided many-to-many](http://mongoid.org/en/mongoid/docs/relations.html#has_and_belongs_to_many) relations. Otherwise, it will define has-and-belongs-to-many (HABTM) relations.
+
 ## Contributing
 
 Anyone and everyone is welcome to contribute.  Go crazy.

data/lib/ladder.rb

@@ -1,7 +1,9 @@
 require 'ladder/version'
+require 'ladder/config'
 
 module Ladder
-  autoload :File,       'ladder/file'
-  autoload :Resource,   'ladder/resource'
-  autoload :Searchable, 'ladder/searchable'
+  autoload :File,         'ladder/file'
+  autoload :Resource,     'ladder/resource'
+  autoload :Searchable,   'ladder/searchable'
+  autoload :Configurable, 'ladder/configurable'
 end

data/lib/ladder/config.rb

@@ -0,0 +1,73 @@
+require 'mongoid'
+require 'mongoid/config/validators/option'
+require 'uri'
+
+module Ladder
+  module Config
+    extend self
+    extend ::Mongoid::Config::Options
+
+    LOCK = Mutex.new
+
+    option :base_uri,            default: URI('urn:x-ladder') # typically a URL (configured)
+    option :localize_fields,     default: false               # self-explanatory
+    option :one_sided_relations, default: false               # otherwise HABTM
+
+    # Get all the models in the application - this is everything that includes
+    # Ladder::Resource or Ladder::File.
+    #
+    # @example Get all the models.
+    #   config.models
+    #
+    # @return [ Array<Class> ] All the models in the application.
+    #
+    # @since 3.1.0
+    def models
+      @models ||= []
+    end
+
+    # Register a model in the application with Ladder.
+    #
+    # @example Register a model.
+    #   config.register_model(Band)
+    #
+    # @param [ Class ] klass The model to register.
+    #
+    # @since 3.1.0
+    def register_model(klass)
+      LOCK.synchronize do
+        models.push(klass) unless models.include?(klass)
+      end
+    end
+
+    # From a hash of settings, load all the configuration.
+    #
+    # @example Load the configuration.
+    #   config.load_configuration(settings)
+    #
+    # @param [ Hash ] settings The configuration settings.
+    #
+    # @since 3.1.0
+    def load_configuration(settings)
+      configuration = settings.with_indifferent_access
+      self.options = configuration[:options]
+    end
+
+    # Set the configuration options. Will validate each one individually.
+    #
+    # @example Set the options.
+    #   config.options = { raise_not_found_error: true }
+    #
+    # @param [ Hash ] options The configuration options.
+    #
+    # @since 3.0.0
+    def options=(options)
+      if options
+        options.each_pair do |option, value|
+          ::Mongoid::Config::Validators::Option.validate(option)
+          send("#{option}=", value)
+        end
+      end
+    end
+  end
+end

data/lib/ladder/configurable.rb

@@ -0,0 +1,26 @@
+module Ladder
+  module Configurable
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      ##
+      # Set a default base URI based on the Ladder::Config settings
+      #
+      # @return [RDF::URI]
+      def base_uri
+        RDF::URI.new(Ladder::Config.settings[:base_uri]) / name.underscore.pluralize
+      end
+
+      protected
+
+      ##
+      # Register with Ladder and set the default base URI
+      #
+      # @return [void]
+      def configure_model
+        configure base_uri: base_uri
+        Ladder::Config.register_model self unless Ladder::Config.models.include? self
+      end
+    end
+  end
+end

data/lib/ladder/file.rb

@@ -7,15 +7,24 @@ module Ladder
 
     include Mongoid::Document
     include ActiveTriples::Identifiable
+    include Ladder::Configurable
 
     included do
-      configure base_uri: RDF::URI.new(LADDER_BASE_URI) / name.underscore.pluralize if defined? LADDER_BASE_URI
+      configure_model
 
       store_in collection: "#{ grid.prefix }.files"
 
       # Define accessor methods for attributes
       define_method(:content_type) { read_attribute(:contentType) }
 
+      # Attributes are:
+      # length      -> RDF::DC.extent
+      # chunkSize   -> (internal) ?
+      # uploadDate  -> RDF::DC.created
+      # md5         -> premis:hasMessageDigest ? with premis:hasMessageDigestAlgorithm = 'MD5'
+      # contentType -> RDF::DC.format
+      # filename    -> RDF::RDFS.label
+
       grid::File.fields.keys.map(&:to_sym).each do |attr|
         define_method(attr) { read_attribute(attr) }
       end

data/lib/ladder/resource.rb

@@ -10,11 +10,10 @@ module Ladder
 
     include Mongoid::Document
     include ActiveTriples::Identifiable
+    include Ladder::Configurable
     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 { configure_model }
 
     delegate :rdf_label, to: :update_resource
 
@@ -27,10 +26,10 @@ module Ladder
     # @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]
+        values = update_from_field(field_name) if fields[field_name]
+        values = update_from_relation(field_name, opts[:related]) if relations[field_name]
 
-        resource.set_value(property.predicate, value) # if value
+        resource.set_value(property.predicate, values)
       end
 
       resource
@@ -40,7 +39,7 @@ module Ladder
     # Push an RDF::Statement into the object
     #
     # @param [RDF::Statement, Hash, Array] statement @see RDF::Statement#from
-    # @return [void]
+    # @return [Object, nil] the value inserted into the object
     def <<(statement)
       # ActiveTriples::Resource expects: RDF::Statement, Hash, or Array
       statement = RDF::Statement.from(statement) unless statement.is_a? RDF::Statement
@@ -49,24 +48,10 @@ module Ladder
       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
+      objects = statement.object.is_a?(RDF::Node) && block_given? ? yield : statement.object
 
-      enum = send(field_name)
-
-      if enum.is_a?(Enumerable)
-        enum.send(:push, value) unless enum.include? value
-      else
-        send("#{field_name}=", value)
-      end
+      update_field(field_name, *objects) if fields[field_name]
+      update_relation(field_name, *objects) if relations[field_name]
     end
 
     ##
@@ -84,8 +69,6 @@ module Ladder
       relation.class_name.constantize
     end
 
-    private
-
     ##
     # Retrieve the attribute name for a field or relation,
     # based on its defined RDF predicate
@@ -99,23 +82,87 @@ module Ladder
       defined_prop.first
     end
 
+    private
+
     ##
-    # Update the delegated ActiveTriples::Resource from a field
+    # Set values on a defined relation
     #
     # @param [String] field_name ActiveModel attribute name for the field
-    # @return [void]
-    def update_from_field(field_name)
+    # @param [Array<Object>] obj objects (usually Ladder::Resources) to be set
+    # @return [Ladder::Resource, nil]
+    def update_relation(field_name, *obj)
+      # Should be an Array of RDF::Term objects
+      return unless obj
+
+      obj.map! { |item| item.is_a?(RDF::URI) ? Ladder::Resource.from_uri(item) : item }
+      relation = send(field_name)
+
+      if Mongoid::Relations::Targets::Enumerable == relation.class
+        obj.map { |item| relation.send(:push, item) unless relation.include? item }
+      else
+        send("#{field_name}=", obj.size > 1 ? obj : obj.first)
+      end
+    end
+
+    ##
+    # Set values on a field; this will cast values
+    # from RDF types to persistable Mongoid types
+    #
+    # @param [String] field_name ActiveModel attribute name for the field
+    # @param [Array<Object>] obj objects (usually RDF::Terms) to be set
+    # @return [Object, nil]
+    def update_field(field_name, *obj)
+      # Should be an Array of RDF::Term objects
+      return unless obj
+
       if fields[field_name].localized?
-        localized_hash = read_attribute(field_name)
+        trans = {}
 
-        unless localized_hash.nil?
-          localized_hash.map do |lang, value|
-            cast_uri = RDF::URI.new(value)
-            cast_uri.valid? ? cast_uri : RDF::Literal.new(value, language: lang)
-          end
+        obj.each do |item|
+          lang = item.is_a?(RDF::Literal) && item.has_language? ? item.language.to_s : I18n.locale.to_s
+          value = item.is_a?(RDF::URI) ? item.to_s : item.object # TODO: tidy this up
+          trans[lang] = trans[lang] ? [*trans[lang]] << value : value
         end
+
+        send("#{field_name}_translations=", trans) unless trans.empty?
       else
-        send(field_name)
+        objects = obj.map { |item| item.is_a?(RDF::URI) ? item.to_s : item.object } # TODO: tidy this up
+        send("#{field_name}=", objects.size > 1 ? objects : objects.first)
+      end
+    end
+
+    ##
+    # Cast values from Mongoid types to RDF types
+    #
+    # @param [Object] value ActiveModel attribute to be cast
+    # @param [Hash] opts options to pass to RDF::Literal
+    # @return [RDF::Term]
+    def cast_value(value, opts = {})
+      case value
+      when Array
+        value.map { |v| cast_value(v, opts) }
+      when String
+        cast_uri = RDF::URI.new(value)
+        cast_uri.valid? ? cast_uri : RDF::Literal.new(value, opts)
+      when Time
+        # Cast DateTimes with 00:00:00 or Date stored as Times in Mongoid to xsd:date
+        # FIXME: this should NOT be applied for fields that are typed as Time
+        value.midnight == value ? RDF::Literal.new(value.to_date) : RDF::Literal.new(value.to_datetime)
+      else
+        RDF::Literal.new(value, opts)
+      end
+    end
+
+    ##
+    # Update the delegated ActiveTriples::Resource from a field
+    #
+    # @param [String] field_name ActiveModel attribute name for the field
+    # @return [Object]
+    def update_from_field(field_name)
+      if fields[field_name].localized?
+        read_attribute(field_name).to_a.map { |lang, value| cast_value(value, language: lang) }.flatten
+      else
+        cast_value send(field_name)
       end
     end
 
@@ -124,7 +171,7 @@ module Ladder
     #
     # @param [String] field_name ActiveModel attribute name for the relation
     # @param [Boolean] related whether to include related objects
-    # @return [void]
+    # @return [Enumerable]
     def update_from_relation(field_name, related = false)
       objects = send(field_name).to_a
 
@@ -133,8 +180,8 @@ module Ladder
         methods.select { |i| i[/autosave_documents/] }.each { |m| send m }
 
         # update inverse relation properties
-        relation_def = relations[field_name]
-        objects.each { |object| object.resource.set_value(relation_def.inverse, rdf_subject) } if relation_def.inverse
+        relation = relations[field_name]
+        objects.each { |object| object.resource.set_value(relation.inverse, rdf_subject) } if relation.inverse
         objects.map(&:update_resource)
       else
         # remove inverse relation properties
@@ -159,9 +206,12 @@ module Ladder
       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
+          # TODO: add/fix tests for this behaviour when true
+          mongoid_opts[:inverse_of] = nil if Ladder::Config.settings[:one_sided_relations]
+
+          has_and_belongs_to_many(field_name, mongoid_opts) unless relations[field_name.to_s]
         else
-          mongoid_opts = { localize: true }.merge(opts.except(:predicate, :multivalue))
+          mongoid_opts = { localize: Ladder::Config.settings[:base_uri] }.merge(opts.except(:predicate, :multivalue))
           field(field_name, mongoid_opts) unless fields[field_name.to_s]
         end
 
@@ -180,7 +230,8 @@ module Ladder
       #
       # 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.
+      # prevent infinite traversal in the case of cyclic graphs (ie.
+      # mark-and-sweep graph traversal).
       #
       # @param [RDF::Graph] graph an RDF::Graph to traverse
       # @param [Hash] objects a keyed Hash of already-created objects in the graph
@@ -200,30 +251,50 @@ module Ladder
         # Add object to stack for recursion
         objects[root_subject] = new_object
 
-        graph.query([root_subject]).each_statement do |statement|
-          next if objects[statement.object]
+        subgraph = graph.query([root_subject])
 
-          # TODO: If the object is a list, process members individually
-          # list = RDF::List.new statement.object, graph
-          # binding.pry unless list.empty?
+        subgraph.each_statement do |statement|
+          # Group statements for this predicate
+          stmts = subgraph.query([root_subject, statement.predicate])
 
-          # 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
+          if stmts.size > 1
+            # We have already set this value in a prior pass
+            next if new_object.read_attribute new_object.field_from_predicate statement.predicate
 
-            object = klass.new_from_graph(graph, objects)
-            next unless object
+            # If there are multiple statements for this predicate, pass an array
+            statement.object = RDF::Node.new
+            new_object.send(:<<, statement) { stmts.objects.to_a } # TODO: implement #set_value instead
 
-            objects[statement.object] = object
-            new_object.send(:<<, statement) { object }
-          else
-            new_object << statement
+          elsif statement.object.is_a? RDF::Node
+            next if objects[statement.object]
+
+            # If the object is a BNode, dereference the relation
+            objects[statement.object] = new_object.send(:<<, statement) do  # TODO: implement #set_value instead
+              klass = new_object.klass_from_predicate(statement.predicate)
+              klass.new_from_graph(graph, objects, [statement.object]) if klass
+            end
+
+          else new_object << statement
           end
         end # end each_statement
 
         new_object
       end
+
+      protected
+
+      ##
+      # Propagate base URI and properties to subclasses
+      #
+      # @return [void]
+      def inherited(subclass)
+        # Copy properties from parent to subclass
+        resource_class.properties.each do |_name, config|
+          subclass.property config.term, predicate: config.predicate, class_name: config.class_name
+        end
+
+        subclass.configure_model
+      end
     end
 
     ##
@@ -236,14 +307,13 @@ module Ladder
     # @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 }
+      klass = Ladder::Config.models.find { |k| uri.to_s.include? k.resource_class.base_uri.to_s }
 
       if klass
         object_id = uri.to_s.match(/[0-9a-fA-F]{24}/).to_s
 
         # 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
+        return klass.where(id: object_id).exists? ? klass.find(object_id) : klass.new
       end
     end
   end