active-triples 0.11.0 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b09ad8aa6210e931834cd37965ea5664d84ef2e3
-  data.tar.gz: 0a33346408aaf322d817c8cb2081a2c7542ef0da
+  metadata.gz: e4826fdb0493f209bf6b520769ce78254fa7821e
+  data.tar.gz: 44c6d5cb09faf8a94c3f6ae94ed42fafe09e6644
 SHA512:
-  metadata.gz: 35628f4606ba23ab183d20d2bd6bc67ee39b1285b5c21e1d4d19bc9b3316ed7af3b55fdf2b44b8a431129a2a778f6e7c8c403c934d308dba9fb34843f7fac599
-  data.tar.gz: b8c3662e7f66c4e720e1b8db88314bd6f7b931e8a7b127f393f44e8ce8969ddcd607171abd03505f18fba25972235e6bc7288dd9943b7c2ef7bd385cc9626c73
+  metadata.gz: 755c2a4fa05ad31bf96334673858c350ff361df74efe7bd592bb91a7e95f0f4e758a295c237d0f7f010b4baacbce0c836b7d174b3eda29fa60f490e4153525cb
+  data.tar.gz: 42293eeab490dd8b63d891a6b405da62776c77b700b9afd0e3bde636980b358cb102150e99a4d10c574198e5d0ad5f0addbfb52bd8701656ae1bfe9f1ef7e676

data/README.md

@@ -215,7 +215,7 @@ Contributing
 
 Please observe the following guidelines:
 
- - Do your work in a feature branch based on ```master``` and rebase before submitting a pull request.
+ - Do your work in a feature branch based on ```develop``` and rebase before submitting a pull request.
  - Write tests for your contributions.
  - Document every method you add using YARD annotations. (_Note: Annotations are sparse in the existing codebase, help us fix that!_)
  - Organize your commits into logical units.

data/active-triples.gemspec

@@ -19,8 +19,9 @@ Gem::Specification.new do |s|
   s.add_dependency 'activemodel',   '>= 3.0.0'
   s.add_dependency 'activesupport', '>= 3.0.0'
 
-  s.add_development_dependency 'rdoc'
+  s.add_development_dependency 'yard'
   s.add_development_dependency 'rspec'
+  s.add_development_dependency 'guard-rspec'
   s.add_development_dependency 'rdf-spec',   '~> 2.0'
   s.add_development_dependency 'rdf-rdfxml', '~> 2.0'
   s.add_development_dependency 'rdf-turtle', '~> 2.0'

data/lib/active_triples/configuration.rb

@@ -3,15 +3,21 @@ module ActiveTriples
   require_relative 'configuration/item'
   require_relative 'configuration/merge_item'
   require_relative 'configuration/item_factory'
+
   ##
   # Class which contains configuration for RDFSources.
   class Configuration
     attr_accessor :inner_hash
+
+    ##
+    # @param item_factory [ItemFactory]
     # @param [Hash] options the configuration options.
-    def initialize(options={})
-      @inner_hash = Hash[options.to_a]
+    def initialize(item_factory: ItemFactory.new, **options)
+      @item_factory = item_factory
+      @inner_hash   = Hash[options.to_a]
     end
 
+    ##
     # Merges this configuration with other configuration options. This uses
     # reflection setters to handle special cases like :type.
     #
@@ -19,13 +25,17 @@ module ActiveTriples
     # @return [ActiveTriples::Configuration] the configuration object which is a
     #   result of merging.
     def merge(options)
-      new_config = Configuration.new(options)
+      options    = options.to_h
+      new_config = self.class.new(**options)
+
       new_config.items.each do |property, item|
         build_configuration_item(property).set item.value
       end
+
       self
     end
 
+    ##
     # Returns a hash with keys as the configuration property and values as
     # reflections which know how to set a new value to it.
     #
@@ -37,6 +47,7 @@ module ActiveTriples
       end
     end
 
