ArxLang 1.27.0

Documentation

Modules

Modules

A module in Arx is a source file (for example, math.x) containing top-level statements such as imports, function definitions, and extern declarations.

Module Layout

```
title: Math module example
summary: Module with one documented function.
```
fn average(x: f32, y: f32) -> f32:
  ```
  title: average
  summary: Returns the arithmetic mean of x and y.
  ```
  return (x + y) * 0.5

Package Layout

When a project uses the default src/ source root, or declares [build].src_dir, Arx treats files under that source root as package modules addressed by dotted names.

Example project layout:

.
├── .arxproject.toml
├── src
│   └── geometry
│       ├── __init__.x
│       ├── shared
│       │   └── math.x
│       └── shapes
│           ├── area.x
│           └── helpers.x
└── tests
    └── test_area.x

With the default src/ source root:

Use __init__.x as the package root, following the same layout idea as Python packages.

Import Syntax

import geometry.shapes.area
import geometry.shapes.area as area

import circle_area from geometry.shapes.area
import circle_area as area_of_circle from geometry.shapes.area

import (circle_area, square_area) from geometry.shapes.area

import radius_to_diameter from .helpers
import (circle_area, square_area) from .area
import clamp from ..shared.math

Rules:

Absolute Imports

Use absolute dotted paths for public imports across package boundaries:

import circle_area from geometry.shapes.area

Installed Package Imports

Arx can also resolve absolute imports from installed Arx source packages declared in [project].dependencies in .arxproject.toml.

For example, if the current project declares an installed dependency that exposes a package root named local_lib, this import resolves from that installed package when no local project source shadows it:

import sum2 from local_lib.stats

Installed package lookup is scoped to the current Python environment running arx. The compiler reads installed distribution metadata, follows transitive dependency metadata, and uses packaged .arxproject.toml files to find Arx source roots. It does not install packages, access the network, or change generated IR/codegen behavior.

For installed packages with the normal project layout, place .arxproject.toml at the packaged project root and declare both [build].src_dir and [build].package:

site-packages/local_lib_project/
├── .arxproject.toml
└── src
    └── local_lib
        ├── __init__.x
        └── stats.x

[build]
src_dir = "src"
package = "local_lib"

With that layout, local_lib.stats resolves to site-packages/local_lib_project/src/local_lib/stats.x.

Flat package layouts are also supported for packages that place .arxproject.toml and .x files directly in the package directory:

site-packages/local_lib/
├── .arxproject.toml
├── __init__.x
└── stats.x

Resolution precedence is:

  1. local/current project source files
  2. installed Arx dependency packages
  3. unresolved import error

The reserved stdlib and internal builtins namespaces always remain owned by the compiler and cannot be replaced by installed packages.

Bundled stdlib

Arx ships a first-party standard library namespace called stdlib.

Example:

import math from stdlib

fn main() -> i32:
  return math.square(4) + math.clamp(0 - 3, 0, 2)

Bundled builtins

Compiler-provided builtins live in bundled .x package resources, separately from the importable stdlib. They are not copied into user projects, and local sources cannot replace the reserved namespace. Ambient names are injected only when not shadowed by a declaration or import. Explicit builtins.files imports resolve the canonical File class, not a second implementation.

Builtin range currently allocates a scalar list; its declaration lives in packages/arx/src/arx/builtins/generators.x. See for-in workflows and list ownership. The module name does not imply Arx supports general generators or yield.

Namespace Imports

Use a module alias when you want to keep names grouped under a module namespace:

```
title: Geometry namespace import
summary: Call one module member through a namespace alias.
```
import geometry.shapes.area as area

fn main() -> f64:
  ```
  title: main
  summary: Demonstrates namespace member access.
  ```
  return area.circle_area(10.0)

Direct symbol imports remain available when you prefer shorter local names:

import circle_area from geometry.shapes.area

Relative Imports

Use relative from imports for package-internal references. For example, inside geometry.shapes.area:

import radius_to_diameter from .helpers
import clamp from ..shared.math

Module Docstring

Arx supports module docstrings in Douki YAML format, delimited by triple backticks:

```
title: Module documentation
summary: Optional summary text
```

Current placement rule:

Valid:

```
title: Module docs
```
fn main() -> i32:
  ```
  title: main
  summary: Entry point for the module.
  ```
  return 1

Invalid (leading indentation before module docstring):

  ```
  title: Module docs
  ```
fn main() -> i32:
  ```
  title: main
  summary: Entry point for the module.
  ```
  return 1

For now, module docstrings are parsed and validated but ignored by AST/IR generation.

stdlib.arrow exports Schema, BatchBuilder, RecordBatch, IPCReader and IPCWriter. It uses ordinary classes and nominal opaque native handles, not new keywords. See the Arrow API and examples. Native bindings are supplied only for the bundled reserved module; a user module cannot gain these bindings merely by declaring matching handle type names.

Tabular standard-library modules

Format classes are not exported from stdlib.arrow. Import shared types from that canonical module rather than through a format module. Namespace-qualified calls and explicit aliases work normally. Format functions are not global builtins, and equally named user functions receive no native privileges. CSV/shared Arrow do not activate the optional Parquet feature.

Search documentation

Type to search.