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

#!/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

# 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

# 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

# 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:

# 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 for the complete learning path.

Built-ins

Luash intentionally stays minimal. The injected helpers are:

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

./luash script.luash

Interactive Shell (REPL)

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

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

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

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

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