315 lines
6.4 KiB
Plaintext
315 lines
6.4 KiB
Plaintext
= 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
|
|
- 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
|
|
|
|
| `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
|
|
|===
|
|
|
|
== 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]
|
|
----
|
|
>>> [1, 2, 3, 4, 5] | map(. * 2)
|
|
[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 '@include "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, toggle multi-line mode:
|
|
|
|
[source]
|
|
----
|
|
>>> multiline
|
|
>>> 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 '@source "calculations.expr"' -e 'result'
|
|
----
|
|
|
|
=== Chaining Operations
|
|
|
|
[source]
|
|
----
|
|
>>> data = [{"name": "alice", "age": 30}, {"name": "bob", "age": 25}]
|
|
>>> data | map(.name)
|
|
[alice, bob]
|
|
----
|
|
|
|
== 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.
|