Make a documentation file known to the help system
add_doc_file (String_Type file)
The add_doc_file is used to add a documentation file to the
system. Such files are searched by the
get_doc_string_from_file function. The file must be
specified using the full path.
Generate a list of functions and variables
Array_Type _apropos (String_Type ns, String_Type s, Integer_Type flags)
The _apropos function may be used to get a list of all defined
objects in the namespace ns whose name matches the regular
expression s and whose type matches those specified by
flags. It returns an array of strings containing the names
matched.
The third parameter flags is a bit mapped value whose bits
are defined according to the following table
1 Intrinsic Function
2 User-defined Function
4 Intrinsic Variable
8 User-defined Variable
define apropos (s)
{
variable n, name, a;
a = _apropos ("Global", s, 0xF);
vmessage ("Found %d matches:", length (a));
foreach name (a)
message (name);
}
If the namespace specifier ns is the empty string "",
then the namespace will default to the static namespace of the
current compilation unit.
Path of the compilation unit
String_Type __FILE__
Every private namespace has __FILE__ variable associated with
it. If the namespace is associated with a file, then the value of
this variable will be equal to the pathname of the file. If the
namespace is associated with a string, such as one passed to the
eval function, then the value of this variable will be
"***string***";
In the case of a file, the pathname may be an absolute path or a
relative one. If it is a relative one, then it will be relative to
the directory from where the file was loaded, i.e., the value
returned by the getcwd function.
Returns the name of the currently executing function
String_Type _function_name ()
This function returns the name of the currently executing function. If called from top-level, it returns the empty string.
Get the symbols defined by the preprocessor
Int_Type __get_defined_symbols ()
The __get_defined_symbols functions is used to get the list of
all the symbols defined by the S-Lang preprocessor. It pushes each
of the symbols on the stack followed by the number of items pushed.
Get the list of documentation files
String_Type[] = get_doc_files ()
The get_doc_files function returns the internal list of
documentation files as an array of strings.
Read documentation from a file
String_Type get_doc_string_from_file ([String_Type f,] String_Type t)
If called with two arguments, get_doc_string_from_file opens
the documentation file f and searches it for topic t.
Otherwise, it will search an internal list of documentation files
looking for the documentation associated with the topic t. If
found, the documentation for t will be returned, otherwise the
function will return NULL.
Files may be added to the internal list via the add_doc_file
or set_doc_files functions.
Returns a list of namespace names
String_Type[] _get_namespaces ()
This function returns a string array containing the names of the currently defined namespaces.
Determine if a variable or function is defined
Integer_Type is_defined (String_Type name)
This function is used to determine whether or not a function or variable of the given name has been defined. If the specified name has not been defined, the function returns 0. Otherwise, it returns a non-zero value that depends on the type of object attached to the name. Specifically, it returns one of the following values:
+1 intrinsic function
+2 slang function
-1 intrinsic variable
-2 slang variable
0 undefined
Consider the function:
define runhooks (hook)
{
if (2 == is_defined(hook)) eval(hook);
}
Determine whether or not a variable has a value
Integer_Type __is_initialized (Ref_Type r)
This function returns non-zero of the object referenced by r
is initialized, i.e., whether it has a value. It returns 0 if the
referenced object has not been initialized.
The function:
define zero ()
{
variable f;
return __is_initialized (&f);
}
define one ()
{
variable f = 0;
return __is_initialized (&f);
}
The number of parameters passed to a function
Integer_Type _NARGS
The value of the _NARGS variable represents the number of
arguments passed to the function. This variable is local to each
function.
This example uses the _NARGS variable to print the list of
values passed to the function:
define print_values ()
{
variable arg;
if (_NARGS == 0)
{
message ("Nothing to print");
return;
}
foreach arg (__pop_args (_NARGS))
vmessage ("Argument value is: %S", arg.value);
}
Set the internal list of documentation files
set_doc_files (String_Type[] list)
The set_doc_files function may be used to set the internal
list of documentation files. It takes a single parameter, which is
required to be an array of strings. The internal file list is set
to the files specified by the elements of the array.
The following example shows how to add all the files in a specified
directory to the internal list. It makes use of the glob
function that is distributed as part of slsh.
files = glob ("/path/to/doc/files/*.sld");
set_doc_files ([files, get_doc_files ()]);
Installed documentation directory
String_Type _slang_doc_dir
The _slang_doc_dir variable is a read-only variable that
specifies the compile-time installation location of the S-Lang
documentation.
The S-Lang library version number
Integer_Type _slang_version
_slang_version is a read-only variable that gives the version
number of the S-Lang library.
The S-Lang library version number as a string
String_Type _slang_version_string
_slang_version_string is a read-only variable that gives a
string representation of the version number of the S-Lang library.