Visualise syntax tree from CLI (#324)

* Exposed --visualise CLI option
* Added serde and serde_json dependencies for the CLI
* Decant Tree-sitter's parsed tree into a recursive structure.
* Use Serde to serialise that structure to JSON.

Author: Xophmeister

Cargo.lock

@@ -13,6 +13,8 @@ itertools = "0.10"
 log = "0.4"
 ouroboros = "0.15"
 pretty_assertions = "1.3"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
 tempfile = "3.4.0"
 test-log = "0.2"
 tree-sitter = "0.20"

Cargo.toml

@@ -163,6 +163,10 @@ Options:
   Format the input file in place. (This has the effect of setting the
   output file equal to the input file.)
 
+* `-v`, `--visualise`\
+  Visualise the syntax tree, rather than format [possible values: `json`
+  (default)].
+
 * `-s`, `--skip-idempotence`\
   Do not check that formatting twice gives the same output.
 

README.md

@@ -1,7 +1,7 @@
 use criterion::{criterion_group, criterion_main, Criterion};
 use std::fs;
 use std::io;
-use topiary::formatter;
+use topiary::{formatter, Operation};
 
 fn criterion_benchmark(c: &mut Criterion) {
     let input = fs::read_to_string("tests/samples/input/ocaml.ml").unwrap();
@@ -13,7 +13,15 @@ fn criterion_benchmark(c: &mut Criterion) {
             let mut query = query.as_bytes();
             let mut output = io::BufWriter::new(Vec::new());
 
-            formatter(&mut input, &mut output, &mut query, None, false)
+            formatter(
+                &mut input,
+                &mut output,
+                &mut query,
+                None,
+                Operation::Format {
+                    skip_idempotence: false,
+                },
+            )
         })
     });
 }

benches/benchmark.rs

@@ -10,7 +10,7 @@ pub type CLIResult<T> = result::Result<T, TopiaryError>;
 #[derive(Debug)]
 pub enum TopiaryError {
     Lib(FormatterError),
-    Bin(String, CLIError),
+    Bin(String, Option<CLIError>),
 }
 
 /// A subtype of `TopiaryError::Bin`
@@ -33,8 +33,9 @@ impl error::Error for TopiaryError {
     fn source(&self) -> Option<&(dyn error::Error + 'static)> {
         match self {
             Self::Lib(error) => error.source(),
-            Self::Bin(_, CLIError::IOError(error)) => error.source(),
-            Self::Bin(_, CLIError::Generic(error)) => error.source(),
+            Self::Bin(_, Some(CLIError::IOError(error))) => error.source(),
+            Self::Bin(_, Some(CLIError::Generic(error))) => error.source(),
+            Self::Bin(_, None) => None,
         }
     }
 }
