The Que Language Tutorial

println("Hello, Que!")

let name = "World"
println("Hello,", name)

// This is a comment
println("hi")   // inline comment

let greeting = "Hello"      // immutable — cannot be reassigned
mut counter = 0             // mutable — can be reassigned

counter += 1
counter += 1
println(counter)            // 2

let x = 1
x = 2   // runtime error: cannot assign to immutable variable

let x = 42          // Int
let pi = 3.14       // Float
let hex = 0xFF      // 255
let octal = 0o755   // 493 (file permissions!)
let yes = true      // Bool
let nothing = null  // Null

println(2 ** 10)       // 1024
println(17 % 5)        // 2
println((2 + 3) * 4)   // 20

println(!false && true)   // true
println(0xFF & 0x0F)      // 15

let n = int("42")      // 42
let f = float(42)      // 42.0
let s = str(3.14)      // "3.14"
let b = bool(1)        // true

// Int methods
let x = 42
println(x.to_float())     // 42.0
println(x.to_string())    // "42"
println((-5).abs())       // 5

// Float methods
let f = 3.7
println(f.to_int())       // 3  (truncates)
println(f.to_string())    // "3.7"
println((-2.5).abs())     // 2.5
println(f.floor())        // 3.0
println(f.ceil())         // 4.0
println(f.round())        // 4.0

// Bool methods
println(true.to_int())    // 1
println(false.to_int())   // 0
println(true.to_string()) // "true"

fn classify(n) {
    if n > 100 { "large" }
    else if n > 10 { "medium" }
    else { "small" }
}

println(classify(5))     // small
println(classify(50))    // medium
println(classify(500))   // large

for word in ["hello", "beautiful", "world"] {
    println(word.to_upper())
}

mut sum = 0
for i in 1..=10 {
    sum += i
}
println(sum)   // 55

mut n = 5
while n > 0 {
    println(n)
    n -= 1
}

mut i = 0
let result = loop {
    i += 1
    if i * i > 50 {
        break i
    }
}
println(result)   // 8

let x = {
    let a = 10
    let b = 20
    a + b
}
println(x)   // 30

let x = 1
{
    let x = 2
    println(x)   // 2
}
println(x)       // 1

let name = "Que"
let version = 1
println("Welcome to ${name} v${version}!")
// Welcome to Que v1!

let path = r"C:\Users\alice\Documents"   // backslashes are literal
let regex_src = r"\d{3}-\d{4}"           // no need to double-escape
let tmpl = r"${not_interpolated}"        // $ has no special meaning

let html = r#"<div class="main">hello</div>"#
let nested = r##"contains "# inside"##

let sql = """
    SELECT *
    FROM users
    WHERE active = true
"""

"  Hello, World!  "
    .trim()
    .to_lower()
    .replace("world", "que")
// "hello, que!"

let csv = "alice,bob,charlie"
let names = csv.split(",")
let upper_names = names.map(|n| n.to_upper())
println(upper_names.join(" | "))
// ALICE | BOB | CHARLIE

let numbers = [1, 2, 3, 4, 5]
let mixed = [1, "two", true, null]

let items = [10, 20, 30]
println(items[0])     // 10
println(items[2])     // 30

let a = [1, 2, 3]
let b = [4, 5, 6]
let combined = [...a, 0, ...b]
println(combined)   // [1, 2, 3, 0, 4, 5, 6]

let nums = [3, 1, 4, 1, 5, 9, 2, 6]
println(nums.len())             // 8
println(nums.first())           // 3
println(nums.last())            // 6
println(nums.sort())            // [1, 1, 2, 3, 4, 5, 6, 9]
println(nums.reverse())         // [6, 2, 9, 5, 1, 4, 1, 3]
println(nums.contains(5))       // true
println(nums.is_empty())        // false

let numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

// Keep only even numbers, square them, sum the result
let result = numbers
    .filter(|x| x % 2 == 0)
    .map(|x| x * x)
    .fold(0, |acc, x| acc + x)

println(result)   // 220

let items = [10, 20, 30, 40]

// find returns the first match, or null
println(items.find(|x| x > 25))     // 30

// any / all return booleans
println(items.any(|x| x > 100))     // false
println(items.all(|x| x > 5))       // true

let config = {
    "host": "localhost",
    "port": 8080,
    "debug": true,
}

println(config.host)       // localhost
println(config["debug"])   // true

println(config["hsot"])    // error: key 'hsot' not found in map
println([1, 2, 3][5])      // error: index 5 out of bounds (len 3)

println(config.get("hsot") ?? "localhost")   // localhost
println(config.get("hsot", "localhost"))     // localhost
println([1, 2, 3].get(5, 0))                 // 0

let defaults = { "timeout": 30, "retries": 3 }
let config = { ...defaults, "timeout": 60 }
println(config.timeout)    // 60
println(config.retries)    // 3

mut config = { server: { host: "localhost", port: 8080 } }
config.server.port = 9090
println(config.server.port)    // 9090

// Works with mixed field/index chains too
mut data = { items: [{ name: "a" }, { name: "b" }] }
data.items[1].name = "updated"
println(data.items[1].name)    // updated

// Compound assignment works through nested paths
mut counters = { stats: { hits: 10 } }
counters.stats.hits += 5
println(counters.stats.hits)   // 15

let scores = { "alice": 95, "bob": 87, "charlie": 92 }

mut total = 0
for (name, score) in scores {
    total += score
}
println(total)   // 274

let point = (10, 20)
println(point[0])    // 10
println(point[1])    // 20

let numbers = #{1, 2, 3}
let deduped = #{1, 2, 2, 3, 3, 3}
println(deduped)              // #{1, 2, 3}

let empty = #{}               // the empty set
let single = #{42}            // one element — no trailing comma needed

let a = #{1, 2, 3}
let b = #{3, 4, 5}

a.union(b)                   // #{1, 2, 3, 4, 5}
a.intersection(b)            // #{3}
a.difference(b)              // #{1, 2}
a.symmetric_difference(b)    // #{1, 2, 4, 5}

a + b    // union:                #{1, 2, 3, 4, 5}
a - b    // difference:           #{1, 2}
a & b    // intersection:         #{3}
a ^ b    // symmetric difference: #{1, 2, 4, 5}

let list = [1, 2, 3]
println(list.to_tuple())  // (1, 2, 3)
println(list.to_set())    // #{1, 2, 3}

let set = #{1, 2, 3}
println(set.to_list())    // [1, 2, 3]

let tuple = (1, 2, 3)
println(tuple.to_list())  // [1, 2, 3]

// List of pairs to Map
let pairs = [["a", 1], ["b", 2]]
println(pairs.to_map())   // {"a": 1, "b": 2}

// Map to list of [key, value] pairs
let map = {"x": 10, "y": 20}
println(map.to_list())    // [["x", 10], ["y", 20]]

fn greet(name) {
    "Hello, " + name + "!"
}

println(greet("Que"))   // Hello, Que!

fn binary_search(arr, target) {
    mut low = 0
    mut high = arr.len() - 1
    while low <= high {
        let mid = (low + high) / 2
        if arr[mid] == target {
            return Ok(mid)
        } else if arr[mid] < target {
            low = mid + 1
        } else {
            high = mid - 1
        }
    }
    Err("not found")
}

fn http_get(url, timeout = 30, retries = 3) {
    println("${url} timeout=${timeout} retries=${retries}")
}

http_get("https://example.com")           // timeout=30, retries=3
http_get("https://example.com", 10)       // timeout=10, retries=3
http_get("https://example.com", 10, 5)    // timeout=10, retries=5

fn deploy(target, dryRun = false) {
    if dryRun { "dry: " + target }
    else { "real: " + target }
}

println(deploy("prod", dryRun: true))   // dry: prod

fn add(a, b, c) {
    a + b + c
}

// Positional first, then named in any order
println(add(1, c: 30, b: 20))   // 51

fn factorial(n) {
    if n <= 1 { 1 }
    else { n * factorial(n - 1) }
}

println(factorial(10))   // 3628800

fn compose(f, g) {
    |x| f(g(x))
}

let double = |x| x * 2
let inc = |x| x + 1
let double_then_inc = compose(inc, double)
println(double_then_inc(5))   // 11

fn add(a, b) { a + b }

let add5 = add(5, _)
println(add5(3))    // 8

fn greet(greeting, name) { greeting + " " + name }
let hello = greet("Hello", _)
println(hello("World"))   // Hello World

let double = |x| x * 2
let add = |a, b| a + b

let process = |x| {
    let squared = x * x
    let doubled = squared * 2
    doubled
}

let get_value = || 42
println(get_value())   // 42

let scale = |x: Int, factor: Int = 2| x * factor
println(scale(5))      // 10
println(scale(5, 3))   // 15

let mask = |x, m = (0xF0 | 0x0F)| x & m

mut count = 0
let inc = || { count = count + 1 }
inc()
inc()
println(count)   // 2

fn make_counter() {
    mut n = 0
    return || {
        n = n + 1
        return n
    }
}

let a = make_counter()
let b = make_counter()
println(a())   // 1
println(a())   // 2
println(b())   // 1  — independent state

fn double(x) { x * 2 }
fn square(x) { x * x }
fn negate(x) { -x }

let result = 3 |> double |> square |> negate
println(result)   // -36

fn add(a, b) { a + b }
fn mul(a, b) { a * b }

