1. Command line

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.

epsilon nrepl-server
epsilon nrepl-server --port 7888
epsilon nrepl-server --bind 127.0.0.1 --port-file /tmp/epsilon.port

client -> {op "clone", id "1"}
server <- {id "1", new-session "s-1", status ["done"]}

client -> {op "eval", id "2", session "s-1", code "(+ 1 2)\n(+ 3 4)"}
server <- {id "2", session "s-1", value "3"}
server <- {id "2", session "s-1", value "7"}
server <- {id "2", session "s-1", status ["done"]}

client -> {op "load-file", id "3", session "s-1", file "(local unit 7)\n(export unit)", file-path "lib/shapes.dust", file-name "shapes.dust"}
server <- {id "3", session "s-1", status ["done"]}
client -> {op "eval", id "4", session "s-1", code ":shapes/unit"}
server <- {id "4", session "s-1", value "7"}

client -> {op "lookup", id "5", session "s-1", sym "shapes/unit"}
server <- {id "5", session "s-1", info {name "shapes/unit", type "integer"}, status ["done"]}

client -> {op "describe", id "6"}
server <- {id "6", ops {clone {}, close {}, describe {}, eval {}, interrupt {}, load-file {}, lookup {}, stdin {}}, status ["done"]}

$ echo '(/ 1 0)' > zero.dust
$ epsilon eval zero.dust
#err {<division integer zero>
      column 1
      line 1
      message "division by zero"}