Add readme

This commit is contained in:
Chris 2024-10-04 12:41:37 +02:00
parent dfdd66b021
commit ab78733b9b

88
README.md Normal file
View File

@ -0,0 +1,88 @@
# JSONEdit
This is an editor for JSON files, that also supports YAML.
## Features
- Interactive terminal TUI application
- Makes use of Unicode glyphs in 16 magnificent colors!
- Handles array, objects and values
- Folding of array and object keys
- Core edit operations: insert, edit, delete
- A minimum of dependencies
- ~300KB executable PHAR
## Installing
The recommended way to install and run JSONEdit is by grabbing the PHAR from
the latest release:
- [https://dev.noccylabs.info/noccy/jsonedit/releases](https://dev.noccylabs.info/noccy/jsonedit/releases)
You can also clone the respository and use [Box](https://box-project.github.io/box/)
to build the .phar yourself:
```bash
$ git clone https://dev.noccylabs.info/noccy/jsonedit
$ cd jsonedit
$ composer install
$ box compile
$ mv bin/jsonedit.phar ~/bin/jsonedit
```
## Using
JSONEdit is controlled using hotkeys. The essential keys are always displayed
at the bottom of the screen.
### Creating a document from scratch
1. Run `jsonedit` from your shell.
2. Press **I** to insert a new key. Select "Object" in the menu. Enter "services" and press enter.
3. Select the newly created "services" key and press **I** to insert another object. Enter "nginx" and press enter.
4. Select the newly created "nginx" key. Press **i** to insert a value. Enter "image" for key and "nginx" for value.
5. Press **I** and select "Array". Enter "ports" and press enter.
6. Select the "ports" key and press **i**. Enter "80:80" and press enter.
7. Press **^W** to save the file. Enter "compose.yaml" and press enter.
8. Press **^X** to exit.
You should now have a `compose.yaml` file that spins up a completely useless
unconfigured nginx container.
### Editing a document
1. Run `jsonedit <filename>` from your shell.
2. Find the value you want to edit and press **e**.
3. Enter the value usng valid JSON value encoding, for example `"1234"` for the
string 1234, and `1234` for the integer 1234. Unparsable JSON will be used
as a verbatim string.
4. Make any additional edits, including using **i** and **I** to insert new
keys and values, and **D** to delete values.
5. Press **^W** to save the file. Enter the filename to write and press enter.
6. Press **^X** to exit.
### Folding
To fold and unfold keys, use the following keys:
- **+** - Toggle folding of current key
- **-** - Collapse all nodes but the first
- **←** - Collapse current key, or go to parent if a value or already collapsed
- **→** - Expand current key
### Customizing JSONEdit
Use the following keys to customize the appearance of JSONEdit. The settings
will be persisted for the next session if the directory `~/.config/jsonedit`
exists.
- **g** - Toggle indentation guides
- **t** - Toggle tail line guide
- **b** - Toggle icons before keys
- **c** - Toggle compact mode
## Caveats
- **YAML comments/formatting is not preserved** - When reading YAML, comments are
not preserved, and YAML formatting is not preserved when writing YAML.