|
| 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 | +
|
1 | 124 | #![deny(clippy::print_stderr)] |
2 | 125 | #![deny(clippy::print_stdout)] |
3 | 126 | #![allow(clippy::uninlined_format_args)] |
|
0 commit comments