jsonc_parser/
lib.rs

1//! # jsonc-parser
2//!
3//! A JSON parser and manipulator that supports comments and other JSON extensions.
4//!
5//! ## Parsing
6//!
7//! To a simple `JsonValue`:
8//!
9//! ```
10//! use jsonc_parser::parse_to_value;
11//!
12//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
13//! let json_value = parse_to_value(r#"{ "test": 5 } // test"#, &Default::default())?;
14//! // check the json_value here
15//! # Ok(())
16//! # }
17//! ```
18//!
19//! Or an AST:
20//!
21//! ```
22//! use jsonc_parser::parse_to_ast;
23//! use jsonc_parser::CollectOptions;
24//! use jsonc_parser::CommentCollectionStrategy;
25//!
26//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
27//! let parse_result = parse_to_ast(r#"{ "test": 5 } // test"#, &CollectOptions {
28//!     comments: CommentCollectionStrategy::Separate, // include comments in result
29//!     tokens: true, // include tokens in result
30//! }, &Default::default())?;
31//! // ...inspect parse_result for value, tokens, and comments here...
32//! # Ok(())
33//! # }
34//! ```
35//!
36//! ## Manipulation (CST)
37//!
38//! When enabling the `cst` cargo feature, parsing to a CST provides a first class manipulation API:
39//!
40//! ```
41//! # #[cfg(feature = "cst")]
42//! # {
43//! use jsonc_parser::cst::CstRootNode;
44//! use jsonc_parser::ParseOptions;
45//! use jsonc_parser::json;
46//!
47//! let json_text = r#"{
48//!   // comment
49//!   "data": 123
50//! }"#;
51//!
52//! let root = CstRootNode::parse(json_text, &ParseOptions::default()).unwrap();
53//! let root_obj = root.object_value_or_set();
54//!
55//! root_obj.get("data").unwrap().set_value(json!({
56//!   "nested": true
57//! }));
58//! root_obj.append("new_key", json!([456, 789, false]));
59//!
60//! assert_eq!(root.to_string(), r#"{
61//!   // comment
62//!   "data": {
63//!     "nested": true
64//!   },
65//!   "new_key": [456, 789, false]
66//! }"#);
67//! # }
68//! ```
69//!
70//! ## Serde
71//!
72//! If you enable the `"serde"` feature as follows:
73//!
74//! ```toml
75//! # in Cargo.toml
76//! jsonc-parser = { version = "...", features = ["serde"] }
77//! ```
78//!
79//! Then you can use the `parse_to_serde_value` function to get a `serde_json::Value`:
80//!
81//! ```
82//! # #[cfg(feature = "serde")]
83//! # {
84//! use jsonc_parser::parse_to_serde_value;
85//!
86//! # fn parse_example() -> Result<(), Box<dyn std::error::Error>> {
87//! let json_value = parse_to_serde_value(r#"{ "test": 5 } // test"#, &Default::default())?;
88//! # Ok(())
89//! # }
90//! # }
91//! ```
92//!
93//! Alternatively, use `parse_to_ast` then call `.into()` (ex. `let value: serde_json::Value = ast.into();`).
94//!
95//! ## Parse Strictly as JSON
96//!
97//! Provide `ParseOptions` and set all the options to false:
98//!
99//! ```
100//! use jsonc_parser::parse_to_value;
101//! use jsonc_parser::ParseOptions;
102//!
103//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
104//! # let text = "{}";
105//! let json_value = parse_to_value(text, &ParseOptions {
106//!   allow_comments: false,
107//!   allow_loose_object_property_names: false,
108//!   allow_trailing_commas: false,
109//!   allow_single_quoted_strings: false,
110//!   allow_hexadecimal_numbers: false,
111//!   allow_unary_plus_numbers: false,
112//! })?;
113//! # Ok(())
114//! # }
115//! ```
116//!
117//! ## Error column number with unicode-width
118//!
119//! To get more accurate display column numbers in error messages, enable the `error_unicode_width` cargo feature,
120//! which will pull in and use the [unicode-width](https://crates.io/crates/unicode-width) dependency internally.
121//! Otherwise it will use the character count, which isn't as accurate of a number, but will probably be good enough
122//! in most cases.
123
124#![deny(clippy::print_stderr)]
125#![deny(clippy::print_stdout)]
126#![allow(clippy::uninlined_format_args)]
127
128pub mod ast;
129pub mod common;
130#[cfg(feature = "cst")]
131pub mod cst;
132pub mod errors;
133mod parse_to_ast;
134mod parse_to_value;
135mod scanner;
136#[cfg(feature = "serde")]
137mod serde;
138mod string;
139pub mod tokens;
140mod value;
141
142pub use parse_to_ast::*;
143pub use parse_to_value::*;
144pub use scanner::*;
145pub use string::ParseStringErrorKind;
146pub use value::*;
147
148#[cfg(feature = "serde")]
149pub use serde::*;
jsonc_parser/lib.rs

jsonc_parser/
lib.rs
