1This directory contains some examples of dynamically loaded modules
2that may be loaded via the `import' intrinsic function:
3
4  import ("NAME");
5
6This intrinsic function is available to applications that enable it
7via a call to the `SLang_init_import' function.  Of course, the OS
8must provide support for dynamic linking.
9
10When a slang script contains a line such as
11
12  import ("NAME");
13
14or
15
16  import ("NAME", "NAMESPACE");
17
18the interpreter will request that the operating system dynamically
19link to a shared object called NAME-module.so.  In order for such
20linking to take place, the OS must be able to find the module.  The
21search for the module takes place as follows:
22
23   First a search takes place along the set of paths returned by the
24   `get_import_module_path' function.  If not found, a search is
25   performed along the paths given by the `SLANG_MODULE_PATH'
26   environment variable.  Then the search will take place in the path
27   defined by the slang/src/Makefile MODULE_INSTALL_DIR variable.  If
28   the module has not been found along any of these paths, a system
29   dependent search will be performed (e.g., using the `LD_LIBRARY_PATH'
30   environment variable).
31
32Hence, if you are writing a module that will work with all slang
33applications, then module should be installed in the path specified by
34the Makefile variable MODULE_INSTALL_DIR, which by default is
35
36   $(exec_prefix)/lib/slang/v2/modules
37
38for this version of the library.
39
40If the module was sucessfully loaded, the slang library will call the
41function `init_NAME_ns' that NAME-module.so must define.  This
42function must have the prototype:
43
44  int init_NAME_module_ns (char *namespace);
45
46and shall return 0 upon success, or -1 if an error occurred.  The
47namespace argument corresponds to the second (optional) parameter of
48the import intrinsic indicating that the module should be imported
49into the specified namespace.  To this end, the module must call one
50of the SLns_* functions to load intrinsics into the namespace.
51
52****NOTE****
53
54  In order to support the inclusion of the module into more than one
55  namespace, this function may be called multiple times.  Hence, the
56  function should be coded in such a way that initialization code
57  that should execute no more than once does so only once.  See, e.g.,
58  the "register_pcre_type" function in pcre-module.c for an explicit
59  example.
60
61  Module writers are encouraged to supply a script called NAME.sl that
62  looks like:
63
64     import ("NAME");
65     % Optional code...
66     provide ("NAME");
67
68  Then a user would be able to load the module by using, e.g.,
69
70     require ("NAME");
71
72*************
73
74Optionally, the module may define a function called `deinit_NAME_module' that
75will be called by the interpreter to deinitialize the module.  This
76function must have the prototype:
77
78   void deinit_NAME_module (void);
79
80To ensure the correct prototypes for these functions, the module
81should include the line:
82
83    SLANG_MODULE(name);
84
85SLANG_MODULE is a macro that expands into function prototypes.
86
87See the examples in this directory for more information.
88
89To run these modules, use the slsh program in ../slsh/.
90slsh.c is a program that embeds the interpreter and may be used to
91test slang scripts.  In fact, it may be used to create unix executable
92scripts via, e.g.,
93
94#! /usr/bin/env slsh
95
96as the first line of the script.  See ../slsh/scripts subdirectory for
97examples of this approach.
98
99