let result = 5 |> add(3) |> mul(2)
println(result)   // 16  —  (5+3)*2

let result = [1, 2, 3, 4, 5]
    |> |list| list.filter(|x| x % 2 == 1)
    |> |list| list.map(|x| x * x)
    |> |list| list.fold(0, |a, b| a + b)

println(result)   // 35  —  1 + 9 + 25

// List destructuring
let [first, second, ...rest] = [1, 2, 3, 4, 5]
println(first)    // 1
println(second)   // 2
println(rest)     // [3, 4, 5]

// Map destructuring
let { name, ...rest } = { name: "que", version: "1.0", license: "MIT" }
println(name)                // que
println(rest.keys().len())   // 2

// Tuple destructuring
let (x, y) = (10, 20)
println(x + y)   // 30

fn describe(x) {
    match x {
        0 => "zero",
        1 => "one",
        _ => "other",
    }
}

fn classify_temp(celsius) {
    match celsius {
        c if c < 0 => "freezing",
        c if c < 20 => "cold",
        c if c < 30 => "warm",
        c => "hot (" + str(c) + ")",
    }
}

fn is_weekend(day) {
    match day {
        "Saturday" | "Sunday" => true,
        _ => false,
    }
}

fn describe_list(list) {
    match list {
        [] => "empty",
        [x] => "single: " + str(x),
        [x, ...rest] => "head: " + str(x) + ", rest len: " + str(rest.len()),
    }
}

println(describe_list([]))           // empty
println(describe_list([42]))         // single: 42
println(describe_list([1, 2, 3]))    // head: 1, rest len: 2

let point = { "x": 3, "y": 4 }
let sum = match point {
    { x, y } => x + y,
}
println(sum)   // 7

let config = { name: "que", version: "1.0", author: "test", license: "MIT" }
match config {
    { name, ...rest } => println("${name}: ${rest.keys().len()} more fields"),
}

fn safe_divide(a, b) {
    if b == 0 { Err("division by zero") }
    else { Ok(a / b) }
}

match safe_divide(10, 2) {
    Ok(val) => println("Result: " + str(val)),
    Err(msg) => println("Error: " + msg),
}

let file = "main.rs"
let lang = match file {
    glob("*.rs") => "Rust",
    glob("*.py") => "Python",
    glob("*.js") => "JavaScript",
    _ => "Unknown",
}
println(lang)   // Rust

match [1, 2, 3] {
    list @ [first, ...rest] => {
        println(first)         // 1
        println(rest)          // [2, 3]
        println(list.len())    // 3
    },
    _ => println("no match"),
}

let result = Ok(42)
if let Ok(val) = result {
    println("got: " + str(val))   // got: 42
}

struct Circle { radius: Float }
struct Rect { width: Float, height: Float }

fn area(shape) {
    match shape {
        Circle { radius } => 3.14159 * radius * radius,
        Rect { width, height } => width * height,
        _ => 0.0,
    }
}

println(area(Circle { radius: 5.0 }))             // 78.53975
println(area(Rect { width: 4.0, height: 3.0 }))   // 12.0

struct Point {
    x: Float,
    y: Float,
}

let p = Point { x: 3.0, y: 4.0 }
println(p.x)          // 3.0
println(typeof(p))    // Point
println(p)            // Point { x: 3.0, y: 4.0 }

struct Config {
    host: String = "localhost",
    port: Int = 8080,
    debug: Bool = false,
}

let c = Config { port: 3000 }
println(c.host)    // localhost
println(c.port)    // 3000

let x = 10.0
let y = 20.0
let p = Point { x, y }    // same as Point { x: x, y: y }

mut p = Point { x: 1.0, y: 2.0 }
p.x = 99.0
println(p.x)    // 99.0

impl Point {
    // Instance method — first parameter is `self`
    fn length(self) {
        (self.x * self.x + self.y * self.y) ** 0.5
    }

    fn translate(self, dx, dy) {
        Point { x: self.x + dx, y: self.y + dy }
    }

    fn scale(self, factor) {
        Point { x: self.x * factor, y: self.y * factor }
    }

    // Static method — no `self` parameter
    fn origin() {
        Point { x: 0.0, y: 0.0 }
    }
}

let p = Point { x: 3.0, y: 4.0 }
println(p.length())        // 5.0

// Method chaining
let p2 = Point.origin().translate(1.0, 1.0).scale(3.0)
println(p2.x)              // 3.0

impl Point {
    fn new(x, y) -> Point { Point { x, y } }
    fn length(self) { (self.x * self.x + self.y * self.y) ** 0.5 }
}

let p = Point(3.0, 4.0)    // same as Point.new(3.0, 4.0)
println(p.length())         // 5.0

// Chains naturally
println(Point(1.0, 0.0).length())    // 1.0

struct Counter { count: Int = 0 }

impl Counter {
    fn increment(self) { Counter { count: self.count + 1 } }
    fn value(self) { self.count }
}

mut c = Counter {}
c = c.increment()
c = c.increment()
println(c.value())    // 2

trait Describable {
    fn describe(self) -> String
}

struct Dog { name: String, breed: String }
struct Cat { name: String, indoor: Bool }

impl Describable for Dog {
    fn describe(self) {
        "${self.name} is a ${self.breed}"
    }
}

impl Describable for Cat {
    fn describe(self) {
        let place = if self.indoor { "indoor" } else { "outdoor" }
        "${self.name} is an ${place} cat"
    }
}

let d = Dog { name: "Rex", breed: "Labrador" }
let c = Cat { name: "Whiskers", indoor: true }
println(d.describe())    // Rex is a Labrador
println(c.describe())    // Whiskers is an indoor cat

trait Greetable {
    fn greet(self) -> String {
        "Hello, I am " + self.name
    }
}

struct Robot { name: String }
impl Greetable for Robot {}    // uses the default

struct Person { name: String, formal: Bool = false }
impl Greetable for Person {
    fn greet(self) {
        if self.formal { "Good day. My name is " + self.name }
        else { "Hey, I'm " + self.name }
    }
}

struct Color { r: Int, g: Int, b: Int }

impl Display for Color {
    fn to_string(self) -> String {
        "rgb(${self.r}, ${self.g}, ${self.b})"
    }
}

let c = Color { r: 255, g: 128, b: 0 }
println(c)              // rgb(255, 128, 0)
println("Fill: ${c}")   // Fill: rgb(255, 128, 0)

struct Version { major: Int, minor: Int, patch: Int }

impl Eq for Version {
    fn equals(self, other) -> Bool {
        self.major == other.major &&
        self.minor == other.minor &&
        self.patch == other.patch
    }
}

let v1 = Version { major: 1, minor: 2, patch: 0 }
let v2 = Version { major: 1, minor: 2, patch: 0 }
println(v1 == v2)    // true
println(v1 != v2)    // false

struct Version { major: Int, minor: Int, patch: Int }

impl Ord for Version {
    fn compare(self, other) -> Int {
        if self.major != other.major { return self.major - other.major }
        if self.minor != other.minor { return self.minor - other.minor }
        self.patch - other.patch
    }
}

let v1 = Version { major: 1, minor: 0, patch: 0 }
let v2 = Version { major: 2, minor: 0, patch: 0 }
println(v1 < v2)    // true

let versions = [v2, v1]
let sorted = versions.sort_by(|a, b| a.compare(b))
println(sorted[0].major)    // 1

struct Point { x: Int, y: Int }

impl Hash for Point {
    fn hash(self) -> Int { self.x * 31 + self.y }
}

impl Eq for Point {
    fn equals(self, other) -> Bool {
        self.x == other.x && self.y == other.y
    }
}

let origin = Point { x: 0, y: 0 }
let unit   = Point { x: 1, y: 0 }
let also_origin = Point { x: 0, y: 0 }

mut visited = #{origin, unit}
visited = visited.add(also_origin)   // deduplicated via equals()
println(visited.len())                // 2
println(visited.contains(also_origin))  // true

trait Contextual {
    fn enter(self)             // returns the resource bound by `as`
    fn exit(self, resource)    // cleans up; called even on error
}

import std.time

struct WorkDir { base: Path }

impl Contextual for WorkDir {
    fn enter(self) {
        let dir = self.base.join("workspace_" + str(time.timestamp()))
        dir.mkdir()
        dir
    }

    fn exit(self, dir) {
        dir.delete()
    }
}

with WorkDir { base: path("/tmp") } as dir {
    dir.join("output.txt").write_text("results").unwrap()
}
// workspace dir removed automatically

enum Direction { North, South, East, West }

enum Shape {
    Circle { radius: Float }
    Rect   { width: Float, height: Float }
    Point
}

enum Msg {
    Quit
    Move  { x: Int, y: Int }
    Write { text: String }
}

enum State {
    Running { pid: Int }      // brace form
    Failed(code: Int, msg: String)   // paren form — same thing
}

enum Direction { North, South, East, West }

let d = Direction.North   // qualified
let e = North             // bare name — same value
println(d)                // Direction.North

enum Shape { Circle { radius: Float }, Rect { width: Float, height: Float }, Point }

let c = Shape.Circle { radius: 5.0 }       // brace form, named fields
let c2 = Shape.Circle(radius: 5.0)         // paren form — identical value
let r = Shape.Rect(3.0, 4.0)               // positional — maps to width, height
let p = Shape.Point                        // unit

println(c == c2)   // true
println(c)         // Shape.Circle {radius: 5}
println(p)         // Shape.Point

