21. Qualifier Functions

21.1 qualifier

Synopsis

Get the value of a qualifier

Usage

value = qualifier (String_Type name [,default_value])

Description

This function may be used to get the value of a qualifier. If the specified qualifier does not exist, NULL will be returned, unless a default value has been provided.

Example

    define echo (text)
    {
       variable fp = qualifier ("out", stdout);
       () = fputs (text, fp);
    }
    echo ("hello");              % writes hello to stdout
    echo ("hello"; out=stderr);  % writes hello to stderr

Notes

Since NULL is a valid value for a qualifier, this function is unable to distinguish between a non-existent qualifier and one whose value is NULL. If such a distinction is important, the qualifier_exists function can be used. For example,

    define echo (text)
    {
       variable fp = stdout;
       if (qualifier_exists ("use_stderr"))
         fp = stderr;
       () = fputs (text, fp);
    }
    echo ("hello"; use_stderr);  % writes hello to stderr

In this case, no value was provided for the use_stderr qualifier: it exists but has a value of NULL.

See Also

qualifier_exists, __qualifiers

21.2 __qualifiers

Synopsis

Get the active set of qualifiers

Usage

Struct_Type __qualifiers ()

Description

This function returns the set of qualifiers associated with the current execution context. If qualifiers are active, then the result is a structure representing the names of the qualifiers and their corresponding values. Otherwise NULL will be returned.

One of the main uses of this function is to pass the current set of qualifiers to another another function. For example, consider a plotting application with a function called called lineto that sets the pen-color before drawing the line to the specified point:

    define lineto (x, y)
    {
       % The color may be specified by a qualifier, defaulting to black
       variable color = qualifier ("color", "black");
       set_pen_color (color);
           .
           .
    }

The lineto function permits the color to be specified by a qualifier. Now consider a function that make use of lineto to draw a line segment between two points:

    define line_segment (x0, y0, x1, y1)
    {
       moveto (x0, y0);
       lineto (x1, y1 ; color=qualifier("color", "black"));
    }
    line_segment (1,1, 10,10; color="blue");

Note that in this implementation of line_segment, the color qualifier was explicitly passed to the lineto function. However, this technique does not scale well. For example, the lineto function might also take a qualifier that specifies the line-style, to be used as

    line_segment (1,1, 10,10; color="blue", linestyle="solid");

But the above implementation of line_segment does not pass the linestyle qualifier. In such a case, it is preferable to pass all the qualifiers, e.g.,

    define line_segment (x0, y0, x1, y1)
    {
       moveto (x0, y0);
       lineto (x1, y1 ;; __qualifiers());
    }

Note the use of the double-semi colon in the lineto statement. This tells the parser that the qualifiers are specified by a structure-valued argument and not a set of name-value pairs.

See Also

qualifier, qualifier_exists

21.3 qualifier_exists

Synopsis

Check for the existence of a qualifier

Usage

Int_Type qualifier_exists (String_Type name)

Description

This function will return 1 if a qualifier of the specified name exists, or 0 otherwise.

See Also

qualifier, __qualifiers