rdf 1.99.1 → 2.0.0.beta1

data/lib/rdf/cli/vocab-loader.rb

@@ -42,6 +42,11 @@ module RDF
       @extra = extra
     end
 
+    # patch to run over loaded vocabulary
+    def patch=(patch)
+      @patch = patch
+    end
+
     # Use StrictVocabulary or Vocabulary
     def strict=(strict)
       @strict = strict
@@ -105,10 +110,10 @@ module RDF
       attributes.keys.sort_by(&:to_s).each do |key|
         next if key == :vocab
         value = Array(attributes[key])
-        component = key.is_a?(Symbol) ? "#{key}: " : "#{key.inspect} => "
+        component = key.is_a?(Symbol) ? "#{key}: " : ":#{key.inspect} => "
         value = value.first if value.length == 1
         component << if value.is_a?(Array)
-          '[' + value.map {|v| serialize_value(v, key)}.join(", ") + "]"
+          '[' + value.map {|v| serialize_value(v, key)}.sort.join(", ") + "]"
         else
           serialize_value(value, key)
         end
@@ -131,14 +136,19 @@ module RDF
     # then call #run
     def run
       @output.print %(# -*- encoding: utf-8 -*-
+        # frozen_string_literal: true
         # This file generated automatically using vocab-fetch from #{source}
         require 'rdf'
         module #{module_name}
+          # @!parse
+          #   # Vocabulary for <#{uri}>
+          #   class #{class_name} < RDF::#{"Strict" if @strict}Vocabulary
+          #   end
           class #{class_name} < RDF::#{"Strict" if @strict}Vocabulary("#{uri}")
         ).gsub(/^        /, '') if @output_class_file
 
       # Extract statements with subjects that have the vocabulary prefix and organize into a hash of properties and values
