first ecli commit
This commit is contained in:
@@ -0,0 +1,314 @@
|
||||
= 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.
|
||||
Reference in New Issue
Block a user