S-Lang Run-Time Library Reference: Version 2.0.4: Informational Functions

Next Previous Contents

## 8. Informational Functions

## 8.1 add_doc_file

Synopsis

  Make a documentation file known to the help system

Usage

  `add_doc_file (String_Type file)`

Description

  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.

See Also

  `set_doc_files, get_doc_files, get_doc_string_from_file`

## 8.2 _apropos

Synopsis

  Generate a list of functions and variables

Usage

  `Array_Type _apropos (String_Type ns, String_Type s, Integer_Type flags)`

Description

  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 second 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

  > `

Example

  > `

  >         define apropos (s)
  >         {
  >           variable n, name, a;
  >           a = _apropos ("Global", s, 0xF);

  >           vmessage ("Found %d matches:", length (a));
  >           foreach name (a)
  >             message (name);
  >         }

  > `

  prints a list of all matches.
Notes

  If the namespace specifier `ns` is the empty string `""`, then the namespace will default to the static namespace of the current compilation unit.

See Also

  `is_defined, sprintf, _get_namespaces`

## 8.3 _function_name

Synopsis

  Returns the name of the currently executing function

Usage

  `String_Type _function_name ()`

Description

  This function returns the name of the currently executing function. If called from top-level, it returns the empty string.

See Also

  `_trace_function, is_defined`

## 8.4 __get_defined_symbols

Synopsis

  Get the symbols defined by the preprocessor

Usage

  `Int_Type __get_defined_symbols ()`

Description

  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.

See Also

  `is_defined, _apropos, _get_namespaces`

## 8.5 get_doc_files

Synopsis

  Get the list of documentation files

Usage

  `String_Type[] = get_doc_files ()`

Description

  The `get_doc_files` function returns the internal list of documentation files as an array of strings.

See Also

  `set_doc_files, add_doc_file, get_doc_string_from_file`

## 8.6 get_doc_string_from_file

Synopsis

  Read documentation from a file

Usage

  `String_Type get_doc_string_from_file ([String_Type f,] String_Type t)`

Description

  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.

See Also

  `add_doc_file, set_doc_files, get_doc_files, _slang_doc_dir`

## 8.7 _get_namespaces

Synopsis

  Returns a list of namespace names

Usage

  `String_Type[] _get_namespaces ()`

Description

  This function returns a string array containing the names of the currently defined namespaces.

See Also

  `_apropos, use_namespace, implements, __get_defined_symbols`

## 8.8 is_defined

Synopsis

  Determine if a variable or function is defined

Usage

  `Integer_Type is_defined (String_Type name)`

Description

  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

  > `

Example

  Consider the function:

  > `

  >         define runhooks (hook)
  >         {
  >            if (2 == is_defined(hook)) eval(hook);
  >         }

  > `

  This function could be called from another S-Lang function to allow customization of that function, e.g., if the function represents a mode, the hook could be called to setup keybindings for the mode.
See Also

  `typeof, eval, autoload, __get_reference, __is_initialized`

## 8.9 __is_initialized

Synopsis

  Determine whether or not a variable has a value

Usage

  `Integer_Type __is_initialized (Ref_Type r)`

Description

  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.

Example

  The function:

  > `

  >         define zero ()
  >         {
  >            variable f;
  >            return __is_initialized (&f);
  >         }

  > `

  will always return zero, but

  > `

  >         define one ()
  >         {
  >            variable f = 0;
  >            return __is_initialized (&f);
  >         }

  > `

  will return one.
See Also

  `__get_reference, __uninitialize, is_defined, typeof, eval`

## 8.10 _NARGS

Synopsis

  The number of parameters passed to a function

Usage

  `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.

Example

  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);
  >          }

  > `

See Also

  `__pop_args, __push_args, typeof`

## 8.11 set_doc_files

Synopsis

  Set the internal list of documentation files

Usage

  `set_doc_files (String_Type[] list)`

Description

  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.

Example

  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 ()]);

  > `

See Also

  `get_doc_files, add_doc_file, get_doc_string_from_file`

## 8.12 _slang_doc_dir

Synopsis

  Installed documentation directory

Usage

  `String_Type _slang_doc_dir`

Description

  The `_slang_doc_dir` variable is a read-only variable that specifies the compile-time installation location of the S-Lang documentation.

See Also

  `get_doc_string_from_file`

## 8.13 _slang_version

Synopsis

  The S-Lang library version number

Usage

  `Integer_Type _slang_version`

Description

  `_slang_version` is a read-only variable that gives the version number of the S-Lang library.

See Also

  `_slang_version_string`

## 8.14 _slang_version_string

Synopsis

  The S-Lang library version number as a string

Usage

  `String_Type _slang_version_string`

Description

  `_slang_version_string` is a read-only variable that gives a string representation of the version number of the S-Lang library.

See Also

  `_slang_version`

Next Previous Contents