rdf-normalize 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15478756de443574bde6120436faf09bec1f7e40dcfc60f39fc97af92e686738
-  data.tar.gz: d5617da52a4d7e3429452f691e4a9ccb7f6ac8bedcef6dd66583b1322e0b57f0
+  metadata.gz: 150cdddab40f368e1d1e68ebc65efe3990032729e8d9a591ef8436d61e81d057
+  data.tar.gz: 4510812f3e52b0159ec2025421d116d5c98d37840f3f87e25affb8392a5aa8b0
 SHA512:
-  metadata.gz: 7c2ccd4449f12d5095702d19a8c1d27539aa5afa23c8b96ffcf6f43ee0d6d10fd763e2dbc98f2ef008ede3edc3fda1801eb6a1cd3ad0e80e3b82995017ae93e4
-  data.tar.gz: f760c7336703292679c82b6abbea86ffe7b8ac1b803508c187d8aee7bcd8cd635d0b039d928b7d145198f7df884027aeb911fa2e97e0e9d171cae92e4d26ed0b
+  metadata.gz: ff3fd846a595da0df711bd83673498d259260a19f42f59a9d5f10e55a70670de7c0fba4b301d63ea725e2484179fd6b91b462ea943df9afe8c3d937660d06327
+  data.tar.gz: c66aa1ec1740e1d0c894d5ed9104b61819d055fc83aa2c6674fa1c34d2c9e62c395a78bb6aeec2b46c68c063fc6e79d55250e8d590a0f97c0624888488c4d60c

data/README.md

