rdf-borsh 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d3f80cf1f9a45652da775024fabd5c00d460f3d02c3ee34ed7ec355829a50f4
-  data.tar.gz: c631076d5c4d8a9c57e2add7c937feb492699c3a5187ea735c06200713e9a03b
+  metadata.gz: 12224960d664fe3f0b70581cb3c1a0bce77e7425cd0cc9a83b4e6df9fe8d71f7
+  data.tar.gz: d83f64ba1f5e33243dd091b0a04e6c7c39a401bb057703ae03b1373278196204
 SHA512:
-  metadata.gz: 1c45cf0db32119a5532825e288630b50d08634f72f8ef2e3c9d49719ca03aeaa2c3b52d03af4639163555ac90a17ff2f123eaaa01b1362fd28877b9c0a2dc13a
-  data.tar.gz: ffc8a1a577fb3f8b0f0253de890dbb93366e7af112aab10af327ff27ce38e683462b2678027d6044c5fbb7106ceffc47768f7268bb71ef863e8108a807330b6d
+  metadata.gz: cea629b36b4aaea1e18c292210f9942e6ac2ee26659164daffa0540ddbe82fbb8bd54f57c55a726268ce4a985f611ee870fcb6feb31c3fb8b9f92dd914927ed4
+  data.tar.gz: 960ba17587d985344357d9c8c1b12e63827e070cb66ea1f0479727df8578519269d8bbfc24ad6a6925c261037db958b1cd897c64e403813b82f74a7e6350b9d5

data/CHANGES.md

@@ -5,4 +5,8 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.0.2 - 2025-01-11
+
+## 1.0.1 - 2025-01-07
+
 ## 1.0.0 - 2025-01-07

data/README.md

