REBOL 3 Concepts: Modules: Defining Modules

Contents

Creating a module

Modules have been designed to be easy to create in order to help you better organize and structure your programs.

To create a module you need to define two blocks:

spec	a specification block that describes the module. It is usually quite small, just a few lines to specify the title, name, and version of your module, and its exported functions. It's format is the same the headers you use for programs.
body	a block of code that is initialized when the module is created. It is used to create functions, data, objects and other values needed by the module.

Modules as files

Here is an example module showing the spec (header) and the body of the module.

REBOL [
    Title: "Stock Trading Module"
    Name: stock-trade
    Version: 1.2.0
    Type: module
    Exports: [buy sell]
]

buy: func [stock price] [...]

sell: func [stock price] [...]

This is the most common way to define a module. However, it is also possible to define a module directly within a program. (More below.)

The specification header

The specification block (called the "spec") is written as a standard header, just like that used for programs. It is prototype is defined by system/standard/header.

The most important spec fields used for modules are:

Field	Datatype	Description
type	word!	Indicates that the file is a module. This field must be set to the word module or the file will be processed by do as normal program code, not as a module.
title	string!	The title of your module. This field can be used for directories, libraries, browsing, and user messages.
name	word!	The name of the module. Identifies the module within the system, such as the argument for import. This field is important because it helps prevent a module from being reloaded if it's already been loaded earlier.
version	tuple!	The version of the module. Multiple versions are allowed to be loaded at the same time, and the import function can be used to request that a specific version or greater be used.
needs	block!	A list of other modules that your module needs to work. These other modules will be imported first, before the code in your module runs. Only used by module scripts, not dynamic modules.
exports	block!	Provides a list of words that are exported by the module to the system's standard export list (if your module is named). (Do not confuse export with public/private properties. More below.)

When a module is created, the specification is converted to an object and the fields of the object are used to control the behavior of the module.

The example above shows an example with a few fields, but depending on your requirements other fields can be provided. Also, you are free to add your own fields, as needed.

The body block

The body block is identical to an object initialization block. It defines the functions and data of the module. Normally, the body block is evaluated when the module is created.

In the example above, the buy and sell functions are defined in the body block, and exported via the exports block of the spec.

Making modules dynamically

Modules can be dynamically created by using the make constructor, in the general form:

mod: make module! [spec body]

where the spec and body are both blocks, as noted above, and mod is the new module.

The module shortcut function is also provided. (This function is similar to func or function helper functions.)

The format is:

mod: module spec body

Now, the earlier stock-trade example can be written:

stocks: module [
    Title: "Stock Trading Module"
    Name: stock-trade
    Version: 1.2.0
    Type: module
    Exports: [buy sell]
][
    buy: func [stock price] [...]
    sell: func [stock price] [...]
]

Note that modules created in this way are not automatically imported into the system. In other words, to call sell, you would need to write:

stocks/sell "acme" $20.00

To import the module, simply import the module, and then you can use its exported functions directly:

import stocks
sell "acme" $20.00

Modules created dynamically don't process the needs block.

Module locations

Modules can be stored in three locations:

• On a website, accessible via HTTP.
• On your local filesystem, in one of a few directories.
• Within other programs (as dynamic modules).

You can change where the system looks for modules by modifying the system/options/module-paths block.

For example, to search first in a directory that you've created:

insert system/options/module-paths %/c/reb-mods/

Or, use append to search there last (after searching all other paths).

Add that line to your rebol.r file if you want to do it each time you run REBOL.

Standard modules for a variety of useful functions will be available on REBOL.com, REBOL.net, and other sites. They can be accessed and updated using DevBase.

Editor note: This section is new or has has recently changed and is still under construction.

Module namespaces

Important notes.