enum Shape { Circle { radius: Float }, Rect { width: Float, height: Float }, Point }

let s = Shape.Circle(radius: 2.5)

match s {
    Circle { radius } => println("circle r=${radius}")
    Rect   { width, height } => println("rect ${width}x${height}")
    Point  {} => println("point")
}
// circle r=2.5

enum Status { ok, err { code: Int } }

let status = Status.err(code: 404)

match status {
    Status.ok => println("ok")
    Status.err { code } => println("err ${code}")
}

enum Response { success(body: String), failure(code: Int) }

match Response.failure(500) {
    Response.success(body) => println(body)
    Response.failure(code) => println(code)
}

match s {
    Circle { radius } if radius > 10.0 => println("big circle")
    Circle { radius } => println("small circle r=${radius}")
    _ => println("other shape")
}

enum Shape { Circle { radius: Float }, Rect { width: Float, height: Float } }

impl Shape {
    fn area(self) -> Float {
        match self {
            Circle { radius } => 3.14159 * radius * radius
            Rect   { width, height } => width * height
        }
    }

    fn describe(self) -> String {
        match self {
            Circle { radius } => "circle with radius ${radius}"
            Rect   { width, height } => "${width}×${height} rectangle"
        }
    }
}

let c = Shape.Circle(radius: 4.0)
println(c.area())       // 50.26544
println(c.describe())   // circle with radius 4

let s = Shape.Circle(radius: 3.0)
println(s.variant())           // Circle
println(s.enum_name())         // Shape
println(s.is_variant("Rect"))  // false
println(s.fields())            // {radius: 3.0}

// shapes.que
pub enum Color { Red, Green, Blue }
pub enum Shape { Circle { radius: Float }, Point }

// main.que
import .shapes { Color, Shape, Red, Green }

let c = Shape.Circle(radius: 1.0)
let color = Red

let good = Ok(42)
let bad = Err("something went wrong")

fn parse_number(s) {
    if s == "42" { Ok(42) }
    else { Err("not a number") }
}

fn process() {
    let n = parse_number("42")?   // unwraps to 42
    n * 2
}

println(process())   // 84

let a = null
let b = null
let c = 42
let result = a ?? b ?? c
println(result)   // 42

let val = Ok(5)
let doubled = val.map(|x| x * 2)
println(doubled.unwrap())   // 10

let found = [1, 2, 3].find(|x| x > 2)    // 3
let missing = [1, 2, 3].find(|x| x > 10) // null

println(found ?? 0)     // 3
println(missing ?? 0)   // 0

let user = load_user()
println(user?.address?.city)          // null if either link is missing
println(user?.address?.city ?? "n/a") // combine with ?? for a fallback

let name = null
println(name?.to_upper())             // null — no error

let n = glob("src/**/*.txt").copy_to(p"/tmp/out")?.len()
let text = path("notes.md").read()?.trim()

fn load_config(p) {
    p.read().context("reading service config")?
}

fn deploy(service) {
    let cfg = load_config(path("services/${service}/config.yaml"))
        .context("loading ${service} configuration")?
    // ... deploy using cfg
}

Error: loading api configuration: reading service config: No such file or directory

fn might_fail() -> Result<String> { Err("boom") }

might_fail()             // raises: boom
println("not reached")

let r = might_fail()          // bound — no raise
if r.is_err() { ... }

match might_fail() {          // matched — no raise
    Ok(v)  => println(v),
    Err(e) => println("failed: ${e}"),
}

let v = might_fail() ?? "default"

try {
    might_fail()
} catch e {
    println("caught: ${e}")   // caught: boom
}

`pytest tests/`              // if pytest exits 5, the script exits 5

if !health_ok {
    fail("health check failed", 75)   // script exits 75
}

mut result = ""
try {
    fail("something went wrong")
} catch e {
    result = "caught: " + e
}
println(result)   // caught: something went wrong

mut cleanup = false
try {
    fail("oops")
} catch e {
    println("caught")
} finally {
    cleanup = true
}
println(cleanup)   // true

fn deploy(env) {
    println("starting deploy to ${env}")
    defer println("deploy to ${env} finished")

    // ... deployment steps ...
}

fn with_temp(work) {
    let tmp = path("/tmp/workdir")
    tmp.mkdir()
    defer tmp.delete()   // cleaned up when the function returns

    work(tmp)            // defer runs after this, even on error
}

let db = spawn(`docker run --rm postgres`)
defer db.kill()

`./run-integration-tests.sh`   // Ctrl-C here still stops the container

// utils.que
pub fn greet(name) {
    "Hello, " + name + "!"
}

pub fn slug(s) {
    s.to_lower().replace(" ", "-")
}

// No `pub` — private to this file
fn internal_helper() {
    "you can't see me"
}

// main.que
import .utils

println(utils.greet("Que"))       // Hello, Que!
println(utils.slug("Hello World")) // hello-world

// Namespace import — module bound to `math`
import .lib.math
println(math.add(2, 3))

// Aliased — choose your own name
import .lib.strings as str
println(str.capitalize("que"))

// Selective — bring specific names into scope directly
import .lib.math { add, mul }
println(add(10, 20))

// Multi-module shorthand
import .{utils, config}

// config.que
pub fn app_name() { "My App" }
pub fn max_retries() { 3 }
fn secret_key() { "don't export me" }  // private

project/
  main.que
  lib/
    mod.que          <-- import .lib loads this
    math.que         <-- import .lib.math
    strings.que      <-- import .lib.strings

// lib/mod.que
pub import .math
pub import .strings

pub fn version() { v"1.0.0" }

import .lib
println(lib.version())
println(lib.math.add(2, 3))

import std.fs { read, write, exists }
import std.json { parse, stringify }

let data = read(path("./config.json"))?
let config = parse(data)?

import std.fs
import std.json

let data = fs.read(path("./config.json"))?
let config = json.parse(data)?

import .lib.math

println(typeof(math))   // Map
println(math.keys())     // ["add", "factorial", "mul", "sub", ...]

fn compute(m, a, b) {
    m.add(a, m.mul(a, b))
}
println(compute(math, 3, 4))   // 15

// lib/math.que
println("Loading math module...")   // prints once, no matter how many importers

pub fn add(a, b) { a + b }

project/
  que.toml
  main.que
  que_packages/
    colors/
      mod.que          <-- import colors
      shades.que       <-- import colors.shades
    deploy_tools/
      mod.que          <-- import deploy_tools
      k8s.que          <-- import deploy_tools.k8s

// main.que
import colors { Color }              // selective from mod.que
import colors.shades as palette      // sub-module, aliased
import deploy_tools                  // whole package as namespace

let c = Color.Red
palette.lighten(c)
deploy_tools.deploy("staging")

# que.toml
[package]
name = "deploy-scripts"
version = "0.1.0"

[dependencies]
colors       = { git = "https://github.com/acme/que-colors", tag = "v1.4.0" }
deploy-tools = { git = "git@github.com:acme/deploy-tools", rev = "9f2c1ab" }
nightly      = { git = "https://github.com/acme/nightly", branch = "main" }
shared       = { path = "../shared" }
helpers      = "https://github.com/acme/helpers#v2"   # shorthand: url#ref

que install              # fetch dependencies, write que.lock
que install --locked     # fail instead of resolving anything not already pinned

[[package]]
name = "colors"
source = "https://github.com/acme/que-colors"
requirement = "v1.4.0"
revision = "3f1d0b8a…"

let bin   = p"/usr/local/bin"    // absolute
let cfg   = p"./config"          // relative — current directory
let logs  = p"../logs"           // relative — parent directory
let empty = p""                  // empty path (identity for /)

let appname = "myapp"
let version = "1.4.2"

let install = p"/opt/${appname}"              // → p"/opt/myapp"
let lib     = p"/opt/${appname}/lib/${version}"  // → p"/opt/myapp/lib/1.4.2"

let key = p"~/.ssh/id_ed25519"                 // → /home/you/.ssh/id_ed25519

let config  = path(env.get("CONFIG") ?? "~/.config/que")
let ssh_key = path.home() / ".ssh" / "id_ed25519"

let template = script_dir() / "templates" / "nginx.conf"
let root     = script_dir() / ".."

let root = p"/opt/myapp"
let bin  = root / "bin" / "myapp"      // → p"/opt/myapp/bin/myapp"
let cfg  = root / p"etc/app.toml"      // → p"/opt/myapp/etc/app.toml"

// Absolute Path on the right wins
p"/a/b" / p"/etc"   // → p"/etc"

// String is never absolute — its leading slash is stripped
p"/a/b" / "/etc"    // → p"/a/b/etc"

let p = p"/opt/myapp/config.toml"

p.name()            // "config.toml"  — last segment
p.stem()            // "config"       — name without extension
p.extension()       // "toml"         — extension without dot
p.ext_dot()         // ".toml"        — extension with dot
p.parent()          // p"/opt/myapp"  — parent directory
p.root()            // p"/"           — root (p"" if relative)
p.is_absolute()     // true
p.is_relative()     // false
p.components()      // ["/", "opt", "myapp", "config.toml"]
p.depth()           // 4

let p = p"/opt/myapp/config.toml"

p.with_name("out.log")       // p"/opt/myapp/out.log"
p.with_stem("settings")      // p"/opt/myapp/settings.toml"
p.with_ext(".bak")           // p"/opt/myapp/config.bak"
p.with_ext("bak")            // same — leading dot is optional
p.normalize()                // resolves . and .., collapses double slashes
p.relative_to(p"/opt/myapp") // p"config.toml"
p.resolve_or(p"/etc/defaults") // absolute form of p, or the fallback if p is empty

