# RDFtk: IO

This crate provides traits for reading and writing `Statement`s and `Graph`s as
well as implementations of these for common representations.

The following are some well-known formats (see [Wikipedia](https://en.wikipedia.org/wiki/Resource_Description_Framework#Serialization_formats) for a description of
different serializations), support is indicated in the final column with an **R**
for read support and **W** for write support. One additional module, `dot` allows for
the creation of [GraphViz](https://graphviz.gitlab.io/) dot files for a visualization of a graph's structure.

| Module    | Name                                                                                                | MIME Type                   | R/W     |
|-----------|---------------------------------------------------------------------------------------------------- |-----------------------------|---------|
| `nt`      | [RDF 1.1 N-Triples](https://www.w3.org/TR/n-triples/); A line-based syntax for an RDF graph         | `application/n-triples`     | **R+W** |
| `nq`      | [RDF 1.1 N-Quads](https://www.w3.org/TR/n-quads/); A line-based syntax for RDF datasets             | `application/n-quads`       | **W**   |
| `turtle`  | [RDF 1.1 Turtle](https://www.w3.org/TR/turtle/); Terse RDF Triple Language                          | `text/turtle`               | **W**   |
| `trig`    | [RDF 1.1 TriG](https://www.w3.org/TR/trig/); RDF Dataset Language                                   | `application/trig`          |         |
| `xml`     | [RDF 1.1 XML Syntax](https://www.w3.org/TR/rdf-syntax-grammar/)                                     | `application/rdf+xml`       | **W**   |
| `json`    | [RDF 1.1 JSON Alternate Serialization](https://www.w3.org/TR/rdf-json/)                             | `application/rdf+json`      | **R+W** |
| `n3`      | [Notation3 (N3): A readable RDF syntax](https://www.w3.org/TeamSubmission/n3/)                      | `text/rdf+n3`               | **W**   |
| TBD       | [Binary RDF Representation for Publication and Exchange (HDT)](https://www.w3.org/Submission/HDT/)  | N/A                         |         |
| TBD       | [RDF Binary using Apache Thrift](https://afs.github.io/rdf-thrift/)                                 | `application/x-binary-rdf`  |         |
| TBD       | [JSON-LD 1.1](https://www.w3.org/TR/json-ld/); A JSON-based Serialization for Linked Data           | `application/ld+json`       |         |
| TBD       | [RDFa Core 1.1 - Third Edition](https://www.w3.org/TR/rdfa-core/)                                   | `text/html`                 |         |

Each module will also provide public constants `NAME`, `FILE_EXTENSION`, and
`MIME_TYPE`.

# Example

An example, reading an existing NTriple file.

```rust
use rdftk_io::nt::reader::NTriplesReader;
use rdftk_io::GraphReader;
use rdftk_memgraph::simple::graph_factory;
use std::fs::File;
use std::path::PathBuf;

let file_path = PathBuf::from("tests/w3c/nt/literal.nt");
let mut file = File::open(file_path).unwrap();
let reader = NTriplesReader::default();
let graph = reader.read(&mut file, graph_factory()).unwrap();
```

## Changes

### Version 0.3.3

* Feature: better `Literal` handling in Turtle;
  * write only the lexical form for numeric and boolean literals,
  * write prefixed-names instead of full IRI where possible.

### Version 0.3.2

* Feature: added `GraphWriter` and `DataSetWriter` traits so that clients need not
  import `objio`.

### Version 0.3.1

* Feature: moved to new v0.5 core package.
* Tests: all tests now passing.

### Version 0.3.0

* Feature: moved to new `rdftk_core` package.
* Refactor: moved reader/writer traits to new `objio` crate.
* Build: updated Rust edition from 2018 to 2021.
* Build: cargo audit/outdated/udeps
* Docs: added API docs as much as possible.
* Docs: run markuplint on `README.md`.

### Version 0.2.1

* Added JSON reader.

### Version 0.2.0

* Updated rdftk_core dependency to 0.3.0, this is a significant API change.
* All read operations require a graph factory now.

### Version 0.1.9

* Added unicode escape handling into the IRI parsing.
* All W3C test cases for NTriples now passing.
* Removed local error module, using core error types now.

### Version 0.1.8

* Using new style interfaces, a consistent use of traits and trait reference
  types.
* Have a working NTriple parser.

### Version 0.1.7

* Using rdftk_core 0.2, this has changes in the signature of both Graph and
  DataSet traits.
  * This results in changes to both GraphWriter and DataSetWriter traits.
* Applied a lot more warnings in lib.rs
* Fixed resulting Clippy suggestions.

### Version 0.1.6

* Made all modules have separate reader/writer sub-modules.
* Put all modules behind features.
* Added JSON writer.
* Re-write NQuad writer to write datasets.
* Re-wrote NTripe writer to use NQuad writer.
* Fixed formatting in Turtle writer.
* Added XML writer.

### Version 0.1.5

* Internal change to use `StatementRef`.

### Version 0.1.4

* API changes in core crate:
  * Altered `PrefixMappings::compress` and `PrefixMappings::expand` to take
    references.

### Version 0.1.2

* Made all `IRI` into `IRIRef`.

### Version 0.1.1

* Made all local dependencies only major/minor valued.

### Version 0.1.0

* First release.
* Provides write support only for N-Triples, N-Quads, and GraphViz.

## TODO

1. The core; N-Triples, N-Quads, N3, and Turtle need read and write support.
2. The extended core; RDF/XML, JSON-LD, and RDFa need read and write support.
3. The rest; RDF/JSON, TriG, HDT, and BinaryRDF will be implemended as needed.
