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

Next Previous Contents

## 5. Informational Functions

## 5.1 _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 (__pop_args (_NARGS))
  >               {
  >                  arg = ();
  >                  vmessage ("Argument value is: %S", arg.value);
  >               }
  >          }

  > `

See Also

  `__pop_args, __push_args, typeof`

## 5.2 __get_defined_symbols

Synopsis

  Get the symbols defined by the preprocessor

Usage

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

## 5.3 __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

  For 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.
Notes

  It is easy to see why a reference to the variable must be passed to `__is_initialized` and not the variable itself; otherwise, the value of the variable would be passed and the variable may have no value if it was not initialized.

See Also

  `__get_reference, __uninitialize, is_defined, typeof, eval`

## 5.4 _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 representing the matches.

  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 (a)
  >             {
  >                name = ();
  >                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`

## 5.5 _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`

## 5.6 _slang_doc_dir

Synopsis

  Installed documentation directory

Usage

  `String_Type _slang_doc_dir;`

Description

  The `_slang_doc_dir` variable is a read-only whose value specifies the installation location of the S-lang documentation.

See Also

  `get_doc_string_from_file`

## 5.7 _slang_version

Synopsis

  The S-Lang library version number

Usage

  `Integer_Type _slang_version`

Description

  The `_slang_version` variable is read-only and and whose value represents the number of the S-lang library.

See Also

  `_slang_version_string`

## 5.8 _slang_version_string

Synopsis

  The S-Lang library version number as a string

Usage

  `String_Type _slang_version_string`

Description

  The `_slang_version_string` variable is read-only and whose value represents the version number of the S-lang library.

See Also

  `_slang_version`

## 5.9 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

  `get_doc_string_from_file` opens the documentation file `f` and searches it for topic `t`. It returns the documentation for `t` upon success, otherwise it returns `NULL` upon error. It will fail if `f` could not be opened or does not contain documentation for the topic.

See Also

  `stat_file`

See Also

  `_slang_doc_dir`

## 5.10 is_defined

Synopsis

  Indicate whether a variable or function defined.

Usage

  `Integer_Type is_defined (String_Type obj)`

Description

  This function is used to determine whether or not a function or variable whose name is `obj` has been defined. If `obj` is not defined, the function returns 0. Otherwise, it returns a non-zero value that defpends on the type of object `obj` represents. Specifically, it returns one of the following values:

  > `

  >          +1 if an intrinsic function
  >          +2 if user defined function
  >          -1 if intrinsic variable
  >          -2 if user defined variable
  >           0 if undefined

  > `

Example

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

Next Previous Contents