142 lines
4.0 KiB
Markdown
142 lines
4.0 KiB
Markdown
### Lyng CLI (`lyng`)
|
|
|
|
The Lyng CLI is the reference command-line tool for the Lyng language. It lets you:
|
|
|
|
- Run Lyng scripts from files or inline strings (shebangs accepted)
|
|
- Use standard argument passing (`ARGV`) to your scripts.
|
|
- Format Lyng source files via the built-in `fmt` subcommand.
|
|
|
|
|
|
#### Building on Linux
|
|
|
|
Requirements:
|
|
- JDK 17+ (for Gradle and the JVM distribution)
|
|
- GNU zip utilities (for packaging the native executable)
|
|
- upx tool (executable in-place compression)
|
|
|
|
The repository provides convenience scripts in `bin/` for local builds and installation into `~/bin`.
|
|
|
|
Note: In this repository the scripts are named `bin/local_release` and `bin/local_jrelease`. In some environments these may be aliased as `bin/release` and `bin/jrelease`. The steps below use the actual file names present here.
|
|
|
|
|
|
##### Option A: Native linuxX64 executable (`lyng`)
|
|
|
|
1) Build the native binary:
|
|
|
|
```
|
|
./gradlew :lyng:linkReleaseExecutableLinuxX64
|
|
```
|
|
|
|
2) Install and package locally:
|
|
|
|
```
|
|
bin/local_release
|
|
```
|
|
|
|
What this does:
|
|
- Copies the built executable to `~/bin/lyng` for easy use in your shell.
|
|
- Produces `distributables/lyng-linuxX64.zip` containing the `lyng` executable.
|
|
|
|
|
|
##### Option B: JVM distribution (`jlyng` launcher)
|
|
|
|
This creates a JVM distribution with a launcher script and links it to `~/bin/jlyng`.
|
|
|
|
```
|
|
bin/local_jrelease
|
|
```
|
|
|
|
What this does:
|
|
- Runs `./gradlew :lyng:installJvmDist` to build the JVM app distribution to `lyng/build/install/lyng-jvm`.
|
|
- Copies the distribution under `~/bin/jlyng-jvm`.
|
|
- Creates a symlink `~/bin/jlyng` pointing to the launcher script.
|
|
|
|
|
|
#### Usage
|
|
|
|
Once installed, ensure `~/bin` is on your `PATH`. You can then use either the native `lyng` or the JVM `jlyng` launcher (both have the same CLI surface).
|
|
|
|
|
|
##### Running scripts
|
|
|
|
- Run a script by file name and pass arguments to `ARGV`:
|
|
|
|
```
|
|
lyng path/to/script.lyng arg1 arg2
|
|
```
|
|
|
|
- Run a script whose name starts with `-` using `--` to stop option parsing:
|
|
|
|
```
|
|
lyng -- -my-script.lyng arg1 arg2
|
|
```
|
|
|
|
- Execute inline code with `-x/--execute` and pass positional args to `ARGV`:
|
|
|
|
```
|
|
lyng -x "println(\"Hello\")" more args
|
|
```
|
|
|
|
- Print version/help:
|
|
|
|
```
|
|
lyng --version
|
|
lyng --help
|
|
```
|
|
|
|
### Use in shell scripts
|
|
|
|
Standard unix shebangs (`#!`) are supported, so you can make Lyng scripts directly executable on Unix-like systems. For example:
|
|
|
|
#!/usr/bin/env lyng
|
|
println("Hello, world!")
|
|
|
|
|
|
##### Formatting source: `fmt` subcommand
|
|
|
|
Format Lyng files with the built-in formatter.
|
|
|
|
Basic usage:
|
|
|
|
```
|
|
lyng fmt [OPTIONS] FILE...
|
|
```
|
|
|
|
Options:
|
|
- `--check` — Check-only mode. Prints file paths that would change and exits with code 2 if any changes are needed, 0 otherwise.
|
|
- `-i, --in-place` — Write formatted content back to the source files (off by default).
|
|
- `--spacing` — Apply spacing normalization.
|
|
- `--wrap`, `--wrapping` — Enable line wrapping.
|
|
|
|
Semantics and exit codes:
|
|
- Default behavior is to write formatted content to stdout. When multiple files are provided, the output is separated with `--- <path> ---` headers.
|
|
- `--check` and `--in-place` are mutually exclusive; using both results in an error and exit code 1.
|
|
- `--check` exits with 2 if any file would change, with 0 otherwise.
|
|
- Other errors (e.g., I/O issues) result in a non-zero exit code.
|
|
|
|
Examples:
|
|
|
|
```
|
|
# Print formatted content to stdout
|
|
lyng fmt src/file.lyng
|
|
|
|
# Format multiple files to stdout with headers
|
|
lyng fmt src/a.lyng src/b.lyng
|
|
|
|
# Check mode: list files that would change; exit 2 if changes are needed
|
|
lyng fmt --check src/**/*.lyng
|
|
|
|
# In-place formatting
|
|
lyng fmt -i src/**/*.lyng
|
|
|
|
# Enable spacing normalization and wrapping
|
|
lyng fmt --spacing --wrap src/file.lyng
|
|
```
|
|
|
|
|
|
#### Notes
|
|
|
|
- Both native and JVM distributions expose the same CLI interface. Use whichever best fits your environment.
|
|
- When executing scripts, all positional arguments after the script name are available in Lyng as `ARGV`.
|
|
- The interpreter recognizes shebang lines (`#!`) at the beginning of a script file and ignores them at runtime, so you can make Lyng scripts directly executable on Unix-like systems.
|