4.4 Require Statement

     Syntax:   require string;
               require string-list;

The require statement informs the parser that a script makes use of a certain extension. Multiple capabilities can be declared using the second form of the statement. The actual handling of a capability name depends on its suffix.

If the name starts with ‘comparator-’, it is understood as a request to use the specified comparator. The comparator name consists of the characters following the suffix.

If the name starts with ‘test-’, it means a request to use the given test. The test name consists of the characters following the suffix.

Otherwise, the capability is understood as a name of an action to be used.

The require statement, if present, must be used before any other statement that is using the required capability. As an extension, the gnu sieve allows the require and any other statements to be interspersed.

By default the following actions and comparators are always required:

• stop
• keep
• discard
• i;octet
• i;ascii-casemap

Example:

     require ["fileinto", "reject"];
     
     require "fileinto";
     
     require "comparator-i;ascii-numeric";

When processing arguments for require statement, gnu libsieve uses the following algorithm:

1. Look up the name in a symbol table. If the name begins with ‘comparator-’ it is looked up in the comparator table. If it begins with ‘test-’, the test table is used instead. Otherwise the name is looked up in the action table.
2. If the name is found, the search is terminated.
3. Otherwise, transform the name. First, any ‘comparator-’ or ‘test-’ prefix is stripped. Then, any character other than alphanumeric characters, ‘.’ and ‘,’ is replaced with dash (‘-’). The name thus obtained is used as a file name of an external loadable module.
4. Try to load the module. The module is searched in the following search paths (in the order given):
   1. Mailutils module directory. By default it is $prefix/lib/mailutils.
   2. Sieve library path as given with the -L options in the command line
   3. Additional search directories specified with the #searchpath directive.
   4. The value of the environment variable LTDL_LIBRARY_PATH.
   5. System library search path: The system dependent library search path (e.g. on Linux it is set by the contents of the file /etc/ld.so.conf and the value of the environment variable LD_LIBRARY_PATH).

   The value of LTDL_LIBRARY_PATH and LD_LIBRARY_PATH must be a colon-separated list of absolute directories, for example, ‘"/usr/lib/mypkg:/lib/foo"’.

   In any of these directories, libsieve first attempts to find and load the given filename. If this fails, it tries to append the following suffixes to the file name:

   1. the libtool archive extension ‘.la’
   2. the extension used for native dynamic libraries on the host platform, e.g., ‘.so’, ‘.sl’, etc.
5. If the module is found, libsieve executes its initialization function (see below) and again looks up the name in the symbol table. If found, search terminates successfully.
6. If either the module is not found, or the symbol wasn't found after execution of the module initialization function, search is terminated with an error status. libsieve then issues the following diagnostic message:

             source for the required action NAME is not available