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;