tomli 0.5.0

A simple CLI for quering and editing TOML files
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

tomli
=====

`tomli` is a *format preserving* command-line tool for querying and editing TOML files.

This project is currently **under development** and the command-line interface
can change at any time.


Installation
------------

### Using Cargo

```
cargo install tomli
```

### Release tarball

```
wget https://github.com/blinxen/tomli/releases/download/$VERSION/tomli.tar.gz
```


Usage
-----

By default, `tomli` will read from stdin unless `--filepath` is specified.

### Query expressions

`tomli` tries to use the same syntax as `jq` for query expressions.
The following expressions are currently supported:

* Key and table identifier paths, e.g `foo.bar` or `.` (whole document)
* Array indices, e.g. `foo[0]` or `foo.bar[0][1]`

### Query TOML files

**Examples**:

Get the value of the `name` key from the `package` table:

```
tomli query -f Cargo.toml package.name
```

Get the first element of the array called `bin`:

```
tomli query -f Cargo.toml bin[0]
```

### Edit TOML files

`tomli` currently supports the following types when setting a value:

* str (String)
* int ([64-bit signed integer](https://doc.rust-lang.org/std/primitive.i64.html))
* float ([64-bit floating point](https://doc.rust-lang.org/std/primitive.f64.html))
* bool (Boolean)
* datetime ([RFC3339](https://datatracker.ietf.org/doc/html/rfc3339))

The value type can be specified with the `--type` argument.
If not type is specified, then `str` is used.

**Examples**:

Add a new key to the `package` table called `website`:

```
tomli set -f Cargo.toml package.website https://example.com
```

Set the `name` of the first element in the `bin` array to `tumli`:

```
tomli set -f Cargo.toml bin[0].name tumli
```

Add a new table called `website` to the first element of the `bin` array:

```
tomli set -f Cargo.toml bin[0].website.url https://example.com
```

Add a new array called `websites` to the table `package`:

```
tomli set -f Cargo.toml package.websites[0] https://example.com
```

Add a new array called `numbers` to the table `package` and specify the type:

```
tomli set -f Cargo.toml --type int package.numbers[0] 5
```

Use dotted key notation instead of creating a subtable:

```
tomli set -f Cargo.toml --dotted-key --type bool package.version.workspace true
```

Delete `name` in the table `package`:

```
tomli delete -f Cargo.toml package.name
```

Delete the first element in the array authors:

```
tomli delete -f Cargo.toml package.authors[0]
```

### Copying TOML items from one file to another

`tomli` supports copying a item (key/value pair, Table, Array etc.) from one file
to another.
If the destination file does not exit then `tomli` will try to create it if `--in-place` is set.
At the moment, everything is simply copied over and overwritten.

**Examples**:

Copy table `package` into another file name `another.toml`:

```
tomli copy -f Cargo.toml package another.toml new_package
```

License
-------

The source code is primarily distributed under the terms of the MIT License.
See LICENSE for details.