oxigraph 0.1.0.rc2-x86_64-linux

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: df0ef7fec4cb646c111b42ec1f02db0a48aed97e5a9c99ae2ec0ab8304796e09
4
+ data.tar.gz: 56205b00daeab484d67d340a4dc8fb48abf45fc1c06e9eda6e9408ab0101e66f
5
+ SHA512:
6
+ metadata.gz: c4f02e856974f11e1b58d66a2152d5c5fcc8fd6c735a2413b3fb6b3d1691068600eff673e44698531ea6259c5e430dc17b02a6dcd677114a0328b4e33b114041
7
+ data.tar.gz: f552b1b6758fc096369be5007bc3028a7c93959722ec69764589e82a2766ed11115de1855bd2d0189ad509eb4990fa6014bf0a59645dac3babc2b4e198abca82
data/CHANGELOG.md ADDED
@@ -0,0 +1,17 @@
1
+ # Changelog
2
+
3
+ Notable changes to `oxigraph` are documented here.
4
+
5
+ ## [Unreleased]
6
+
7
+ ### Added
8
+
9
+ - Added the gem scaffold: a Rust native extension that builds and loads on Ruby 3.4 and 4.0.
10
+ - Added `Oxigraph::Store`, an in-memory store backed by Oxigraph 0.5, with `#size` and `#empty?`.
11
+ - Added the term classes `Oxigraph::NamedNode`, `Oxigraph::BlankNode`, `Oxigraph::Literal`, and `Oxigraph::Triple`.
12
+ - Added `Oxigraph::Store#load`, which reads Turtle, RDF/XML, N-Triples, N-Quads, TriG, N3, and JSON-LD from a string, an `IO`, or a file, and returns an `Oxigraph::LoadSummary`.
13
+ - Added `Oxigraph::ParseError`, which carries the line and column of malformed RDF input.
14
+ - Added `Oxigraph::Store#query`, which runs `SELECT`, `ASK`, `CONSTRUCT`, and `DESCRIBE` queries and streams their results.
15
+ - Added `Oxigraph::Query.parse` and `Oxigraph::Update.parse`, which parse SPARQL without running it. A query reports its form and whether it has a `SERVICE` or a dataset clause.
16
+ - Added `Oxigraph::QuerySyntaxError`, `Oxigraph::QueryEvaluationError`, and `Oxigraph::UnsupportedError`.
17
+ - Added precompiled gems for Linux (glibc and musl) and macOS on x86-64 and ARM64, and for Windows on x64 and ARM64. Installing on those platforms needs no Rust toolchain; other platforms compile the extension from the source gem.
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Grant Hutchins
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,180 @@
1
+ # oxigraph-ruby
2
+
3
+ Ruby bindings for [Oxigraph](https://github.com/oxigraph/oxigraph), a SPARQL database and RDF toolkit. The gem is named `oxigraph` and wraps the Oxigraph Rust library in a native extension.
4
+
5
+ This is an unofficial binding and is not affiliated with the Oxigraph project.
6
+
7
+ ## Install
8
+
9
+ The gem is not published to RubyGems yet. Build it from source by pointing Bundler at a commit of this repository:
10
+
11
+ ```ruby
12
+ gem "oxigraph", git: "https://github.com/nertzy/oxigraph-ruby", ref: "<commit SHA>"
13
+ ```
14
+
15
+ Building needs Ruby 3.4 or newer and a [Rust toolchain](https://rustup.rs) at version 1.87 or newer.
16
+
17
+ ## Stores and queries
18
+
19
+ A store holds an RDF dataset in memory:
20
+
21
+ ```ruby
22
+ require "oxigraph"
23
+
24
+ store = Oxigraph::Store.new
25
+ store.size # => 0
26
+ store.empty? # => true
27
+ ```
28
+
29
+ ## Loading RDF
30
+
31
+ `Store#load` reads RDF from a string, from an `IO`, or from a file:
32
+
33
+ ```ruby
34
+ store.load("<http://example.com/a> <http://example.com/p> <http://example.com/b> .", format: :n_triples)
35
+ File.open("more.ttl") { |io| store.load(io, format: :turtle) }
36
+ store.load(path: "vocabulary.ttl")
37
+ store.load(path: "ontology.owl", format: :rdf_xml, base_iri: "http://example.com/")
38
+ ```
39
+
40
+ - The formats are `:turtle`, `:rdf_xml`, `:n_triples`, `:n_quads`, `:trig`, `:n3`, and `:json_ld`.
41
+ - `format:` is required with a string or an `IO`. With `path:` it defaults to the format the file extension names, and an extension that names none raises `ArgumentError`.
42
+ - Data goes to the default graph unless the format carries graph names.
43
+ - An `IO` is read in chunks, so a large file is never held in memory as one string. Any object with an `IO`-style `read(length)` works.
44
+ - A load is all or nothing. Malformed input raises `Oxigraph::ParseError` and leaves the store unchanged.
45
+ - Blank nodes are renamed on the way in, so a label from the input is not the identifier in the store.
46
+
47
+ `load` returns an `Oxigraph::LoadSummary`:
48
+
49
+ ```ruby
50
+ summary = store.load("@prefix ex: <http://example.com/> . ex:a ex:p ex:b .", format: :turtle)
51
+ summary.prefixes # => {"ex" => "http://example.com/"}
52
+ summary.base_iri # => nil
53
+ ```
54
+
55
+ `prefixes` holds what the input declared, in no particular order (sort it if the order matters), and `base_iri` is the base IRI in effect at its end. Turtle, TriG, and N3 report their prefixes. RDF/XML reports none: its `xmlns` declarations do not appear.
56
+
57
+ `Oxigraph::ParseError` has `line` and `column`, counted from one:
58
+
59
+ ```ruby
60
+ begin
61
+ store.load("<http://example.com/a> oops", format: :turtle)
62
+ rescue Oxigraph::ParseError => error
63
+ error.message # => "Parser error at line 1 between columns 24 and 28: oops is not a valid predicate"
64
+ error.line # => 1
65
+ error.column # => 24
66
+ end
67
+ ```
68
+
69
+ Both are `nil` when the parser reports no position, which is the case for RDF/XML.
70
+
71
+ ## Querying
72
+
73
+ `Store#query` runs a SPARQL query, given as a string or as a parsed `Oxigraph::Query`:
74
+
75
+ ```ruby
76
+ store = Oxigraph::Store.new
77
+ store.load(<<~TURTLE, format: :turtle)
78
+ @prefix ex: <http://example.com/> .
79
+ @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
80
+ ex:a rdfs:subClassOf ex:b ; rdfs:label "chat"@fr .
81
+ ex:b rdfs:subClassOf ex:c .
82
+ TURTLE
83
+
84
+ query = Oxigraph::Query.parse(
85
+ "SELECT ?x WHERE { ex:a rdfs:subClassOf+ ?x } ORDER BY ?x",
86
+ prefixes: {"ex" => "http://example.com/", "rdfs" => "http://www.w3.org/2000/01/rdf-schema#"}
87
+ )
88
+
89
+ solutions = store.query(query)
90
+ solutions.variables # => [:x]
91
+ solutions.each do |solution|
92
+ solution[:x] # => #<Oxigraph::NamedNode <http://example.com/b>>, then <http://example.com/c>
93
+ end
94
+ ```
95
+
96
+ What `query` returns depends on the form of the query:
97
+
98
+ | Form | Result |
99
+ | --- | --- |
100
+ | `SELECT` | `Oxigraph::QuerySolutions`, an `Enumerable` of `Oxigraph::QuerySolution` |
101
+ | `CONSTRUCT`, `DESCRIBE` | `Oxigraph::QueryTriples`, an `Enumerable` of `Oxigraph::Triple` |
102
+ | `ASK` | `true` or `false` |
103
+
104
+ - A solution is read with `solution[:x]`, `solution["x"]`, or `solution[0]`. An unbound variable reads as `nil`, and a variable the query does not select raises `IndexError`. `to_h` gives every binding.
105
+ - Results stream from the store one at a time and can be read once. Reading them again raises `Oxigraph::Error`; run the query again instead.
106
+ - Results come from a snapshot taken when the query ran, so a later `load` does not change them.
107
+ - Row order is only defined by `ORDER BY`.
108
+ - Blank node identifiers differ from one process to the next, so neither they nor an order based on them is stable.
109
+ - `prefixes:` and `base_iri:` declare prefixes and a base IRI without adding lines to the query text, which keeps the positions in error messages true to it.
110
+
111
+ ### What a query cannot do
112
+
113
+ A query reads what the store holds and nothing else:
114
+
115
+ - **It never writes.** An update passed to `query` or `Query.parse` raises `Oxigraph::QuerySyntaxError`.
116
+ - **It never opens a network connection.** A query that contains `SERVICE`, `SERVICE SILENT` included, raises `Oxigraph::UnsupportedError` before it runs. `Query#service?` reports the same thing without running it.
117
+ - **`FROM` and `FROM NAMED` choose among the graphs in the store** and never fetch one. A graph the store does not hold matches nothing, so the query returns no rows rather than failing. `Query#dataset?` tells a caller that a query has such a clause, so it can refuse the query.
118
+
119
+ ```ruby
120
+ Oxigraph::Query.parse("SELECT * FROM <http://example.com/g> WHERE { ?s ?p ?o }").dataset? # => true
121
+ Oxigraph::Query.parse("ASK { ?s ?p ?o }").form # => :ask
122
+ ```
123
+
124
+ `Oxigraph::Update.parse` recognizes a SPARQL update and cannot run it. It tells a valid update apart from text that is not SPARQL at all:
125
+
126
+ ```ruby
127
+ Oxigraph::Update.parse("DROP ALL").to_s # => "DROP ALL ;"
128
+ Oxigraph::Update.parse("nonsense") # raises Oxigraph::QuerySyntaxError
129
+ ```
130
+
131
+ A query or update that does not parse raises `Oxigraph::QuerySyntaxError`, whose message gives the line and column. A query that fails while it runs raises `Oxigraph::QueryEvaluationError`.
132
+
133
+ ## Terms
134
+
135
+ RDF terms are value objects:
136
+
137
+ ```ruby
138
+ node = Oxigraph::NamedNode.new("http://example.com/a")
139
+ node.value # => "http://example.com/a"
140
+ node.to_s # => "<http://example.com/a>"
141
+
142
+ Oxigraph::BlankNode.new("b0").to_s # => "_:b0"
143
+ Oxigraph::BlankNode.new.value # => a generated identifier
144
+
145
+ literal = Oxigraph::Literal.new("chat", language: "fr")
146
+ literal.value # => "chat"
147
+ literal.language # => "fr"
148
+ literal.datatype # => #<Oxigraph::NamedNode <http://www.w3.org/1999/02/22-rdf-syntax-ns#langString>>
149
+
150
+ integer = Oxigraph::NamedNode.new("http://www.w3.org/2001/XMLSchema#integer")
151
+ Oxigraph::Literal.new("1", datatype: integer).to_s # => "\"1\"^^<http://www.w3.org/2001/XMLSchema#integer>"
152
+
153
+ triple = Oxigraph::Triple.new(node, Oxigraph::NamedNode.new("http://example.com/p"), literal)
154
+ triple.subject # => #<Oxigraph::NamedNode <http://example.com/a>>
155
+ triple.to_s # => "<http://example.com/a> <http://example.com/p> \"chat\"@fr"
156
+ ```
157
+
158
+ - Terms are frozen. They compare by value with `==` and `eql?`, so they work as `Hash` keys.
159
+ - `to_s` is the N-Triples form.
160
+ - An invalid IRI, blank node identifier, or language tag raises `ArgumentError`.
161
+ - Literals compare by lexical form and datatype: `"1"` and `"01"` as `xsd:integer` are different terms.
162
+ - A language tag is lowercased.
163
+
164
+ ## Scope and limitations
165
+
166
+ - A store is read through SPARQL queries. There is no way yet to add or remove single triples, match a triple pattern directly, run an update, or write RDF back out.
167
+ - A query reads the default graph unless it uses `GRAPH`, `FROM`, or `FROM NAMED`. A store has named graphs only when it loaded a format that names them.
168
+ - JSON-LD that refers to a remote context fails to load, because the gem never fetches anything.
169
+ - Stores live in memory only. The gem is built without RocksDB, so there is no on-disk store.
170
+ - The gem is built without an HTTP client, so it never opens a network connection.
171
+ - There are no precompiled gems, so every install compiles the Rust extension.
172
+ - Only Ruby 3.4 and 4.0 are tested.
173
+
174
+ ## Contributing
175
+
176
+ See [CONTRIBUTING.md](CONTRIBUTING.md).
177
+
178
+ ## License
179
+
180
+ MIT. See [LICENSE](LICENSE).
Binary file
Binary file
@@ -0,0 +1,29 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Oxigraph
4
+ # The base class of every error this gem raises on its own account.
5
+ class Error < StandardError; end
6
+
7
+ # Raised when RDF input is malformed. +line+ and +column+ count from one and
8
+ # are +nil+ when the parser reports no position.
9
+ class ParseError < Error
10
+ attr_reader :line, :column
11
+
12
+ def initialize(message = nil, line: nil, column: nil)
13
+ super(message)
14
+ @line = line
15
+ @column = column
16
+ end
17
+ end
18
+
19
+ # Raised when a SPARQL query or update does not parse. The message says
20
+ # where.
21
+ class QuerySyntaxError < Error; end
22
+
23
+ # Raised when a query fails while it runs.
24
+ class QueryEvaluationError < Error; end
25
+
26
+ # Raised for a query that uses a feature this gem leaves out on purpose,
27
+ # which is SERVICE.
28
+ class UnsupportedError < Error; end
29
+ end
@@ -0,0 +1,8 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Oxigraph
4
+ # What Store#load learned from its input: the prefixes it declared, as a
5
+ # frozen Hash of prefix name to namespace IRI, and the base IRI in effect at
6
+ # its end, or +nil+.
7
+ LoadSummary = Data.define(:prefixes, :base_iri)
8
+ end
@@ -0,0 +1,30 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Oxigraph
4
+ # What QuerySolutions and QueryTriples share: results that arrive from the
5
+ # store one at a time and can be read once.
6
+ module QueryResults
7
+ include Enumerable
8
+
9
+ # Yields each result in turn, or returns an Enumerator without a block.
10
+ # Reading a second time raises Error, whether or not the first reading
11
+ # reached the end.
12
+ def each
13
+ return enum_for(:each) unless block_given?
14
+
15
+ start_reading
16
+ while (result = next_result)
17
+ yield result
18
+ end
19
+ self
20
+ end
21
+ end
22
+
23
+ class QuerySolutions
24
+ include QueryResults
25
+ end
26
+
27
+ class QueryTriples
28
+ include QueryResults
29
+ end
30
+ end
@@ -0,0 +1,27 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Oxigraph
4
+ class Store
5
+ # Loads RDF and returns a LoadSummary.
6
+ #
7
+ # Give either +input+, a String of RDF content or an object that responds
8
+ # to +read+ as an IO does, or +path:+, the name of a file. +format:+ is one
9
+ # of +:turtle+, +:rdf_xml+, +:n_triples+, +:n_quads+, +:trig+, +:n3+, and
10
+ # +:json_ld+. It is required with +input+; with +path:+ it defaults to the
11
+ # format the file extension names.
12
+ #
13
+ # A load is all or nothing: malformed input raises ParseError and leaves
14
+ # the store unchanged.
15
+ def load(input = nil, format: nil, path: nil, base_iri: nil)
16
+ if path.nil?
17
+ raise ArgumentError, "give RDF content, a reader, or path:" if input.nil?
18
+
19
+ load_input(input, format, nil, base_iri)
20
+ else
21
+ raise ArgumentError, "give input or path:, not both" unless input.nil?
22
+
23
+ File.open(path, "rb") { |file| load_input(file, format, File.extname(path), base_iri) }
24
+ end
25
+ end
26
+ end
27
+ end
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Oxigraph
4
+ VERSION = "0.1.0.rc2"
5
+ end
data/lib/oxigraph.rb ADDED
@@ -0,0 +1,22 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "oxigraph/version"
4
+ require_relative "oxigraph/errors"
5
+ require_relative "oxigraph/load_summary"
6
+
7
+ # The extension raises the error classes and builds a LoadSummary, so it loads
8
+ # after they exist. A precompiled gem ships one extension for each Ruby minor
9
+ # version, in a directory named for it; a gem compiled at install time has
10
+ # one, beside this file's directory. Only a missing file falls back, so an
11
+ # extension that is present and fails to load reports its own error.
12
+ versioned_extension = "oxigraph/#{RUBY_VERSION[/\A\d+\.\d+/]}/oxigraph"
13
+ begin
14
+ require versioned_extension
15
+ rescue LoadError => error
16
+ raise unless error.path == versioned_extension
17
+
18
+ require "oxigraph/oxigraph"
19
+ end
20
+
21
+ require_relative "oxigraph/query_results"
22
+ require_relative "oxigraph/store"
metadata ADDED
@@ -0,0 +1,62 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: oxigraph
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.1.0.rc2
5
+ platform: x86_64-linux
6
+ authors:
7
+ - Grant Hutchins
8
+ autorequire:
9
+ bindir: bin
10
+ cert_chain: []
11
+ date: 2026-11-17 00:00:00.000000000 Z
12
+ dependencies: []
13
+ description: Ruby bindings for Oxigraph, a SPARQL database and RDF toolkit.
14
+ email:
15
+ - gems@nertzy.com
16
+ executables: []
17
+ extensions: []
18
+ extra_rdoc_files: []
19
+ files:
20
+ - CHANGELOG.md
21
+ - LICENSE
22
+ - README.md
23
+ - lib/oxigraph.rb
24
+ - lib/oxigraph/3.4/oxigraph.so
25
+ - lib/oxigraph/4.0/oxigraph.so
26
+ - lib/oxigraph/errors.rb
27
+ - lib/oxigraph/load_summary.rb
28
+ - lib/oxigraph/query_results.rb
29
+ - lib/oxigraph/store.rb
30
+ - lib/oxigraph/version.rb
31
+ homepage: https://github.com/nertzy/oxigraph-ruby
32
+ licenses:
33
+ - MIT
34
+ metadata:
35
+ allowed_push_host: https://rubygems.org
36
+ homepage_uri: https://github.com/nertzy/oxigraph-ruby
37
+ source_code_uri: https://github.com/nertzy/oxigraph-ruby
38
+ changelog_uri: https://github.com/nertzy/oxigraph-ruby/blob/main/CHANGELOG.md
39
+ rubygems_mfa_required: 'true'
40
+ post_install_message:
41
+ rdoc_options: []
42
+ require_paths:
43
+ - lib
44
+ required_ruby_version: !ruby/object:Gem::Requirement
45
+ requirements:
46
+ - - ">="
47
+ - !ruby/object:Gem::Version
48
+ version: '3.4'
49
+ - - "<"
50
+ - !ruby/object:Gem::Version
51
+ version: 4.1.dev
52
+ required_rubygems_version: !ruby/object:Gem::Requirement
53
+ requirements:
54
+ - - ">="
55
+ - !ruby/object:Gem::Version
56
+ version: '0'
57
+ requirements: []
58
+ rubygems_version: 3.5.23
59
+ signing_key:
60
+ specification_version: 4
61
+ summary: Ruby bindings for Oxigraph, a SPARQL database and RDF toolkit.
62
+ test_files: []