Builtins Reference

// Verbose error checking:
let res = fileRead("data.json")
if !res.ok { return res.error }
let data = res.value

// With try (v0.4+):
let data = try fileRead("data.json")

// Modern error handling with try + pipe (v0.4)
// Errors propagate automatically through the chain

// Fetch and transform user data
fn getUserStats(id) {
    return try httpGet("https://api.example.com/users/" + str(id))
        |> try parseJson
        |> map(fn(u) -> table{
            name: u.name,
            email: u.email,
            score: u.score,
        })
}

// Safe file processing pipeline
fn processFile(path) {
    return try fileRead(path)
        |> try parseJson
        |> filter(fn(d) -> d.active)
        |> map(fn(d) -> d.name)
}

// Chained JSON operations
let config = try fileRead("config.json")
    |> try parseJson
    |> filter(fn(c) -> c.enabled)
    |> map(fn(c) -> c.settings)

// print() - outputs with trailing newline (v0.4.5, default)
// printn() - outputs without trailing newline (v0.4.5)
print("Hello!")
printn("No newline")
print("Next line")

// input() - reads one line from user (no prompt)
let name = input()
print("You typed: " + name)

// prompt(message) - shows message AND reads input
let age = prompt("Enter your age: ")
print("You are " + age)

// confirm() - yes/no question, returns true/false
if confirm("Delete all files?") {
    print("Deleted!")
}

// select() - numbered menu, returns chosen value
let choice = select("Pick a color:", ["red", "green", "blue"])
print("You chose: " + choice)

	// clear() - clear the terminal
	clear()

if confirm("Delete this file?") {
    print("Deleting...")
    try fileDelete("data.txt")
} else {
    print("Cancelled")
}

let choice = select("Pick a color:", ["red", "green", "blue"])

if choice == "red" {
    print(colorRed("You picked red"))
} else if choice == "green" {
    print(colorGreen("You picked green"))
}

print(colorRed("Error"))
print(colorGreen("Success"))
print(colorBold(colorYellow("Warning")))

// File functions return {ok, value, error}
// Use try to unwrap and propagate errors (v0.4+)

let content = try fileRead("config.json")
print("File has ${len(content)} characters")

let written = try fileWrite("output.txt", "Hello, World!")
print("Written: ${written}")

try fileAppend("log.txt", "New log entry\n")

if fileExists("data.json") {
    let data = try fileRead("data.json")
    print(data)
}

try fileMkdir("backup/2024/january")

let files = try fileReadDir(".")
for item in files {
    print("Found: " + item)
}

let globRes = try fileGlob("*.lgs")
for script in globRes {
    print("Script: " + script)
}

let s = "  Hello, World!  "

print(upper(s))
print(lower(s))
print(trim(s))

print(replace("banana", "a", "o"))
print(str(contains("hello", "ell")))
print(str(startsWith("hello", "he")))
print(str(endsWith("hello", "lo")))

let words = split("a,b,c,d", ",")
print(join(words, "-"))

print(repeat("ha", 3))
print(slice("hello", 1, 4))
print(format("Name: {}, Age: {}", "Bob", 25))

let n = int("42")
let f = float("3.14")

let s1 = str(42)
let s2 = str(3.14)

let b1 = toBool(true)
let b2 = toBool(false)

print(type(42))
print(type("hello"))
print(type([1,2,3]))

let nums = [1, 2, 3, 4, 5]

nums = push(nums, 6)
nums = prepend(nums, 0)

print(first(nums))
print(last(nums))

let popped = pop(nums)
print(str(popped))

let rest = tail(nums)

let reversed = reverse([1, 2, 3])
let sorted = sort([3, 1, 4, 1, 5])

print(str(contains([1, 2, 3], 2)))

// range() for numeric iteration (v0.4.2)
for i in range(0, 10) {
    print(i)
}

// With step
for i in range(0, 20, 2) {
    print(i)  // 0, 2, 4, 6, ...
}

// Countdown
for i in range(5, 0, -1) {
    print(i)  // 5, 4, 3, 2
}

let user = table{
    name: "Alice",
    age: 30,
    active: true,
}

print(user.name)

print(str(has(user, "email")))

let k = keys(user)
let v = values(user)

let updated = tableDelete(user, "age")

let extra = table{ role: "admin", age: 31 }
let merged = merge(user, extra)

// parseJson, toJson, prettyJson return {ok, value, error}
// Use try for clean error handling (v0.4+)

let data = try parseJson("{\"name\": \"Bob\", \"scores\": [95, 87, 92]}")
print(data["name"])
print(str(data["scores"][0]))

let obj = table{ "status": "ok", "count": 42 }
let jsonStr = try toJson(obj)
print(jsonStr)

let parsed = try parseJson("{\"user\": {\"name\": \"Alice\"}}")
print(try prettyJson(parsed))

	print(str(mathAbs(-42)))