-      vocab = RDF::Vocabulary.load(uri, location: source, extra: @extra)
+      vocab = RDF::Vocabulary.load(uri, location: source, extra: @extra, patch: @patch)
 
       # Split nodes into Class/Property/Datatype/Other
       term_nodes = {

data/lib/rdf/format.rb

@@ -56,7 +56,7 @@ module RDF
     end
 
     ##
-    # Finds an RDF serialization format class based on the given criteria.
+    # Finds an RDF serialization format class based on the given criteria. If multiple formats are identified, the last one found is returned; this allows descrimination of equivalent formats based on load order.
     #
     # @overload for(format)
     #   Finds an RDF serialization format class based on a symbolic name.
@@ -67,7 +67,7 @@ module RDF
     # @overload for(filename)
     #   Finds an RDF serialization format class based on a file name.
     #
-    #   @param  [String] filename
+    #   @param  [String, RDF::URI] filename
     #   @return [Class]
     #
     # @overload for(options = {})
@@ -83,19 +83,17 @@ module RDF
     #   @option options [Boolean]   :has_writer   (false)
     #     Only return a format having a writer.
     #   @option options [String]          :sample (nil)
-    #     A sample of input used for performing format detection.
-    #     If we find no formats, or we find more than one, and we have a sample, we can
-    #     perform format detection to find a specific format to use, in which case
-    #     we pick the first one we find
+    #     A sample of input used for performing format detection. If we find no formats, or we find more than one, and we have a sample, we can perform format detection to find a specific format to use, in which case we pick the last one we find
     #   @return [Class]
     #   @yieldreturn [String] another way to provide a sample, allows lazy for retrieving the sample.
     #
     # @return [Class]
     def self.for(options = {})
       format = case options
-        when String
+        when String, RDF::URI
           # Find a format based on the file name
-          self.for(file_name: options) { yield if block_given? }
+          fn, options = options, {}
+          self.for(file_name: fn) { yield if block_given? }
 
         when Hash
           case
@@ -112,7 +110,7 @@ module RDF
               content_types[mime_type] unless mime_type == 'text/plain' && (options[:sample] || block_given?)
             # Find a format based on the file name:
             when file_name = options[:file_name]
-              self.for(file_extension: File.extname(file_name.to_s)[1..-1]) { yield if block_given? }
+              self.for(file_extension: File.extname(RDF::URI(file_name).path)[1..-1]) { yield if block_given? }
             # Find a format based on the file extension:
             when file_ext  = options[:file_extension]
               file_extensions[file_ext.to_sym]
@@ -121,21 +119,23 @@ module RDF
         when Symbol
           # Try to find a match based on the full class name
           # We want this to work even if autoloading fails
-          format = options
-          @@subclasses.detect { |klass| klass.to_sym == format } ||
-          case format
-          when :ntriples
-            RDF::NTriples::Format
-          when :nquads
-            RDF::NQuads::Format
+          fmt, options = options, {}
+          classes = @@subclasses.select { |klass| klass.symbols.include?(fmt) }
+          if classes.empty?
+            classes = case fmt
+            when :ntriples then [RDF::NTriples::Format]
+            when :nquads   then [RDF::NQuads::Format]
+            else                []
+            end
           end
+          classes
       end
 
       if format.is_a?(Array)
         format = format.select {|f| f.reader} if options[:has_reader]
         format = format.select {|f| f.writer} if options[:has_writer]
         
-        return format.first if format.uniq.length == 1
+        return format.last if format.uniq.length == 1
       elsif !format.nil?
         return format
       end
@@ -144,15 +144,14 @@ module RDF
       if sample = (options[:sample] if options.is_a?(Hash)) || (yield if block_given?)
         sample = sample.dup.to_s
         sample.force_encoding(Encoding::ASCII_8BIT) if sample.respond_to?(:force_encoding)
-        # Given a sample, perform format detection across the appropriate formats, choosing
-        # the first that matches
+        # Given a sample, perform format detection across the appropriate formats, choosing the last that matches
         format ||= @@subclasses
 
-        # Return first format that has a positive detection
-        format.detect {|f| f.detect(sample)} || format.first
+        # Return last format that has a positive detection
+        format.reverse.detect {|f| f.detect(sample)} || format.last
       elsif format.is_a?(Array)
-        # Otherwise, just return the first matching format
-        format.first
+        # Otherwise, just return the last matching format
+        format.last
       else
         nil
       end
@@ -192,7 +191,7 @@ module RDF
     #
     # @return [Array<Symbol>]
     def self.reader_symbols
-      @@readers.keys.compact.map(&:to_sym).uniq
+      @@readers.keys.map(&:symbols).flatten.uniq
     end
 
     ##
@@ -218,7 +217,7 @@ module RDF
     #
     # @return [Array<Symbol>]
     def self.writer_symbols
-      @@writers.keys.compact.map(&:to_sym).uniq
+      @@writers.keys.map(&:symbols).flatten.uniq
     end
 
     ##
@@ -235,7 +234,9 @@ module RDF
     end
 
     ##
-    # Returns a symbol appropriate to use with RDF::Format.for()
+    # Returns a symbol appropriate to use with `RDF::Format.for()`
+    #
+    # @note Defaults to the last element of the class name before `Format` downcased and made a symbol. Individual formats can override this.
     # @return [Symbol]
     def self.to_sym
       elements = self.to_s.split("::")
@@ -244,6 +245,17 @@ module RDF
       sym.downcase.to_s.to_sym if sym.is_a?(String)
     end
 
+    ##
+    # Returns the set of symbols for a writer appropriate for use with with `RDF::Format.for()`
+    #
+    # @note Individual formats can override this to provide an array of symbols; otherwise, it uses `self.to_sym`
+    # @return [Array<Symbol>]
+    # @see to_sym
+    # @since 2.0
+    def self.symbols
+      [self.to_sym]
+    end
+
     ##
     # Returns a human-readable name for the format.
     # Subclasses should override this to use something
@@ -347,6 +359,12 @@ module RDF
       end
     end
 
+    ##
+    # Hash of CLI commands appropriate for this format
+    # @return [Hash{Symbol => Lambda(Array, Hash)}]
+    def self.cli_commands
+      {}
+    end
 
     ##
     # Use a text sample to detect the format of an input file. Sub-classes implement

data/lib/rdf/mixin/enumerable.rb

@@ -41,6 +41,7 @@ module RDF
   #   enumerable.each_subject   { |term| puts term.inspect }
   #   enumerable.each_predicate { |term| puts term.inspect }
   #   enumerable.each_object    { |term| puts term.inspect }
+  #   enumerable.each_term      { |term| puts term.inspect }
   #
   # @example Obtaining all statements
   #   enumerable.statements  #=> [RDF::Statement(subject1, predicate1, object1), ...]
@@ -62,12 +63,12 @@ module RDF
     include RDF::Countable # NOTE: must come after ::Enumerable
 
     ##
-    # Returns `true` if this repository supports the given `feature`.
+    # Returns `true` if this enumerable supports the given `feature`.
     #
     # Supported features include:
     #   * `:graph_name` supports statements with a graph_name, allowing multiple named graphs
-    #   * `:context` supports statements with a context, allowing multiple contexts (DEPRECATED, use graph_name. `context` will be removed in RDF.rb 2.0)
     #   * `:inference` supports RDFS inferrence of queryable contents.
+    #   * `:literal_equality' preserves [term-equality](https://www.w3.org/TR/rdf11-concepts/#dfn-literal-term-equality) for literals. Literals are equal only if their lexical values and datatypes are equal, character by character. Literals may be "inlined" to value-space for efficiency only if `:literal_equality` is `false`.
     #   * `:validity` allows a concrete Enumerable implementation to indicate that it does or does not support valididty checking. By default implementations are assumed to support validity checking.
     #   * `:skolemize` supports [Skolemization](https://www.w3.org/wiki/BnodeSkolemization) of an `Enumerable`. Implementations supporting this feature must implement a `#skolemize` method, taking a base URI used for minting URIs for BNodes as stable identifiers and a `#deskolemize` method, also taking a base URI used for turning URIs having that prefix back into the same BNodes which were originally skolemized.
     #
@@ -75,7 +76,7 @@ module RDF
     # @return [Boolean]
     # @since  0.3.5
     def supports?(feature)
-      feature == :validity
+      feature == :validity || feature == :literal_equality
     end
 
     ##
@@ -117,11 +118,11 @@ module RDF
     # Returns all RDF statements.
     #
     # @param  [Hash{Symbol => Boolean}] options
-    # @return [Enumerator<RDF::Statement>]
+    # @return [Array<RDF::Statement>]
     # @see    #each_statement
     # @see    #enum_statement
     def statements(options = {})
-      enum_statement
+      Array(enum_statement)
     end
 
     ##
@@ -149,9 +150,8 @@ module RDF
     #   @return [void]
     #
     # @overload each_statement
-    #   @return [Enumerator]
+    #   @return [Enumerator<RDF::Statement>]
     #
-    # @return [void]
     # @see    #enum_statement
     def each_statement(&block)
       if block_given?
@@ -166,7 +166,7 @@ module RDF
     # FIXME: enum_for doesn't seem to be working properly
     # in JRuby 1.7, so specs are marked pending
     #
-    # @return [Enumerator]
+    # @return [Enumerator<RDF::Statement>]
     # @see    #each_statement
     def enum_statement
       # Ensure that statements are queryable, countable and enumerable
@@ -181,11 +181,11 @@ module RDF
     # Returns all RDF triples.
     #
     # @param  [Hash{Symbol => Boolean}] options
-    # @return [Enumerator<Array(RDF::Resource, RDF::URI, RDF::Term)>]
+    # @return [Array<Array(RDF::Resource, RDF::URI, RDF::Term)>]
     # @see    #each_triple
     # @see    #enum_triple
     def triples(options = {})
-      enum_statement.map(&:to_triple).to_enum # TODO: optimize
+      enum_statement.map(&:to_triple) # TODO: optimize
     end
 
     ##
@@ -214,9 +214,8 @@ module RDF
     #   @return [void]
     #
     # @overload each_triple
-    #   @return [Enumerator]
+    #   @return [Enumerator<Array(RDF::Resource, RDF::URI, RDF::Term)>]
     #
-    # @return [void]
     # @see    #enum_triple
     def each_triple
       if block_given?
@@ -230,7 +229,7 @@ module RDF
     ##
     # Returns an enumerator for {RDF::Enumerable#each_triple}.
     #
-    # @return [Enumerator]
+    # @return [Enumerator<Array(RDF::Resource, RDF::URI, RDF::Term)>]
     # @see    #each_triple
     def enum_triple
       Countable::Enumerator.new do |yielder|
@@ -243,11 +242,11 @@ module RDF
     # Returns all RDF quads.
     #
     # @param  [Hash{Symbol => Boolean}] options
-    # @return [Enumerator<Array(RDF::Resource, RDF::URI, RDF::Term, RDF::Resource)>]
+    # @return [Array<Array(RDF::Resource, RDF::URI, RDF::Term, RDF::Resource)>]
     # @see    #each_quad
     # @see    #enum_quad
     def quads(options = {})
-      enum_statement.map(&:to_quad).to_enum # TODO: optimize
+      enum_statement.map(&:to_quad) # TODO: optimize
     end
 
     ##
@@ -292,7 +291,7 @@ module RDF
     ##
     # Returns an enumerator for {RDF::Enumerable#each_quad}.
     #
-    # @return [Enumerator]
+    # @return [Enumerator<Array(RDF::Resource, RDF::URI, RDF::Term, RDF::Resource)>]
     # @see    #each_quad
     def enum_quad
       Countable::Enumerator.new do |yielder|
@@ -304,16 +303,15 @@ module RDF
     ##
     # Returns all unique RDF subject terms.
     #
-    # @param  [Hash{Symbol => Boolean}] options
-    # @option options [Boolean] :unique (true)
-    # @return [Enumerator<RDF::Resource>]
+    # @param  unique (true)
+    # @return [Array<RDF::Resource>]
     # @see    #each_subject
     # @see    #enum_subject
-    def subjects(options = {})
-      if options[:unique] == false
-        enum_statement.map(&:subject).to_enum # TODO: optimize
+    def subjects(unique: true)
+      unless unique
+        enum_statement.map(&:subject) # TODO: optimize
       else
-        enum_subject
+        Array(enum_subject)
       end
     end
 
@@ -370,16 +368,15 @@ module RDF
     ##
     # Returns all unique RDF predicate terms.
     #
-    # @param  [Hash{Symbol => Boolean}] options
-    # @option options [Boolean] :unique (true)
+    # @param  unique (true)
     # @return [Array<RDF::URI>]
     # @see    #each_predicate
     # @see    #enum_predicate
-    def predicates(options = {})
-      if options[:unique] == false
-        enum_statement.map(&:predicate).to_enum # TODO: optimize
+    def predicates(unique: true)
+      unless unique
+        enum_statement.map(&:predicate) # TODO: optimize
       else
-        enum_predicate
+        Array(enum_predicate)
       end
     end
 
@@ -436,16 +433,15 @@ module RDF
     ##
     # Returns all unique RDF object terms.
     #
-    # @param  [Hash{Symbol => Boolean}] options
-    # @option options [Boolean] :unique (true)
-    # @return [Enumerator<RDF::Term>]
+    # @param  unique (true)
+    # @return [Array<RDF::Term>]
     # @see    #each_object
     # @see    #enum_object
-    def objects(options = {})
-      if options[:unique] == false
-        enum_statement.map(&:object).to_enum # TODO: optimize
+    def objects(unique: true)
+      unless unique
+        enum_statement.map(&:object) # TODO: optimize
       else
-        enum_object
+        Array(enum_object)
       end
     end
 
@@ -501,97 +497,96 @@ module RDF
     alias_method :enum_objects, :enum_object
 
     ##
-    # Returns all unique RDF contexts, other than the default context.
+    # Returns all unique RDF terms (subjects, predicates, objects, and graph_names).
     #
-    # @param  [Hash{Symbol => Boolean}] options
-    # @option options [Boolean] :unique (true)
-    # @return [Enumerator<RDF::Resource>]
-    # @see    #each_context
-    # @see    #enum_context
-    # @deprecated use {#graph_names} instead.
-    def contexts(options = {})
-      warn "[DEPRECATION] Enumerable#contexts is being replaced with Enumerable#graph_names in RDF.rb 2.0. Called from #{Gem.location_of_caller.join(':')}"
-      if options[:unique] == false
-        enum_statement.map(&:context).compact.to_enum # TODO: optimize
-      else
-        enum_context
-      end
-    end
-
-    ##
-    # Returns all unique RDF graph names, other than the default graph.
+    # @example finding all Blank Nodes used within an enumerable
+    #   enumberable.terms.select(&:node?)
     #
-    # @param  [Hash{Symbol => Boolean}] options
-    # @option options [Boolean] :unique (true)
+    # @param  unique (true)
     # @return [Array<RDF::Resource>]
-    # @see    #each_graph
-    # @see    #enum_graph
     # @since 2.0
-    def graph_names(options = {})
-      if options[:unique] == false
-        enum_statement.map(&:graph_name).compact # TODO: optimize
+    # @see    #each_resource
+    # @see    #enum_resource
+    def terms(unique: true)
+      unless unique
+        enum_statement.
+          map(&:to_quad).
+          flatten.
+          compact
       else
-        enum_graph.map(&:graph_name).compact
+        Array(enum_term)
       end
     end
 
     ##
-    # Returns `true` if `self` contains the given RDF context.
+    # Returns `true` if `self` contains the given RDF subject term.
     #
-    # @param  [RDF::Resource, false] value
-    #   Use value `false` to query for the default context
+    # @param  [RDF::Resource] value
     # @return [Boolean]
-    # @deprecated Use {#has_graph?} instead.
-    def has_context?(value)
-      warn "[DEPRECATION] Enumerable#has_context? is being replaced with Enumerable#has_graph? in RDF.rb 2.0. Called from #{Gem.location_of_caller.join(':')}"
-      has_graph?(value)
+    # @since 2.0
+    def has_term?(value)
+      enum_term.include?(value)
     end
 
     ##
-    # Iterates the given block for each unique RDF context, other than the default context.
+    # Iterates the given block for each unique RDF term (subject, predicate, object, or graph_name).
     #
     # If no block was given, returns an enumerator.
     #
     # The order in which values are yielded is undefined.
     #
-    # @overload each_context
-    #   @yield  [context]
-    #     each context term
-    #   @yieldparam  [RDF::Resource] context
+    # @overload each_term
+    #   @yield  [term]
+    #     each term
+    #   @yieldparam  [RDF::Term] term
     #   @yieldreturn [void] ignored
     #   @return [void]
     #
-    # @overload each_context
-    #   @return [Enumerator]
-    #
-    # @see    #enum_context
-    # @deprecated Use {#each_graph} instead.
-    def each_context
-      warn "[DEPRECATION] Enumerable#each_context is being replaced with Enumerable#each_graph in RDF.rb 2.0. Called from #{Gem.location_of_caller.join(':')}"
+    # @overload each_term
+    #   @return [Enumerator<RDF::Term>]
+    # @since 2.0
+    # @see    #enum_term
+    def each_term
       if block_given?
         values = {}
         each_statement do |statement|
-          value = statement.context
-          unless value.nil? || values.include?(value)
-            values[value] = true
-            yield value
+          statement.to_quad.each do |value|
+            unless value.nil? || values.include?(value.hash)
+              values[value.hash] = true
+              yield value
+            end
           end
         end
       end
-      enum_context
+      enum_term
     end
 
     ##
-    # Returns an enumerator for {RDF::Enumerable#each_context}.
+    # Returns an enumerator for {RDF::Enumerable#each_term}.
     #
-    # @return [Enumerator]
-    # @see    #each_context
-    # @deprecated Use {#enum_graph} instead.
-    def enum_context
-      warn "[DEPRECATION] Enumerable#enum_context is being replaced with Enumerable#enum_graph in RDF.rb 2.0. Called from #{Gem.location_of_caller.join(':')}"
-      enum_for(:each_context)
+    # @return [Enumerator<RDF::Term>]
+    # @see    #each_term
+    # @since 2.0
+    def enum_term
+      enum_for(:each_term)
+    end
+    alias_method :enum_terms, :enum_term
+
+    ##
+    # Returns all unique RDF graph names, other than the default graph.
+    #
+    # @param  unique (true)
+    # @return [Array<RDF::Resource>]
+    # @see    #each_graph
+    # @see    #enum_graph
+    # @since 2.0
+    def graph_names(unique: true)
+      unless unique
+        enum_statement.map(&:graph_name).compact # TODO: optimize
+      else
+        enum_graph.map(&:graph_name).compact
+      end
     end
-    alias_method :enum_contexts, :enum_context
 
     ##
     # Returns `true` if `self` contains the given RDF graph_name.
@@ -603,6 +598,45 @@ module RDF
       enum_statement.any? {|s| s.graph_name == graph_name}
     end
 
+    ##
+    # Limits statements to be from a specific graph.
+    #
+    # If no block was given, returns an enumerator.
+    #
+    # The order in which statements are yielded is undefined.
+    #
+    # @overload project_graph(graph_name)
+    #   @param [RDF::Resource, nil] graph_name
+    #     The name of the graph from which statements are taken.
+    #     Use `nil` for the default graph.
+    #   @yield  [statement]
+    #     each statement
+    #   @yieldparam  [RDF::Statement] statement
+    #   @yieldreturn [void] ignored
+    #   @return [void]
+    #
+    # @overload project_graph(graph_name)
+    #   @param [RDF::Resource, false] graph_name
+    #     The name of the graph from which statements are taken.
+    #     Use `false` for the default graph.
+    #   @return [Enumerable]
+    #
+    # @see    #each_statement
+    # @since 3.0
+    def project_graph(graph_name)
+      if block_given?
+        self.each do |statement|
+          yield statement if statement.graph_name == graph_name
+        end
+      else
+        # Ensure that statements are queryable, countable and enumerable
+        this = self
+        Queryable::Enumerator.new do |yielder|
+          this.send(:project_graph, graph_name) {|y| yielder << y}
+        end
+      end
+    end
+
     ##
     # Iterates the given block for each RDF graph in `self`.
     #
@@ -624,10 +658,12 @@ module RDF
     # @since  0.1.9
     def each_graph
       if block_given?
-        yield RDF::Graph.new(nil, data: self)
+        yield RDF::Graph.new(graph_name: nil, data: self)
         # FIXME: brute force, repositories should override behavior
-        enum_statement.map(&:graph_name).uniq.compact do |graph_name|
-          yield RDF::Graph.new(graph_name, data: self)
+        if supports?(:graph_name)
+          enum_statement.map(&:graph_name).uniq.compact.each do |graph_name|
+            yield RDF::Graph.new(graph_name: graph_name, data: self)
+          end
         end
       end
       enum_graph