dtl-js/docs/DTL-repl.md

Data Transformation Language - JSON templates and data transformation

# DTL REPL (Read-Eval-Print Loop) Documentation

## Overview
The DTL REPL (`dtlr`) is an interactive shell for experimenting with and executing Data Transformation Language (DTL) code. It reads DTL commands, evaluates them, and prints the output, facilitating an interactive programming experience.

## Usage

To start the DTL REPL, use the following command:
```
dtlr [options] [inputfile]
```

### Options
- `-h`: Displays help information about the REPL and its options.
- `-p`: Prints parsed input data immediately upon starting the REPL. This option is helpful for verifying the input data before performing transformations.
- `-s`: Skips the suggestion text on startup. Use this to start the REPL without the usual suggestions or tips.
- `-V`, `--version`: Shows the current version of the DTL REPL and exits.
- `--init <init_file>`: Initializes the DTL REPL with the contents of `init_file`, which should be a JavaScript file. This is useful for setting up a predefined environment or loading common libraries.

### Input File
Optionally, you can specify an `inputfile` when starting the REPL. This file should contain JSON data that you want to load into the REPL session.

## Examples

1. **Starting with Help Option**:
   ```
   dtlr -h
   ```
   This command displays help information about the DTL REPL.

2. **Using an Input File**:
   ```
   dtlr myfile.json
   ```
   This starts the REPL and processes `myfile.json` so you can explore the data

## Example `dtlr` session:

```
$ dtlr sample.json 
DTL: Copyright (c) 2013-2023 Jay Kuri
Welcome to the DTL REPL interpreter.

To load input data use: .load filename
To edit transform in editor type: .edit
Type .help for help

Enter transform at prompt to apply transform
Based on your input data, here are some expressions to try...

$users.0.height
keys($users.0)
$users.0.registered
$users.0

input data: object size: ~319 bytes
DTL>$users.0.height
182.88
DTL>keys($users.0)
[
    "first",
    "last",
    "registered",
    "height",
    "address"
]
DTL>
```