turtle_syntax/
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 locspan::Meta;
20//! use std::fs::File;
21//! use std::io::Read;
22//! use turtle_syntax::{
23//!   parsing::Parse,
24//!   Document,
25//! };
26//!
27//! fn main() -> std::io::Result<()> {
28//!   let mut args = std::env::args();
29//!   args.next();
30//!
31//!   let mut files = SimpleFiles::new();
32//!
33//!   for filename in args {
34//!     let mut file = File::open(&filename)?;
35//!     let mut buffer = String::new();
36//!     file.read_to_string(&mut buffer)?;
37//!     let file_id = files.add(filename.clone(), buffer);
38//!     let buffer = files.get(file_id).unwrap();
39//!
40//!     match Document::parse_str(buffer.source().as_str(), |span| span) {
41//!       Ok(_doc) => {
42//!         // do something
43//!       }
44//!       Err(Meta(e, span)) => {
45//!         let diagnostic = Diagnostic::error()
46//!           .with_message(format!("parse error: {}", e))
47//!           .with_labels(vec![Label::primary(file_id, span)]);
48//!
49//!         let writer = StandardStream::stderr(ColorChoice::Auto);
50//!         let config = codespan_reporting::term::Config::default();
51//!         codespan_reporting::term::emit(&mut writer.lock(), &config, &files, &diagnostic)
52//!           .unwrap();
53//!       }
54//!     }
55//!   }
56//!
57//!   Ok(())
58//! }
59//! ```
60//!
61//! The above code will have the following kind of output when a syntax error is
62//! detected:
63//! ```text
64//! error: parse error: unexpected character ` `
65//!   ┌─ examples/syntax_error.ttl:5:34
66//!   │
67//! 5 │ <http://www.w3.org/TR/rdf-syntax- grammar>
68//!   │                                  ^
69//! ```
70mod ast;
71pub mod build;
72pub mod lexing;
73pub mod parsing;
74
75pub use ast::*;
76pub use build::Build;
77pub use lexing::Lexer;
78pub use parsing::Parse;
turtle_syntax/lib.rs

turtle_syntax/
lib.rs