@@ -3,15 +3,25 @@
 [![License](https://img.shields.io/badge/license-Public%20Domain-blue.svg)](https://unlicense.org)
 [![Compatibility](https://img.shields.io/badge/ruby-3.0%2B-blue)](https://rubygems.org/gems/rdf-borsh)
 [![Package](https://img.shields.io/gem/v/rdf-borsh)](https://rubygems.org/gems/rdf-borsh)
+[![Documentation](https://img.shields.io/badge/rubydoc-latest-blue)](https://rubydoc.info/gems/rdf-borsh)
 
-A Ruby library for encoding and decoding RDF data using the [Borsh]
-binary serialization format.
+**RDF/Borsh** is a [Ruby] library and [RDF.rb] extension for encoding
+and decoding [RDF] knowledge graphs in the [Borsh] binary serialization
+format. (See the [specification].)
 
-[Borsh]: https://borsh.io
+## ✨ Features
+
+- Serializes RDF datasets into compact and efficient binary files.
+- Implements the `application/x-rdf+borsh` MIME type with a `.rdfb` extension.
+- Employes LZ4 compression for both the term dictionary and quad data.
+- Designed for blockchain and distributed ledger applications.
+- Supports reading from and writing to files or I/O streams.
+- Plays nice with others: entirely contained in the `RDF::Borsh` module.
+- 100% free and unencumbered public domain software.
 
 ## 🛠️ Prerequisites
 
-- [Ruby](https://ruby-lang.org) 3.0+
+- [Ruby] 3.0+
 
 ## ⬇️ Installation
 
@@ -27,8 +37,35 @@ gem install rdf-borsh
 
 ```ruby
 require 'rdf/borsh'
+
+include RDF
+```
+
+### Serializing an RDF graph into an RDF/Borsh file
+
+```ruby
+RDF::Borsh::Writer.open("mygraph.rdfb") do |writer|
+  writer << [RDF::URI("https://rubygems.org/gems/rdf-borsh"), RDFS.label, "RDF/Borsh for Ruby"]
+end
 ```
 
+### Parsing an RDF graph from an RDF/Borsh file
+
+```ruby
+graph = RDF::Graph.load("mygraph.rdfb")
+graph.to_a
+```
+
+### Parsing an RDF/Borsh dataset from standard input
+
+```ruby
+RDF::Borsh::Reader.new($stdin).to_a
+```
+
+## 📚 Reference
+
+https://rubydoc.info/gems/rdf-borsh
+
 ## 👨‍💻 Development
 
 ```bash
@@ -41,3 +78,9 @@ git clone https://github.com/ruby-rdf/rdf-borsh.git
 [![Share on Reddit](https://img.shields.io/badge/share%20on-reddit-red?logo=reddit)](https://reddit.com/submit?url=https://github.com/ruby-rdf/rdf-borsh&title=RDF%2FBorsh+for+Ruby)
 [![Share on Hacker News](https://img.shields.io/badge/share%20on-hacker%20news-orange?logo=ycombinator)](https://news.ycombinator.com/submitlink?u=https://github.com/ruby-rdf/rdf-borsh&t=RDF%2FBorsh+for+Ruby)
 [![Share on Facebook](https://img.shields.io/badge/share%20on-facebook-1976D2?logo=facebook)](https://www.facebook.com/sharer/sharer.php?u=https://github.com/ruby-rdf/rdf-borsh)
+
+[Borsh]: https://borsh.io
+[RDF]: https://www.w3.org/TR/rdf12-concepts/
+[RDF.rb]: https://github.com/ruby-rdf/rdf
+[Ruby]: https://ruby-lang.org
+[specification]: https://github.com/ruby-rdf/rdf-borsh/blob/master/doc/spec.md

data/VERSION

@@ -1 +1 @@
-1.0.0
+1.0.2

data/lib/rdf/borsh/format.rb

@@ -4,7 +4,7 @@ require 'rdf/format'
 
 module RDF::Borsh
   class Format < RDF::Format
-    content_type 'application/x-rdf+borsh', extension: :borsh
+    content_type 'application/x-rdf+borsh', extension: :rdfb
     reader { RDF::Borsh::Reader }
     writer { RDF::Borsh::Writer }
 

data/lib/rdf/borsh/reader.rb

@@ -1,5 +1,6 @@
 # This is free and unencumbered software released into the public domain.
 
+require 'borsh'
 require 'extlz4'
 require 'rdf'
 require 'stringio'
@@ -15,15 +16,17 @@ module RDF::Borsh
     def initialize(input = $stdin, **options, &block)
       super(input, **options) do
         input = @input
+
+        @input.extend(Borsh::Readable)
         @version, @flags, @quad_count = self.read_header
 
-        input_size = input.read(4).unpack('V').first
-        @input = StringIO.new(self.decompress(input.read(input_size)), 'rb')
+        input_size = input.read_u32
+        @input = Borsh::Buffer.new(self.decompress(input.read(input_size)))
         @terms = [nil] + self.read_terms
 
-        input_size = input.read(4).unpack('V').first
-        @input = StringIO.new(self.decompress(input.read(input_size)), 'rb')
-        _ = @input.read(4).unpack('V').first
+        input_size = input.read_u32
+        @input = Borsh::Buffer.new(self.decompress(input.read(input_size)))
+        _ = @input.read_u32
 
         if block_given?
           case block.arity
@@ -46,9 +49,9 @@ module RDF::Borsh
     ##
     # Reads the compressed terms dictionary.
     def read_terms
-      term_count = @input.read(4).unpack('V').first
+      term_count = @input.read_u32
       term_count.times.map do
-        term_kind, term_string_size = @input.read(5).unpack('CV')
+        term_kind, term_string_size = @input.read_u8, @input.read_u32
         term_string = @input.read(term_string_size)
 
         case term_kind
@@ -56,10 +59,10 @@ module RDF::Borsh
           when 2 then RDF::Node(term_string)
           when 3 then RDF::Literal(term_string)
           when 4
-            term_datatype_size = @input.read(4).unpack('V')
+            term_datatype_size = @input.read_u32
             RDF::Literal(term_string, datatype: @input.read(term_datatype_size))
           when 5
-            term_language_size = @input.read(4).unpack('V')
+            term_language_size = @input.read_u32
             RDF::Literal(term_string, language: @input.read(term_language_size))
           else
             raise RDF::ReaderError, "unknown RDF/Borsh term type: #{term_kind}"
@@ -73,13 +76,13 @@ module RDF::Borsh
       magic = @input.read(4).unpack('a4').first
       raise RDF::ReaderError, "invalid RDF/Borsh header: #{magic.inspect}" if magic != MAGIC
 
-      version = @input.read(1).unpack('C').first
+      version = @input.read_u8
       raise RDF::ReaderError, "invalid RDF/Borsh version: #{version}" if version != VERSION
 
-      flags = @input.read(1).unpack('C').first
+      flags = @input.read_u8
       raise RDF::ReaderError, "invalid RDF/Borsh flags: #{flags}" if flags != FLAGS
 
-      quad_count = @input.read(4).unpack('V').first
+      quad_count = @input.read_u32
       [version, flags, quad_count]
     end
 

data/lib/rdf/borsh/writer.rb

@@ -1,9 +1,9 @@
 # This is free and unencumbered software released into the public domain.
 
+require 'borsh'
 require 'extlz4'
 require 'rdf'
 require 'sorted_set'
-require 'stringio'
 
 module RDF::Borsh
   class Writer < RDF::Writer
@@ -14,7 +14,19 @@ module RDF::Borsh
     FLAGS = RDF::Borsh::Format::FLAGS
     LZ4HC_CLEVEL_MAX = 12
 
+    ##
+    # Initializes the RDF/Borsh writer.
+    #
+    # @param  [IO, StringIO] output
+    # @param  [Hash{Symbol => Object}] options
+    # @yield  [writer]
+    # @yieldparam  [RDF::Borsh::Writer] writer
+    # @yieldreturn [void]
+    # @return [void]
     def initialize(output = $stdout, **options, &block)
+      output.extend(Borsh::Writable)
+      output.binmode if output.respond_to?(:binmode)
+
       @terms_dict, @terms_map = [], {}
       @quads_set = SortedSet.new
 
@@ -24,14 +36,30 @@ module RDF::Borsh
             when 0 then self.instance_eval(&block)
             else block.call(self)
           end
+          self.finish
         end
       end
     end
 
+    ##
+    # Writes an RDF triple.
+    #
+    # @param  [RDF::Resource] subject
+    # @param  [RDF::URI] predicate
+    # @param  [RDF::Term] object
+    # @return [void]
     def write_triple(subject, predicate, object)
       self.write_quad(subject, predicate, object, nil)
     end
 
+    ##
+    # Writes an RDF quad.
+    #
+    # @param  [RDF::Resource] subject
+    # @param  [RDF::URI] predicate
+    # @param  [RDF::Term] object
+    # @param  [RDF::Resource] context
+    # @return [void]
     def write_quad(subject, predicate, object, context)
       s = self.intern_term(subject)
       p = self.intern_term(predicate)
@@ -40,28 +68,42 @@ module RDF::Borsh
       @quads_set << [g, s, p, o]
     end
 
+    ##
+    # Flushes the output.
+    #
+    # @return [void]
     def flush
       self.finish
       super
     end
 
+    ##
+    # Finishes writing the output.
+    #
+    # @return [void]
     def finish
       self.write_header
       self.write_terms
       self.write_quads
     end
 
+    ##
     # Writes the uncompressed header.
+    #
+    # @return [void]
     def write_header
+      @output.binmode
       @output.write([MAGIC, VERSION, FLAGS].pack('a4CC'))
-      @output.write([@quads_set.size].pack('V'))
+      @output.write_u32(@quads_set.size)
     end
 
+    ##
     # Writes the compressed terms dictionary.
+    #
+    # @return [void]
     def write_terms
-      buffer = StringIO.open do |output|
-        output.binmode
-        output.write([@terms_dict.size].pack('V'))
+      buffer = self.compress do |output|
+        output.write_u32(@terms_dict.size)
         @terms_dict.each do |term|
           output.write(case
             when term.iri?
@@ -85,25 +127,30 @@ module RDF::Borsh
               raise RDF::WriterError, "unsupported RDF/Borsh term type: #{term.inspect}"
           end)
         end
-        self.compress(output.string)
       end
-      @output.write([buffer.size].pack('V'))
+      @output.write_u32(buffer.size)
       @output.write(buffer)
     end
 
+    ##
+    # Writes the compressed quads set.
+    #
+    # @return [void]
     def write_quads
-      buffer = StringIO.open do |output|
-        output.binmode
-        output.write([@quads_set.size].pack('V'))
+      buffer = self.compress do |output|
+        output.write_u32(@quads_set.size)
         @quads_set.each do |quad|
-          output.write(quad.pack('v4'))
+          quad.each { |tid| output.write_u16(tid) }
         end
-        self.compress(output.string)
       end
-      @output.write([buffer.size].pack('V'))
+      @output.write_u32(buffer.size)
       @output.write(buffer)
     end
 
+    ##
+    # Interns the given RDF term.
+    #
+    # @param  [RDF::Term] term
     # @return [Integer]
     def intern_term(term)
       return 0 if term.nil? # for the default graph
@@ -116,8 +163,12 @@ module RDF::Borsh
       term_id
     end
 
-    def compress(data)
-      LZ4::BlockEncoder.new(LZ4HC_CLEVEL_MAX).encode(data)
+    ##
+    # @yield [Borsh::Buffer]
+    # @return [String]
+    def compress(&block)
+      uncompressed = Borsh::Buffer.open(&block)
+      LZ4::BlockEncoder.new(LZ4HC_CLEVEL_MAX).encode(uncompressed)
     end
   end # Writer
 end # RDF::Borsh

data/lib/rdf/borsh.rb

@@ -1,8 +1,10 @@
 # This is free and unencumbered software released into the public domain.
 
+require 'rdf'
+
 module RDF
   ##
-  # RDF/Borsh.
+  # RDF/Borsh extension for RDF.rb.
   module Borsh
     autoload :Format, 'rdf/borsh/format'
     autoload :Reader, 'rdf/borsh/reader'
@@ -10,4 +12,4 @@ module RDF
   end
 end
 
-require 'rdf/borsh/version'
+require_relative 'borsh/version'

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: rdf-borsh
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Arto Bendiken
 bindir: bin
 cert_chain: []
-date: 2025-01-07 00:00:00.000000000 Z
+date: 2025-01-11 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: borsh
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: extlz4
   requirement: !ruby/object:Gem::Requirement
@@ -93,8 +107,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
-description: A Ruby library for encoding and decoding RDF data using the Borsh binary
-  serialization format.
+description: An RDF.rb extension for encoding and decoding RDF knowledge graphs in
+  the Borsh binary serialization format.
 email: public-rdf-ruby@w3.org
 executables: []
 extensions: []
@@ -116,7 +130,7 @@ licenses:
 metadata:
   bug_tracker_uri: https://github.com/ruby-rdf/rdf-borsh/issues
   changelog_uri: https://github.com/ruby-rdf/rdf-borsh/blob/master/CHANGES.md
-  documentation_uri: https://github.com/ruby-rdf/rdf-borsh/blob/master/README.md
+  documentation_uri: https://rubydoc.info/gems/rdf-borsh
   homepage_uri: https://github.com/ruby-rdf/rdf-borsh
   source_code_uri: https://github.com/ruby-rdf/rdf-borsh
 rdoc_options: []