feat: CST and first class manipulation API (#41)

Author: dsherret

.github/workflows/ci.yml

@@ -19,19 +19,12 @@ jobs:
       RUST_BACKTRACE: full
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - uses: dsherret/rust-toolchain-file@v1
     - uses: Swatinem/rust-cache@v2
       with:
         save-if: ${{ github.ref == 'refs/heads/main' }}
 
-    - name: Build debug
-      if: matrix.config.kind == 'test_debug'
-      run: cargo build --verbose
-    - name: Build release
-      if: matrix.config.kind == 'test_release'
-      run: cargo build --release --verbose
-
     - name: Test debug
       if: matrix.config.kind == 'test_debug'
       run: |

.gitignore

@@ -1,2 +1,3 @@
+.vscode
 target
 Cargo.lock

Cargo.toml

@@ -7,11 +7,15 @@ license = "MIT"
 description = "JSONC parser."
 repository = "https://github.com/dprint/jsonc-parser"
 
+[package.metadata.docs.rs]
+all-features = true
+
 [dependencies]
-indexmap = { version = "2.0.2", optional = true }
+indexmap = { version = "2.2.6", optional = true }
 serde_json = { version = "1.0", optional = true }
 
 [features]
+cst = []
 preserve_order = ["indexmap", "serde_json/preserve_order"]
 serde = ["serde_json"]
 

README.md

@@ -2,9 +2,9 @@
 
 [![](https://img.shields.io/crates/v/jsonc-parser.svg)](https://crates.io/crates/jsonc-parser)
 
-JSONC parser implemented in Rust.
+JSONC parsing and manipulation for Rust.
 
-## Example
+## Parsing
 
 To a simple `JsonValue`:
 
@@ -28,6 +28,37 @@ let parse_result = parse_to_ast(r#"{ "test": 5 } // test"#, &CollectOptions {
 // ...inspect parse_result for value, tokens, and comments here...
 ```
 
+## Manipulation (CST)
+
+When enabling the `cst` cargo feature, parsing to a CST provides a first class manipulation API:
+
+```rs
+use jsonc_parser::cst::CstRootNode;
+use jsonc_parser::ParseOptions;
+use jsonc_parser::json;
+
+let json_text = r#"{
+  // comment
+  "data": 123
+}"#;
+
+let root = CstRootNode::parse(json_text, &ParseOptions::default()).unwrap();
+let root_obj = root.root_value().unwrap().as_object().unwrap();
+
+root_obj.get("data").unwrap().set_value(json!({
+  "nested": true
+}));
+root_obj.append("new_key", json!([456, 789, false]));
+
+assert_eq!(root.to_string(), r#"{
+  // comment
+  "data": {
+    "nested": true,
+  },
+  "new_key": [456, 789, false]
+}"#);
+```
+
 ## Serde
 
 If you enable the `"serde"` feature as follows:

dprint.json

@@ -1,5 +1,4 @@
 {
-  "incremental": true,
   "indentWidth": 2,
   "exec": {
     "commands": [{
@@ -13,7 +12,7 @@
     "./benches/json"
   ],
   "plugins": [
-    "https://plugins.dprint.dev/markdown-0.15.2.wasm",
-    "https://plugins.dprint.dev/exec-0.4.3.json@42343548b8022c99b1d750be6b894fe6b6c7ee25f72ae9f9082226dd2e515072"
+    "https://plugins.dprint.dev/markdown-0.17.8.wasm",
+    "https://plugins.dprint.dev/exec-0.5.0.json@8d9972eee71fa1590e04873540421f3eda7674d0f1aae3d7c788615e7b7413d0"
   ]
 }

rust-toolchain.toml

@@ -1,3 +1,3 @@
 [toolchain]
-channel = "1.71.0"
+channel = "1.81.0"
 components = ["clippy", "rustfmt"]

src/ast.rs

@@ -411,7 +411,7 @@ impl<'a> Comment<'a> {
 }
 
 impl<'a> Ranged for Comment<'a> {
-  fn range(&self) -> &Range {
+  fn range(&self) -> Range {
     match self {
       Comment::Line(line) => line.range(),
       Comment::Block(line) => line.range(),
@@ -445,7 +445,7 @@ impl<'a, 'b> From<&'b ObjectPropName<'a>> for Node<'a, 'b> {
 }
 
 impl<'a> Ranged for ObjectPropName<'a> {
-  fn range(&self) -> &Range {
+  fn range(&self) -> Range {
     match self {
       ObjectPropName::String(lit) => lit.range(),
       ObjectPropName::Word(lit) => lit.range(),
@@ -456,29 +456,29 @@ impl<'a> Ranged for ObjectPropName<'a> {
 // Implement Traits
 
 macro_rules! impl_ranged {
-    ($($node_name:ident),*) => {
-        $(
-            impl Ranged for $node_name {
-                fn range(&self) -> &Range {
-                    &self.range
-                }
-            }
-        )*
-    };
+  ($($node_name:ident),*) => {
+    $(
+      impl Ranged for $node_name {
+        fn range(&self) -> Range {
+            self.range
+        }
+      }
+    )*
+  };
 }
 
 impl_ranged![BooleanLit, NullKeyword];
 
 macro_rules! impl_ranged_lifetime {
-    ($($node_name:ident),*) => {
-        $(
-            impl<'a> Ranged for $node_name<'a> {
-                fn range(&self) -> &Range {
-                    &self.range
-                }
-            }
-        )*
-    };
+  ($($node_name:ident),*) => {
+    $(
+      impl<'a> Ranged for $node_name<'a> {
+        fn range(&self) -> Range {
+            self.range
+        }
+      }
+    )*
+  };
 }
 
 impl_ranged_lifetime![
@@ -493,7 +493,7 @@ impl_ranged_lifetime![
 ];
 
 impl<'a> Ranged for Value<'a> {
-  fn range(&self) -> &Range {
+  fn range(&self) -> Range {
     match self {
       Value::Array(node) => node.range(),
       Value::BooleanLit(node) => node.range(),
@@ -506,7 +506,7 @@ impl<'a> Ranged for Value<'a> {
 }
 
 impl<'a, 'b> Ranged for Node<'a, 'b> {
-  fn range(&self) -> &Range {
+  fn range(&self) -> Range {
     match self {
       Node::StringLit(node) => node.range(),
       Node::NumberLit(node) => node.range(),
@@ -586,11 +586,11 @@ mod test {
     assert_eq!(obj.properties.len(), 2);
     assert_eq!(obj.take_number("prop"), None);
     assert_eq!(obj.properties.len(), 2);
-    assert_eq!(obj.take_string("prop").is_some(), true);
+    assert!(obj.take_string("prop").is_some());
     assert_eq!(obj.properties.len(), 1);
     assert_eq!(obj.take("something"), None);
     assert_eq!(obj.properties.len(), 1);
-    assert_eq!(obj.take("other").is_some(), true);
+    assert!(obj.take("other").is_some());
     assert_eq!(obj.properties.len(), 0);
   }
 
@@ -604,7 +604,7 @@ mod test {
 
     assert_eq!(obj.properties.len(), 1);
     assert_eq!(obj.get_string("asdf"), None);
-    assert_eq!(obj.get_string("prop").is_some(), true);
+    assert!(obj.get_string("prop").is_some());
     assert_eq!(obj.get("asdf"), None);
     assert_eq!(obj.properties.len(), 1);
   }

src/common.rs

@@ -18,15 +18,15 @@ impl Range {
 }
 
 impl Ranged for Range {
-  fn range(&self) -> &Range {
-    self
+  fn range(&self) -> Range {
+    *self
   }
 }
 
 /// Represents an object that has a range in the text.
 pub trait Ranged {
   /// Gets the range.
-  fn range(&self) -> &Range;
+  fn range(&self) -> Range;
 
   /// Gets the byte index of the first character in the text.
   fn start(&self) -> usize {

src/cst/input.rs

@@ -0,0 +1,62 @@
+#[derive(Debug, Clone)]
+pub enum CstInputValue {
+  Null,
+  Bool(bool),
+  Number(String),
+  String(String),
+  Array(Vec<CstInputValue>),
+  Object(Vec<(String, CstInputValue)>),
+}
+
+impl CstInputValue {
+  pub(crate) fn force_multiline(&self) -> bool {
+    match self {
+      CstInputValue::Null | CstInputValue::Bool(_) | CstInputValue::Number(_) | CstInputValue::String(_) => false,
+      CstInputValue::Array(v) => v.iter().any(|v| v.is_object_or_array_with_elements()),
+      CstInputValue::Object(v) => !v.is_empty(),
+    }
+  }
+
+  fn is_object_or_array_with_elements(&self) -> bool {
+    match self {
+      CstInputValue::Null | CstInputValue::Bool(_) | CstInputValue::Number(_) | CstInputValue::String(_) => false,
+      CstInputValue::Array(v) => !v.is_empty(),
+      CstInputValue::Object(v) => !v.is_empty(),
+    }
+  }
+}
+
+#[macro_export]
+macro_rules! json {
+  (null) => {
+    $crate::cst::CstInputValue::Null
+  };
+
+  (true) => {
+    $crate::cst::CstInputValue::Bool(true)
+  };
+
+  (false) => {
+    $crate::cst::CstInputValue::Bool(false)
+  };
+
+  ($num:literal) => {
+    $crate::cst::CstInputValue::Number($num.to_string())
+  };
+
+  ($str:literal) => {
+    $crate::cst::CstInputValue::String($str.to_string())
+  };
+
+  ([ $($elems:tt),* $(,)? ]) => {
+    $crate::cst::CstInputValue::Array(vec![
+      $(json!($elems)),*
+    ])
+  };
+
+  ({ $($key:tt : $value:tt),* $(,)? }) => {
+    $crate::cst::CstInputValue::Object(vec![
+      $(($key.to_string(), json!($value))),*
+    ])
+  };
+}