turtle_syntax_next/lib.rs
1//! Turtle is a textual syntax for RDF that allows an RDF graph to be completely
2//! written in a compact and natural text form, with abbreviations for common
3//! usage patterns and datatypes. This library provides a Turtle parser for Rust that keeps tracks of code mapping metadata for each syntax node using the [`locspan`](https://crates.io/crates/locspan) library.
4//!
5//! ## Basic usage
6//!
7//! Elements of the Turtle abstract syntax tree (implementing `Parsable`)
8//! are parsed using a `Token` iterator (a.k.a a lexer).
9//! A `Lexer` can be created from a `char` iterator.
10//! We can then use the `Document::parse` function to parse a Turtle document
11//! from the lexer.
12//! In the following example, we use the excellent [`codespan_reporting`](https://crates.io/crates/codespan-reporting) crate
13//! to report errors.
14//!
15//! ```rust
16//! use codespan_reporting::diagnostic::{Diagnostic, Label};
17//! use codespan_reporting::files::SimpleFiles;
18//! use codespan_reporting::term::termcolor::{ColorChoice, StandardStream};
19//! use std::fs::File;
20//! use std::io::Read;
21//! use turtle_syntax::{
22//! parsing::Parse,
23//! Document,
24//! };
25//!
26//! fn main() -> std::io::Result<()> {
27//! let mut args = std::env::args();
28//! args.next();
29//!
30//! let mut files = SimpleFiles::new();
31//!
32//! for filename in args {
33//! let mut file = File::open(&filename)?;
34//! let mut buffer = String::new();
35//! file.read_to_string(&mut buffer)?;
36//! let file_id = files.add(filename.clone(), buffer);
37//! let buffer = files.get(file_id).unwrap();
38//!
39//! match Document::parse_str(buffer.source().as_str(), |span| span) {
40//! Ok(_doc) => {
41//! // do something
42//! }
43//! Err(error_and_span) => {
44//! let e = error_and_span.0;
45//! let span = error_and_span.1;
46//! let diagnostic = Diagnostic::error()
47//! .with_message(format!("parse error: {}", e))
48//! .with_labels(vec![Label::primary(file_id, span)]);
49//!
50//! let writer = StandardStream::stderr(ColorChoice::Auto);
51//! let config = codespan_reporting::term::Config::default();
52//! codespan_reporting::term::emit(&mut writer.lock(), &config, &files, &diagnostic)
53//! .unwrap();
54//! }
55//! }
56//! }
57//!
58//! Ok(())
59//! }
60//! ```
61//!
62//! The above code will have the following kind of output when a syntax error is
63//! detected:
64//! ```text
65//! error: parse error: unexpected character ` `
66//! ┌─ examples/syntax_error.ttl:5:34
67//! │
68//! 5 │ <http://www.w3.org/TR/rdf-syntax- grammar>
69//! │ ^
70//! ```
71mod ast;
72pub mod build;
73pub mod lexing;
74pub mod parsing;
75
76pub use ast::*;
77pub use build::Build;
78pub use lexing::Lexer;
79pub use parsing::Parse;