Frequently Asked Questions

Common questions and answers about the Zamin programming language.

How do I install Zamin?

Build Zamin from source (the only supported installation method):

git clone https://github.com/young-developer90/zamin.git
cd zamin
cargo build --release

The binary will be at target/release/zamin. Add it to your PATH.

How do I concatenate strings?

Use the + operator (both operands must be strings) or the .. operator (coerces non-strings).

let greeting = "Hello" + " " + "World";
print(greeting);  // "Hello World"

// Use .. to coerce non-strings to strings
let n = 42;
print("The answer is " .. n);  // "The answer is 42"

// f-strings are preferred for interpolation
let name = "Alice";
print("Hello {name}");

What's the difference between let and const?

let declares a mutable variable. const declares an immutable constant that must be assigned at compile time.

let x = 10
x = 20  // OK

const PI = 3.14159
PI = 3.0  // Error: cannot reassign constant

How do I read files?

Use the fs standard library module:

let content = fs.read("data.txt");
print(content);

// Write to a file
fs.write("output.txt", "Hello, Zamin!");

How do I make HTTP requests?

Use the http module:

let resp = http.get("https://api.example.com/data");
print(resp.status);    // 200
print(resp.body);      // response body string

// POST with JSON body
let resp2 = http.post("https://api.example.com/submit",
    json.stringify({"name": "Alice", "email": "alice@example.com"})
);
print(resp2.status);

How do I handle errors?

Zamin uses try/catch for error handling and throw to raise errors:

try {
    let content = fs.read("nonexistent.txt");
} catch (e) {
    print(f"Error: {e}");
}

// Throw errors explicitly
func validate(n) {
    if n < 0 {
        throw Error("negative value not allowed");
    }
    return n;
}

try {
    validate(-1);
} catch (e) {
    print(f"Caught: {e}");
}

How do I use regular expressions?

Use the re module:

let text = "Contact: user@example.com, admin@test.com";

let first = re.find(r"[\w.]+@[\w.]+", text);
print(first);                          // "user@example.com"

let all = re.find_all(r"[\w.]+@[\w.]+", text);
print(all);                            // ["user@example.com", "admin@test.com"]

// Check if pattern matches
print(re.is_match(r"\d+", "abc 123"));  // true

// Replace matches
let cleaned = re.sub(r"\d+", "#", "abc 123 def 456");
print(cleaned);                         // "abc # def 456"

// Extract capture groups
let caps = re.captures(r"(\w+)@(\w+)", "user@example.com");
print(caps);                            // ["user@example.com", "user", "example.com"]

How do I parse JSON?

Use the json module:

let data = json.parse('{"name": "Alice", "age": 30}');
print(data["name"]);   // "Alice"
print(data["age"]);    // 30

// Serialize to JSON string
let obj = {"name": "Bob", "age": 25};
let str = json.stringify(obj);
print(str);             // {"name":"Bob","age":25}

// Pretty-print with indentation
print(json.pretty(obj));

How do I create a project?

Use the zamin new command:

zamin new my_project
cd my_project
zamin run src/main.zamin

This creates the standard project layout with zamin.json, src/main.zamin, tests/, and modules/ directories.

How do I run tests?

Write test functions using the test module, then run zamin test:

use test

func test_addition() {
    test.assert_eq(1 + 1, 2);
}

func test_string_upper() {
    test.assert_eq("hello".upper(), "HELLO");
}

zamin test

Filter tests by name: zamin test addition.

Does Zamin support multithreading?

Zamin uses a single-threaded VM with cooperative concurrency via fibers (lightweight coroutines). Each fiber runs within the same thread and yields control explicitly, allowing concurrent task scheduling without shared-state synchronization issues.

For CPU-bound work, Zamin can spawn independent processes via the subprocess module. True parallelism across multiple OS threads is available through Rust's embedding API when calling Zamin from a multi-threaded Rust application.

How do I use GUI on Linux?

Zamin includes a built-in GUI toolkit that works on Linux via GTK4. Install the required system dependencies:

# Ubuntu/Debian
sudo apt install libgtk-4-dev

# Fedora
sudo dnf install gtk4-devel

Then use the luna module (build with --features luna):

let win = luna.Leo("My App", 800, 600);
let label = luna.Label(win, "Hello, Linux!");
luna.pack(label);
luna.mainloop(win);

See the GUI Guide for full details.

How do I use OpenCV?

Zamin wraps OpenCV through the cv module. Install OpenCV on your system first, then:

use cv

let img = cv.imread("photo.jpg")
let gray = cv.cvtColor(img, cv.COLOR_BGR2GRAY)
let edges = cv.canny(gray, 50, 150)
cv.imwrite("edges.jpg", edges)
print("Saved edges.jpg")

See the OpenCV Guide for full details.

Why is my program slow?

Common causes and fixes:

• String concatenation in loops - Use f-strings or list.join() instead of repeated + on strings.
• Global variable access - Local variables are ~10x faster. Cache globals in locals when accessing them in tight loops.
• Repeated list allocation - Use list.new(capacity) to pre-allocate.
• Unoptimized build - Use zamin build for release builds with AOT optimizations.
• Suboptimal algorithm - Profile first with zamin run --disassemble to inspect bytecode, then consider algorithmic improvements.

See the Performance page for detailed benchmarks and optimization techniques.

How can I contribute to Zamin?

Zamin is open source under the MIT license. To contribute:

• Report bugs — Open an issue at github.com/young-developer90/zamin/issues
• Submit code — Fork the repo, create a feature branch, and open a pull request
• Improve docs — All documentation is in the docs/ directory as HTML files
• Share feedback — Feature requests and suggestions are welcome on the issue tracker

See the README for build instructions and project structure.

How do I embed Zamin in my Rust application?

Zamin is published on crates.io. Add it as a dependency and use the embedding API:

// Cargo.toml
[dependencies]
zamin = "1.7.3"

// main.rs
func main() {
    zamin::execute_source(r#"
        print("Hello from embedded Zamin!");
    "#).unwrap();

    zamin::execute_file("scripts/plugin.zamin").unwrap();
}

See the Embedding in Rust section for the full API reference.