let p = p"/usr/local/bin"
p.to_string()            // "/usr/local/bin"  — explicit
"binary is at: ${p}"     // automatic in string interpolation

let p = p"/opt/myapp/config.toml"

p.exists()      // bool — file or directory exists
p.is_file()     // bool — exists and is a regular file
p.is_dir()      // bool — exists and is a directory
p.is_link()     // bool — exists and is a symbolic link
p.size()        // Int  — file size in bytes
p.modified()    // Int  — last modification time (ms since epoch)

// Read and write
let content = p"data.txt".read()?
p"output.txt".write_text("hello")?
p"log.txt".append_text("new line\n")?

// Create directories and manage files
p"./build".mkdir()?
p"./config.json".copy_to(p"./backup/config.json")?
p"./build/output".move_to(p"/mnt/deploy/output")?
p"./old".delete()?

// List directory contents — paths are directly iterable
for f in p"./src" {
    println(f.name())
}

// Or use .ls() explicitly
let entries = p"./src".ls()
println(entries.len())

// .ls() takes an optional glob pattern to filter entries by file name
let configs = p"./etc".ls("*.toml")

let src = p"./src"

// All descendants (files and directories)
let everything = src.walk()

// Only files, recursively
let all_files = src.files()

// Only directories, recursively
let all_dirs = src.dirs()

// Find all .rs files using a pipeline
let rust_files = src.files().filter(|f| f.extension() == "rs")
for f in rust_files {
    println(f)
}

// Create a temp directory — deleted when block exits
with TempDir {} as work {
    work.join("data.txt").write_text("hello").unwrap()
    println(work.join("data.txt").read().unwrap())   // hello
}
// work directory no longer exists

// Create a temp file — deleted when block exits
with TempFile { suffix: ".json" } as scratch {
    scratch.write_text("{\"ok\": true}").unwrap()
    println(scratch.read().unwrap())
}

with TempDir { prefix: "build_", dir: p"./.cache" } as work { ... }
with TempFile { suffix: ".part", dir: p"/mnt/data" } as scratch { ... }

import std.fs
let stage = fs.temp_dir("stage_", { dir: p"./.cache" }).unwrap()
let part  = fs.temp_file("part_", ".bin", { dir: p"./.cache" }).unwrap()

let data = with TempDir {} as tmp {
    tmp.join("work.txt").write_text("processed").unwrap()
    tmp.join("work.txt").read().unwrap()
}
println(data)   // processed (tmp is already cleaned up)

let logs     = g"/tmp/*.log"                  // all .log files in /tmp
let all_logs = g"/var/log/**/*.log"           // recursive
let configs  = g"/etc/{dev,prod}/*.toml"      // alternation
let backups  = g"/backup/[0-9][0-9][0-9][0-9]" // character class

let app = "myapp"
let pattern = g"/etc/${app}/*.conf"   // → g"/etc/myapp/*.conf"

let g = glob("src/**/*.rs")      // from a string
let g = glob(p"./src") / "**" / "*.rs"   // from a Path

let base = g"/var/log"
let logs = base / "**" / "*.log"   // → g"/var/log/**/*.log"

// Convert a Path to a Glob first, then attach a pattern:
let dir  = p"/var/log/myapp"
let pattern = glob(dir) / "**" / "*.log"   // → g"/var/log/myapp/**/*.log"

p"/var/log" / g"*.log"     // runtime error
glob(p"/var/log") / "*.log" // correct

let g = g"/var/log/**/*.log"    // no I/O

// Iteration expands lazily
for file in g {                 // I/O here — file is a Path
    println(file)
}

let pattern = g"/var/log/**/*.log"

pattern.any()       // Bool — at least one match?
pattern.count()     // Int  — total match count
pattern.first()     // Path — first match, or null
pattern.pattern()   // String — the raw pattern string

// Explicit expansion
let files = g"src/**/*.rs".expand()
println(files)   // [src/ast.rs, src/lexer.rs, ...]

// Globs are iterable — expand automatically in for loops
for file in g"src/*.rs" {
    println(file)
}

// Expand relative to a directory
let rust_files = p"./src".glob("*.rs")

let large_files = g"build/**/*"
    .expand()
    .filter(|f| f.is_file() && f.size() > 1_000_000)
    .sort()

for f in large_files {
    println("${f}: ${f.size()} bytes")
}

let pattern = glob("src/**/*.rs")
println(pattern.test("src/main.rs"))         // true
println(pattern.test("src/nested/lib.rs"))   // true
println(pattern.test("README.md"))           // false

g"build/**/*.log".copy_to(p"./archived-logs")
g"/tmp/uploads/*.tmp".move_to(p"./incoming")

let timeout = 30s
let retry_delay = 500ms

let total = timeout + retry_delay
println(total.to_seconds())   // 30.5

let a = 10s
let b = 3s
println((a - b).to_seconds())   // 7.0
println((a * 3).to_seconds())   // 30.0
println(a > b)                  // true

import std.time

let deadline = time.timestamp() + 24h
let one_week_ago = time.timestamp() - 7d

// Check whether a cached file is fresh
let file_age_ms = time.timestamp() - path("cache.json").modified()
if file_age_ms > (1h).to_millis() {
    println("cache is stale, refreshing...")
}

let current = v"1.2.3"
let minimum = v"1.0.0"

println(current > minimum)    // true
println(current.major)        // 1
println(current.minor)        // 2
println(current.patch)        // 3

let result = semver_parse("2.0.0")
match result {
    Ok(ver) => println(ver.major),   // 2
    Err(e) => println("invalid: " + e),
}

let constraint = v">=1.2.0, <2.0.0"
println(constraint.satisfied_by(v"1.3.0"))   // true
println(constraint.satisfied_by(v"2.0.0"))   // false

let pattern = re"^\d{3}-\d{4}$"
println(pattern.test("555-1234"))   // true
println(pattern.test("abc"))        // false

let pattern = regex(user_supplied_pattern)?
println(pattern.test("hello"))

let token = secret("super-secret-token")
println(token)          // <redacted>

let token = env.secret("API_TOKEN").unwrap()          // Ok(Secret) | Err(String)
let db = fs.read_secret(p"/run/secrets/db_password").unwrap()

`curl -H "Authorization: Bearer ${token}" https://api.example.com`

$ que deploy.que --dry-run
[dry-run] curl -H "Authorization: Bearer <redacted>" https://api.example.com

let token = secret("hunter2")
println("token is " + token.expose())   // token is <redacted>
println(`echo $CI_TOKEN`.out())         // <redacted>, if the values match

`cargo build --release`     // runs; raises on non-zero exit
println("build succeeded")  // only reached if the build worked

let cmd = `echo hello`
println(typeof(cmd))   // Cmd

// Streamed, checked — the everyday case
`npm ci`

// Capture output you need
let branch = `git rev-parse --abbrev-ref HEAD`.out()

// Handle failure yourself
let probe = `which docker`.try()
if probe.exit_code != 0 {
    println("docker is not installed")
}

let tag = "myapp:latest"
println(`echo -n ${tag}`.out())   // myapp:latest

// Run in a specific directory
let cwd = `pwd`.dir(path("/tmp")).out()

// Set environment variables
let greeting = `echo -n $MY_VAR`
    .env("MY_VAR", "hello_que")
    .out()

// Pipe data into stdin
let echoed = `cat`.stdin("hello from stdin").out()

// Suppress stdout/stderr
`echo noisy`.silent()

mut cmd = `kubectl apply`
if namespace != null { cmd = cmd.flag("--namespace", namespace) }
if dry_run() { cmd = cmd.flag("--dry-run", "client") }
cmd = cmd.flag("-f").arg(manifest_path)
cmd.run()

`apt-get install -y nginx`.sudo().run()
`psql -c "select 1"`.sudo("postgres").out()
`make install`.sudo({ preserve_env: true, non_interactive: true }).run()

`echo "127.0.0.1 db" > /etc/hosts`.sudo()   // error

`echo "127.0.0.1 db"` | `tee -a /etc/hosts`.sudo()

let pattern = "connection refused"
let count = `grep -F ${pattern} app.log | wc -l`.out()

`./build.sh > build.log 2>&1`
`sort < names.txt`

let logs = `cat app.log`
let errors = logs | `grep ERROR` | `wc -l`
println(errors.out())

let versions = `git log --oneline`.dir(repo) | `head -20`

// `sh` reports success here — `wc` succeeded. Que raises.
`cat missing-file.txt | wc -l`.out()      // shell text: shell rules apply
(`cat missing-file.txt` | `wc -l`).out()  // raises: exit code 1 from `cat`

let docker = which("docker")
if docker == null {
    fail("docker is required but not installed")
}
println("docker found at: ${docker}")

let server = spawn `npm run dev`

println("server started, pid: ${server.pid()}")

if server.is_alive() {
    println("server is up")
}

// Wait until it exits
let code = server.wait()

// Kill the process
server.kill()        // SIGTERM (graceful)
server.kill_force()  // SIGKILL (immediate)

let db = spawn `docker run --rm -p 5432:5432 postgres:15`
defer db.kill()

sleep(3s)

let test_result = `pytest integration/`.try()
if test_result.exit_code != 0 {
    fail("tests failed")
}

