grapho/docs/LUX-LIMITATIONS.md

Lux Language Limitations (grapho CLI)

This document tracks limitations encountered while developing the grapho CLI in Lux, to help improve the language.

Fixed Issues

1. Double Execution Bug (FIXED)

Severity: Critical Status: Fixed in Lux c_backend.rs

When using let result = run main() with {} to invoke the main function, the entire program was executing twice.

Root Cause: In c_backend.rs:3878-3907, the generated C code was:

1. Executing all run expressions (including run main() with {})
2. Then ALSO calling main_lux() separately because has_main was true

Fix: Added tracking of whether main was already called via a run expression, and skip the separate main_lux() call if so.

---

String Handling Issues

2. No Escape Sequences in String Literals

Severity: High Status: Confirmed

Lux does not support backslash escape sequences like \", \n, \t in string literals.

// This FAILS - backslash causes parse error
Console.print("Hello \"World\"")  // ERROR: Unexpected character: '\'

// This FAILS
Console.print("Line1\nLine2")  // ERROR: Unexpected character: '\'

Impact: Cannot include quotes in strings, cannot create multi-line strings, cannot output JSON with proper formatting.

Workaround:

• Use shell commands via Process.exec to generate quoted output
• Use String.fromChar('"') for quotes (but this had issues too)
• For JSON output, use key=value format instead

3. Dollar Sign in Strings Causes Parse Error

Severity: Medium Status: Confirmed

The $ character in strings triggers the string interpolation lexer, even inside shell command strings.

// This FAILS
execQuiet("jq -n --arg x '$foo' ...")  // ERROR: Unexpected character: '$'

Impact: Cannot use shell variable syntax or jq arguments in command strings.

Workaround: Avoid $ in strings, or construct commands differently.

4. String.fromChar Returns Int, Not String

Severity: Medium Status: Bug

String.fromChar('"') appears to return an Int instead of a String, causing C compilation errors.

let q = String.fromChar('"')  // Compiles but C code is wrong
Console.print(q + "hello")    // C error: int + string

Impact: Cannot use character literals to build strings.

Workaround: Use execQuiet("printf '%s' '\"'") to get a quote character.

---

Type System Issues

5. Record Type Definitions Don't Work as Expected

Severity: Medium Status: Needs Investigation

Defining a record type and then creating values of that type doesn't work:

type ComponentStatus = {
    name: String,
    status: HealthStatus,
    message: String,
    fix: String
}

fn checkNb(): ComponentStatus with {Process} = {
    // ...
    { name: "nb", status: Healthy, message: "ok", fix: "" }
    // ERROR: Cannot unify { name: String, ... } with ComponentStatus
}

Impact: Cannot use structured types for cleaner code organization.

Workaround: Avoid record types, use multiple return values via tuples or restructure code.

6. Int.parse Doesn't Exist or Has Wrong Signature

Severity: Low Status: Confirmed

There's no obvious way to parse a string to an integer.

let count = Int.parse(someString)  // ERROR: Unknown effect operation

Impact: Cannot convert string output from shell commands to numbers.

Workaround: Keep numbers as strings, use shell for numeric comparisons.

---

Suggestions for Lux

1. Add escape sequence support - At minimum \", \\, \n, \t
2. Fix String.fromChar to return String, not Int
3. Add raw string literals - Something like r"..." or '''...''' for shell commands
4. Fix the double execution bug in the runtime
5. Support record type literals matching their declared type
6. Add Int.parse and Float.parse for string-to-number conversion
7. Consider a heredoc syntax for multi-line strings with special characters

---

Current Workarounds in grapho CLI

1. Double output: FIXED in Lux c_backend.rs
2. JSON output: Using key=value format instead of proper JSON
3. Quotes in output: Avoided entirely or generated via shell
4. Structured types: Using individual variables instead of records
5. Numeric parsing: Keeping counts as strings throughout