@@ -22,7 +22,7 @@ Algorithms implemented:
 Install with `gem install rdf-normalize`
 
 * 100% free and unencumbered [public domain](https://unlicense.org/) software.
-* Compatible with  Ruby >= 2.6.
+* Compatible with  Ruby >= 3.0.
 
 ## Usage
 
@@ -37,7 +37,14 @@ Full documentation available on [GitHub][Normalize doc]
     require 'rdf/normalize'
     require 'rdf/turtle'
     g = RDF::Graph.load("etc/doap.ttl")
-    puts g.dump(:normalize)
+    puts g.dump(:normalize) # Can also use :canonicalize
+
+### Normalizing an abstract Graph/Dataset
+    require 'rdf/normalize'
+    require 'rdf/turtle'
+    g = RDF::Graph.load("etc/doap.ttl")
+    g_canon = g.canonicalize # graph with URIs, literals, and blank nodes canonicalized.
+    puts g_canon.dump(:nquads) # Normalized, but not sorted
 
 ### Principle Classes
 * {RDF::Normalize}
@@ -46,11 +53,13 @@ Full documentation available on [GitHub][Normalize doc]
   * {RDF::Normalize::Writer}
   * {RDF::Normalize::URGNA2012}
   * {RDF::Normalize::RDFC10}
+* {RDF::Canonicalize} – extends {RDF::Normalize}
+  * {RDF::Canonicalize::Format}
 
 ## Dependencies
 
-* [Ruby](https://ruby-lang.org/) (>= 2.6)
-* [RDF.rb](https://rubygems.org/gems/rdf) (~> 3.2)
+* [Ruby](https://ruby-lang.org/) (>= 3.0)
+* [RDF.rb](https://rubygems.org/gems/rdf) (~> 3.3)
 
 ## Installation
 

data/VERSION

@@ -1 +1 @@
-0.6.0
+0.7.0

data/lib/rdf/normalize/base.rb

@@ -1,7 +1,7 @@
 module RDF::Normalize
   ##
   # Abstract class for pluggable normalization algorithms. Delegates to a default or selected algorithm if instantiated
-  module Base
+  class Base
     attr_reader :dataset
 
     # Enumerates normalized statements
@@ -11,5 +11,12 @@ module RDF::Normalize
     def each(&block)
       raise "Not Implemented"
     end
+
+    # Returns a map from input blank node identifiers to canonical blank node identifiers.
+    #
+    # @return [Hash{String => String}]
+    def to_hash
+      raise "Not Implemented"
+    end
   end
 end

data/lib/rdf/normalize/carroll2001.rb

@@ -1,8 +1,6 @@
 module RDF::Normalize
-  class Carroll2001
+  class Carroll2001 < Base
     include RDF::Enumerable
-    include Base
-    include Utils
 
     ##
     # Create an enumerable with grounded nodes

data/lib/rdf/normalize/format.rb

@@ -2,7 +2,18 @@ require 'rdf/nquads'
 
 module RDF::Normalize
   class Format < RDF::Format
-    content_type     'application/normalized+n-quads', alias: 'application/x-normalized+n-quads'
+    content_type     'application/canonical+n-quads', alias: 'application/x-canonical+n-quads'
+    content_encoding 'utf-8'
+
+    # It reads like normal N-Quads
+    reader { RDF::NQuads::Reader}
+    writer { RDF::Normalize::Writer }
+  end
+end
+
+module RDF::Canonicalize
+  class Format < RDF::Format
+    content_type     'application/canonical+n-quads', alias: 'application/x-canonical+n-quads'
     content_encoding 'utf-8'
 
     # It reads like normal N-Quads

data/lib/rdf/normalize/rdfc10.rb

@@ -6,27 +6,49 @@ rescue LoadError
 end
 
 module RDF::Normalize
-  class RDFC10
+  class RDFC10 < Base
     include RDF::Enumerable
     include RDF::Util::Logger
-    include Base
 
     ##
     # Create an enumerable with grounded nodes
     #
     # @param [RDF::Enumerable] enumerable
+    # @option options [Integer] :max_calls (40)
+    #   Maximum number of calls allowed for recursive blank node labeling,
+    #   as a multiple of the total number of blank nodes in the dataset.
+    # @options options [:MD5, :SHA1, :SHA2, :SHA256, :SHA384, :SHA512] :hash_algorithm (:SHA256)
+    #   See [Digest Algorithms](https://github.com/ruby/digest#digest-algorithms)
     # @return [RDF::Enumerable]
+    # raise [RuntimeError] if the maximum number of levels of recursion is exceeded.
     def initialize(enumerable, **options)
       @dataset, @options = enumerable, options
+      @options[:hash_algorithm] ||= :SHA256
+      unless %i{MD5 SHA1 SHA2 SHA256 SHA384 SHA512}.include?(@options[:hash_algorithm])
+        raise UnknownHashAlgorithm, "UnknownHashAlgorithm: #{@options[:hash_algorithm].inspect}. Use one of MD5, SHA1, SHA2, SHA256, SHA384, or SHA512"
+      end
     end
 
+    # Yields each normalized statement
     def each(&block)
-      ns = NormalizationState.new(@options)
+      ns = NormalizationState.new(**@options)
       log_debug("ca:")
       log_debug("  log point", "Entering the canonicalization function (4.5.3).")
       log_depth(depth: 2) {normalize_statements(ns, &block)}
     end
 
+    # Returns a map from input blank node identifiers to canonical blank node identifiers.
+    #
+    # @return [Hash{String => String}]
+    def to_hash
+      ns = NormalizationState.new(**@options)
+      log_debug("ca:")
+      log_debug("  log point", "Entering the canonicalization function (4.5.3).")
+      log_depth(depth: 2) {normalize_statements(ns)}
+      ns.canonical_issuer.to_hash
+    end
+
+    #
     protected
     def normalize_statements(ns, &block)
       # Step 2: Map BNodes to the statements they are used by
@@ -79,6 +101,11 @@ module RDF::Normalize
       log_debug("ca.5:") unless ns.hash_to_bnodes.empty?
       log_debug("  log point", "Calculate hashes for identifiers with shared hashes (4.5.3 (5)).")
       log_debug("  with:") unless ns.hash_to_bnodes.empty?
+
+      # Initialize the number of calls allowed to hash_n_degree_quads
+      # as a multiple of the total number of blank nodes in the dataset.
+      ns.max_calls = ns.bnode_to_statements.keys.length * @options.fetch(:max_calls, 40)
+
       ns.hash_to_bnodes.keys.sort.each do |hash|
         identifier_list = ns.hash_to_bnodes[hash]
 
@@ -105,27 +132,29 @@ module RDF::Normalize
         hash_path_list.sort_by(&:first).each do |result, issuer|
           issuer.issued.each do |node|
             id = ns.canonical_issuer.issue_identifier(node)
-            log_debug("            - blank node") {node.id}
-            log_debug("              canonical identifier", id)
+            log_debug("          - blank node") {node.id}
+            log_debug("            canonical identifier", id)
           end
         end
       end
 
       # Step 6: Yield statements using BNodes from canonical replacements
-      dataset.each_statement do |statement|
-        if statement.has_blank_nodes?
-          quad = statement.to_quad.compact.map do |term|
-            term.node? ? RDF::Node.intern(ns.canonical_issuer.identifier(term)) : term
+      if block_given?
+        dataset.each_statement do |statement|
+          if statement.has_blank_nodes?
+            quad = statement.to_quad.compact.map do |term|
+              term.node? ? RDF::Node.intern(ns.canonical_issuer.identifier(term)) : term
+            end
+            block.call RDF::Statement.from(quad)
+          else
+            block.call statement
           end
-          block.call RDF::Statement.from(quad)
-        else
-          block.call statement
         end
       end
 
       log_debug("ca.6:")
-      log_debug("  log point", "Replace original with canonical labels (4.5.3 (6)).")
-      log_debug("  canonical issuer: #{ns.canonical_issuer.inspect}")
+      log_debug("  log point", "Issued identifiers map (4.4.3 (6)).")
+      log_debug("  issued identifiers map: #{ns.canonical_issuer.inspect}")
       dataset
     end
 
@@ -135,12 +164,17 @@ module RDF::Normalize
       include RDF::Util::Logger
 
       attr_accessor :bnode_to_statements
+      attr_accessor :hash_algorithm
       attr_accessor :hash_to_bnodes
       attr_accessor :canonical_issuer
+      attr_accessor :max_calls
+      attr_accessor :total_calls
 
-      def initialize(options)
+      def initialize(**options)
         @options = options
+        @hash_algorithm = Digest.const_get(options.fetch(:hash_algorithm, :SHA256))
         @bnode_to_statements, @hash_to_bnodes, @canonical_issuer = {}, {}, IdentifierIssuer.new("c14n")
+        @max_calls, @total_calls = nil, 0
       end
 
       def add_statement(node, statement)
@@ -204,34 +238,40 @@ module RDF::Normalize
         hexdigest(input)
       end
 
-      # @param [RDF::Node] identifier
+      # @param [RDF::Node] node
       # @param [IdentifierIssuer] issuer
       # @return [Array<String,IdentifierIssuer>] the Hash and issuer
-      def hash_n_degree_quads(identifier, issuer)
+      # @raise [MaxCallsExceeded] If total number of calls has exceeded `max_calls` times the number of blank nodes in the dataset.
+      def hash_n_degree_quads(node, issuer)
         log_debug("hndq:")
         log_debug("  log point", "Hash N-Degree Quads function (4.9.3).")
-        log_debug("  identifier") {identifier.id}
+        log_debug("  identifier") {node.id}
         log_debug("  issuer") {issuer.inspect}
 
+        if max_calls && total_calls >= max_calls
+          raise MaxCallsExceeded, "Exceeded maximum number of calls (#{total_calls}) allowed to hash_n_degree_quads"
+        end
+        @total_calls += 1
+
         # hash to related blank nodes map
         hn = {}
 
         log_debug("  hndq.2:")
         log_debug("    log point", "Quads for identifier (4.9.3 (2)).")
         log_debug("    quads:")
-        bnode_to_statements[identifier].each do |s|
+        bnode_to_statements[node].each do |s|
           log_debug {"    - #{s.to_nquads.strip}"}
         end
 
         # Step 3
         log_debug("  hndq.3:")
         log_debug("    log point", "Hash N-Degree Quads function (4.9.3 (3)).")
-        log_debug("    with:") unless bnode_to_statements[identifier].empty?
-        bnode_to_statements[identifier].each do |statement|
+        log_debug("    with:") unless bnode_to_statements[node].empty?
+        bnode_to_statements[node].each do |statement|
           log_debug {"      - quad: #{statement.to_nquads.strip}"}
           log_debug("        hndq.3.1:")
           log_debug("          log point", "Hash related bnode component (4.9.3 (3.1))")
-          log_depth(depth: 10) {hash_related_statement(identifier, statement, issuer, hn)}
+          log_depth(depth: 10) {hash_related_statement(node, statement, issuer, hn)}
         end
         log_debug("    Hash to bnodes:")
         hn.each do |k,v|
@@ -286,7 +326,9 @@ module RDF::Normalize
             log_debug("              with:") unless recursion_list.empty?
             recursion_list.each do |related|
               log_debug("                - related") {related.id}
-              result = log_depth(depth: 18) {hash_n_degree_quads(related, issuer_copy)}
+              result = log_depth(depth: 18) do
+                hash_n_degree_quads(related, issuer_copy)
+              end
               path << '_:' + issuer_copy.issue_identifier(related)
               path << "<#{result.first}>"
               issuer_copy = result.last
@@ -333,14 +375,14 @@ module RDF::Normalize
       protected
 
       def hexdigest(val)
-        Digest::SHA256.hexdigest(val)
+        hash_algorithm.hexdigest(val)
       end
 
       # Group adjacent bnodes by hash
-      def hash_related_statement(identifier, statement, issuer, map)
+      def hash_related_statement(node, statement, issuer, map)
         log_debug("with:") if statement.to_h.values.any? {|t| t.is_a?(RDF::Node)}
         statement.to_h(:s, :p, :o, :g).each do |pos, term|
-          next if !term.is_a?(RDF::Node) || term == identifier
+          next if !term.is_a?(RDF::Node) || term == node
 
           log_debug("  - position", pos)
           hash = log_depth(depth: 4) {hash_related_node(term, statement, issuer, pos)}
@@ -374,6 +416,11 @@ module RDF::Normalize
         @issued[node]
       end
 
+      # @return [Hash{Symbol => Symbol}] the issued identifiers map
+      def to_hash
+        @issued.inject({}) {|memo, (node, canon)| memo.merge(node.id => canon)}
+      end
+
       # Duplicate this issuer, ensuring that the issued identifiers remain distinct
       # @return [IdentifierIssuer]
       def dup

data/lib/rdf/normalize/urgna2012.rb

@@ -2,10 +2,16 @@ module RDF::Normalize
   class URGNA2012 < RDFC10
 
     def each(&block)
-      ns = NormalizationState.new(@options)
+      ns = NormalizationState.new(**@options)
       normalize_statements(ns, &block)
     end
 
+    def to_hash
+      ns = NormalizationState.new(**@options)
+      normalize_statements(ns)
+      ns.canonical_issuer.to_h
+    end
+
     class NormalizationState < RDFC10::NormalizationState
       protected
 

data/lib/rdf/normalize.rb

@@ -3,7 +3,7 @@ require 'digest'
 
 module RDF
   ##
-  # **`RDF::Normalize`** is an RDF Graph normalization plugin for RDF.rb.
+  # **`RDF::Normalize`** is an RDF Graph canonicalization plugin for RDF.rb.
   #
   # @example Requiring the `RDF::Normalize` module
   #   require 'rdf/normalize'
@@ -18,7 +18,7 @@ module RDF
   # @example Returning normalized N-Quads
   #
   #   g = RDF::Graph.load("etc/doap.ttl")
-  #   g.dump(:normalize)
+  #   g.dump(:normalize) # or :canonicalize
   #
   # @example Writing a repository as normalized N-Quads
   #
@@ -52,6 +52,10 @@ module RDF
     # @param [Hash{Symbol => Object}] options
     # @option options [Base] :algorithm (:rdfc10)
     #   One of `:carroll2001`, `:urgna2012`, or `:rdfc10`
+    # @option options [Integer] :max_calls
+    #   Maximum number of calls allowed for recursive blank node labeling,
+    #   as a multiple of the total number of blank nodes in the dataset.
+    # @option options [Boolean] :identifier_map
     # @return [RDF::Normalize::Base]
     # @raise [ArgumentError] selected algorithm not defined
     def new(enumerable, **options)
@@ -62,5 +66,30 @@ module RDF
     end
     module_function :new
 
+    class MaxCallsExceeded < RuntimeError; end
+    class UnknownHashAlgorithm < RuntimeError; end
+  end
+
+  module Canonicalize
+    # RDF::Canonicalize extends RDF::Normalize.
+    include Normalize
+  end
+
+  # Change RDF::Enumerable#canonicalize
+  module Enumerable
+    ##
+    # Returns the resulting Enumerable result from RDF::Normalize.
+    # This also canonicalizes URIs and Literals.
+    #
+    # @return [RDF::Enumerable]
+    remove_method :canonicalize if method_defined? :canonicalize
+    def canonicalize
+      # Ensure that statements are queryable, countable and enumerable
+      this = self
+      enum = Enumerator.new do |yielder|
+        this.send(:each_statement) {|y| yielder << y.canonicalize}
+      end
+      RDF::Normalize.new(enum)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rdf-normalize
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Gregg Kellogg
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-10 00:00:00.000000000 Z
+date: 2023-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdf
@@ -16,70 +16,70 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '3.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '3.3'
 - !ruby/object:Gem::Dependency
   name: rdf-spec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '3.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '3.3'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.10'
+        version: '3.12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.10'
+        version: '3.12'
 - !ruby/object:Gem::Dependency
   name: json-ld
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '3.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '3.3'
 - !ruby/object:Gem::Dependency
   name: rdf-trig
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '3.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '3.3'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -129,14 +129,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.13
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: RDF Graph normalizer for Ruby.