If you want to do any real programming in Evlan, you obviously won't want to do it all in the interpreter. This is where modules come in. A module is some Evlan code written to a file which can then be imported into other modules or into the interpreter.

Physical Issues

Modules are located in the Evlan module directory. In the source distribution, this is located in the "share/evlan/modules" subdirectory of the virtual machine source code. On Unix systems, you would normally install this to someplace like "/usr/share/evlan/modules". In the Windows binary distribution, the modules directory is just called "modules" and located next to the executable.

Within the modules directory are subdirectories named after domains. For example, the current (0.3.3) distribution comes with "evlan.org" and "fateofio.org" domains. When writing your own code, you must place it within a new folder named after your own domain. If you don't own a domain, you should make arrangements with someone who does. Of course, if you do not intend to distribute your code, this doesn't matter too much.

Evlan source code files must have the file name extension ".evlan".

Writing Modules

Modules are easy to write. A module file is just a text file containing a single Evlan expression. There is no special syntax whatsoever for writing modules.

Most modules should evaluate to an object. This object can then contain all of the module's functionality as member fields.

As an example, almost all of the modules I write look something like this:

MyModule where
   MyModule = object of
      #publicly exported stuff
      public1 = #...
      public2 = #...
   #imports
   Map = import "/evlan.org/utility/Map"
   MyOtherModule = import "MyOtherModule"
   #private symbols
   private1 = #...
   private2 = #...

Here, the variables "private1" and "private2" (as well as "Map" and "MyOtherModule") are only accessible within the file, but "public1" and "public2" are exported and can be used by anyone importing the module. As you can see, no special syntax is required to set this up.

Importing Modules

To import a module, use the "import" keyword:

import "/evlan.org/utility/Map"

"import" is followed by a string containing the path to the module. If the path starts with a / (slash), it is interpreted as an absolute path, which should start with a domain name. Otherwise, the path is interpreted relative to the module importing it, and may use the directory name ".." any number of times to refer to parent directories. Note that the ".evlan" file name extension is not included when importing a module.

The "import" expression evaluates to the result of evaluating the module's code. "import" is just an expression, like any other expression. It does not modify the namespace or have any other side effects. Normally, you would store the result of an import into a variable, which you would then use to refer to the module:

Map = import "/evlan.org/utility/Map"

You can also place data files into the module tree and import them. To import a data file, give the path including the file name extension. The "import" will then evaluate to a read-only "File" object, implementing the same interface as files that you might load through the API. Note that future versions of Evlan will probably change this to produce the file data in a form that can be used in purely functional code.

Automatic Imports

All modules in the "/evlan.org/common" directory are imported automatically by the compiler. Thus, variables like "String" and "Scalar" are automatically declared in all Evlan code and refer to their respective modules.