https://github.com/gnprice/toml-cli
https://github.com/gnprice/toml-cli
Last synced: 23 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/gnprice/toml-cli
- Owner: gnprice
- License: mit
- Created: 2019-08-31T04:34:07.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-01-19T03:44:34.000Z (over 1 year ago)
- Last Synced: 2024-03-15T07:23:46.864Z (about 1 year ago)
- Language: Rust
- Size: 98.6 KB
- Stars: 101
- Watchers: 3
- Forks: 21
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-ccamel - gnprice/toml-cli - (Rust)
README
# toml-cli
This is the home of the `toml` command, a simple CLI for editing
and querying TOML files.
The intent of the `toml` command is to be useful
* in shell scripts, for consulting or editing a config file;
* and in instructions a human can follow for editing a config file,
as a command to copy-paste and run.
A source of inspiration for the interface is the `git config` command,
which serves both of these purposes very well without knowing anything
about the semantics of Git config files -- only their general
structure.
A key property is that when editing, we seek to *preserve formatting
and comments* -- the only change to the file should be the one the
user specifically asked for. To do this we rely on the `toml_edit`
crate, which also underlies `cargo-edit`. There are a few edge cases
where `toml_edit` can rearrange an oddly-formatted file (described in
the `toml_edit` documentation); but for typical TOML files, we
maintain this property with perfect fidelity.
The command's status is **experimental**. The current interface does
not yet serve its purposes as well as it could, and **incompatible
changes** are anticipated.
## Installation
### Linux download
[Precompiled binaries are published for Linux.][releases]
The binaries are static executables, and work on any Linux
distribution.
Currently no binaries are published for other platforms.
Doing so for more platforms is a desired future step
([#22], [#21], [#5]). In the meantime, see Cargo instructions below.
[releases]: https://github.com/gnprice/toml-cli/releases
### Using Cargo
If you have Cargo (the Rust build tool) installed, you can install the
`toml` CLI by running:
```
$ cargo install toml-cli
```
To install Cargo, follow the instructions [on rust-lang.org][install-rust].
[install-rust]: https://www.rust-lang.org/learn/get-started
[#5]: https://github.com/gnprice/toml-cli/issues/5
[#21]: https://github.com/gnprice/toml-cli/issues/21
[#22]: https://github.com/gnprice/toml-cli/issues/22
## Usage
### Reading: `toml get`
To read specific data, pass a *TOML path*: a sequence of *path
segments*, each of which is either:
* `.KEY`, to index into a table or inline-table, or
* `[INDEX]`, to index into an array-of-tables or array.
Data is emitted by default as JSON:
```
$ toml get Cargo.toml bin[0]
{"name":"toml","path":"src/main.rs"}
```
When the data is a string, the `--raw`/`-r` option prints it directly,
for convenience in contexts like a shell script:
```
$ toml get Cargo.toml dependencies.serde --raw
1.0
```
If you need a more complex query, consider a tool like `jq`, with
`toml` simply transforming the file to JSON:
```
$ toml get pyoxidizer.toml . | jq '
.embedded_python_config[] | select(.build_target | not) | .raw_allocator
' -r
jemalloc
```
(The TOML path `.` is an alias for the empty path, describing the
whole file.)
### Writing (ish): `toml set`
To edit the data, pass a TOML path specifying where in the parse tree
to put it, and then the data value to place there:
```
$ cat >foo.toml <
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
SUBCOMMANDS:
get Print some data from the file
help Prints this message or the help of the given subcommand(s)
set Edit the file to set some data (currently, just print modified version)
```
### `toml get`
```
$ toml get --help
toml-get 0.2.3
Print some data from the file
Read the given TOML file, find the data within it at the given query,
and print.
If the TOML document does not have the given key, exit with a
failure status.
Output is JSON by default. With `--raw`/`-r`, if the data is a
string, print it directly. With `--output-toml`, print the data
as a fragment of TOML.
USAGE:
toml get [FLAGS]
FLAGS:
-h, --help Prints help information
--output-toml Print as a TOML fragment (default: print as JSON)
-r, --raw Print strings raw, not as JSON
-V, --version Prints version information
ARGS:
Path to the TOML file to read
Query within the TOML data (e.g. `dependencies.serde`, `foo[0].bar`)
```
### `toml set`
```
$ toml set --help
toml-set 0.2.3
Edit the file to set some data (currently, just print modified version)
USAGE:
toml set
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
ARGS:
Path to the TOML file to read
Query within the TOML data (e.g. `dependencies.serde`, `foo[0].bar`)
String value to place at the given spot (bool, array, etc. are TODO)
```