luash/README.md

# Luash - Minimal Lua Shell Scripting

A lightweight Lua preprocessor that makes Lua a capable shell scripting language, combining the readability of Lua with the power of shell commands.

## Why Luash?

**Clean Syntax**: No more `$((arithmetic))`, `${parameter:-default}`, or complex quoting nightmares
**Real Programming**: Full Lua language features - tables, functions, proper data structures
**Shell Integration**: Seamless shell command execution with familiar syntax
**Minimal**: Just 4 core functions, no bloat

## Quick Start

```bash
#!/usr/bin/env luash

# Environment variables (clean syntax)
print("Hello " .. $USER .. "!")

# Variable assignment  
$MY_VAR = "some value"

# Shell commands with backticks
files = `ls -la`
current_dir = `pwd`

# Interactive commands
!git status

# The power of Lua + shell
if `test -f README.md` ~= "" then
    lines = `wc -l < README.md`
    print("README has " .. lines .. " lines")
end
```

## Core Features

### Environment Variables
```lua
# Access with clean $ syntax
print("User: " .. $USER)
print("Shell: " .. $SHELL)

# Assignment
$MY_VAR = "hello world"
print($MY_VAR)

# Inside strings are preserved literally
print("This prints: $USER (not substituted)")
```

### Shell Commands
```lua
# Command substitution with backticks
files = `ls -la`
date = `date +%Y-%m-%d`

# Variable interpolation in commands
service = "ssh"
result = `pgrep #{service} | wc -l`

host = "google.com"
ping_result = `ping -c 1 #{host} >/dev/null 2>&1 && echo "ok"`

# Interactive commands (direct output)  
!git status
!top
```

### The Power of Lua
```lua
# Real data structures
users = {"alice", "bob", "charlie"}
for i = 1, #users do
    print("User " .. i .. ": " .. users[i])
end

# Functions and logic
function backup_file(filename)
    if `test -f ` .. filename .. `` ~= "" then
        `cp ` .. filename .. ` ` .. filename .. `.bak`
        return true
    end
    return false
end
```

## 🎯 Examples

Explore organized examples that demonstrate Luash features:

```bash
# Start with the showcase for a complete overview
./luash examples/09_showcase.luash

# Learn step-by-step with numbered examples
./luash examples/01_basic_features.luash
./luash examples/02_quick_comparison.luash
./luash examples/03_interpolation.luash

# Try practical use cases
./luash examples/04_system_admin.luash
./luash examples/05_development.luash
./luash examples/06_data_processing.luash

# Or use the interactive runner
./luash run_examples.luash
```

See [examples/README.md](examples/README.md) for the complete learning path.

### Built-ins

Luash intentionally stays minimal. The injected helpers are:

```lua
-- Minimal helpers available globally
env_get(name)  -- Get environment variable (with session overrides)
env_set(name, value)  -- Set environment variable (session + subprocess export)
shell(cmd)     -- Run shell command and return trimmed stdout
run(cmd)       -- Run shell command and stream output (exit code returned)
```

Everything else is standard Lua.

## Usage

### Basic Usage
```bash
./luash script.luash
```

### Interactive Shell (REPL)
```bash
./luash -i
# or
./luash --interactive
```

The interactive shell supports:
- All luash preprocessing features
- Multiline input for functions, loops, etc.
- Command history with `.history`
- Special commands: `.help`, `.exit`, `.clear`
- Real-time expression evaluation

See [examples/08_repl_guide.luash](examples/08_repl_guide.luash) for a comprehensive guide.

Notes:
- Raw terminal mode (immediate Ctrl+L/Ctrl+C/Ctrl+D) auto-enables when attached to a TTY.
- Force enable/disable with `LUASH_RAW=1` or `LUASH_RAW=0`.

### Debug Mode
```bash
LUASH_DEBUG=1 ./luash script.luash
```

## Installation

1. Clone or download the luash repository
2. Make the script executable: `chmod +x luash`
3. Optionally, add to your PATH for system-wide access

## Syntax Examples

### Environment Variables in Strings
```lua
-- These will substitute environment variables
message = "Hello ${USER}, your shell is ${SHELL}"
path = "$HOME/Documents"

-- These will print literally (inside double quotes)
print("This will just print normally $SHELL")
print("This will substitute with the environment variable ${SHELL}")
```

### Command Interpolation
```lua
-- Variable substitution in commands
branch = "main"
result = `git checkout #{branch}`

-- Multiple variables
user = "john"
host = "server.com"
output = `ssh #{user}@#{host} 'ls -la'`
```

### File Processing Pipeline
```lua
-- Read, process, and write files
lines = file.lines("input.txt")
processed = array.map(lines, function(line)
  return str.trim(line):upper()
end)
file.write_lines("output.txt", processed)
```

## Why Luash?

- **Readable**: Lua's clean syntax is more maintainable than bash
- **Powerful**: Full programming language features (tables, functions, modules)
- **Fast**: Lua is lightweight and executes quickly
- **Portable**: Works on any system with Lua installed
- **Safe**: Better error handling than shell scripts
- **Familiar**: Shell-like utilities with programming language benefits

## Preprocessor Pipeline

Luash applies these preprocessing steps:

1. **Shebang removal (line-preserving)**: `#!/usr/bin/env luash` is removed and replaced by a blank line to preserve line numbers.
2. **Environment variable assignment**: `$VAR = value` → `env_set('VAR', value)` (outside strings only)
3. **Environment variable substitution**: `$VAR` → `env_get('VAR')` (outside strings only; `${VAR}` is not supported)
4. **Interactive commands**: lines starting with `!cmd` → `run("cmd")`
5. **Command substitution**: `` `command` `` → `shell("command")`
6. **Lua variable interpolation in commands**: inside backticks, `#{var}` is replaced with the Lua value of `var`, with proper quoting handled by the caller

## License

This project is designed to make shell scripting more pleasant and maintainable while retaining the power and familiarity of traditional shell tools.