feat: tinty list --json

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- Support `--json` option in `tinty list`.
+
+
 ## [0.25.0] - 2025-01-14
 
 ### Added

Cargo.toml

@@ -18,6 +18,7 @@ clap_complete = { version = "4.5.40" }
 hex_color = "3.0.0"
 serde = { version = "1.0.216", features = ["derive"] }
 serde_yaml = "0.9.33"
+serde_json = "1.0.135"
 shell-words = "1.1.0"
 strip-ansi-escapes = "0.2.0"
 tinted-builder-rust = "0.12.1"
@@ -29,3 +30,4 @@ xdg = "2.5.2"
 home = "0.5.11"
 rand = "0.8.5"
 regex = "1.7"
+rayon = "1.10"

README.md

@@ -166,7 +166,7 @@ The following is a table of the available subcommands for the CLI tool (Tinty),
 | Subcommand | Description                                         | Arguments            | Example Usage                              |
 |------------|-----------------------------------------------------|----------------------|--------------------------------------------|
 | `sync`     | Installs and updates schemes and templates defined in `tinty/config.toml` | - | `tinty sync` |
-| `list`     | Lists all available themes. | Optional argument `--custom-schemes` to list saved custom theme files using `tinty generate-scheme` | `tinty list` |
+| `list`     | Lists all available themes. | Optional argument `--custom-schemes` to list saved custom theme files using `tinty generate-scheme`.<br>Optional argument `--json` to output more info about each scheme in JSON form | `tinty list` |
 | `apply`    | Applies a specific theme. | `<scheme_system>-<scheme_name>`: Name of the system and scheme to apply. | `tinty apply base16-mocha` |
 | `init`     | Initializes the tool with the last applied theme otherwise `default-scheme` from `config.toml`. | - | `tinty init` |
 | `current`  | Displays the currently applied theme or current theme values. | `<scheme_property_name>` (Optional argument with the following supported values: `author` \| `description` \| `name` \| `slug` \| `system` \| `variant`) | `tinty current` |

USAGE.md

@@ -9,6 +9,7 @@ For more general usage, look at the [Usage section] in [README.md].
 - [How it works](#how-it-works)
 - [Sourcing scripts that set environment variables](#sourcing-scripts-that-set-environment-variables)
 - [Use your own schemes](#use-your-own-schemes)
+- [Scripting](#scripting)
 - [shell](#shell)
 - [Vim or Neovim](#vim-or-neovim)
 - [tmux](#tmux)
@@ -167,6 +168,40 @@ file by including this line:
 import = ["~/.config/alacritty/colors.toml"]
 ```
 
+## Scripting
+
+The `tinty list --json` option outputs a list of all available schemes in JSON format. It provides extensive information
+about each scheme, like its human-friendly name, its variant (`light` vs `dark`), its scheme (`base16` vs `base24`),
+as well as its color palette in multiple formats. See [this sample object entry](./fixtures/gruvbox-material-dark-hard.json) to see the information available.
+
+Installing [jq] to parse & process the output is recommended.
+
+### Examples
+
+Pretty print:
+
+```sh
+tinty list --json | jq
+```
+
+List light themes only:
+
+```sh
+tinty list --json | jq '.[] | select(.variant == "light") | .id' -r
+```
+
+List all themes but grouping light themes and dark themes together:
+
+```sh
+tinty list --json | jq 'sort_by(.variant) | reverse' -r
+```
+
+Sort themes by background color, from darkest to lightest:
+
+```sh
+tinty list --json | jq 'sort_by(.lightness.background)' -r
+```
+
 ## Shell
 
 When Tinty does not have any `[[items]]` set up in `config.toml`, Tinty
@@ -549,3 +584,4 @@ Configure [delta] as your Git pager and/or difftool under the name `delta`, like
 [contrib/completion]: contrib/completion
 [base16-qutebrowser]: https://github.com/tinted-theming/base16-qutebrowser
 [delta]: https://github.com/dandavison/delta
+[jq]: https://jqlang.github.io/jq/