print(str(mathPow(2, 10)))
print(str(mathRandomInt(1, 6)))

// Running: lgs script.lgs --name "Alice" --verbose
let cliArgs = args()

print(len(cliArgs))  // 2 (not 4)
print(cliArgs[0])    // "--name"
print(cliArgs[1])    // "Alice"
// Binary and script paths are already removed

// Use with flags
if contains(cliArgs, "--verbose") {
    print("Verbose mode enabled")
}

// run() - executes a command directly (no shell)
// Use try for clean error handling (v0.4+)

let result = try run("ls", "-la")
print(result)

// With arguments
let gitResult = try run("git", "status")
print(gitResult)

let echoResult = try run("echo", "hello")
print(echoResult)

// shell() - executes command through shell (sh -c)
// Use try for clean error handling (v0.4+)

let dateResult = try shell("date")
print(dateResult)

// Shell features work!
let psResult = try shell("ps aux | grep node")
print(psResult)

// Variables
let pathResult = try shell("echo $HOME")
print(pathResult)

// Multiple commands
let multiResult = try shell("echo 'First' && echo 'Second'")
print(multiResult)

print(str(timeNow()))
print(str(timeMs()))

print(timeStr())
print(dateStr())
print(dateTimeStr())

let ts = timeNow()
print(timeFormat(ts, "January 2, 2006"))
print(timeFormat(ts, "02/01/2006"))

// HTTP functions return {ok, value: {body, status}, error}
// body is a string, status is an integer HTTP status code

// All HTTP functions accept: (url, body?, headers?)
// body is optional for GET/DELETE; headers always optional

// GET - fetch data
let body = try httpGet("https://api.example.com/users")
print(body)

// GET with headers (authentication, custom headers)
let headers = table{
    "Authorization": "Bearer " + env("API_TOKEN"),
    "Content-Type": "application/json"
}
let data = try httpGet("https://api.example.com/private", headers)

// POST - create resource (url, body, headers?)
let payload = try toJson(table{ name: "Alice", email: "alice@example.com" })
let res = try httpPost("https://api.example.com/users", payload)
print("Created! Status: " + str(res.value.status))

// POST with all three args (url, body, headers)
let authHeaders = table{ "Authorization": "Bearer " + env("API_TOKEN") }
let createRes = try httpPost("https://api.example.com/users", payload, authHeaders)

// Tables are auto-serialized to JSON — no need for toJson() (v0.4.6)
let tablePayload = table{ name: "Alice", email: "alice@example.com" }
let autoRes = try httpPost("https://api.example.com/users", tablePayload)

// PUT - replace resource entirely (url, body, headers?)
let update = try toJson(table{ name: "Alice", id: 1 })
let putRes = try httpPut("https://api.example.com/users/1", update)

// PUT with headers
let putAuth = table{ "Authorization": "Bearer " + env("API_TOKEN") }
let putRes2 = try httpPut("https://api.example.com/users/1", update, putAuth)

// PATCH - partial update (url, body, headers?)
let patch = try toJson(table{ email: "newemail@example.com" })
let patchRes = try httpPatch("https://api.example.com/users/1", patch)

// DELETE - remove resource (url, headers?)
let delRes = try httpDelete("https://api.example.com/users/1")
print("Deleted! Status: " + str(delRes.value.status))

// DELETE with headers
let delAuth = table{ "Authorization": "Bearer " + env("API_TOKEN") }
let delRes2 = try httpDelete("https://api.example.com/users/1", delAuth)

// Handle non-2xx responses (status is included in response)
let res = httpGet("https://api.example.com/not-found")
if !res.ok {
    print("Error: " + res.error)
} else if res.value.status >= 400 {
    print("HTTP error: " + str(res.value.status))
} else {
    print("Success: " + res.value.body)
}

// Pipes - fetch, parse, transform
let users = try httpGet("https://api.example.com/users")
    |> try parseJson
    |> filter(fn(u) -> u.active)
    |> map(fn(u) -> u.name)

// reMatch - returns true/false if pattern matches
print(reMatch(`\d+`, "hello 123"))     // true
print(reMatch(`\d+`, "hello world"))  // false

// reFind - find first match, returns string or null
print(reFind(`\d+`, "there are 3 cats"))    // "3"
print(reFind(`\d+`, "no numbers here"))    // null

// reFindAll - find all matches, returns array
print(reFindAll(`\d+`, "3 cats and 12 dogs"))  // ["3", "12"]

// reReplace - replace all matches
print(reReplace(`\d+`, "I have 3 cats", "X"))  // "I have X cats"

// reSplit - split by pattern
print(reSplit(`\s+`, "split   this   string"))  // ["split", "this", "string"]

// reGroups - extract capture groups
let email = "uthman@gmail.com"
let parts = reGroups(`(\w+)@(\w+)\.(\w+)`, email)
print(parts)  // ["uthman", "gmail", "com"]