// Unnamed branches: returns a Tuple
let base = 5
let (doubled, tripled, squared) = parallel {
    base * 2,
    base * 3,
    base ** 2
}

// Named branches: returns a Map
let results = parallel {
    coverage:  run_coverage_check(),
    lint:      run_linter(),
    typecheck: run_typechecker()
}

println("lint passed: ${results["lint"]}")

let results = parallel {
    unit:        `cargo test`.out(),
    integration: `cargo test --test integration`.out(),
    docs:        `cargo doc`.out(),
}

sleep(2s)
sleep(500ms)

let result = retry(3, |attempt| {
    if attempt < 2 {
        fail("not ready yet")
    }
    "success on attempt " + str(attempt)
})
println(result)   // success on attempt 2

let result = timeout(5s, || {
    42
})
println(result)   // 42

import std.http { get }

let resp = retry(3, || {
    let r = get("https://api.example.com/health").unwrap()
    if !r.ok { fail("unhealthy: " + str(r.status)) }
    r
})

let f = open("data.txt")          // read mode (default)
let f = open("out.txt", "w")      // write / truncate
let f = open("log.txt", "a")      // append / create

let f = open("report.txt")
defer f.close()

let content = f.read()
println(content)

let f = open("data.txt")
defer f.close()

let all = f.read()          // Ok(String) | Err(String)
let line1 = f.read_line()   // String | Null (Null at EOF)
let lines = f.lines()       // List<String>

let f = open("output.txt", "w")
defer f.close()
f.write("first line\n")     // no trailing newline added
f.writeln("second line")    // adds \n automatically
f.flush()                   // force OS flush

import std.stream

let s = stream.file(path("./data/input.txt"))  // lazy file source — not read yet
let s = stream.of("hello\nworld")             // from a string
let s = stream.of(["alice", "bob"])           // from a list (joined with newlines)
let s = stream.of(file_handle)                // from an open FileHandle (writable sink)

// Standard I/O streams
let out = stream.stdout()   // stream wired to process stdout
let err = stream.stderr()   // stream wired to process stderr
let inp = stream.stdin()    // stream that lazily reads stdin

let result = stream.of("  hello world  ")
    .trim()
    .to_upper()
    .collect()

println(result)   // HELLO WORLD

stream.file(path("./input.txt"))
    .to_upper()
    .write_to(path("./output.txt"))

// Print the last 20 ERROR lines straight to stdout — file is read lazily,
// output is written line-by-line, no full file in memory.
stream.file(path("./log.txt"))
    .grep("ERROR")
    .tail(20)
    .write_to(stream.stdout())

// Mirror the child's stdout directly to our stdout
`cargo build --release`.forward_stdout(stream.stdout()).run()

// Capture stderr to a file while printing stdout normally
let build_log = open("build.log", "w")
defer build_log.close()

`make all`
    .forward_stdout(stream.stdout())
    .forward_stderr(stream.of(build_log))
    .run()

// Find errors in a log file
stream.file(path("/var/log/app.log"))
    .grep("ERROR")
    .tail(10)
    .write_to(path("./recent-errors.txt"))

// Filter and transform lines
let admins = stream.file(path("./users.csv"))
    .filter(|line| line.contains("admin"))
    .map(|line| line.split(",")[0])
    .to_upper()
    .collect()

let home = env.get("HOME")            // string or null
let port = env.get("PORT", "8080")    // with a default
let present = env.has("CI")           // true / false
println(home)   // /home/user

let debug = env.bool("DEBUG")       // true / false, or null if unset
let port = env.int("PORT")          // 8080, or null if unset
let tags = env.list("TAGS")         // ["a", "b"], or null  (splits on ",")

let dirs = env.list("PATH", os.path_separator)
// ["/usr/local/bin", "/usr/bin", "/bin", ...]

env.set("CARGO_TERM_COLOR", "always")
env.set("NODE_ENV", "production")

println(env.get("NODE_ENV"))   // production

env.unset("NODE_ENV")
println(env.has("NODE_ENV"))   // false

env.load_file(".env")?

env.require(["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION"])
// Error: required environment variables not set: AWS_REGION

let all = env.all()
println("PATH: ${all["PATH"]}")

if env.is_ci() {
    println("running in CI: ${env.ci_name()}")  // "github-actions", "jenkins", etc.
}

if env.is_interactive() {
    // show prompts, progress bars, etc.
}

let platform = env.platform()  // "linux", "macos", "windows"

println(os.name)             // "linux", "macos", "windows"
println(os.family)           // "unix" or "windows"
println(os.arch)             // "x86_64", "aarch64", etc.
println(os.path_separator)   // ":" on Unix, ";" on Windows
println(os.dir_separator)    // "/" on Unix, "\" on Windows

if !checks_passed {
    println("checks failed")
    os.exit(1)
}

set QUE_SHELL=C:\Program Files\Git\bin\bash.exe

let open = if os.family == "windows" { "start" } else { "xdg-open" }
`${open} report.html`.run()

with env.scope({ "DATABASE_URL": "postgres://localhost/test" }) {
    let url = env.get("DATABASE_URL")
    println(url)   // postgres://localhost/test
}
// DATABASE_URL is restored to its previous value (or unset)

que script.que one two three        # args() → ["one", "two", "three"]
que script.que -- --flag a b        # args() → ["--flag", "a", "b"]

let a = args()
if a.len() < 1 {
    println("usage: greet.que <name>")
    os.exit(1)
}
println("hello,", a[0])

import std.tty

tty.is_stdin()    // true if stdin is a TTY (not piped)
tty.is_stdout()   // true if stdout is a TTY (not redirected)
tty.is_stderr()   // true if stderr is a TTY
tty.size()        // {"cols": Int, "rows": Int} or null

import std.tty

let use_color = tty.is_stdout()
fn red(s) { if use_color { "\e[31m" + s + "\e[0m" } else { s } }
println(red("error: file not found"))

import std.tty
let sz = tty.size()
let wide = sz != null && sz["cols"] >= 100

let name = input("name: ")            // reads a line from stdin
if confirm("proceed?") {              // "y" or "yes" (case-insensitive) → true
    println("continuing as ${name}")
}

import std.prompt

print("name: ")
let name = prompt.read_line()

import std.prompt

print("password: ")
let pw = prompt.read_line({ "echo": false })
println()   // newline after hidden input

import std.prompt

println("press any key…")
let k = prompt.read_key()
println("you pressed:", k)

import std.prompt

fn select(title, options) {
    mut cursor = 0
    let n = options.len()
    println(title)
    loop {
        // Render
        for i in range(0, n) {
            let marker = if i == cursor { "> " } else { "  " }
            println(marker + options[i])
        }
        // Read key
        let k = prompt.read_key()
        if k == "enter"   { return options[cursor] }
        if k == "ctrl+c"  { return null }
        if k == "up"      { cursor = (cursor - 1 + n) % n }
        if k == "down"    { cursor = (cursor + 1) % n }
        // Move cursor back up to overwrite the menu (ANSI: \e[<n>A = up n lines, \e[J = clear below).
        // Note: use `print`, not `println` — println adds a newline that would push the menu down each iteration.
        print("\e[" + str(n) + "A\e[J")
    }
}

let env = select("Deploy to:", ["dev", "staging", "prod"])
println("→", env)

import std.json
import std.yaml
import std.toml

let data = json.parse("{\"name\": \"myapp\", \"port\": 8080}").unwrap()
println(data["name"])    // myapp

let data = yaml.parse("name: myapp\nport: 8080").unwrap()
let data = toml.parse("name = \"myapp\"\nport = 8080").unwrap()

let data = {"name": "myapp", "port": 8080}

json.stringify(data)        // compact JSON
json.stringify(data, 2)     // pretty-printed with 2-space indent
yaml.stringify(data)        // YAML format
toml.stringify(data)        // TOML format

let data = {"name": "myapp", "port": 8080}
println(data.to_json(2))
println(data.to_yaml())
println(data.to_toml())

import std.config

let settings = config.read(path("./config.json"))?
let more     = config.read(path("./settings.yaml"))?
let manifest = config.read(path("./Cargo.toml"))?

config.write(path("./output.json"), data)   // writes JSON
config.write(path("./output.yaml"), data)   // writes YAML
config.write(path("./output.toml"), data)   // writes TOML

import std.json { parse }

let config = parse("{\"database\": {\"host\": \"localhost\", \"port\": 5432}}").unwrap()

// Navigate with dot notation
println(config.get_path("database.host"))    // localhost
println(config.get_path("database.port"))    // 5432

let data = parse("{\"servers\": [{\"host\": \"web1\"}, {\"host\": \"web2\"}]}").unwrap()
println(data.get_path("servers[0].host"))     // web1
println(data.get_path("servers[*].host"))     // ["web1", "web2"]

let updated = config
    .set_path("app.version", "2.0")
    .set_path("app.debug", false)
    .set_path("app.port", 9090)

config.has_path("database.host")    // true
config.delete_path("app.debug")     // returns new map without that key
config.paths()                      // list all leaf paths: ["app.name", "app.port", ...]

import std.toml

// Bump the version in Cargo.toml
toml.edit("Cargo.toml", |doc| {
    doc.package.version = "2.0.0"
    doc.package.edition = "2024"
    doc
})

import std.json

// Update a package.json dependency
json.edit("package.json", |doc| {
    doc.dependencies.react = "^19.0.0"
    doc
})

