1 //! Welcome to the syntect docs.
2 //!
3 //! Much more info about syntect is available on the [Github Page](https://github.com/trishume/syntect).
4 //!
5 //! May I suggest that you start by reading the `Readme.md` file in the main repo.
6 //! Once you're done with that you can look at the docs for [`parsing::SyntaxSet`]
7 //! and for the [`easy`] module.
8 //!
9 //! Almost everything in syntect is divided up into either the [`parsing`] module
10 //! for turning text into text annotated with scopes, and the [`highlighting`] module
11 //! for turning annotated text into styled/colored text.
12 //!
13 //! Some docs have example code but a good place to look is the `syncat` example as
14 //! well as the source code for the [`easy`] module in `easy.rs` as that shows how to
15 //! plug the various parts together for common use cases.
16 //!
17 //! [`parsing::SyntaxSet`]: parsing/struct.SyntaxSet.html
18 //! [`easy`]: easy/index.html
19 //! [`parsing`]: parsing/index.html
20 //! [`highlighting`]: highlighting/index.html
21 
22 #![doc(html_root_url = "https://docs.rs/syntect/4.6.0")]
23 
24 #[macro_use]
25 extern crate lazy_static;
26 #[macro_use]
27 extern crate serde_derive;
28 #[cfg(test)]
29 #[macro_use]
30 extern crate pretty_assertions;
31 
32 #[cfg(any(feature = "dump-load-rs", feature = "dump-load", feature = "dump-create", feature = "dump-create-rs"))]
33 pub mod dumps;
34 #[cfg(feature = "parsing")]
35 pub mod easy;
36 #[cfg(feature = "html")]
37 mod escape;
38 pub mod highlighting;
39 #[cfg(feature = "html")]
40 pub mod html;
41 pub mod parsing;
42 pub mod util;
43 
44 use std::io::Error as IoError;
45 use std::error::Error;
46 use std::fmt;
47 
48 #[cfg(feature = "metadata")]
49 use serde_json::Error as JsonError;
50 #[cfg(all(feature = "yaml-load", feature = "parsing"))]
51 use crate::parsing::ParseSyntaxError;
52 use crate::highlighting::{ParseThemeError, SettingsError};
53 
54 /// Common error type used by syntax and theme loading
55 #[derive(Debug)]
56 pub enum LoadingError {
57     /// error finding all the files in a directory
58     WalkDir(walkdir::Error),
59     /// error reading a file
60     Io(IoError),
61     /// a syntax file was invalid in some way
62     #[cfg(feature = "yaml-load")]
63     ParseSyntax(ParseSyntaxError, Option<String>),
64     /// a metadata file was invalid in some way
65     #[cfg(feature = "metadata")]
66     ParseMetadata(JsonError),
67     /// a theme file was invalid in some way
68     ParseTheme(ParseThemeError),
69     /// a theme's Plist syntax was invalid in some way
70     ReadSettings(SettingsError),
71     /// A path given to a method was invalid.
72     /// Possibly because it didn't reference a file or wasn't UTF-8.
73     BadPath,
74 }
75 
76 impl From<SettingsError> for LoadingError {
from(error: SettingsError) -> LoadingError77     fn from(error: SettingsError) -> LoadingError {
78         LoadingError::ReadSettings(error)
79     }
80 }
81 
82 impl From<IoError> for LoadingError {
from(error: IoError) -> LoadingError83     fn from(error: IoError) -> LoadingError {
84         LoadingError::Io(error)
85     }
86 }
87 
88 impl From<ParseThemeError> for LoadingError {
from(error: ParseThemeError) -> LoadingError89     fn from(error: ParseThemeError) -> LoadingError {
90         LoadingError::ParseTheme(error)
91     }
92 }
93 
94 #[cfg(feature = "metadata")]
95 impl From<JsonError> for LoadingError {
from(src: JsonError) -> LoadingError96     fn from(src: JsonError) -> LoadingError {
97         LoadingError::ParseMetadata(src)
98     }
99 }
100 
101 #[cfg(all(feature = "yaml-load", feature = "parsing"))]
102 impl From<ParseSyntaxError> for LoadingError {
from(error: ParseSyntaxError) -> LoadingError103     fn from(error: ParseSyntaxError) -> LoadingError {
104         LoadingError::ParseSyntax(error, None)
105     }
106 }
107 
108 impl fmt::Display for LoadingError {
fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result109     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
110         use crate::LoadingError::*;
111 
112         match *self {
113             WalkDir(ref error) => error.fmt(f),
114             Io(ref error) => error.fmt(f),
115             #[cfg(feature = "yaml-load")]
116             ParseSyntax(ref error, ref filename) => {
117                 if let Some(ref file) = filename {
118                     write!(f, "{}: {}", file, error)
119                 } else {
120                     error.fmt(f)
121                 }
122             },
123             #[cfg(feature = "metadata")]
124             ParseMetadata(_) => write!(f, "Failed to parse JSON"),
125             ParseTheme(_) => write!(f, "Invalid syntax theme"),
126             ReadSettings(_) => write!(f, "Invalid syntax theme settings"),
127             BadPath => write!(f, "Invalid path"),
128         }
129     }
130 }
131 
132 impl Error for LoadingError {
cause(&self) -> Option<&dyn Error>133     fn cause(&self) -> Option<&dyn Error> {
134         use crate::LoadingError::*;
135 
136         match *self {
137             WalkDir(ref error) => Some(error),
138             Io(ref error) => Some(error),
139             _ => None,
140         }
141     }
142 }
143