@@ -48,11 +49,13 @@ impl From<FormatterError> for TopiaryError {
 impl From<io::Error> for TopiaryError {
     fn from(e: io::Error) -> Self {
         match e.kind() {
-            io::ErrorKind::NotFound => Self::Bin("File not found".into(), CLIError::IOError(e)),
+            io::ErrorKind::NotFound => {
+                Self::Bin("File not found".into(), Some(CLIError::IOError(e)))
+            }
 
             _ => Self::Bin(
-                "Cound not read or write to file".into(),
-                CLIError::IOError(e),
+                "Could not read or write to file".into(),
+                Some(CLIError::IOError(e)),
             ),
         }
     }
@@ -62,7 +65,7 @@ impl From<tempfile::PersistError> for TopiaryError {
     fn from(e: tempfile::PersistError) -> Self {
         Self::Bin(
             "Could not persist output to disk".into(),
-            CLIError::IOError(e.error),
+            Some(CLIError::IOError(e.error)),
         )
     }
 }
@@ -75,8 +78,8 @@ where
 {
     fn from(e: io::IntoInnerError<W>) -> Self {
         Self::Bin(
-            "Cannot flush internal buffer".into(),
-            CLIError::Generic(Box::new(e)),
+            "Could not flush internal buffer".into(),
+            Some(CLIError::Generic(Box::new(e))),
         )
     }
 }

src/bin/topiary/error.rs

@@ -1,24 +1,29 @@
 mod error;
 mod output;
 mod supported;
+mod visualise;
 
-use crate::{error::CLIResult, output::OutputFile, supported::SupportedLanguage};
-use clap::{ArgGroup, Parser};
 use std::{
     error::Error,
     fs::File,
     io::{stdin, BufReader, BufWriter},
     path::PathBuf,
 };
-use topiary::{formatter, Language};
+
+use clap::{ArgGroup, Parser};
+
+use crate::{
+    error::CLIResult, output::OutputFile, supported::SupportedLanguage, visualise::Visualisation,
+};
+use topiary::{formatter, Language, Operation};
 
 #[derive(Parser, Debug)]
 #[clap(author, version, about, long_about = None)]
 // Require at least one of --language, --input-file or --query (n.b., language > input > query)
 #[clap(group(ArgGroup::new("rule").multiple(true).required(true).args(&["language", "input-file", "query"]),))]
 struct Args {
     /// Which language to parse and format
-    #[clap(short, long, arg_enum, display_order = 1)]
+    #[clap(short, long, value_enum, display_order = 1)]
     language: Option<SupportedLanguage>,
 
     /// Path to an input file. If omitted, or equal to "-", read from standard
@@ -39,8 +44,21 @@ struct Args {
     #[clap(short, long, requires = "input-file", display_order = 5)]
     in_place: bool,
 
+    /// Visualise the syntax tree, rather than format.
+    #[clap(
+        short,
+        long,
+        value_enum,
+        aliases = &["view", "visualize"],
+        value_name = "OUTPUT_FORMAT",
+        conflicts_with_all = &["in-place", "skip-idempotence"],
+        default_missing_value = "json",
+        display_order = 6
+    )]
+    visualise: Option<Visualisation>,
+
     /// Do not check that formatting twice gives the same output
-    #[clap(short, long, display_order = 6)]
+    #[clap(short, long, display_order = 7)]
     skip_idempotence: bool,
 }
 
@@ -94,13 +112,17 @@ fn run() -> CLIResult<()> {
 
     let mut query = BufReader::new(File::open(query_path)?);
 
-    formatter(
-        &mut input,
-        &mut output,
-        &mut query,
-        language,
-        args.skip_idempotence,
-    )?;
+    let operation = if let Some(visualisation) = args.visualise {
+        Operation::Visualise {
+            output_format: visualisation.into(),
+        }
+    } else {
+        Operation::Format {
+            skip_idempotence: args.skip_idempotence,
+        }
+    };
+
+    formatter(&mut input, &mut output, &mut query, language, operation)?;
 
     output.into_inner()?.persist()?;
 

src/bin/topiary/main.rs

@@ -1,7 +1,7 @@
-use clap::ArgEnum;
+use clap::ValueEnum;
 use topiary::Language;
 
-#[derive(ArgEnum, Clone, Copy, Debug)]
+#[derive(ValueEnum, Clone, Copy, Debug)]
 pub enum SupportedLanguage {
     Json,
     Toml,

src/bin/topiary/supported.rs

@@ -0,0 +1,17 @@
+// This is somewhat redundant, but we cannot implement clap::ValueEnum for topiary::Visualisation
+// without breaking the orphan rules. So we have to maintain a local copy for the sake of the CLI.
+
+use clap::ValueEnum;
+
+#[derive(ValueEnum, Clone, Copy, Debug)]
+pub enum Visualisation {
+    Json,
+}
+
+impl From<Visualisation> for topiary::Visualisation {
+    fn from(visualisation: Visualisation) -> Self {
+        match visualisation {
+            Visualisation::Json => Self::Json,
+        }
+    }
+}

src/bin/topiary/visualise.rs

@@ -169,3 +169,9 @@ where
         ))
     }
 }
+
+impl From<serde_json::Error> for FormatterError {
+    fn from(e: serde_json::Error) -> Self {
+        Self::Internal("Could not serialise JSON output".into(), Some(e.into()))
+    }
+}