= Ecli
Expression Calculator Interactive Tool
:authors: Celestino Amoroso
:email: celestino.amoroso@gmail.com
:docinfo: shared
:encoding: utf-8
:toc: right
:toclevels: 4
:icons: font
:icon-set: fi
:numbered:
:data-uri:
:docinfo1:
:sectlinks:
:sectanchors:
:source-highlighter: rouge
:rouge-style: manni
:stylesdir: /home/share/s3-howto/styles
:stylesheet: adoc-colony.css

// Workaround to manage double-column in back-tick quotes
:2c: ::
// Workaround to manage double-plus in back-tick quotes
:plusplus: ++
// Workaround to manage asterisk in back-tick quotes
:star: *

#Generated by Copilot#

== Overview

`ecli` (Expression Calculator Interactive Tool) is an interactive REPL (Read-Eval-Print Loop) application for evaluating expressions using the Expr package. It provides a powerful command-line interface for expression evaluation with support for multiple builtin modules, file operations, and interactive scripting.

The tool combines the expression evaluation capabilities of the Expr package with an interactive shell environment, making it ideal for:

- Interactive expression testing and prototyping
- Command history survival across sessions
- Batch expression evaluation from scripts
- Data processing and transformation
- Mathematical computations with fractions and complex operators

== Getting Started

=== Installation

To build and install `ecli`:

[source,bash]
----
cd cmd/ecli
./build.bash
----

The compiled binary will be available as `ecli` in the current directory.

=== Basic Usage

Start the interactive REPL:

[source,bash]
----
./ecli
----

You'll see the prompt `>>>` where you can enter expressions to evaluate.

=== Command Line Options

[cols="1,4", options="header"]
|===
| Option | Description

| `-e <expression>` | Evaluate an expression directly without entering REPL mode
| `-i` | Force REPL operation after processing all `-e` options
| `-b <builtin>` | Import builtin modules (comma-separated list, glob patterns, or 'all')
| `-B, --list-builtins` | List all available builtin module names
| `-m, --modules` | List all builtin modules
| `-p` | Print expressions in prefix form
| `-t` | Print expressions in tree form
| `--noout` | Disable printing of expression results
| `-h, --help` | Show help message
| `-v, --version` | Show program version
|===

== Interactive Commands

Within the REPL, you can use the following commands:

[cols="2,5", options="header"]
|===
| Command | Description

| `base [2\|8\|10\|16]` | Set the integer output base. Use without arguments to show current base
| `exit` | Exit the REPL
| `help` | Display available commands and command-line options
| `ml` | Enable/Disable multi-line input mode for complex expressions
| `mods` | List all builtin modules (with `*` marking imported ones)
| `output [on\|off\|status]` | Enable/Disable printing of expression results
| `source <file>` | Load and execute expressions from a file
| `tty` | Enable/Disable ANSI terminal output
|===

== Features

=== Expression Evaluation

`ecli` supports the full expression language provided by the Expr package, including:

- **Arithmetic Operations**: Addition, subtraction, multiplication, division, modulo
- **Bitwise Operations**: AND, OR, XOR, NOT, shift operations
- **Boolean Logic**: AND, OR, NOT operations
- **Relational Operators**: Comparison and equality operators
- **String Operations**: Concatenation and string manipulation
- **Iterators**: Range, list, and custom iterators
- **Functions**: Builtin and user-defined functions
- **Collections**: Lists, dictionaries, and linked lists
- **Fractions**: Support for fractional arithmetic

=== Builtin Modules

`ecli` provides access to various builtin modules through the `-b` option:

[cols="1,4", options="header"]
|===
| Module | Functionality

| `base` | Core expression evaluation functions
| `fmt` | String formatting and output functions
| `string` | String manipulation functions
| `math-arith` | Mathematical and arithmetic operations
| `iterator` | Iterator-related functions
| `os-file` | File I/O operations
| `import` | Module import functionality
|===

Use `-B` or `--list-builtins` to see all available modules:

[source,bash]
----
./ecli --list-builtins
----

== Examples

=== Basic Arithmetic

[source,bash]
----
>>> 2 + 3 * 4
14
>>> (2 + 3) * 4
20
----

=== String Operations

[source,bash]
----
>>> "hello" + " " + "world"
hello world
----

=== Using Iterators

[source,bash]
----
>>> it = [1, 2, 3, 4, 5] map $_ * 2
$($([#5]))
>>> $$(it)
[<
  2,
  4,
  6,
  8,
  10
>]
----

=== Evaluating from Command Line

[source,bash]
----
./ecli -e "2 + 2"
4
----

=== Loading Builtin Modules

[source,bash]
----
./ecli -b "math-arith,string"
----

=== Loading Expressions from Files

Inside the REPL:

[source]
----
>>> source "expressions.expr"
----

Or from command line:

[source,bash]
----
./ecli -e "@expressions.expr"
----

== Configuration

=== Resource Files

`ecli` supports startup resource files:

- `.ecli.rc` - Main configuration file
- `.ecli.rc.d/` - Directory for modular configuration files

These files are automatically loaded at startup if they exist in the current directory or home directory.

== Building from Source

=== Prerequisites

- Go 1.18 or later
- Make or bash shell

=== Build Steps

[source,bash]
----
cd cmd/ecli
./build.bash
----

=== Build Artifacts

The build process generates:

- `ecli` - The main executable
- `version.txt` - Version information
- Platform-specific binaries (e.g., `ecli_v1.17.0_linux_amd64`, `ecli_v1.17.0_darwin_arm64`)

== Advanced Usage

=== Multi-line Input

For complex expressions, split operations across multiple lines terminating with a backslash (`\`):

[source]
----
>>> ml
>>> result = [1, 2, 3, 4, 5] \
...   filter $_ > 2 \
...   map $_ * 2
>>> $$(result)
[<6, 8, 10>
----

=== Script Execution

Create a file `calculations.expr`:

[source]
----
x = 10
y = 20
result = x + y * 2
----

Execute it:

[source,bash]
----
./ecli -e '@calculations.expr' -e 'result'
50
----

=== Other Iterator Examples

[source]
----
>>> data = [{"name": "alice", "age": 30}, {"name": "bob", "age": 25}]

// Extract names using map iterator
>>> $$(data map ($_).name)
[<
  "alice",
  "bob"
>]

// Filter ages greater than 28
>>> $$(data filter ($_).age > 28 map ($_).name)
[<
  "alice"
>]

----

== Troubleshooting

=== Expression Parsing Errors

If you encounter parsing errors, check:

- Bracket matching and quotation marks
- Operator precedence
- Variable and function names

=== Module Loading Issues

Verify available modules:

[source,bash]
----
./ecli --list-builtins
----

=== File Not Found Errors

Ensure file paths are:

- Properly quoted in expressions
- Relative to the current working directory or absolute paths
- Readable by the current user

== Related Documentation

- link:../../../README.adoc[Expr Package Documentation]
- Expr Expression Language Syntax
- Builtin Modules Reference

== Version History

For version information and changes, see the link:version.txt[version file].

== License

Copyright (c) 2024-2026 Celestino Amoroso (celestino.amoroso@gmail.com). All rights reserved.
