Getting Started

Get up and running with Behl in minutes.

Table of contents

1. Installation
   1. Prerequisites
   2. Building from Source
   3. Installation
2. Your First Script
   1. Hello, World!
   2. Variables and Types
   3. Functions
   4. Control Flow
   5. Tables
3. Interactive Mode (REPL)
4. Debugging
   1. Viewing Bytecode
   2. Error Messages
   3. Protected Calls
5. Standard Library
   1. Available Modules
   2. Importing Modules
6. Next Steps
7. Getting Help

---

Installation

Prerequisites

• CMake 3.26 or higher
• C++20 compatible compiler:
  • MSVC 2022+
  • GCC 11+
  • Clang 14+

Building from Source

# Clone the repository
git clone https://github.com/behl-lang/behl.git
cd behl

# Configure with CMake
cmake -B build -DCMAKE_BUILD_TYPE=Release

# Build (cross-platform)
cmake --build build --config Release

# Run tests (optional)
cd build
ctest -C Release --output-on-failure

Note: The executable will be located in:

• Multi-config generators (MSVC, Xcode): build/Release/behl[.exe]
• Single-config generators (Make, Ninja): build/behl

Installation

# Install system-wide (optional)
sudo cmake --install build

---

Your First Script

Hello, World!

Create a file hello.behl:

print("Hello, World!");

Run it:

# Run the script
./behl hello.behl

Note: On Windows, use behl.exe instead of behl.

Output:

Hello, World!

Variables and Types

// Variables with let
let x = 42;
let name = "behl";
let pi = 3.14159;
let isActive = true;

// Constants
const MAX_SIZE = 1000;

// Type checking
print(typeof(x));        // "integer"
print(typeof(pi));       // "number"
print(typeof(name));     // "string"
print(typeof(isActive)); // "boolean"

Functions

// Define a function
function greet(name) {
    return "Hello, " + name + "!";
}

// Call it
let message = greet("World");
print(message); // "Hello, World!"

// Functions are first-class values
let fn = greet;
print(fn("behl")); // "Hello, behl!"

Control Flow

// If/else
let x = 10;
if (x > 5) {
    print("x is greater than 5");
} elseif (x == 5) {
    print("x is 5");
} else {
    print("x is less than 5");
}

// While loop
let i = 0;
while (i < 5) {
    print(i);
    i = i + 1;
}

// For loop
for (let j = 0; j < 5; j++) {
    print(j);
}

Tables

Tables are the primary data structure in Behl - they work as arrays, dictionaries, and objects:

// Array-like (0-indexed)
let arr = {10, 20, 30, 40};
print(arr[0]); // 10
print(arr[3]); // 40

// Dictionary-like
let person = {
    ["name"] = "Alice",
    ["age"] = 30,
    ["city"] = "Seattle"
};
print(person["name"]); // "Alice"

// Iteration with pairs
for (k, v in pairs(person)) {
    print(k + ": " + tostring(v));
}

---

Interactive Mode (REPL)

Start the interactive read-eval-print loop without any arguments:

./behl

This launches an interactive session where you can type Behl code and see results immediately:

Behl REPL
> let x = 42
> print(x)
42
> function greet(name) { return "Hello, " + name }
> greet("World")
Hello, World
> exit()

---

Debugging

Viewing Bytecode

You can dump the compiled bytecode to understand how your code is executed:

# Dump bytecode to console
./behl -b script.behl

Error Messages

Behl provides detailed error messages with stack traces:

function divide(a, b) {
    if (b == 0) {
        error("Division by zero!");
    }
    return a / b;
}

divide(10, 0); // RuntimeError: Division by zero!

Protected Calls

Use pcall to catch errors:

function risky() {
    error("Something went wrong!");
}

let success, result = pcall(risky);
if (!success) {
    print("Error caught: " + result);
}

---

Standard Library

Load the standard library for access to built-in functions and modules:

// When embedding in C++
behl::State* S = behl::new_state();

// Option 1: Make modules globally accessible
behl::load_stdlib(S);
// Usage: string.upper("hello"), math.sqrt(16)

// Option 2: Require explicit import() for better control
behl::load_stdlib(S);
// Usage: let str = import("string"); str.upper("hello")

Available Modules

• Core - typeof(), pairs(), import(), pcall(), error()
• Math - Math functions and constants
• String - String manipulation functions
• Table - Table utilities
• OS - Operating system functions

Importing Modules

const math = import("math");
print(math.PI);        // 3.14159...
print(math.sqrt(16));  // 4

---

Next Steps

• Explore the Language reference for complete syntax details
• Check out the Standard Library documentation
• Learn about compiler optimizations and performance
• Learn about embedding Behl in C++ applications
• Read Examples for practical code samples

---

Getting Help

• GitHub Issues - Report bugs or request features
• Discussions - Ask questions and share ideas
• Examples - Check the docs/examples.md documentation