import std.yaml

// Toggle a feature flag in a YAML config
yaml.edit("config.yaml", |doc| {
    doc.features.dark_mode = true
    doc
})

let base = parse("{\"a\": 1, \"nested\": {\"x\": 10}}").unwrap()
let overlay = parse("{\"b\": 2, \"nested\": {\"y\": 20}}").unwrap()
let merged = base.deep_merge(overlay)
println(merged.get_path("nested.x"))     // 10
println(merged.get_path("nested.y"))     // 20

import std.stream

let config = stream.file(path("./config.json")).parse_json()?
let settings = stream.file(path("./settings.yaml")).parse_yaml()?
let manifest = stream.file(path("./Cargo.toml")).parse_toml()?

import std.http { get, post, download, url_encode, query_string }

import std.http { get }

let resp = get("https://api.github.com/zen").unwrap()
println(resp.status)    // 200
println(resp.body)      // some GitHub zen wisdom
println(resp.ok)        // true

let resp = get("https://api.github.com/repos/acme/ferry").unwrap()
if resp.ok() {
    let repo = resp.json().unwrap()   // parses .body as JSON
    println(repo["full_name"])
}

import std.http { post }
import std.json { stringify }

let payload = stringify({"name": "Alice", "role": "admin"})
let resp = post("https://api.example.com/users", payload, {
    "Content-Type": "application/json",
}).unwrap()
println(resp.status)   // 201

import std.http { request }

let resp = request({
    "method": "POST",
    "url": "https://api.example.com/webhook",
    "headers": { "Content-Type": "application/json" },
    "body": stringify({"event": "deploy"}),
    "timeout": 30,
}).unwrap()

import std.http { download }

let result = download(
    "https://example.com/tool-linux-amd64",
    path("./bin/tool"),
).unwrap()
println(result.size)     // bytes written
println(result.path)     // ./bin/tool

import std.http { url_encode, url_decode, query_string, get }

let encoded = url_encode("hello world & more")
println(encoded)   // hello%20world%20%26%20more

let qs = query_string({"q": "que lang", "page": 1})
let url = "https://api.example.com/search?" + qs
let resp = get(url).unwrap()

import std.fs

// Atomic write: temp+rename to prevent partial writes
fs.atomic_write(path("config.json"), config.to_json())?

// Recursive directory operations
fs.copy_dir(path("src/"), path("dist/"))?
fs.remove_dir(path("build/"))?

// Find files recursively
let configs = fs.find(path("."), "*.config.json")
for cfg in configs {
    println("found: ${cfg}")
}

// Read and write lines
let hosts = fs.read_lines(path("/etc/hosts")).unwrap()
let filtered = hosts.filter(|line| !line.starts_with("#"))
fs.write_lines(filtered, path("/tmp/active_hosts.txt"))?

// Temp files and directories (manual cleanup)
let tmp = fs.temp_dir("build_").unwrap()
defer fs.remove_dir(tmp)

// Transform a file in place (read → callback → atomic write back)
fs.transform("config.txt", |content| {
    content.replace("localhost", "prod-server.example.com")
})

import std.archive

// Bare paths — each file/directory is archived under its own name.
// A directory is archived as  dirname/contents.
archive.tar_gz(p"out.tar.gz", [p"README.md", p"LICENSE", p"dist/"])

// { src, dest } maps — control exactly where each entry lands.
// For a file,  dest  is the exact archive path.
// For a directory,  dest  is the prefix for the directory's *contents*.
archive.zip(p"release.zip", [
    { src: p"target/release/myapp", dest: "bin/myapp" },
    { src: p"config/default.toml",  dest: "etc/myapp.toml" },
    p"README.md",
])

// Archive a directory's contents at the archive root (no wrapper directory).
// { dest: "." } means "contents go to the top level".
archive.tar_gz(p"site.tar.gz", [{ src: p"build/", dest: "." }])
// build/index.html  ->  index.html   (not  build/index.html)

// Archive a directory's contents under a named prefix.
archive.tar_gz(p"myapp-1.0.tar.gz", [{ src: p"dist/", dest: "myapp-1.0" }])
// dist/bin/myapp  ->  myapp-1.0/bin/myapp

// Optional top-level prefix applied to every entry (convenience shorthand
// equivalent to wrapping all entries in a dest prefix).
archive.tar_gz(p"myapp-v1.0.tar.gz", [
    p"README.md",
    p"LICENSE",
    { src: p"dist/", dest: "." },
], "myapp-v1.0")
// README.md  ->  myapp-v1.0/README.md
// dist/bin   ->  myapp-v1.0/bin

// Set Unix permission bits on a specific entry
archive.tar_gz(p"tools.tar.gz", [
    { src: p"target/release/tool", dest: "bin/tool", mode: 0o755 },
])

// Extract (destination directory is created if it does not exist)
archive.extract(p"release.tar.gz", p"./extracted/")

// List contents
let entries = archive.list(p"release.tar.gz")

import std.hash

// Hash a string or file
let digest = hash.sha256("hello world")
let file_hash = hash.sha256(path("release.tar.gz"))
let sha512 = hash.sha512("important data")
let md5 = hash.md5(path("legacy.bin"))

// Verify integrity
let ok = hash.verify(path("release.tar.gz"),
    "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e...")
if !ok { fail("checksum mismatch") }

// Generate and verify checksum files
let artifacts = glob("dist/*.tar.gz").expand()
hash.write_checksums(artifacts, path("dist/SHA256SUMS"))
hash.verify_checksums(path("dist/SHA256SUMS"))

import std.csv

// Parse a CSV file (first row = headers)
let rows = csv.parse(path("data.csv"))
for row in rows {
    println("name=${row["name"]}, age=${row["age"]}")
}

// Parse from a string
let rows = csv.parse_str("name,age\nAlice,30\nBob,25")
println(rows[0]["name"])   // Alice

// TSV (tab-separated)
let rows = csv.parse_str(tsv_text, "\t")

// Write CSV
let data = [
    { "name": "Alice", "score": "100" },
    { "name": "Bob",   "score": "85"  }
]
csv.write(data, path("results.csv"))

// Serialize to string
let text = csv.to_string(data)

import std.log

log.debug("checking connection", { host: "prod-1", port: 5432 })
log.info("deployment started", { version: "1.2.3", env: "production" })
log.warn("retry attempt", { attempt: 3, max: 5 })
log.error("healthcheck failed", { service: "api", status: 503 })

[INFO] 1708371234 | deployment started | version=1.2.3 env=production

log.set_level("warn")       // only warn and error emitted

log.set_format("json")
log.info("deploy", { env: "prod" })
// {"level":"INFO","timestamp":1708371234,"message":"deploy","env":"prod"}

log.add_file_sink("/var/log/app.log")
log.add_file_sink("/var/log/errors.json", { format: "json", level: "error" })
log.add_console_sink({ format: "json", level: "debug" })

// Reset to default console-only output
log.remove_sinks()

let logger = log.new({ service: "api", version: "1.2" })
logger.info("starting")
// [INFO] 1708371234 | starting | service=api version=1.2

let db_log = logger.child({ component: "db" })
db_log.warn("slow query", { ms: 1200 })

import std.git

let branch = git.branch()           // "main"
let sha    = git.commit()           // full 40-char SHA
let short  = git.short_commit()     // 7-char abbreviation
let tag    = git.tag()              // "v1.2.3" or null
let dirty  = git.is_dirty()         // Bool
let clean  = git.is_clean()         // Bool
let tags   = git.tags()             // List<String>
let origin = git.remote_url()       // "https://github.com/org/repo"

let version = git.tag() ?? "0.0.0-dev+${git.short_commit()}"

if git.is_dirty() {
    fail("cannot release — uncommitted changes detected")
}

import std.dotenv

// Load .env into current process environment
dotenv.load(path(".env"))

// Load and overwrite existing vars
dotenv.load_overwrite(path(".env.local"))

// Parse without loading into environment
let vars = dotenv.parse(path(".env"))
println(vars["PORT"])

// Write a .env file from a map
dotenv.write({
    "PORT": "8080",
    "DATABASE_URL": "postgres://localhost/mydb",
}, path(".env"))

import std.template

let result = template.render("Hello, {{ name }}!", { "name": "World" })
// "Hello, World!"

let ctx = { "server": { "host": "localhost", "port": 8080 } }
template.render("bind {{ server.host }}:{{ server.port }}", ctx)
// "bind localhost:8080"

let tmpl = "mode: {{# if production }}PROD{{# else }}DEV{{/ if }}"
template.render(tmpl, { "production": true })   // "mode: PROD"

let tmpl = "{{# for svc in services }}- {{ svc.name }}: {{ svc.port }}\n{{/ for }}"
let ctx = {
    "services": [
        { "name": "api", "port": 8080 },
        { "name": "web", "port": 3000 }
    ]
}
template.render(tmpl, ctx)

let config = template.render_file(path("templates/nginx.conf.tmpl"), {
    "server_name": "example.com",
    "upstream_port": 8080
})

import std.net

// Check host reachability
net.ping("example.com")
net.ping("10.0.0.1", 2s)      // with timeout

// Check if a port is open
net.port_open("localhost", 5432)

// DNS resolution
let ips = net.resolve("example.com")

// Wait for port (essential after spawn)
let server = spawn `npm run dev`
defer server.kill()
net.wait_for_port("localhost", 3000, 60s, 1s)

