rdf-borsh 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35de9225111f9f281e91c1a287470859366dfe8fce5d211416e8e0a4216cf42a
-  data.tar.gz: 01f1d2ecd33f0f016c021fb4d24de4ca1333beb739c27b3f1de2f8eff15f579e
+  metadata.gz: 12224960d664fe3f0b70581cb3c1a0bce77e7425cd0cc9a83b4e6df9fe8d71f7
+  data.tar.gz: d83f64ba1f5e33243dd091b0a04e6c7c39a401bb057703ae03b1373278196204
 SHA512:
-  metadata.gz: 8b3442aaf6fffe3abd8de243ca3f3af85fd3ae4b288997344d8051f43198d5601475539e63eea3a62c424b3075ce17dbf3a15f7092883a5909bb3f0c2a7187b5
-  data.tar.gz: bf2e5f7860fa8f733112713993ccb743b67960f732a7cfc0c4caada867b653d6d8b355d154a91649892459305c8177fe8c8eb6b4ae48f35684e652b1bb2baa0f
+  metadata.gz: cea629b36b4aaea1e18c292210f9942e6ac2ee26659164daffa0540ddbe82fbb8bd54f57c55a726268ce4a985f611ee870fcb6feb31c3fb8b9f92dd914927ed4
+  data.tar.gz: 960ba17587d985344357d9c8c1b12e63827e070cb66ea1f0479727df8578519269d8bbfc24ad6a6925c261037db958b1cd897c64e403813b82f74a7e6350b9d5

data/CHANGES.md

@@ -5,6 +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,17 +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)
 
-An [RDF.rb] extension for encoding and decoding [RDF] knowledge graphs in
-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
-[RDF]: https://www.w3.org/TR/rdf12-concepts/
-[RDF.rb]: https://github.com/ruby-rdf/rdf
+## ✨ 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
 
@@ -54,6 +62,10 @@ graph.to_a
 RDF::Borsh::Reader.new($stdin).to_a
 ```
 
+## 📚 Reference
+
+https://rubydoc.info/gems/rdf-borsh
+
 ## 👨‍💻 Development
 
 ```bash
@@ -66,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.1
+1.0.2

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
 
@@ -29,10 +41,25 @@ module RDF::Borsh
       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)
@@ -41,29 +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?
@@ -87,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
@@ -118,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.1
+  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
@@ -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: []