Merge pull request #629 from tweag/chris/cli/full-subcommands-and-com…

…pletion Full-form subcommands and completion
tweag · Sep 19, 2023 · 600c059 · 600c059
2 parents 7e6cb4f + 601ed10
commit 600c059
Show file tree

Hide file tree

Showing 8 changed files with 198 additions and 99 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -39,6 +39,7 @@ assert_cmd = "2.0"
 async-scoped = { version = "0.7.1", features = ["use-tokio"] }
 cfg-if = "1.0.0"
 clap = { version = "4.3", features = [ "env" ] }
+clap_complete = "4.4.1"
 criterion = "0.5"
 directories = "5.0"
 env_logger = "0.10"

diff --git a/README.md b/README.md
@@ -171,10 +171,11 @@ CLI app for Topiary, the universal code formatter.
 Usage: topiary [OPTIONS] <COMMAND>
 
 Commands:
-  fmt   Format inputs
-  vis   Visualise the input's Tree-sitter parse tree
-  cfg   Print the current configuration
-  help  Print this message or the help of the given subcommand(s)
+  format      Format inputs
+  visualise   Visualise the input's Tree-sitter parse tree
+  config      Print the current configuration
+  completion  Generate shell completion script
+  help        Print this message or the help of the given subcommand(s)
 
 Options:
   -C, --configuration <CONFIGURATION>
@@ -210,11 +211,11 @@ Options:
 #### Format
 
 <!-- DO NOT REMOVE THE "usage" COMMENTS -->
-<!-- usage:start:fmt -->
+<!-- usage:start:format -->
 ```
 Format inputs
 
-Usage: topiary fmt [OPTIONS] <--language <LANGUAGE>|FILES>
+Usage: topiary format [OPTIONS] <--language <LANGUAGE>|FILES>
 
 Arguments:
   [FILES]...
@@ -263,23 +264,23 @@ Options:
   -h, --help
           Print help (see a summary with '-h')
 ```
-<!-- usage:end:fmt -->
+<!-- usage:end:format -->
 
 When formatting inputs from disk, language selection is detected from
 the input files' extensions. To format standard input, you must specify
 the `--language` and, optionally, `--query` arguments, omitting any
 input files.
 
-Note: `format` is a recognised alias of the `fmt` subcommand.
+Note: `fmt` is a recognised alias of the `format` subcommand.
 
 #### Visualise
 
 <!-- DO NOT REMOVE THE "usage" COMMENTS -->
-<!-- usage:start:vis -->
+<!-- usage:start:visualise -->
 ```
 Visualise the input's Tree-sitter parse tree
 
-Usage: topiary vis [OPTIONS] <--language <LANGUAGE>|FILE>
+Usage: topiary visualise [OPTIONS] <--language <LANGUAGE>|FILE>
 
 Arguments:
   [FILE]
@@ -331,24 +332,24 @@ Options:
   -h, --help
           Print help (see a summary with '-h')
 ```
-<!-- usage:end:vis -->
+<!-- usage:end:visualise -->
 
 When visualising inputs from disk, language selection is detected from
 the input file's extension. To visualise standard input, you must
 specify the `--language` and, optionally, `--query` arguments, omitting
 the input file. The visualisation output is written to standard out.
 
-Note: `visualise`, `visualize` and `view` are recognised aliases of the
-`vis` subcommand.
+Note: `vis`, `visualize` and `view` are recognised aliases of the
+`visualise` subcommand.
 
 #### Configuration
 
 <!-- DO NOT REMOVE THE "usage" COMMENTS -->
-<!-- usage:start:cfg -->
+<!-- usage:start:config -->
 ```
 Print the current configuration
 
-Usage: topiary cfg [OPTIONS]
+Usage: topiary config [OPTIONS]
 
 Options:
   -C, --configuration <CONFIGURATION>
@@ -376,12 +377,65 @@ Options:
   -h, --help
           Print help (see a summary with '-h')
 ```