// Wait for HTTP endpoint
net.wait_for_url("http://localhost:8080/health", 60s, 2s)

import std.time

let now   = time.now()                      // local timezone (from $TZ, default UTC)
let dt    = time.of(2024, 6, 15, 14, 30, 0) // June 15 2024, 2:30pm UTC
let east  = time.of(2024, 6, 15, 10, 0, 0, "America/New_York")
let ts    = time.from_timestamp(time.timestamp())  // from a millisecond count
let parsed = time.parse("2024-03-15 14:30:00", "%Y-%m-%d %H:%M:%S")

let started = time.timestamp()
build()
println("took ${time.timestamp() - started}ms")

println(dt.year())       // 2024
println(dt.month())      // 6
println(dt.day())        // 15
println(dt.hour())       // 14
println(dt.minute())     // 30
println(dt.weekday())    // "Sat"
println(dt.day_of_year()) // 167

println(dt.format("%Y/%m/%d %H:%M"))  // "2024/06/15 14:30"
println(dt.to_iso())                    // RFC 3339 string
println(dt.timestamp())                 // Unix ms

let nyc = dt.in_tz("America/New_York")
println(nyc.timezone())   // "America/New_York"
println(nyc.hour())       // 10 (UTC-4 in summer)
let back = nyc.utc()
println(back.timezone())  // "UTC"

let tomorrow  = dt.add_days(1)
let yesterday = dt.add_days(-1)
let later     = dt.add_hours(3)
let soon      = dt.add_minutes(15)

let a = time.of(2024, 1, 1)
let b = time.of(2024, 6, 15)
println(a < b)   // true

println("deployed at ${dt}")  // "deployed at 2024-06-15T14:30:00+00:00"

import std.container

import std.container

let pw = env.secret("TEST_DB_PASSWORD")?

container.run({
    image: "postgres:16",
    name: "test-db",
    ports: { "5432": 5432 },
    env: { "POSTGRES_PASSWORD": pw, "POSTGRES_DB": "testdb" },
})?
defer container.remove("test-db")

container.wait_healthy("test-db", 30s)?
container.exec("test-db", "psql -U postgres -c 'select 1'")?

container.exec("db", "pg_dump mydb | gzip > /tmp/dump.gz")   // shell
container.exec("db", ["pg_dump", "mydb"])                    // argv

`docker compose -f ${compose_file} up -d`.run()
defer `docker compose -f ${compose_file} down -v`.run()

import std.ssh

import std.ssh

ssh.cmd("web-1", `systemctl restart nginx`, { user: "deploy" })
    .timeout(30s)
    .run()

let kernel = ssh.out("web-1", "uname -r")?

ssh.cmd("ephemeral-ci-box", "id", { strict_host_key_checking: false })

ssh.cmd("web-1", "echo $HOSTNAME > /tmp/who")   // $HOSTNAME expands remotely

import std.watch

import std.watch

watch.run(p"src", |changes| {
    println("changed: ${changes.len()} file(s)")
    `cargo build`
}, { initial: true, debounce: 300ms })

let changes = watch.wait([p"src", p"Cargo.toml"], { timeout: 30s })?
for c in changes {
    println("${c["kind"]}: ${c["path"]}")
}

if watch.snapshot(p"src") == 0 {
    fail("nothing to watch under src/")
}

@description("Compile the project")
task build {
    println("compiling...")
    println("done!")
}

build()
// [RUN]  build
// compiling...
// done!
// [DONE] build

@description("Compile source files")
@inputs(["src/**/*.que", "que.toml"])
@outputs(["./build/app"])
@env([CC, CFLAGS])
task compile {
    println("compiling from sources...")
}

@description("Run the test suite")
@aliases([t, tests])
task test {
    `cargo test`
}

que run t          # same task as `que run test`

task clean {
    println("cleaning build artifacts")
}

task compile { println("compiling") }
@deps([compile])
task link { println("linking") }
@deps([link])
task package { println("packaging") }

package()
// [RUN]  compile  -> [DONE]
// [RUN]  link     -> [DONE]
// [RUN]  package  -> [DONE]

@description("Bundle the release artifact")
@deps([link])
@inputs(["./build/app"])
@outputs(["./dist/app.tar.gz"])
task package {
    println("packaging")
}

@description("Build for a specific target")
task build(target, mode = "debug") {
    println("building ${target} in ${mode} mode")
}

build("linux-amd64")                    // positional — debug mode
build("linux-arm64", "release")         // positional — release mode
build(target: "darwin-arm64")           // named — uses default mode
build(target: "win-amd64", mode: "release")  // all named

que run build -- linux-amd64          # positional
que run build -- target=darwin-arm64  # named
que run build -- target=win mode=release

que run build --help
# Usage: build [target] [mode]
#
# Build for a specific target
#
# Arguments:
#   target  (required)
#   mode    default: "debug"

@inputs(["src/**/*.rs"])
@outputs(["./target/release/app"])
task compile {
    println("compiling (this is expensive)...")
}

compile()  // First run:  [RUN] -> [DONE]
compile()  // Second run: [SKIP] (outputs are fresh)

@description("Deploy to production")
task deploy {
    42
}

println(deploy.name)          // "deploy"
println(deploy.description)   // "Deploy to production"
println(deploy.status)        // "pending"
deploy()
println(deploy.status)        // "succeeded"

// List all registered tasks
let all = tasks()      // Map of task_name -> task_value
for name in all.keys() {
    println(name)
}

// Execute a task dynamically by name
run_task("build")

// Quefile
import std.fs { read, write, exists }

@description("Remove build artifacts")
task clean {
    if exists(path("./build")) {
        path("./build").delete()
    }
}

@description("Compile the project")
@deps([clean])
task compile {
    println("compiling...")
}

@description("Run test suite")
@deps([compile])
task test {
    println("testing...")
}

que tasks                              # list all tasks
que run deploy                         # run a task (with dependencies)
que run -f build/pipeline.que deploy   # use a specific Quefile
que run build --help                   # show task usage and argument table
que run build -- linux-amd64           # positional arguments
que run build -- target=linux mode=release  # named arguments

// math_test.que
import .math { add }

fn test_adds_positive_numbers() {
    assert(add(2, 3) == 5)
}

fn test_adds_negatives() {
    assert(add(-2, -3) == -5)
}

fn round_trip(x) {       // no prefix: a helper, not a test
    add(x, 0)
}

que test                       # every test file under the current directory
que test tests/                # a directory
que test math_test.que         # one file, whatever it is named
que test --filter adds_neg     # only tests whose name contains this

math_test.que
  ok   test_adds_positive_numbers
  FAIL test_adds_negatives
       math_test.que:8:5: assertion failed: add(-2, -3) == -5  (5 == -5)

1 of 2 failed

que fmt                    # format all .que files recursively
que fmt script.que        # format a specific file
que fmt --check            # check without writing (exit 1 if unformatted)
que fmt --diff             # show diff without writing

que lint                   # lint all .que files
que lint script.que       # lint a specific file

fn deploy(env, version) {
    println("deploying ${version} to ${env}")
}

let version = "1.4.0"
if env.get("CI") != null {
    deploy("prod")        // arity: 'deploy' takes 2 argument(s), but 1 were given
} else {
    deploy("staging", verison)   // undefined-name: 'verison' (did you mean 'version'?)
}

#!strict

fn add(a: Int, b: Int) -> Int {
    a + b
}

add(1, 2)       // OK
// add("x", 2)  // ERROR: parameter 'a' expected Int, got String

#!strict

fn get_name() -> String {
    "Alice"           // OK
}

fn bad() -> Int {
    "not a number"    // ERROR: return type expected Int, got String
}

que --strict deploy.que

let is_strict = strict()  // query current state

que deploy.que --dry-run
que run release --dry-run

[dry-run] kubectl apply -f deploy.yaml
[dry-run] write /etc/app.conf (214 bytes)
[dry-run] http.post https://hooks.example.com/notify

[dry-run] open ./build/manifest.json for writing (truncate)
[dry-run] write ./build/manifest.json (214 bytes)

if dry_run() {
    println("would restart ${service}")
} else {
    restart(service)
}

que t.que --allow read=.        # open("log.txt")        ok
                               # open("log.txt", "w")   denied -- that is a write
                               # stream.of("a\nb")      ok -- in memory, reads nothing
                               # stream.file(p"log.txt") ok -- a file read

que build.que                       # unrestricted, exactly as before

que build.que --allow read --allow exec

que build.que \
    --allow read=src,Cargo.toml \
    --allow write=target \
    --allow net=crates.io,static.crates.io \
    --allow exec

que t.que --allow read=src        # src/main.que  ok
                                  # src/../etc    denied

que vendored.que --deny net       # everything except the network

runtime error: permission denied: exec 'curl https://example.com' —
  grant it with --allow exec=curl https://example.com (or --allow exec for all)

let result = [1, 2, 3]
    .map(|x| x * 2)
    |> dbg                // prints: [dbg] List = List(len=3)
    .filter(|x| x > 2)
    |> dbg                // prints: [dbg] List = List(len=2)

println(result)           // [4, 6]

let info = [1, 2, 3].inspect()
println(info["type"])          // List
println(info["length"])        // 3
println(info["homogeneous"])   // true
println(info["element_type"])  // Int

import std.reflect

typeof(42)                 // "Int"
typeof([1, 2])             // "List"

