Docs
chromia.com

Rell modules

On this page

The Rell dapp consists of modules. A module is either a single .rell file or a directory with one or multiple .rell files.

A single-file Rell module must have a module header:

Rell
module;

// entities, operations, queries, functions, and other definitions

If a .rell file has no module header, it's part of a directory module. All such .rell files in a directory belong to the same directory module. An exception is a file called module.rell: it always belongs to a directory-module, even if it has a module header. A directory-module doesn't need to have module.rell.

Every file of a directory module sees definitions of all other module files. A file module file sees only its definitions. There may be a root module - a directory module that consists of .rell files located in the root of the source directory. The root module has an empty name.

Example of a Rell source directory tree:

Files
.
└── app
    ├── module.rell
    ├── entities.rell
    ├── operations.rell
    ├── queries.rell
    ├── functions.rell
    └── structs.rell

Understanding the file structure in depth reveals the organization and purpose behind each component, providing insights into how the module is built and operates:

  • module_name: This directory serves as the central hub for each module, housing all related files. It is the foundation where the module’s functionalities and features are defined and interconnected.

  • module.rell: This file is essential for initial module setup, including import statements and custom mount names. It serves as a blueprint, outlining how the module integrates with the broader application architecture.

    Example:

    Rell
    module;
  • entities.rell: Contains the structural backbone, housing entities, enums, and structures (for modules with up to three structs). It also includes functions for retrieving entities by ID, offering a quick reference to the module's fundamental data structures.

    Example:

    Rell
    entity house {
        index street;
        number: integer;
        key street, number;
        number_of_rooms: integer;
        number_of_floors: integer;
        floor_area: integer;
        index number_of_rooms, floor_area;
    }
  • operations.rell: Lists all the operations the module can perform. These operations are the actionable components, enabling the module to execute its primary functions.

    Example:

    Rell
    operation create_house(
        street_id: rowid,
        number: integer,
        number_of_rooms: integer,
        number_of_floors: integer,
        floor_area: integer
    ) {
        val street = street @ { .rowid == street_id };
        create house ( street, number, number_of_rooms, number_of_floors, floor_area );
    }
  • queries.rell: A repository of all queries within the module, dictating how it communicates with the database to fetch and present data.

    Example:

    Rell
    query get_houses_with_streets() = ( house, street) @* { street == house.street } ( street = .street.address, .number );
  • functions.rell: Encapsulates the core of the module's business logic. This file contains a variety of functions that define how the module processes data and responds to different inputs.

    Example:

    Rell
    function require_user(id: byte_array) = require(user @? { id }, "User with id %b does not exist".format(id));
  • structs.rell: For modules containing more than three structs, this file provides a dedicated space to maintain clarity and organization, especially in complex modules.

    Example:

    Rell
    struct user {
        name: text;
        address: text;
        mutable balance: integer = 0;
    }

Import

To access the module's definitions, you need to import the module:

Rell
import app.single;

function test() {
    single.f(); // Calling the function "f" defined in the module "app.single".
}

When importing a module, it's added to the current namespace with some alias. By default, the alias is the last part of the module name, single for the module app.single or multi for app.multi. The definitions of the module can be accessed via the alias.

A custom alias can be specified:

Rell
import alias: app.multi;

function test() {
    alias.g();
}

It's possible to specify a relative name of a module when importing. In that case, the name of the imported module is derived from the current module's name. For example, if the current module is a.b.c,

  • import .d; imports a.b.c.d
  • import alias: ^; imports a.b
  • import alias: ^^; imports a
  • import ^.e; imports a.b.e

Wildcard imports

Importing all definitions of a module:

Rell
import foo.*;

All definitions are added directly to the importing namespace.

It's possible to import definitions of a specific namespace defined within a module:

Rell
import foo.{ns.*};

An import alias, if specified, creates a nested namespace and adds imported definitions there:

Rell
import sub: foo.{ns.*};

Definitions from the namespace ns of module foo in this example are added to a new namespace sub.

Import specific definitions

To import a specific definition (or a set of definitions) from a module, specify their names in braces:

Rell
import foo.{f};
import foo.{g, h};

The definitions "f", "g", and "h" are added to the importing namespace like they were defined there.

If an import alias is specified, a nested namespace is created:

Rell
import ns: foo.{f, g};

This creates a namespace ns containing definitions f and g.

One can specify an alias for individual definitions in braces:

Rell
import foo.{a: f, b: g};

Imported definitions in this example are added to the namespace under names a and b.

Namespace import

When a program requires multiple imports, you can benefit from using namespaces, which help organize your imports into distinct groups:

Rell
namespace ft4 {
  import lib.ft4.core.accounts.{ft4_account: account};
  import lib.ft4.core.admin;
  import lib.ft4.core.auth;
  import .utils;
}

By using these namespaces, you can easily identify the source of an import when it is used in the code:

Rell
function foo() {
  ft4.admin.require_admin();
}

In this example, it is clear that the require_admin() function belongs to the ft4 namespace.

Without namespaces, managing the code and handling imports becomes more challenging:

Rell
function foo() {
  admin.require_admin();
}

Run-time

At run-time, not all modules defined in a source directory tree are active. Only the main module and all modules it imports (directly or indirectly) are active. There is a main module that is specified when starting a Rell app.

When a module is active, its operations and queries can be invoked, and tables for its entities and objects are added to the database on initialization.