export Statement

Overview

Filtrera supports modularity through modules, which are specialized scripts designed to expose symbols using export statements. Unlike regular scripts that utilize from statements to return tuples of values, modules provide reusable functions, constants, and types that can be imported into other scripts or modules.

A module is distinguished by:

Using export statements to declare what is visible outside the module.
Allowing multiple named exports, similar in syntax to let statements.
Providing encapsulation by exposing only explicitly exported symbols.

This approach aligns with Filtrera’s core goals: simplicity, safety, and clarity, while enabling code reuse and separation of concerns.

Module Loading Conventions

Standard Modules such as "iterators" or "math" are referenced by name in import statements:
```
import 'iterators'
import 'math'
```
Custom Modules are usually loaded by a relative or absolute path, depending on the host’s module loader. A common convention is to use a distinct file extension for modules (e.g., .module.flt) to differentiate between regular scripts and modules:
```
import './math-constants.module.flt'
```

This convention helps the runtime or host application to recognize and treat the file explicitly as a module.

Note: Because module loading depends on the host environment, users should refer to their host’s documentation on how to load external custom modules correctly.

Syntax

Exporting Symbols

To expose values, functions, types, or filters from a module, declare them with the export keyword:

export <name>[: <type>][= <value>]

<name>: The symbol name to export.
<type> (optional): Type annotation, inferred if omitted.
<value> (optional): The value for the symbol, must be a valid expression.

Example:

export pi: number = 3.14159
export greet (name: text) => $'Hello, {name}!'

Exporting Multiple Symbols

A module can have multiple export statements. Each exported symbol becomes part of that module’s public interface and is accessible when imported.

Usage

How to Import Exports From a Module

Modules are imported using the import statement. Access to exported members is done via from or by directly referencing the imported module’s namespace.

Standard module import:

import 'text'

from 'a/path/to/a/file' explode '/'

Custom module import by path:

import myModule from './my-module.module.flt'

from myModule.pi
from myModule.greet 'User'

Note: The value used to reference the imported module (e.g., text, ./my-module.module.flt) is typically determined by the host/runtime and may correspond to the module’s filename or module loader configuration.

Examples

Defining a Module With Exports

export pi: number = 3.14159
export e = 2.71828

// A pure function export
export square (n: number) => n * n

Importing and Using a Module

import './math-constants.module.flt'

from mathConstants.pi
from mathConstants.square 5
from 'Euler''s number is {mathConstants.e}'

Notes and Best Practices

Explicit Export Only: Only symbols marked with export are visible outside the module. Internal symbols declared with let remain private.
Module Naming: Use distinct extensions like .module.flt for custom modules to avoid confusion with regular scripts.
No Circular Imports: Cyclic dependencies will result in a parsing error.
No Mutable State: As Filtrera is pure at heart, exported symbols are immutable.
No Recursive Functions: Recursion is disallowed even in exported functions to maintain guaranteed termination.

Summary

The export statement in Filtrera modules allows you to share named values and functions safely and explicitly, encouraging modular design:

Use export instead of let for publicly accessible symbols.
Import modules by name for standard modules; by path (with distinctive extensions) for custom modules.
Access exported symbols via the imported namespace.
Maintain purity and clarity by preventing unintended side effects.