+    ##
     # Returns the configured value for an option
     #
     # @return the configured value
@@ -44,30 +55,30 @@ module ActiveTriples
       to_h[value]
     end
 
+    ##
     # Returns the available configured options as a hash.
     #
     # This filters the options the class is initialized with.
     #
     # @return [Hash{Symbol => String, ::RDF::URI}]
     def to_h
-      @inner_hash.slice(*valid_config_options)
+      inner_hash.slice(*valid_config_options)
     end
 
     protected
 
     def build_configuration_item(key)
-      configuration_item_factory.new(self, key)
+      item_factory.new(self, key)
     end
 
     private
-
-    def configuration_item_factory
-      @configuration_item_factory ||= ItemFactory.new
-    end
+    
+    CONFIG_OPTIONS = [:base_uri, :rdf_label, :type, :repository].freeze
+    
+    attr_reader :item_factory
 
     def valid_config_options
-      [:base_uri, :rdf_label, :type, :repository]
+      CONFIG_OPTIONS
     end
   end
-
 end

data/lib/active_triples/extension_strategy.rb

@@ -10,7 +10,7 @@ module ActiveTriples
       #   the property to.
       # @param [ActiveTriples::Property] property The property to copy.
       def apply(resource, property)
-        resource.property property.name, property.to_h
+        resource.property(property.name, property.to_h, &property.config)
       end
     end
   end

data/lib/active_triples/list.rb

@@ -112,7 +112,6 @@ module ActiveTriples
             values.delete key
           end
         end
-        persist!
         super
       end
 
@@ -176,7 +175,6 @@ module ActiveTriples
         resource << value
         value.set_persistence_strategy(ParentStrategy)
         value.persistence_strategy.parent = resource
-        value.persist!
       end
     end
   end

data/lib/active_triples/node_config.rb

@@ -1,20 +1,48 @@
 # frozen_string_literal: true
+
 module ActiveTriples
+  ##
+  # Configuration for properties
   class NodeConfig
+    ##
+    # @!attribute class_name [rw]
+    #   @return [Class, String]
+    # @!attribute predicate [rw]
+    #   @return [RDF::URI]
+    # @!attribute term [rw]
+    #   @return [Symbol]
+    # @!attribute type [rw]
+    #   @return [Symbol]
+    # @!attribute behaviors [rw]
+    #   @return [Enumerator<Symbol>]
+    # @!attribute cast [rw]
+    #   @return [Boolean]
     attr_accessor :predicate, :term, :class_name, :type, :behaviors, :cast
 
-    def initialize(term, predicate, args={})
+    ##
+    # @param  term      [Symbol]
+    # @param  predicate [RDF::URI]
+    # @param  opts      [Hash<Symbol, Object>]
+    # @option opts      [String, Class] :class_name
+    # @option opts      [String, Class] :class_name
+    #
+    # @yield yields self to the block
+    # @yieldparam config [NodeConfig] self
+    def initialize(term, predicate, opts={})
       self.term = term
       self.predicate = predicate
-      self.class_name = args.delete(:class_name) { default_class_name }
-      self.cast = args.delete(:cast) { true }
-      @opts = args
+      self.class_name = opts.delete(:class_name) { nil }
+      self.cast = opts.delete(:cast) { true }
+      @opts = opts
       yield(self) if block_given?
     end
 
+    ##
+    # @param value [#to_sym]
+    # @return [Object] the attribute or option represented by the symbol
     def [](value)
       value = value.to_sym
-      self.respond_to?(value) ? self.send(value) : @opts[value]
+      self.respond_to?(value) ? self.public_send(value) : @opts[value]
     end
 
     def class_name
@@ -30,7 +58,10 @@ module ActiveTriples
       @class_name
     end
 
-    def with_index (&block)
+    ##
+    # @yield yields an index configuration object
+    # @yieldparam index [NodeConfig::IndexObject]
+    def with_index(&block)
       # needed for solrizer integration
       iobj = IndexObject.new
       yield iobj
