rdf-hamster-repo 3.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f9a06151808cb3e8163fb27a8f378e9b507c99c784761ac3dfc6bcd9efc42306
+  data.tar.gz: b3353ac4627e79194ed360cf022d51a98f1d0c96062527cee36d653e2eb8dabc
+SHA512:
+  metadata.gz: fe7606f4c71c852706b6a97a2e8632ca32921768280dda101e946c44c010d04cc438bc8436865f22dc698f6608f9369cff98b8fa4f38ed6569ee0a85ac9f9d15
+  data.tar.gz: e27972369c6fb37e6d616329266dd09c69740d8bc5bfe508c5b3b7dca04df6723d73c40f9191d78a3839970afa57372d191387badcad7fe1a6819ca823c423db

data/AUTHORS

@@ -0,0 +1 @@
+* Gregg Kellogg <gregg@greggkellogg.net>

data/README.md

@@ -0,0 +1,62 @@
+# RDF::HamsterRepo
+An RDF repository implementation using an in-memory Hamster Hash.
+
+[![Gem Version](https://badge.fury.io/rb/rdf-hamster-repo.png)](https://badge.fury.io/rb/rdf-hamster-repo)
+[![Build Status](https://github.com/ruby-rdf/rdf-hamster-repo/workflows/CI/badge.svg?branch=develop)](https://github.com/ruby-rdf/rdf-hamster-repo/actions?query=workflow%3ACI)
+[![Coverage Status](https://coveralls.io/repos/ruby-rdf/rdf-hamster-repo/badge.svg?branch=develop)](https://coveralls.io/github/ruby-rdf/rdf-hamster-repo?branch=develop)
+[![Gitter chat](https://badges.gitter.im/ruby-rdf/rdf.png)](https://gitter.im/ruby-rdf/rdf)
+
+## Description
+
+An in-memory implementation of RDF::Repository using an efficient, immutable, and thread-safe Hash.
+
+## Examples
+
+    require 'rdf/hamster_repo'
+    require 'rdf/nquads'
+    repo = RDF::HamsterRepo.load("https://ruby-rdf.github.com/rdf/etc/doap.nq")
+
+## Dependencies
+
+* [Ruby](https://ruby-lang.org/) (>= 2.6)
+* [RDF.rb][] (~> 3.2)
+* [Hamster][] (~> 3.0)
+
+## Mailing List
+
+* <https://lists.w3.org/Archives/Public/public-rdf-ruby/>
+
+## Author
+
+* [Gregg Kellogg](https://github.com/gkellogg) - <https://greggkellogg.net/>
+
+## Contributing
+This repository uses [Git Flow](https://github.com/nvie/gitflow) to mange development and release activity. All submissions _must_ be on a feature branch based on the _develop_ branch to ease staging and integration.
+
+* Do your best to adhere to the existing coding conventions and idioms.
+* Don't use hard tabs, and don't leave trailing whitespace on any line.
+  Before committing, run `git diff --check` to make sure of this.
+* Do document every method you add using [YARD][] annotations. Read the
+  [tutorial][YARD-GS] or just look at the existing code for examples.
+* Don't touch the `.gemspec` or `VERSION` files. If you need to change them,
+  do so on your private branch only.
+* Do feel free to add yourself to the `CREDITS` file and the
+  corresponding list in the the `README`. Alphabetical order applies.
+* Don't touch the `AUTHORS` file. If your contributions are significant
+  enough, be assured we will eventually add you in there.
+* Do note that in order for us to merge any non-trivial changes (as a rule
+  of thumb, additions larger than about 15 lines of code), we need an
+  explicit [public domain dedication][PDD] on record from you,
+  which you will be asked to agree to on the first commit to a repo within the organization.
+  Note that the agreement applies to all repos in the [Ruby RDF](https://github.com/ruby-rdf/) organization.
+
+## License
+
+This is free and unencumbered public domain software. For more information,
+see <https://unlicense.org/> or the accompanying {file:UNLICENSE} file.
+
+[RDF.rb]:           https://ruby-rdf.github.com/
+[YARD]:             https://yardoc.org/
+[YARD-GS]:          https://rubydoc.info/docs/yard/file/docs/GettingStarted.md
+[PDD]:              https://unlicense.org/#unlicensing-contributions
+[Hamster]:        https://github.com/hamstergem/hamster

data/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

data/VERSION

@@ -0,0 +1 @@
+3.2.0

data/etc/doap.ttl

@@ -0,0 +1,29 @@
+@base         <https://rubygems.org/gems/rdf-hamster-repo> .
+@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix dc:   <http://purl.org/dc/terms/> .
+@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+@prefix doap: <http://usefulinc.com/ns/doap#> .
+@prefix ex:   <http://example.org/> .
+@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
+
+<> a doap:Project ;
+  doap:name          "RDF::HamsterRepo" ;
+  doap:homepage      <https://github.com/ruby-rdf/rdf-hamster-repo> ;
+  doap:license       <https://unlicense.org/1.0/> ;
+  doap:shortdesc     "An RDF repository implementation using an in-memory Hamster Hash."@en ;
+  doap:description   "An in-memory implementation of RDF::Repository using an efficient, immutable, and thread-safe Hash."@en ;
+  doap:created       "2021-12-28"^^xsd:date;
+  doap:programming-language "Ruby" ;
+  doap:implements    <http://www.w3.org/TR/rdf11-concepts/> ;
+  doap:category      <http://dbpedia.org/resource/Resource_Description_Framework>,
+                     <http://dbpedia.org/resource/Ruby_(programming_language)> ;
+  doap:download-page <> ;
+  doap:mailing-list  <https://lists.w3.org/Archives/Public/public-rdf-ruby/> ;
+  doap:bug-database  <https://github.com/ruby-rdf/rdf-hamster-repo/issues> ;
+  doap:blog          <https://greggkellogg.net/> ;
+  doap:developer     <https://greggkellogg.net/foaf#me> ;
+  doap:maintainer    <https://greggkellogg.net/foaf#me> ;
+  doap:documenter    <https://greggkellogg.net/foaf#me> ;
+  foaf:maker         <https://greggkellogg.net/foaf#me> ;
+  dc:creator         <https://greggkellogg.net/foaf#me> .

data/lib/rdf/hamster_repo.rb

@@ -0,0 +1,437 @@
+require 'rdf'
+require 'hamster'
+
+module RDF
+  ##
+  # Sub-class of RDF::Repository with order-preserving properties.
+  class HamsterRepo < RDF::Repository
+    DEFAULT_GRAPH = false
+
+    ##
+    # @private
+    def self.extend_object(obj)
+      obj.instance_variable_set(:@data, obj.options.delete(:data) || 
+                                        Hamster::Hash.new)
+      obj.instance_variable_set(:@tx_class, 
+                                obj.options.delete(:transaction_class) || 
+                                SerializedTransaction)
+      super
+    end
+
+    ##
+    # Initializes this repository instance.
+    #
+    # @param [URI, #to_s]    uri (nil)
+    # @param [String, #to_s] title (nil)
+    # @param [Hash{Symbol => Object}] options
+    # @option options [Boolean]   :with_graph_name (true)
+    #   Indicates that the repository supports named graphs, otherwise,
+    #   only the default graph is supported.
+    # @option options [Boolean]   :with_validity (true)
+    #   Indicates that the repository supports named validation.
+    # @option options [Boolean]   :transaction_class (SerializedTransaction)
+    #   Specifies the RDF::Transaction implementation to use in this Repository.
+    # @yield  [repository]
+    # @yieldparam [Repository] repository
+    def initialize(uri: nil, title: nil, **options, &block)
+      @data = options.delete(:data) || Hamster::Hash.new
+      super do
+        if block_given?
+          case block.arity
+            when 1 then block.call(self)
+            else instance_eval(&block)
+          end
+        end
+      end
+    end
+
+    ##
+    # Returns `true` if this respository supports the given `feature`.
+    #
+    # This repository supports list_terms.
+    def supports?(feature)
+      case feature.to_sym
+      when :atomic_write     then true
+      when :rdfstar          then true
+      when :snapshots        then true
+      else super
+      end
+    end
+
+    ##
+    # Creates a query from the statements in this repository, turning blank nodes into non-distinguished variables. This can be used to determine if this repository is logically a subset of another repository.
+    #
+    # @return [RDF::Query]
+    def to_query
+      RDF::Query.new do |query|
+        each do |statement|
+          query.pattern RDF::Query::Pattern.from(statement, ndvars: true)
+        end
+      end
+    end
+
+    ##
+    # @private
+    # @see RDF::Countable#count
+    def count
+      count = 0
+      @data.each do |_, ss|
+        ss.each do |_, ps|
+          ps.each { |_, os| count += os.size }
+        end
+      end
+      count
+    end
+    
+    ##
+    # @overload graph?
+    #   Returns `false` to indicate that this is not a graph.
+    #
+    #   @return [Boolean]
+    # @overload graph?(name)
+    #   Returns `true` if `self` contains the given RDF graph_name.
+    #
+    #   @param  [RDF::Resource, false] graph_name
+    #     Use value `false` to query for the default graph_name
+    #   @return [Boolean]
+    def graph?(*args)
+      case args.length
+      when 0 then false
+      when 1 then @data.key?(args.first)
+      else raise ArgumentError("wrong number of arguments (given #{args.length}, expected 0 or 1)")
+      end
+    end
+    alias_method :has_graph?, :graph?
+
+    ##
+    # @private
+    # @see RDF::Enumerable#each_graph
+    def graph_names(options = nil, &block)        
+      @data.keys.reject { |g| g == DEFAULT_GRAPH }.to_a
+    end
+
+    ##
+    # @private
+    # @see RDF::Enumerable#each_graph
+    def each_graph(&block)
+      if block_given?
+        @data.each_key do |gn|
+          yield RDF::Graph.new(graph_name: (gn == DEFAULT_GRAPH ? nil : gn), data: self)
+        end
+      end
+      enum_graph
+    end
+
+    ##
+    # @overload statement?
+    #   Returns `false` indicating this is not an RDF::Statemenet.
+    #   @return [Boolean]
+    #   @see RDF::Value#statement?
+    # @overload statement?(statement)
+    #   @private
+    #   @see    RDF::Enumerable#statement?
+    def statement?(*args)
+      case args.length
+      when 0 then false
+      when 1 then args.first && statement_in?(@data, args.first)
+      else raise ArgumentError("wrong number of arguments (given #{args.length}, expected 0 or 1)")
+      end
+    end
+    alias_method :has_statement?, :statement?
+
+    ##
+    # @private
+    # @see RDF::Enumerable#each_statement
+    def each_statement(&block)
+      if block_given?
+        @data.each do |g, ss|
+          ss.each do |s, ps|
+            ps.each do |p, os|
+              os.each do |o, object_options|
+                yield RDF::Statement.new(s, p, o, object_options.merge(graph_name: g.equal?(DEFAULT_GRAPH) ? nil : g))
+              end
+            end
+          end
+        end
+      end
+      enum_statement
+    end
+    alias_method :each, :each_statement
+
+    ##
+    # @see Mutable#apply_changeset
+    def apply_changeset(changeset)
+      data = @data
+      changeset.deletes.each do |del|
+        if del.constant?
+          data = delete_from(data, del)
+        else
+          # we need this condition to handle wildcard statements
+          query_pattern(del) { |stmt| data = delete_from(data, stmt) }
+        end
+      end
+      changeset.inserts.each { |ins| data = insert_to(data, ins) }
+      @data = data
+    end
+
+    ##
+    # @see RDF::Dataset#isolation_level
+    def isolation_level
+      :serializable
+    end
+
+    ##
+    # A readable & queryable snapshot of the repository for isolated reads. 
+    # 
+    # @return [Dataset] an immutable Dataset containing a current snapshot of
+    #   the Repository contents.
+    #
+    # @see Mutable#snapshot
+    def snapshot
+      self.class.new(data: @data).freeze
+    end
+
+    protected
+
+    ##
+    # Match elements with `eql?`, not `==`
+    #
+    # `graph_name` of `false` matches default graph. Unbound variable matches
+    # non-false graph name.
+    #
+    # Matches terms which are native lists.
+    #
+    # @private
+    # @see RDF::Queryable#query_pattern
+    def query_pattern(pattern, **options, &block)
+      snapshot = @data
+      if block_given?
+        graph_name  = pattern.graph_name
+        subject     = pattern.subject
+        predicate   = pattern.predicate
+        object      = pattern.object
+
+        cs = snapshot.has_key?(graph_name) ? { graph_name => snapshot[graph_name] } : snapshot
+
+        cs.each do |c, ss|
+          next unless graph_name.nil? ||
+                      graph_name == DEFAULT_GRAPH && !c ||
+                      graph_name.eql?(c)
+
+          ss = if subject.nil? || subject.is_a?(RDF::Query::Variable)
+            ss
+          elsif subject.is_a?(RDF::Query::Pattern)
+            # Match subjects which are statements matching this pattern
+            ss.keys.select {|s| s.statement? && subject.eql?(s)}.inject({}) do |memo, st|
+              memo.merge(st => ss[st])
+            end
+          elsif ss.has_key?(subject)
+            { subject => ss[subject] }
+          else
+            []
+          end
+          ss.each do |s, ps|
+            ps = if predicate.nil? || predicate.is_a?(RDF::Query::Variable)
+              ps
+            elsif ps.has_key?(predicate)
+              { predicate => ps[predicate] }
+            else
+              []
+            end
+            ps.each do |p, os|
+              os.each do |o, object_options|
+                next unless object.nil? || object.eql?(o)
+                yield RDF::Statement.new(s, p, o, object_options.merge(graph_name: c.equal?(DEFAULT_GRAPH) ? nil : c))
+              end
+            end
+          end
+        end
+      else
+        enum_for(:query_pattern, pattern, **options)
+      end
+    end
+
+    ##
+    # @private
+    # @see RDF::Mutable#insert
+    def insert_statement(statement)
+      @data = insert_to(@data, statement)
+    end
+
+    ##
+    # @private
+    # @see RDF::Mutable#delete
+    def delete_statement(statement)
+      @data = delete_from(@data, statement)
+    end
+
+    ##
+    # @private
+    # @see RDF::Mutable#clear
+    def clear_statements
+      @data = @data.clear
+    end
+
+    ##
+    # @private
+    # @return [Hash]
+    def data
+      @data
+    end
+
+    ##
+    # @private
+    # @return [Hash]
+    def data=(hash)
+      @data = hash
+    end
+
+    private
+
+    ##
+    # @private
+    # @see #statement?
+    def statement_in?(data, statement)
+      s, p, o, g = statement.to_quad
+      g ||= DEFAULT_GRAPH
+
+      data.key?(g) &&
+        data[g].key?(s) &&
+        data[g][s].key?(p) &&
+        data[g][s][p].key?(o)
+    end
+    alias_method :has_statement_in?, :statement_in?
+
+    ##
+    # @private
+    # @return [Hash] a new, updated hash 
+    def insert_to(data, statement)
+      raise ArgumentError, "Statement #{statement.inspect} is incomplete" if statement.incomplete?
+
+      unless statement_in?(data, statement)
+        s, p, o, c = statement.to_quad
+        c ||= DEFAULT_GRAPH
+        
+        return data.put(c) do |subs|
+          (subs || Hamster::Hash.new).put(s) do |preds|
+            (preds || Hamster::Hash.new).put(p) do |objs|
+              (objs || Hamster::Hash.new).put(o, statement.options)
+            end
+          end
+        end
+      end
+      data
+    end
+    
+    ##
+    # @private
+    # @return [Hash] a new, updated hash 
+    def delete_from(data, statement)
+      if has_statement_in?(data, statement)
+        s, p, o, g = statement.to_quad
+        g = DEFAULT_GRAPH unless supports?(:graph_name)
+        g ||= DEFAULT_GRAPH
+
+        os   = data[g][s][p].delete(o)
+        ps   = os.empty? ? data[g][s].delete(p) : data[g][s].put(p, os)
+        ss   = ps.empty? ? data[g].delete(s)    : data[g].put(s, ps)
+        return ss.empty? ? data.delete(g) : data.put(g, ss)
+      end
+      data
+    end
+
+    ##
+    # A transaction for the Hamster-based `RDF::Repository::Implementation` 
+    # with full serializability.
+    # 
+    # @todo refactor me!
+    # @see RDF::Transaction
+    class SerializedTransaction < Transaction
+      ##
+      # @see Transaction#initialize
+      def initialize(*args, **options, &block)
+        super(*args, **options, &block)
+        @base_snapshot = @snapshot
+      end
+      
+      ##
+      # Inserts the statement to the transaction's working snapshot.
+      #
+      # @see Transaction#insert_statement
+      def insert_statement(statement)
+        @snapshot = @snapshot.class
+          .new(data: @snapshot.send(:insert_to, 
+                                    @snapshot.send(:data), 
+                                    process_statement(statement)))
+      end
+
+      ##
+      # Deletes the statement from the transaction's working snapshot.
+      #
+      # @see Transaction#insert_statement
+      def delete_statement(statement)
+        @snapshot = @snapshot.class
+          .new(data: @snapshot.send(:delete_from, 
+                                    @snapshot.send(:data), 
+                                    process_statement(statement)))
+      end
+
+      ##
+      # @see RDF::Dataset#isolation_level
+      def isolation_level
+        :serializable
+      end
+      
+      ##
+      # @note this is a simple object equality check.
+      # 
+      # @see RDF::Transaction#mutated?
+      def mutated?
+        !@snapshot.send(:data).equal?(repository.send(:data))
+      end
+      
+      ##
+      # Replaces repository data with the transaction's snapshot in a safely 
+      # serializable fashion.
+      # 
+      # @note this transaction uses a pessimistic merge strategy which 
+      #   fails the transaction if any data has changed in the repository
+      #   since transaction start time. However, the specific guarantee is 
+      #   softer: multiple concurrent conflicting transactions will not 
+      #   succeed. We may choose to implement a less pessimistic merge 
+      #   strategy as a non-breaking change.
+      # 
+      # @raise [TransactionError] when the transaction can't be merged.
+      # @see Transaction#execute
+      def execute
+        raise TransactionError, 'Cannot execute a rolled back transaction. ' \
+                                'Open a new one instead.' if instance_variable_defined?(:@rolledback) && @rolledback
+
+        raise TransactionError, 'Error merging transaction. Repository' \
+                                'has changed during transaction time.' unless 
+          repository.send(:data).equal? @base_snapshot.send(:data)
+
+        repository.send(:data=, @snapshot.send(:data))
+      end
+    end
+
+    module VERSION
+      VERSION_FILE = File.expand_path("../../../VERSION", __FILE__)
+      MAJOR, MINOR, TINY, EXTRA = File.read(VERSION_FILE).chop.split(".")
+
+      STRING = [MAJOR, MINOR, TINY, EXTRA].compact.join('.')
+
+      ##
+      # @return [String]
+      def self.to_s()   STRING end
+
+      ##
+      # @return [String]
+      def self.to_str() STRING end
+
+      ##
+      # @return [Array(Integer, Integer, Integer)]
+      def self.to_a() STRING.split(".") end
+    end
+  end
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: rdf-hamster-repo
+version: !ruby/object:Gem::Version
+  version: 3.2.0
+platform: ruby
+authors:
+- Gregg Kellogg
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-12-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rdf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: hamster
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rdf-spec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: An in-memory implementation of RDF::Repository using an efficient, immutable,
+  and thread-safe Hash.
+email: public-rdf-ruby@w3.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AUTHORS
+- README.md
+- UNLICENSE
+- VERSION
+- etc/doap.ttl
+- lib/rdf/hamster_repo.rb
+homepage: https://github.com/ruby-rdf/rdf-hamster-repo
+licenses:
+- Unlicense
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: An RDF repository implementation using an in-memory Hamster Hash.
+test_files: []