-<!-- usage:end:cfg -->
+<!-- usage:end:config -->
 
 Please refer to the [Configuration](#configuration-1) section below to
 understand the different sources of configuration and collation modes.
 
-Note: `config` is a recognised alias of the `cfg` subcommand.
+Note: `cfg` is a recognised alias of the `config` subcommand.
+
+#### Shell Completion
+
+Shell completion scripts for Topiary can be generated with the
+`completion` subcommand. The output of which can be sourced into your
+shell session or profile, as required.
+
+<!-- DO NOT REMOVE THE "usage" COMMENTS -->
+<!-- usage:start:completion -->
+```
+Generate shell completion script
+
+Usage: topiary completion [OPTIONS] [SHELL]
+
+Arguments:
+  [SHELL]
+          Shell (omit to detect from the environment)
+
+          [possible values: bash, elvish, fish, powershell, zsh]
+
+Options:
+  -C, --configuration <CONFIGURATION>
+          Configuration file
+
+          [env: TOPIARY_CONFIG_FILE]
+
+      --configuration-collation <CONFIGURATION_COLLATION>
+          Configuration collation mode
+
+          [env: TOPIARY_CONFIG_COLLATION]
+          [default: merge]
+
+          Possible values:
+          - merge:    When multiple sources of configuration are available, matching items are
+            updated from the higher priority source, with collections merged as the union of sets
+          - revise:   When multiple sources of configuration are available, matching items
+            (including collections) are superseded from the higher priority source
+          - override: When multiple sources of configuration are available, the highest priority
+            source is taken. All values from lower priority sources are discarded
+
+  -v, --verbose...
+          Logging verbosity (increased per occurrence)
+
+  -h, --help
+          Print help (see a summary with '-h')
+```
+<!-- usage:end:completion -->
+
+For example, in Bash:
+
+```bash
+source <(topiary completion)
+```
 
 #### Logging
 

diff --git a/default.nix b/default.nix
@@ -1,16 +1,17 @@
-{
-  pkgs,
-  system,
-  advisory-db,
-  crane,
-  rust-overlay,
-  nix-filter,
-}: let
-  wasmRustVersion = "1.67.1";
+{ pkgs
+, system
+, advisory-db
+, crane
+, rust-overlay
+, nix-filter
+,
+}:
+let
+  wasmRustVersion = "1.70.0";
   wasmTarget = "wasm32-unknown-unknown";
 
   rustWithWasmTarget = pkgs.rust-bin.stable.${wasmRustVersion}.default.override {
-    targets = [wasmTarget];
+    targets = [ wasmTarget ];
   };
 
   craneLib = crane.mkLib pkgs;
@@ -50,83 +51,84 @@
   # Instead, we just want to update the scope that crane will use by appending
   # our specific toolchain there.
   craneLibWasm = craneLib.overrideToolchain rustWithWasmTarget;
-in {
+in
+{
   clippy = craneLib.cargoClippy (commonArgs
     // {
-      inherit cargoArtifacts;
-      cargoClippyExtraArgs = "-- --deny warnings";
-    });
+    inherit cargoArtifacts;
+    cargoClippyExtraArgs = "-- --deny warnings";
+  });
 
   clippy-wasm = craneLibWasm.cargoClippy (commonArgs
     // {
-      inherit cargoArtifacts;
-      cargoClippyExtraArgs = "-p topiary-playground --target ${wasmTarget} -- --deny warnings";
-    });
+    inherit cargoArtifacts;
+    cargoClippyExtraArgs = "-p topiary-playground --target ${wasmTarget} -- --deny warnings";
+  });
 
   fmt = craneLib.cargoFmt commonArgs;
 
   audit = craneLib.cargoAudit (commonArgs
     // {
-      inherit advisory-db;
-    });
+    inherit advisory-db;
+  });
 
   benchmark = craneLib.buildPackage (commonArgs
     // {
-      inherit cargoArtifacts;
-      cargoTestCommand = "cargo bench --profile release";
-    });
+    inherit cargoArtifacts;
+    cargoTestCommand = "cargo bench --profile release";
+  });
 
   topiary-lib = craneLib.buildPackage (commonArgs
     // {
-      inherit cargoArtifacts;
-      pname = "topiary-lib";
-      cargoExtraArgs = "-p topiary";
-    });
+    inherit cargoArtifacts;
+    pname = "topiary-lib";
+    cargoExtraArgs = "-p topiary";
+  });
 
   topiary-cli = craneLib.buildPackage (commonArgs
     // {
-      inherit cargoArtifacts;
-      pname = "topiary";
-      cargoExtraArgs = "-p topiary-cli";
-      postInstall = ''
-        install -Dm444 languages/* -t $out/share/languages
-      '';
-
-      # Set TOPIARY_LANGUAGE_DIR to the Nix store
-      # for the build
-      TOPIARY_LANGUAGE_DIR = "${placeholder "out"}/share/languages";
-
-      # Set TOPIARY_LANGUAGE_DIR to the working directory
-      # in a development shell
-      shellHook = ''
-        export TOPIARY_LANGUAGE_DIR=$PWD/languages
-      '';
-    });
+    inherit cargoArtifacts;
+    pname = "topiary";
+    cargoExtraArgs = "-p topiary-cli";
+    postInstall = ''
+      install -Dm444 languages/* -t $out/share/languages
+    '';
+
+    # Set TOPIARY_LANGUAGE_DIR to the Nix store
+    # for the build
+    TOPIARY_LANGUAGE_DIR = "${placeholder "out"}/share/languages";
+
+    # Set TOPIARY_LANGUAGE_DIR to the working directory
+    # in a development shell
+    shellHook = ''
+      export TOPIARY_LANGUAGE_DIR=$PWD/languages
+    '';
+  });
 
   topiary-playground = craneLibWasm.buildPackage (commonArgs
     // {
-      inherit cargoArtifacts;
-      pname = "topiary-playground";
-      cargoExtraArgs = "-p topiary-playground --no-default-features --target ${wasmTarget}";
-
-      # Tests currently need to be run via `cargo wasi` which
-      # isn't packaged in nixpkgs yet...
-      doCheck = false;
-
-      postInstall = ''
-        echo 'Removing unneeded dir'
-        rm -rf $out/lib
-        echo 'Running wasm-bindgen'
-        wasm-bindgen --version
-        wasm-bindgen --target web --out-dir $out target/wasm32-unknown-unknown/release/topiary_playground.wasm;
-        echo 'Running wasm-opt'
-        wasm-opt --version
-        wasm-opt -Oz -o $out/output.wasm $out/topiary_playground_bg.wasm
-        echo 'Overwriting topiary_playground_bg.wasm with the optimized file'
-        mv $out/output.wasm $out/topiary_playground_bg.wasm
-        echo 'Extracting custom build outputs'
-        export LANGUAGES_EXPORT="$(ls -t target/wasm32-unknown-unknown/release/build/topiary-playground-*/out/languages_export.ts | head -1)"
-        cp $LANGUAGES_EXPORT $out/
-      '';
-    });
+    inherit cargoArtifacts;
+    pname = "topiary-playground";
+    cargoExtraArgs = "-p topiary-playground --no-default-features --target ${wasmTarget}";
+
+    # Tests currently need to be run via `cargo wasi` which
+    # isn't packaged in nixpkgs yet...
+    doCheck = false;
+
+    postInstall = ''
+      echo 'Removing unneeded dir'
+      rm -rf $out/lib
+      echo 'Running wasm-bindgen'
+      wasm-bindgen --version
+      wasm-bindgen --target web --out-dir $out target/wasm32-unknown-unknown/release/topiary_playground.wasm;
+      echo 'Running wasm-opt'
+      wasm-opt --version
+      wasm-opt -Oz -o $out/output.wasm $out/topiary_playground_bg.wasm
+      echo 'Overwriting topiary_playground_bg.wasm with the optimized file'
+      mv $out/output.wasm $out/topiary_playground_bg.wasm
+      echo 'Extracting custom build outputs'
+      export LANGUAGES_EXPORT="$(ls -t target/wasm32-unknown-unknown/release/build/topiary-playground-*/out/languages_export.ts | head -1)"
+      cp $LANGUAGES_EXPORT $out/
+    '';
+  });
 }
diff --git a/topiary-cli/Cargo.toml b/topiary-cli/Cargo.toml
@@ -28,6 +28,7 @@ path = "src/main.rs"
 # Eventually we will want to dynamically load them, like Helix does.
 async-scoped = { workspace = true }
 clap = { workspace = true, features = ["derive", "env", "wrap_help"] }
+clap_complete = { workspace = true }
 directories = { workspace = true }
 env_logger = { workspace = true }
 futures = { workspace = true }