Next Previous Contents

5. Informational Functions

5.1 __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.2 __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, is_defined, typeof, eval

5.3 _apropos

Synopsis

Generate a list of functions and variable

Usage

Integer_Type _apropos (String_Type s, Integer_Type flags)

Description

The _apropos function may be used to get a list of all defined objects whose name consists of the substring s and whose type matches those specified by flags. It returns the number of matches. If the number returned is non-zero, that number of strings which represent the names of the matched objects will also be present on the stack.

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;
      n = _apropos (s, 0xF);
      if (n) vmessage ("Found %d matches:", n);
      else message ("No matches.");
      loop (n)
        {
           name = ();
           message (name);
        }
    }
prints a list of all matches.
Notes

Since the function returns the matches to the stack, it is possible that a stack overfow error could result if there are two many matches. If this happens, the interpreter should be recompiled to use a larger stack size.

See Also

is_defined, sprintf

5.4 _function_name

Synopsis

Returns the name of the currently executing function

Usage

String _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.5 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

5.6 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