tomq

tomq is a simple tool that converts TOML to JSON and JSON to TOML.

Table of Contents

• Installation
• Examples
  • TOML to JSON
  • jq filters
  • Re-transcode to TOML
  • JSON to TOML
  • Handling null values
  • Fallback key

Installation

Nix and NixOS

Release

nix-env -f https://gitlab.com/Kores/tomq/-/archive/master/tomq-master.tar.bz2 -i tomq

Development

nix-env -f https://gitlab.com/Kores/tomq/-/archive/master/tomq-master.tar.bz2 -i tomq-bleeding

Additional packages

You may also want to install jq and bat:

nix-env -iA nixpkgs.jq nixpkgs.bat

They are not required in order to convert from TOML to JSON and vice versa, but jq is required for filtering and bat is required for the --bat option.

Shell

You can easily try tomq with jq and bat using nix-shell:

nix-shell https://gitlab.com/Kores/tomq/-/archive/shell/tomq-shell.tar.bz2

Cargo

Release

cargo install tomq

Development

cargo install --git https://gitlab.com/Kores/tomq.git

Other distros

tomq was recently released, I'm still cleaning up the code and haven't had time to package it for other distros. Once I feel comfortable, I will first submit it to nixpkgs and then start packaging it for other distros.

Examples

TOML to JSON

sh (and compatibles, like tcsh/csh/zsh/bash):

cat <<EOF | tomq
title = "tomq example"
description = "tomq is extraordinary"
EOF

fish:

printf %s\n 'title = "tomq example"' 'description = "tomq is extraordinary"' | tomq

nushell:

'
title = "tomq example"
description = "tomq is extraordinary"
' | tomq

Extra

Converts all Cargo.toml files to JSON format by streaming the contents from the files and piping to jq on demand.

fd -0 'Cargo.toml' | xargs -r0 tomq --input-files

jq filtering

requires jq binary to be installed and available in the PATH (or any default location)

Applies a jq filter and outputs the JSON format.

tomq '.package' Cargo.toml

Re-trasconding to TOML

tomq -R '.package' Cargo.toml

Converting JSON to TOML

echo -ne '{"package": {"name": "tomq"}}' | tomq -T

Converting JSON to TOML (multi-document)

Converts from JSON to TOML using multi-document extension (non TOML spec compliant).

echo -ne '{"package": {"name": "tomq"}}{"package": {"name": "tomq2"}}' | tomq -T

This is not compliant to the TOML specification, but preserves the original JSON structure.

Converting JSON to TOML (common key)

Converts from JSON to TOML using a common key (TOML spec compliant).

echo -ne '{"package": {"name": "tomq"}}{"package": {"name": "tomq2"}}' | tomq -T -U packages

Note

This is compliant to the TOML specification, but changes the JSON structure, which can be recovered using jq:

echo -ne '{"package": {"name": "tomq", "version": "1.0.0"}}{"package": {"name": "tomq2", "version": "2.0.0"}}' | tomq -T -U packages | tomq '.packages[]'

Handling null values

Turn null values into empty documents:

echo -ne '{"package": {"name": "tomq"}}{"package": {"name": "tomq2"}}{"foo": "bar"}' | jq '.package' | tomq -T -E

Note

And even with the fact that tomq moslty preserves the original JSON structure, TOML doesn't have a sense of null values, so turning the previous output back to JSON will result in an empty object:

❯ echo -ne '{"package": {"name": "tomq"}}{"package": {"name": "tomq2"}}{"foo": "bar"}' | jq '.package'

{
  "name": "tomq"
}
{
  "name": "tomq2"
}
null

❯ echo -ne '{"package": {"name": "tomq"}}{"package": {"name": "tomq2"}}{"foo": "bar"}' | jq '.package' | tomq -T -E

name = "tomq"

---
name = "tomq2"

---

❯ echo -ne '{"package": {"name": "tomq"}}{"package": {"name": "tomq2"}}{"foo": "bar"}' | jq '.package' | tomq -T -E | tomq

{
  "name": "tomq"
}
{
  "name": "tomq2"
}
{}⏎ 

Providing a fallback key

For cases where the JSON output is not an object:

❯ echo -ne '{"package": {"name": "tomq"}}{"package": {"name": "tomq2"}}' | jq '.package.name'

"tomq"
"tomq2"

❯ echo -ne '{"package": {"name": "tomq"}}{"package": {"name": "tomq2"}}' | jq '.package.name' | tomq -T -K names

names = "tomq"

---
names = "tomq2"

In case there are null values, TOML can't represent them, so you will need the -E flag:

❯ echo -ne '{"package": {"name": "tomq"}}{"package": {"name": "tomq2"}}{"foo": "bar"}' | jq '.package.name'

"tomq"
"tomq2"
null

❯ echo -ne '{"package": {"name": "tomq"}}{"package": {"name": "tomq2"}}{"foo": "bar"}' | jq '.package.name' | tomq -T -E -K names

names = "tomq"

---
names = "tomq2"

---

-U may also be handy in those cases:

❯ echo -ne '{"package": {"name": "tomq"}}{"package": {"name": "tomq2"}}' | jq '.package.name' | tomq -T -E -K value -U names

[[names]]
value = "tomq"

[[names]]
value = "tomq2"

❯ echo -ne '{"package": {"name": "tomq"}}{"package": {"name": "tomq2"}}' | jq '.package.name' | tomq -T -E -K value -U names | tomq '.names[].value'

"tomq"
"tomq2"