@@ -40,27 +71,52 @@ module ActiveTriples
 
     private
 
+    ##
+    # @deprecated Use `nil` instead.
     def default_class_name
+        warn 'DEPRECATION: `ActiveTriples::NodeConfig#default_class_name` ' \
+             'will be removed in 1.0. Use `nil`.'
       nil
     end
 
     # this enables a cleaner API for solr integration
     class IndexObject
+      ##
+      # @!attribute data_type [rw]
+      #   @return [Symbol]
+      # @!attribute behaviors [rw]
+      #   @return [Enumerator<Symbol>]
       attr_accessor :data_type, :behaviors
+
       def initialize
         @behaviors = []
         @data_type = :string
       end
+
+      ##
+      # @param [Array<Symbol>] *args Behaviors for this index object
+      #
+      # @return [Array<Symbol>]
       def as(*args)
         @behaviors = args
       end
+
+      ##
+      # @param sym [Symbol]
       def type(sym)
         @data_type = sym
       end
-      def defaults
+
+      ##
+      # @deprecated Omit calls to this method; it has always been a no-op.
+      #
+      # @return [Symbol] :noop
+      def defaults # no-op
+        warn 'DEPRECATION: `ActiveTriples::NodeConfig::IndexObject#defaults` ' \
+             'will be removed in 1.0. If you are doing `index.defaults` in a ' \
+             'property config block, you can simply omit the call.'
         :noop
       end
     end
   end
 end
-

data/lib/active_triples/persistable.rb

@@ -27,13 +27,6 @@ module ActiveTriples
       persistence_strategy.graph
     end
 
-    ##
-    # @see RDF::Enumerable.each
-    def each(*args)
-      graph.each(*args)
-    end
-
-    ##
     # @see RDF::Writable.insert_statement
     def insert_statement(*args)
       graph.send(:insert_statement, *args)
@@ -77,19 +70,16 @@ module ActiveTriples
     end
 
     ##
-    # Sends a persistence message to the persistence_startegy, saving the
-    # RDFSource.
+    # Sends a persistence message to the `persistence_startegy`, saving the
+    # `Persistable`.
     #
     # @return [Boolean]
     def persist!(opts={})
-      return if @persisting
       result = false
       return result if opts[:validate] && !valid?
-      @persisting = true
       run_callbacks :persist do
         result = persistence_strategy.persist!
       end
-      @persisting = false
       result
     end
 

data/lib/active_triples/persistence_strategies/parent_strategy.rb

@@ -27,25 +27,25 @@ module ActiveTriples
     # @see PeristenceStrategy#graph=
     def graph=(graph)
       final_parent.insert(graph || source.to_a)
