Skip to content

modules.md

Latest commit

 

History

History
226 lines (161 loc) · 4.89 KB

modules.md

File metadata and controls

226 lines (161 loc) · 4.89 KB

Modules and Standard Library

Importing Modules

Use the import statement to bring in other Olive files. Dots in the module name map to directory separators:

import math
import utilities.network
import physics.gravity as gravity

let x = math.sqrt(16)
let g = gravity.G

By default, import math looks for math.liv in the same directory as the current file.

Top-Level Execution and Imported Modules

Olive separates imported modules from executable main scripts by placing strict restrictions on top-level execution:

  • Entry Point Only: Only the file executed directly by the pit run command is treated as the "main" script. The compiler automatically executes its top-level statements and calls its main() function (if defined).
  • Imported Modules: When a module is imported by another file, its top-level statements (such as prints, loops, or direct function calls) are not executed. The compiler only processes variable declarations, constants, structures, and function definitions.
  • Safe, Side-Effect-Free Imports: This design ensures that importing a file never produces unexpected side effects (like initiating network calls, print outputs, or database connections). It makes modules completely safe, predictable, and modular.

From-Imports

If you only need specific names from a module, use from ... import:

from math import sqrt, pi
from data.processing import clean_string as clean, parse_json as parse

print(sqrt(pi))
let data = parse(clean(raw_input))

Native Imports

If a library is written in another language (like C or Rust), it can be used in Olive by defining its interface through a native import.

import "physics.so" as physics

let result = physics.compute_gravity(10.0, 5.0)

The compiler manages symbol resolution and calling convention compliance.

Visibility and Privacy

Olive uses a naming convention for visibility:

  • Public: Any name that doesn't start with an underscore. Accessible from other modules.
  • Private: Names starting with _ are private to the module where they're defined. The compiler enforces this.
// In utils.liv
fn _secret():
    pass

// In main.liv
import utils
// utils._secret()  // Error: cannot access private member `_secret`

Project Organization

A typical project layout:

my_project/
├── main.liv
├── models.liv
└── utils/
    ├── __init__.liv (optional)
    └── network.liv

In main.liv:

import models
import utils.network

Standard Library

The standard library is resolved dynamically at runtime and exposed via built-in namespaces.

math

import math

Constants

math.PI    // 3.141592653589793
math.E     // 2.718281828459045
math.TAU   // 6.283185307179586
math.INF   // 1.0e308

Trigonometry (all angles in radians)

math.sin(x)         math.asin(x)
math.cos(x)         math.acos(x)
math.tan(x)         math.atan(x)
                    math.atan2(y, x)
math.degrees(x)     // radians -> degrees
math.radians(x)     // degrees -> radians

Exponential and logarithm

math.exp(x)         // e^x
math.log(x)         // natural log
math.log10(x)       // log base 10
math.pow(b, e)      // b^e (floats)
math.ipow(b, e)     // b^e (integers)

Roots and rounding

math.sqrt(x)
math.cbrt(x)
math.hypot(x, y)    // sqrt(x² + y²)
math.floor(x)       // -> int
math.ceil(x)        // -> int
math.round(x)       // -> int
math.abs(x)
math.clamp(x, lo, hi)
math.fmod(x, y)
math.copysign(x, y)

Hyperbolic

math.sinh(x)    math.asinh(x)
math.cosh(x)    math.acosh(x)
math.tanh(x)    math.atanh(x)

Number theory

math.gcd(a, b)
math.lcm(a, b)
math.factorial(n)
math.comb(n, k)     // n choose k
math.perm(n, k)     // n permute k

Utilities

math.min(a, b)
math.max(a, b)
math.isclose(a, b)  // abs(a - b) < 1e-9
math.erf(x)

io

Synchronous file operations:

import io

let contents = io.file_read("data.txt")
io.file_write("output.txt", "hello")

aio

Asynchronous file operations that return futures. Must be used with await:

import aio

async fn read_file():
    let contents = await aio.async_file_read("data.txt")
    await aio.async_file_write("output.txt", contents)

net

Low-level TCP networking:

import net

let stream = net.tcp_connect("127.0.0.1:8080")
net.tcp_send(stream, "GET / HTTP/1.0\r\n\r\n")
let response = net.tcp_recv(stream, 4096)
net.tcp_close(stream)

http

Simple HTTP client:

import http

let body = http.http_get("https://example.com/api/data")
let resp = http.http_post("https://example.com/api/submit", "{\"key\": \"value\"}")

random

Random number generation:

import random

random.random_seed(42)
let f = random.random_get()          // float in [0.0, 1.0)
let n = random.random_int(1, 100)    // int in [1, 100]