expr/cmd/ecli/ecli.adoc

Ecli

Table of Contents

• 1. Overview
• 2. Getting Started
  • 2.1. Installation
  • 2.2. Basic Usage
  • 2.3. Command Line Options
• 3. Interactive Commands
• 4. Features
  • 4.1. Expression Evaluation
  • 4.2. Builtin Modules
• 5. Examples
  • 5.1. Basic Arithmetic
  • 5.2. String Operations
  • 5.3. Using Iterators
  • 5.4. Evaluating from Command Line
  • 5.5. Loading Builtin Modules
  • 5.6. Loading Expressions from Files
• 6. Configuration
  • 6.1. Resource Files
• 7. Building from Source
  • 7.1. Prerequisites
  • 7.2. Build Steps
  • 7.3. Build Artifacts
• 8. Advanced Usage
  • 8.1. Multi-line Input
  • 8.2. Script Execution
  • 8.3. Chaining Operations
• 9. Troubleshooting
  • 9.1. Expression Parsing Errors
  • 9.2. Module Loading Issues
  • 9.3. File Not Found Errors
• 10. Related Documentation
• 11. Version History
• 12. License

Generated by Copilot

1. 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

• Batch expression evaluation from scripts

• Data processing and transformation

• Mathematical computations with fractions and complex operators

2. Getting Started

2.1. Installation

To build and install ecli:

cd cmd/ecli
./build.bash

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

2.2. Basic Usage

Start the interactive REPL:

./ecli

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

2.3. Command Line Options

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

3. Interactive Commands

Within the REPL, you can use the following commands:

Command	Description
help	Display available commands and command-line options
exit	Exit the REPL
multiline	Toggle multi-line input mode for complex expressions
tty	Toggle TTY mode
source <file>	Execute expressions from a file

4. Features

4.1. 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

4.2. Builtin Modules

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

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:

./ecli --list-builtins

5. Examples

5.1. Basic Arithmetic

>>> 2 + 3 * 4
14
>>> (2 + 3) * 4
20

5.2. String Operations

>>> "hello" + " " + "world"
hello world

5.3. Using Iterators

>>> [1, 2, 3, 4, 5] | map(. * 2)
[2, 4, 6, 8, 10]

5.4. Evaluating from Command Line

./ecli -e "2 + 2"
4

5.5. Loading Builtin Modules

./ecli -b "math-arith,string"

5.6. Loading Expressions from Files

Inside the REPL:

>>> source "expressions.expr"

Or from command line:

./ecli -e '@include "expressions.expr"'

6. Configuration

6.1. 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.

7. Building from Source

7.1. Prerequisites

• Go 1.18 or later

• Make or bash shell

7.2. Build Steps

cd cmd/ecli
./build.bash

7.3. 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)

8. Advanced Usage

8.1. Multi-line Input

For complex expressions, toggle multi-line mode:

>>> multiline
>>> result = [1, 2, 3, 4, 5]
...   | filter(. > 2)
...   | map(. * 2)
>>> result
[6, 8, 10]

8.2. Script Execution

Create a file calculations.expr:

x = 10
y = 20
result = x + y * 2

Execute it:

./ecli -e '@source "calculations.expr"' -e 'result'

8.3. Chaining Operations

>>> data = [{"name": "alice", "age": 30}, {"name": "bob", "age": 25}]
>>> data | map(.name)
[alice, bob]

9. Troubleshooting

9.1. Expression Parsing Errors

If you encounter parsing errors, check:

• Bracket matching and quotation marks

• Operator precedence

• Variable and function names

9.2. Module Loading Issues

Verify available modules:

./ecli --list-builtins

9.3. 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

10. Related Documentation

• Expr Package Documentation

• Expr Expression Language Syntax

• Builtin Modules Reference

11. Version History

For version information and changes, see the version file.

12. License

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