-      @graph = BufferedTransaction.begin(parent, 
+      @graph = BufferedTransaction.begin(parent,
                                          mutable:   true,
                                          subject:   source.to_term)
     end
 
     ##
-    # @return [ActiveTriples::BufferedTransaction] a transaction on parent with 
-    #   buffered changes, with reads projected against an "Extended Bounded 
+    # @return [ActiveTriples::BufferedTransaction] a transaction on parent with
+    #   buffered changes, with reads projected against an "Extended Bounded
     #   Description" of the strategy's `#source`.
     #
     # @see ActiveTriples::ExtendedBoundedDescription
     def graph
-      @graph ||= BufferedTransaction.begin(parent, 
+      @graph ||= BufferedTransaction.begin(parent,
                                            mutable:   true,
                                            subject:   source.to_term)
     end
 
     ##
-    # Resources using this strategy are persisted only if their parent is also 
+    # Resources using this strategy are persisted only if their parent is also
     # persisted.
     #
     # @see PersistenceStrategy#persisted?
@@ -66,8 +66,8 @@ module ActiveTriples
     end
 
     ##
-    # @abstract Clear out any old assertions in the datastore / repository 
-    # about this node or statement thus preparing to receive the updated 
+    # @abstract Clear out any old assertions in the datastore / repository
+    # about this node or statement thus preparing to receive the updated
     # assertions.
     def erase_old_resource; end # noop
 
@@ -91,6 +91,7 @@ module ActiveTriples
     # @param parent [RDFSource] source with a persistence strategy,
     #   must be mutable.
     def parent=(parent)
+      raise NilParentError if parent.nil?
       raise UnmutableParentError unless parent.is_a? RDF::Mutable
       raise UnmutableParentError unless parent.mutable?
 
@@ -108,7 +109,7 @@ module ActiveTriples
 
       graph.execute
 
-      parent.persist! if 
+      parent.persist! if
         ancestors.find { |a| a.is_a?(ActiveTriples::List::ListResource) }
 
       reload
@@ -152,17 +153,17 @@ module ActiveTriples
       #
       # @raise [NilParentError] if `source` does not persist to a parent
       def each
-        raise NilParentError if 
-          !source.persistence_strategy.respond_to?(:parent) || 
+        raise NilParentError if
+          !source.persistence_strategy.respond_to?(:parent) ||
           source.persistence_strategy.parent.nil?
-        
+
         current = source.persistence_strategy.parent
-        
+
         if block_given?
           loop do
             yield current
-            
-            break unless (current.persistence_strategy.respond_to?(:parent) && 
+
+            break unless (current.persistence_strategy.respond_to?(:parent) &&
                           current.persistence_strategy.parent)
             break if current.persistence_strategy.parent == current
 
@@ -172,7 +173,7 @@ module ActiveTriples
         to_enum
       end
     end
-    
+
     class NilParentError < RuntimeError; end
     class UnmutableParentError < ArgumentError; end
   end

data/lib/active_triples/property.rb

@@ -4,40 +4,65 @@ module ActiveTriples
   # A value object to encapsulate what a Property is. Instantiate with a hash of
   # options.
   #
-  # @todo Should we enforce the interface on the various attributes that are set?
+  # @example configuring a property in a schema
+  #   title_prop = ActiveTriples::Property.new(name:     :title,
+  #                                            predicate: RDF::Vocab::DC.title)
   class Property
-    def initialize(options = {})
-      self.name = options.fetch(:name)
+    ##
+    # @param options [Hash] Options for the property
+    # @option options [RDF::URI] :name
+    # @option options [Boolean] :cast
+    # @option options [String, Class] :class_name
+    # @option options [RDF::URI] :predicate
+    def initialize(options = {}, &block)
+      self.name       = options.fetch(:name)
       self.attributes = options.except(:name)
+      self.config     = block 
     end
 
-    # @return Symbol
-    attr_reader :name
+    ##
+    # @!attribute [r] name
+    #   @return [Symbol]
+    # @!attribute [r] config
+    #   @return [Proc]
+    attr_reader :name, :config
 
-    # @return Boolean
+    ##
+    # @return [Boolean]
     def cast
       attributes.fetch(:cast, false)
     end
 
-    # @return Class
+    ##
+    # @return [Class]
     def class_name
       attributes[:class_name]
     end
 
-    # @return RDF::Vocabulary::Term
+    ##
+    # @return [RDF::Vocabulary::Term]
     def predicate
       attributes[:predicate]
     end
 
     private
 
-    attr_writer :name
+    ##
+    # @!attribute [w] name
+    #   @return [Symbol]
+    # @!attribute [w] config
+    #   @return [Proc]
+    # @!attribute [rw] attributes
+    #   @return [Hash<Symbol, Object>]
+    attr_writer   :name, :config
     attr_accessor :attributes
 
     alias_method :to_h, :attributes
 
-    # Returns the property's configuration values. Will not return #name, which is
-    # meant to only be accessible via the accessor.
+    ##
+    # Returns the property's configuration values. Will not return #name, which 
+    # is meant to only be accessible via the accessor.
+    # 
     # @return [Hash] Configuration values for this property.
     public :to_h
   end