# Remarshal
Convert between CBOR, JSON, MessagePack, TOML, and YAML.
When installed,
Remarshal provides the command-line command `remarshal`
as well as the short commands
{cbor,json,msgpack,toml,yaml}2{cbor,json,msgpack,toml,yaml}.
You can use these commands
to convert between formats,
reformat,
and detect errors.
## Known limitations and quirks
There are limitations
on what data can be converted
between what formats.
- CBOR, MessagePack, and YAML with binary fields cannot be converted
to JSON or TOML.
Binary fields can be converted between CBOR, MessagePack, and YAML.
- The following date-time value conversions are possible:
- Local dates are converted between
[CBOR RFC 8943](https://www.rfc-editor.org/rfc/rfc8943.html)
dates (tag 1004),
[TOML Local Dates](https://toml.io/en/v1.0.0#local-date),
and
[YAML timestamps](https://yaml.org/type/timetamp.html)
without a time or a time zone.
- Local date-time is converted between
[TOML Local Date-Time](https://toml.io/en/v1.0.0#local-date-time)
and
[YAML timestamps](https://yaml.org/type/timestamp.html)
without a time zone.
- Date-time with a time zone
is converted between
[CBOR standard date-time strings](https://www.rfc-editor.org/rfc/rfc8949.html#stringdatetimesect)
(tag 0),
the
[MessagePack Timestamp extension type](https://github.com/msgpack/msgpack/blob/master/spec.md#timestamp-extension-type),
[TOML Offset Date-Times](https://toml.io/en/v1.0.0#offset-date-time),
and
[YAML timestamps](https://yaml.org/type/timestamp.html) with a time zone.
- [TOML Local Time](https://toml.io/en/v1.0.0#local-time)
cannot be converted to a date-time in another format.
- All date-time types can be converted to JSON
with the `-k`/`--stringify` option,
which turns them into strings.
- Contrary to the
[YAML timestamp draft spec](https://yaml.org/type/timestamp.html),
Remarshal converts YAML dates to TOML Local Dates instead of TOML Offset Dates
in the UTC time zone.
It converts TOML Local Dates to YAML dates.
## Installation
You will need Python 3.8 or later.
Earlier versions of Python 3 will not work.
The recommended way to run Remarshal is to install the latest release
[from PyPI](https://pypi.org/project/remarshal/)
with
[pipx](https://github.com/pypa/pipx).
```sh
pipx install remarshal
```
Regular installation is not mandatory.
The command
```sh
pipx run remarshal [arg ...]
```
will download Remarshal and run it from a temporary location.
It will cache the downloaded version for up to 14 days.
Remarshal will not be automatically upgraded during this period.
You can also install Remarshal using pip.
```sh
python3 -m pip install --user remarshal
```
It is possible to install the current development version of Remarshal.
Prefer releases unless you have a reason to run the development version.
```sh
pipx install git+https://github.com/remarshal-project/remarshal
```
## Usage
```
usage: remarshal [-h] [-v] [-i ] [--if {cbor,json,msgpack,toml,yaml}]
[--json-indent ] [-k] [--max-values ] [-o