# JSONEdit

This is an editor for JSON files, that also supports YAML. 

> [!WARNING]
> This software is still very much beta. That means there will be bugs. Please
> report them, and don't go doing stupid stuff like editing your live configuration
> files in place.

## 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, duplicate
- A minimum of dependencies

![screenshot](./doc/screens/main.png)

## 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. The recommended way of doing this is with the included
`Makefile` and GNU Make:

```bash
$ git clone https://dev.noccylabs.info/noccy/jsonedit
$ cd jsonedit
$ make
$ mv jsonedit.phar ~/bin/jsonedit
```

## Using

JSONEdit is controlled using hotkeys. The essential keys are always displayed
at the bottom of the screen. Press **h** for the help, which lists all available
keys.

### 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, or run `jsonedit` and press **^O**
   to browse for a file to open.
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
- **^S** - Open settings menu

## Caveats

- **YAML comments/formatting is not preserved** - When reading YAML, comments are
  not preserved, and YAML formatting is not preserved when writing YAML.