let info = reflect.type_info(|x| x + 1)
println(info.is_callable)  // true
println(info.type_name)    // "Function"

42.is_type("Int")          // true

"hello".methods()              // ["len", "to_upper", "to_lower", ...]

reflect.has_method([1, 2], "map")      // true
reflect.has_method([1, 2], "to_upper") // false

reflect.fields({"a": 1, "b": 2})       // ["a", "b"]
reflect.fields((10, 20, 30))           // [0, 1, 2]

fn greet(name, greeting) { greeting + ", " + name }
reflect.fields(greet)                  // ["name", "greeting"]

let x = 42
let name = "que"
reflect.vars()                    // {"name": "que", "x": 42}

mut counter = 0
let info = reflect.var_info("counter")
println(info.name)       // "counter"
println(info.type_name)  // "Int"
println(info.mutable)    // true

reflect.scope_depth()    // 0  (global)

help()                    // overview: builtin categories, std modules,
                          //   local packages, REPL meta-commands
help("println")           // signature and docs for the `println` builtin
help("map")               // documentation for the `.map()` method
help("if")                // documentation for a language keyword
help("fs")                // list the functions exported by std module `fs`

help(42)                  // type + available methods, grouped
help([1, 2, 3])           // same, for a List

help(stream.file("data.txt"))  // describes a stream value
help(json)                // lists exports of an imported module

// User-defined types — pass the type name or any instance.
struct Point { x = 0, y = 0 }
impl Point {
    fn distance() { (self.x * self.x + self.y * self.y).abs() }
}
help(Point)               // shows struct fields + impl methods
help(Point{x: 3, y: 4})   // same, plus current field values

import std.reflect

reflect.modules()
// {"fs": ["read", "write", "exists", ...],
//  "http": ["get", "post", ...],
//  "json": ["parse", "stringify", "edit"], ... }

reflect.modules()["fs"]     // ["read", "write", "exists", ...]
reflect.modules().keys()    // ["archive", "config", "csv", "dotenv", "fs", ...]

que> ?fs
Standard library module `fs`

Import with:
  import fs
  import fs { read }

Functions (12):
  fs.read, fs.write, fs.exists, fs.atomic_write, fs.temp_file, fs.temp_dir
  fs.copy_dir, fs.remove_dir, fs.find, fs.read_lines, fs.write_lines
  fs.transform

que> let xs = [1, 2, 3]
que> ?xs
Value of type `List`
  = [1, 2, 3]

Methods (28):
  len, push, pop, map, filter, fold, ...
que> :t xs.first()
=> Int

# deploy.toml
[service]
name = "ferry"
health_path = "/health"
port = 8080

[fleet]
hosts = ["api-1.internal", "api-2.internal", "api-3.internal"]
user = "deploy"

[registry]
host = "registry.example.com"
repo = "acme/ferry"

// Quefile
import std.config
import std.container
import std.ssh
import std.net
import std.git
import std.hash
import std.log
import std.time

let manifest = config.read(script_dir() / "deploy.toml").unwrap()
let service  = manifest.service.name
let hosts    = manifest.fleet.hosts
let registry = "${manifest.registry.host}/${manifest.registry.repo}"

let logger = log.new({ service: service })

// ---- Stage 1: checks, run concurrently ------------------------------

@description("Lint, test, and type-check — all three run in parallel")
task verify {
    if git.is_dirty() {
        fail("working tree is dirty — commit or stash before deploying")
    }

    let results = parallel {
        lint:      `que lint`.try(),
        test:      `que test`.try(),
        typecheck: `que --strict src/main.que`.try(),
    }

    for (name, r) in results {
        if r.exit_code != 0 {
            fail("${name} failed:\n${r.stdout}${r.stderr}")
        }
    }
    logger.info("verification passed")
}

// ---- Stage 2: build and push the image -------------------------------

@description("Build and tag the container image with the git commit")
@deps([verify])
task build {
    let tag = "${registry}:${git.short_commit()}"
    container.build({
        tag: tag,
        context: ".",
        build_args: { "GIT_SHA": git.commit() },
    })?
    logger.info("image built", { tag: tag })
}

@description("Push the image to the registry")
@deps([build])
task push {
    let tag = "${registry}:${git.short_commit()}"
    let user = env.get("REGISTRY_USER") ?? fail("REGISTRY_USER not set")
    let pass = env.secret("REGISTRY_PASSWORD").unwrap()

    container.login(manifest.registry.host, user, pass)?
    container.push(tag)?
    logger.info("image pushed", { tag: tag })
}

// ---- Stage 3: roll the fleet, one host at a time ----------------------

fn current_tag(host) {
    ssh.out(host, "docker inspect --format='{{.Config.Image}}' ${service}",
        { user: manifest.fleet.user }).unwrap_or(null)
}

fn deploy_to(host, tag) {
    logger.info("deploying", { host: host, tag: tag })

    ssh.cmd(host, `docker pull ${tag}`, { user: manifest.fleet.user })
        .timeout(2m)
        .run()

    ssh.cmd(host,
        `docker run -d --rm --name ${service} -p ${str(manifest.service.port)}:${str(manifest.service.port)} ${tag}`,
        { user: manifest.fleet.user }
    ).run()

    let url = "http://${host}:${manifest.service.port}${manifest.service.health_path}"
    retry(5, |attempt| {
        sleep(2s)
        net.wait_for_url(url, 20s, 2s)?
    })
    logger.info("host healthy", { host: host })
}

fn rollback(host, previous_tag) {
    if previous_tag == null {
        logger.warn("no previous image recorded, cannot roll back", { host: host })
        return
    }
    logger.warn("rolling back", { host: host, tag: previous_tag })
    ssh.cmd(host, `docker stop ${service}`, { user: manifest.fleet.user }).try()
    ssh.cmd(host,
        `docker run -d --rm --name ${service} -p ${str(manifest.service.port)}:${str(manifest.service.port)} ${previous_tag}`,
        { user: manifest.fleet.user }
    ).run()
}

@description("Roll the new image out to every host, one at a time")
@deps([push])
task deploy {
    let tag = "${registry}:${git.short_commit()}"
    mut rolled_back = []

    for host in hosts {
        let previous = current_tag(host)

        try {
            deploy_to(host, tag)
        } catch e {
            logger.error("deploy failed, rolling back this host and every host already updated",
                { host: host, error: e })
            rollback(host, previous)
            for done_host in rolled_back {
                rollback(done_host, previous)
            }
            fail("deploy aborted: ${e}")
        }

        rolled_back = rolled_back.push(host)
    }

    logger.info("fleet fully deployed", { tag: tag, hosts: hosts.len() })
}

// ---- Stage 4: record what shipped -------------------------------------

@description("Record a signed record of this release")
@deps([deploy])
@outputs(["./releases/${git.short_commit()}.json"])
task record {
    let record = {
        service: service,
        version: git.tag() ?? "0.0.0-dev+${git.short_commit()}",
        commit: git.commit(),
        hosts: hosts,
        deployed_at: time.now().to_iso(),
        manifest_sha256: hash.sha256(script_dir() / "deploy.toml"),
    }
    path("./releases").mkdir()
    config.write(path("./releases/${git.short_commit()}.json"), record)
    logger.info("release recorded", record)
}

@description("Full pipeline: verify, build, push, deploy, record")
@deps([record])
task release {
    println("✓ ${service} ${git.tag() ?? git.short_commit()} deployed to ${hosts.len()} hosts")
}

que run release -- \
    2>&1 | tee release.log

que run release \
    --allow read \
    --allow write=releases \
    --allow exec \
    --allow net=registry.example.com,api-1.internal,api-2.internal,api-3.internal \
    --allow env=REGISTRY_USER,REGISTRY_PASSWORD

que run release --dry-run

let  mut  fn  pub  task  struct  enum  impl  trait  type
if  else  match  for  in  while  loop
return  break  continue
import  as
true  false  null
defer  try  catch  finally
with  spawn  parallel

type UserId = Int
type Handler = Function

let x = expr
mut x = expr
let [a, ...b] = expr
let { key, ...rest } = expr
fn name(params) { body }
pub fn name(params) { body }
@deps([...])
task name { body }
struct Name { field: Type = default }
enum Name { Variant, DataVariant { field: Type } }
impl Name { methods }
trait Name { methods }
impl Trait for Name { methods }
import .module
import std.module { name1, name2 }
for x in expr { body }
while cond { body }
loop { body }
return expr
break expr
continue
defer expr
try { } catch e { } finally { }
with Expr as name { body }

if cond { } else if cond { } else { }
match expr { pattern => expr, ... }
|params| expr
|params| { body }
fn(params) { body }
parallel { expr, expr }
parallel { name: expr, name: expr }
spawn `cmd`
{ block }
expr |> fn
expr..expr
expr..=expr

_                           // wildcard
42, "str", true, null       // literal
x                           // binding
[a, b, ...rest]             // list
{ key, ...rest }            // map
(a, b)                      // tuple
Ok(p), Err(p)               // result
StructName { field, ... }   // struct instance
Variant { field, ... }      // enum variant (named fields)
Variant {}                  // unit enum variant
EnumName.variant            // qualified unit enum variant
EnumName.variant(p)         // qualified positional enum variant
EnumName.variant { field }  // qualified named-field enum variant
glob("*.rs")                // glob
p1 | p2                     // or-pattern
x @ pattern                 // binding with sub-pattern
pattern if guard            // guard