oxigraph 0.1.0.rc2

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.
data/Cargo.toml ADDED
@@ -0,0 +1,13 @@
1
+ # This Cargo.toml is here to let externals tools (IDEs, etc.) know that this is
2
+ # a Rust project. Your extensions dependencies should be added to the Cargo.toml
3
+ # in the ext/ directory.
4
+
5
+ [workspace]
6
+ members = ["./ext/oxigraph"]
7
+ resolver = "2"
8
+
9
+ [profile.release]
10
+ # Debug information made each Linux and Windows extension about 100 MB.
11
+ # Stripping it keeps the symbol table, so a backtrace still names functions;
12
+ # it loses file names and line numbers.
13
+ strip = "debuginfo"
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).
@@ -0,0 +1,24 @@
1
+ [package]
2
+ name = "oxigraph"
3
+ version = "0.1.0"
4
+ edition = "2021"
5
+ rust-version = "1.87"
6
+ authors = ["Grant Hutchins <gems@nertzy.com>"]
7
+ license = "MIT"
8
+ publish = false
9
+
10
+ [lib]
11
+ crate-type = ["cdylib"]
12
+
13
+ [dependencies]
14
+ magnus = { version = "0.9" }
15
+ # The in-memory store only: RocksDB is the default feature, and no HTTP client
16
+ # feature is enabled, so nothing here can open a network connection.
17
+ oxigraph = { version = "0.5.13", default-features = false }
18
+ rb-sys = { version = "0.9", features = ["stable-api-compiled-fallback"] }
19
+ # The SPARQL syntax tree, read to find SERVICE clauses. Upstream pins the exact
20
+ # version; these are the features it turns on, so the tree has the same shape here.
21
+ spargebra = { version = "0.4.8", features = ["sep-0002", "sep-0006"] }
22
+
23
+ [build-dependencies]
24
+ rb-sys-env = "0.2.2"
@@ -0,0 +1,5 @@
1
+ pub fn main() -> Result<(), Box<dyn std::error::Error>> {
2
+ let _ = rb_sys_env::activate()?;
3
+
4
+ Ok(())
5
+ }
@@ -0,0 +1,6 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "mkmf"
4
+ require "rb_sys/mkmf"
5
+
6
+ create_rust_makefile("oxigraph/oxigraph")
@@ -0,0 +1,45 @@
1
+ use std::fmt::Display;
2
+
3
+ use magnus::{kwargs, prelude::*, Error, ExceptionClass, RModule, Ruby};
4
+ use oxigraph::io::RdfSyntaxError;
5
+
6
+ /// Builds an `Oxigraph::Error`, the base class that `lib/oxigraph/errors.rb`
7
+ /// defines.
8
+ pub fn error(ruby: &Ruby, cause: impl Display) -> Error {
9
+ named_error(ruby, "Error", cause)
10
+ }
11
+
12
+ /// Builds one of the subclasses of `Oxigraph::Error` that carry only a message.
13
+ pub fn named_error(ruby: &Ruby, class: &str, cause: impl Display) -> Error {
14
+ match error_class(ruby, class) {
15
+ Ok(class) => Error::new(class, cause.to_string()),
16
+ Err(lookup_failure) => lookup_failure,
17
+ }
18
+ }
19
+
20
+ /// Builds an `Oxigraph::ParseError` that carries where the input went wrong.
21
+ /// Upstream counts lines and columns from zero, and Ruby callers get them
22
+ /// counted from one, as upstream's own message does.
23
+ pub fn parse_error(ruby: &Ruby, cause: &RdfSyntaxError) -> Error {
24
+ let start = cause.location().map(|location| location.start);
25
+ let position = kwargs!(
26
+ "line" => start.map(|start| start.line + 1),
27
+ "column" => start.map(|start| start.column + 1)
28
+ );
29
+ let exception = error_class(ruby, "ParseError")
30
+ .and_then(|class| class.new_instance((cause.to_string(), position)));
31
+ match exception {
32
+ Ok(exception) => exception.into(),
33
+ Err(failure) => failure,
34
+ }
35
+ }
36
+
37
+ pub fn argument_error(ruby: &Ruby, cause: impl Display) -> Error {
38
+ Error::new(ruby.exception_arg_error(), cause.to_string())
39
+ }
40
+
41
+ fn error_class(ruby: &Ruby, name: &str) -> Result<ExceptionClass, Error> {
42
+ ruby.class_object()
43
+ .const_get::<_, RModule>("Oxigraph")?
44
+ .const_get(name)
45
+ }
@@ -0,0 +1,15 @@
1
+ use magnus::{Error, Ruby};
2
+
3
+ mod error;
4
+ mod load;
5
+ mod model;
6
+ mod query;
7
+ mod store;
8
+
9
+ #[magnus::init]
10
+ fn init(ruby: &Ruby) -> Result<(), Error> {
11
+ let module = ruby.define_module("Oxigraph")?;
12
+ model::init(ruby, module)?;
13
+ query::init(ruby, module)?;
14
+ store::init(ruby, module)
15
+ }
@@ -0,0 +1,181 @@
1
+ use std::io::{self, BufReader, Read};
2
+
3
+ use magnus::{prelude::*, Error, RModule, RString, Ruby, Symbol, Value};
4
+ use oxigraph::io::{JsonLdProfileSet, RdfFormat, RdfParseError, RdfParser};
5
+ use oxigraph::store::Store;
6
+
7
+ use crate::error::{argument_error, error, parse_error};
8
+
9
+ /// The most that is asked of a Ruby reader in one call.
10
+ const CHUNK_SIZE: usize = 64 * 1024;
11
+
12
+ /// Loads RDF into `store` from a Ruby `String` of content or from an object
13
+ /// that responds to `read`, and returns an `Oxigraph::LoadSummary`.
14
+ pub fn load(
15
+ ruby: &Ruby,
16
+ store: &Store,
17
+ input: Value,
18
+ format: Option<Symbol>,
19
+ extension: Option<String>,
20
+ base_iri: Option<String>,
21
+ ) -> Result<Value, Error> {
22
+ let mut parser = RdfParser::from_format(format_from(ruby, format, extension)?);
23
+ if let Some(base_iri) = base_iri {
24
+ parser = parser
25
+ .with_base_iri(base_iri)
26
+ .map_err(|cause| argument_error(ruby, cause))?;
27
+ }
28
+
29
+ let loaded = if let Some(content) = RString::from_value(input) {
30
+ // Copied so that the parser never borrows memory that Ruby owns.
31
+ let content = unsafe { content.as_slice() }.to_vec();
32
+ load_quads(ruby, store, parser, content.as_slice())?
33
+ } else if input.respond_to("read", false)? {
34
+ let mut raised = None;
35
+ let outcome = {
36
+ let reader = RubyReader {
37
+ reader: input,
38
+ raised: &mut raised,
39
+ };
40
+ let reader = BufReader::with_capacity(CHUNK_SIZE, reader);
41
+ load_quads(ruby, store, parser, reader)
42
+ };
43
+ // What the reader raised is the cause, so it wins over the parser's
44
+ // report of a failed read.
45
+ match raised {
46
+ Some(raised) => return Err(raised),
47
+ None => outcome?,
48
+ }
49
+ } else {
50
+ return Err(Error::new(
51
+ ruby.exception_type_error(),
52
+ format!(
53
+ "wrong argument type {} (expected a String or an object that responds to read)",
54
+ input.class()
55
+ ),
56
+ ));
57
+ };
58
+
59
+ let prefixes = ruby.hash_new();
60
+ for (name, iri) in loaded.prefixes {
61
+ prefixes.aset(name, iri)?;
62
+ }
63
+ prefixes.freeze();
64
+ ruby.class_object()
65
+ .const_get::<_, RModule>("Oxigraph")?
66
+ .const_get::<_, Value>("LoadSummary")?
67
+ .funcall("new", (prefixes, loaded.base_iri))
68
+ }
69
+
70
+ /// What the parser knew when it reached the end of the input.
71
+ struct Loaded {
72
+ prefixes: Vec<(String, String)>,
73
+ base_iri: Option<String>,
74
+ }
75
+
76
+ /// Parses `reader` into one transaction, so a failure part-way through leaves
77
+ /// the store as it was.
78
+ fn load_quads(
79
+ ruby: &Ruby,
80
+ store: &Store,
81
+ parser: RdfParser,
82
+ reader: impl Read,
83
+ ) -> Result<Loaded, Error> {
84
+ let mut transaction = store
85
+ .start_transaction()
86
+ .map_err(|cause| error(ruby, cause))?;
87
+ let mut quads = parser.rename_blank_nodes().for_reader(reader);
88
+ for quad in &mut quads {
89
+ match quad {
90
+ Ok(quad) => transaction.insert(quad.as_ref()),
91
+ Err(RdfParseError::Syntax(cause)) => return Err(parse_error(ruby, &cause)),
92
+ Err(RdfParseError::Io(cause)) => return Err(error(ruby, cause)),
93
+ }
94
+ }
95
+ let loaded = Loaded {
96
+ prefixes: quads
97
+ .prefixes()
98
+ .map(|(name, iri)| (name.to_owned(), iri.to_owned()))
99
+ .collect(),
100
+ base_iri: quads.base_iri().map(str::to_owned),
101
+ };
102
+ transaction.commit().map_err(|cause| error(ruby, cause))?;
103
+ Ok(loaded)
104
+ }
105
+
106
+ fn format_from(
107
+ ruby: &Ruby,
108
+ format: Option<Symbol>,
109
+ extension: Option<String>,
110
+ ) -> Result<RdfFormat, Error> {
111
+ let Some(format) = format else {
112
+ return match extension {
113
+ Some(extension) => RdfFormat::from_extension(extension.trim_start_matches('.'))
114
+ .ok_or_else(|| {
115
+ let file = if extension.is_empty() {
116
+ "a file with no extension".to_owned()
117
+ } else {
118
+ format!("a {extension} file")
119
+ };
120
+ argument_error(
121
+ ruby,
122
+ format!("cannot tell the RDF format of {file}; pass format:"),
123
+ )
124
+ }),
125
+ None => Err(argument_error(
126
+ ruby,
127
+ "format: is required when loading from a string or a reader",
128
+ )),
129
+ };
130
+ };
131
+ match &*format.name()? {
132
+ "turtle" => Ok(RdfFormat::Turtle),
133
+ "rdf_xml" => Ok(RdfFormat::RdfXml),
134
+ "n_triples" => Ok(RdfFormat::NTriples),
135
+ "n_quads" => Ok(RdfFormat::NQuads),
136
+ "trig" => Ok(RdfFormat::TriG),
137
+ "n3" => Ok(RdfFormat::N3),
138
+ "json_ld" => Ok(RdfFormat::JsonLd {
139
+ profile: JsonLdProfileSet::empty(),
140
+ }),
141
+ unknown => Err(argument_error(
142
+ ruby,
143
+ format!(
144
+ "unknown format :{unknown}; expected :turtle, :rdf_xml, :n_triples, :n_quads, :trig, :n3, or :json_ld"
145
+ ),
146
+ )),
147
+ }
148
+ }
149
+
150
+ /// Reads from a Ruby object by calling its `read(length)`, as `IO` defines it:
151
+ /// a `String` of at most `length` bytes, or `nil` at the end.
152
+ struct RubyReader<'a> {
153
+ reader: Value,
154
+ raised: &'a mut Option<Error>,
155
+ }
156
+
157
+ impl Read for RubyReader<'_> {
158
+ fn read(&mut self, buffer: &mut [u8]) -> io::Result<usize> {
159
+ let chunk = self
160
+ .reader
161
+ .funcall::<_, _, Option<RString>>("read", (buffer.len(),));
162
+ match chunk {
163
+ Ok(None) => Ok(0),
164
+ Ok(Some(chunk)) => {
165
+ // Copied out before any other Ruby code can run.
166
+ let bytes = unsafe { chunk.as_slice() };
167
+ let Some(target) = buffer.get_mut(..bytes.len()) else {
168
+ return Err(io::Error::other(
169
+ "the reader returned more bytes than were asked for",
170
+ ));
171
+ };
172
+ target.copy_from_slice(bytes);
173
+ Ok(bytes.len())
174
+ }
175
+ Err(raised) => {
176
+ *self.raised = Some(raised);
177
+ Err(io::Error::other("the reader raised an exception"))
178
+ }
179
+ }
180
+ }
181
+ }