Epsilon

convert supports .json, .edn, .tron, .ron, and .dust. The input and output extensions select the formats. Using the same extension for both files writes a normalized representation. The output file is written only after the input has been parsed and converted successfully.

Use - for standard input or standard output. Specify standard input's format with --from FORMAT and standard output's format with --to FORMAT. The format names are json, edn, tron, ron, and dust. These options can also override a file extension. Use --comment-roundtrip to preserve DUST and RON comment placements in JSON's $comment strings and interpret those strings when converting back. Without this option JSON $comment strings remain literal.

epsilon convert input.dust output.json
epsilon convert input.dust - --to json
cat input.edn | epsilon convert - output.dust --from edn
cat input.dust | epsilon convert - - --from dust --to json

--from and --to also take files. --from is then a path or a glob, and --to a path, or a directory followed by *.EXT or **/*.EXT. Each matching file is converted to the path it maps to: the --to directory, then, with **, the file's directories below the --from directory, then its name with the --to extension. Formats come from the extensions. Missing directories are created, an output that would not change is not rewritten, and two inputs that map to one output are an error before anything is written. A single --from file with a --to format name goes to standard output.

epsilon convert --from order.ron --to order.dust
epsilon convert --from 'data/**/*.json' --to 'out/**/*.dust'   # data/x/b.json -> out/x/b.dust
epsilon convert --from 'data/*.json' --to 'out/*.ron'          # top level of data only

In a glob, *, ?, and [...] match within one name and a ** name matches any number of names, none included. ** does not enter hidden directories, and hidden files match only a name pattern that starts with ..

Run epsilon convert -h for command help and examples.

DUST and RON output sorts map keys and the tags in a tag group, which gives the canonical form. --no-sort keeps both in source order instead. Either way a map's tag group comes first. A source that does not parse gives a #err diagnostic with its line and column on standard error and exit status 1.

fmt is convert from each file to its own format, dust or ron, with --no-sort, and its output ends with a newline, as editors save files: DUST output already does, and fmt adds one to RON output, which convert writes without one. A PATH is a file, a directory, or - for standard input (with --from dust or --from ron); with no PATH and no --from files, it is the current directory. A directory is searched recursively for files that match an --include glob (default *.dust and *.ron) and no --exclude glob. Hidden files and directories, build, and vendor are always skipped, and an excluded directory is not entered. A glob without / matches a name at any depth; one with / matches the path below the directory. --from also takes files, as for convert.

One file prints its result. --write (-w) rewrites each file whose result differs: it writes a temporary file in the same directory, gives it the file's permissions, and renames it over the file, so the file is never half written. Through a symbolic link it rewrites the target and keeps the link. --check writes nothing; it names each file formatting would change on standard error. Several files need --write or --check. A file that does not parse gives its path and a #err diagnostic on standard error, and the other files are still formatted. The exit status is 1 when any file failed or would change, and 2 for an invalid combination of options.

epsilon fmt order.dust
epsilon fmt --write order.dust
epsilon fmt --check                                 # the current directory
epsilon fmt --write src --exclude fixtures
epsilon fmt --check . --include '*.dust'
epsilon fmt --write --from 'src/**/*.dust'
cat order.dust | epsilon fmt - --from dust

For example, with tags and keys out of order, and with a root list:

EDN lists and sets become arrays, while keywords, symbols, and characters become text. Map keys become strings. Numeric ratios and decimal values become floating point numbers; integers outside the supported range are rejected. EDN #inst values are represented by #utc, and #uuid values become strings. Other EDN tags retain their tag and value as DUST tagged elements. DUST tags are written as EDN tagged elements when their names can be read as EDN tags; otherwise they are represented as maps. These mappings do not preserve all original EDN types. Only the first EDN form is read; an empty input reads as nil.

TRON encodes JSON-compatible values as a binary document. Floating-point values retain their numeric kind, including integral floats such as 1.0. This can differ from encoders that normalize integral floats to integers. A #b64 tagged value with valid base64 is represented as binary data and decoded back to that tag.

task repl builds the engine and starts the REPL from the repository.

Each REPL and each nREPL session may use 1 GiB of runtime memory, because it keeps its top-level locals and namespaces between evaluations; epsilon eval may use 64 MiB. An evaluation that needs more fails, and the garbage it leaves is collected before the next one. !reset returns the REPL to a fresh runtime.

Converting a DUST document to DUST writes its canonical spelling: the same value always formats to the same bytes. For example, epsilon convert input.dust output.dust writes canonical DUST to output.dust. epsilon fmt keeps map keys in source order, so its output is canonical only when the keys are sorted. Canonical output is what Epsilon prints, what conformance fixtures store, and what hash digests, so two programs that format alike are the same program.

The rules are those of RON and DUST. In brief, the formatter:

• sorts map keys and collects boolean members into a tag group;
• uses the short forms .name, :name, (f x), `x, and \x for locals, constants, invocations, quotes, and muted forms;
• drops the brackets of a root list with two or more forms, writing one form per line;
• normalizes #utc and #dur payloads, so #dur PT90M becomes #dur PT1H30M.

The REPL reads an entry, evaluates each of its top-level forms on its own, and prints each result as one canonical DUST form. A list keeps its brackets, so [1 2 (+ 3 4)] prints [1 2 7]. It keeps history and highlights input as you type. A form that spans lines continues until its brackets balance.

> (+ 1 2)
   compile 77.9µs · 143.1KiB arena · key 5d902e22 · 1/64 cached
3  eval 57.9µs cpu · 130.5KiB peak · +4.6KiB net · 323.5KiB live
> (+ 1 2)
3  eval 17.3µs cpu · 128.5KiB peak · +2.5KiB net · 326.0KiB live

A local form defines a top-level local that later entries read:

> (local rate 3)
   compile 47.9µs · 129.0KiB arena · key 64c24dfd · 2/64 cached
.rate  eval 10.6µs cpu · 5.7KiB peak · +3.3KiB net · 580.8KiB live
> [.rate (* .rate 2)]
   compile 81.8µs · 130.3KiB arena · key eb0abee0 · 3/64 cached
[3 6]  eval 8.1µs cpu · 8.4KiB peak · +5.5KiB net · 586.3KiB live

Every evaluation reports its cost, dimmed, to the right of the result. A form that had to be compiled first reports the compile on its own line above.