1\function{qualifier}
2\synopsis{Get the value of a qualifier}
3\usage{value = qualifier (String_Type name [,default_value])}
4\description
5 This function may be used to get the value of a qualifier.  If the
6 specified qualifier does not exist, \NULL will be returned,
7 unless a default value has been provided.
8\example
9#v+
10    define echo (text)
11    {
12       variable fp = qualifier ("out", stdout);
13       () = fputs (text, fp);
14    }
15    echo ("hello");              % writes hello to stdout
16    echo ("hello"; out=stderr);  % writes hello to stderr
17#v-
18\notes
19 Since \NULL is a valid value for a qualifier, this function is
20 unable to distinguish between a non-existent qualifier and one whose
21 value is \NULL.  If such a distinction is important, the
22 \ifun{qualifier_exists} function can be used.  For example,
23#v+
24    define echo (text)
25    {
26       variable fp = stdout;
27       if (qualifier_exists ("use_stderr"))
28         fp = stderr;
29       () = fputs (text, fp);
30    }
31    echo ("hello"; use_stderr);  % writes hello to stderr
32#v-
33 In this case, no value was provided for the \exmp{use_stderr}
34 qualifier: it exists but has a value of \NULL.
35\seealso{qualifier_exists, __qualifiers}
36\done
37
38\function{__qualifiers}
39\synopsis{Get the active set of qualifiers}
40\usage{Struct_Type __qualifiers ()}
41\description
42 This function returns the set of qualifiers associated with the
43 current execution context.  If qualifiers are active, then the result
44 is a structure representing the names of the qualifiers and their
45 corresponding values.  Otherwise \NULL will be returned.
46
47 One of the main uses of this function is to pass the current set of
48 qualifiers to another another function.  For example, consider a
49 plotting application with a function called called \exmp{lineto} that
50 sets the pen-color before drawing the line to the specified point:
51#v+
52    define lineto (x, y)
53    {
54       % The color may be specified by a qualifier, defaulting to black
55       variable color = qualifier ("color", "black");
56       set_pen_color (color);
57           .
58           .
59    }
60#v-
61 The \exmp{lineto} function permits the color to be specified by a
62 qualifier.  Now consider a function that make use of lineto to draw a
63 line segment between two points:
64#v+
65    define line_segment (x0, y0, x1, y1)
66    {
67       moveto (x0, y0);
68       lineto (x1, y1 ; color=qualifier("color", "black"));
69    }
70    line_segment (1,1, 10,10; color="blue");
71#v-
72 Note that in this implementation of \exmp{line_segment}, the
73 \exmp{color} qualifier was explicitly passed to the \exmp{lineto}
74 function.  However, this technique does not scale well.  For example, the
75 \exmp{lineto} function might also take a qualifier that specifies the
76 line-style, to be used as
77#v+
78    line_segment (1,1, 10,10; color="blue", linestyle="solid");
79#v-
80 But the above implementation of \exmp{line_segment} does not pass the
81 \exmp{linestyle} qualifier.  In such a case, it is preferable to pass
82 all the qualifiers, e.g.,
83#v+
84    define line_segment (x0, y0, x1, y1)
85    {
86       moveto (x0, y0);
87       lineto (x1, y1 ;; __qualifiers());
88    }
89#v-
90 Note the use of the double-semi colon in the \exmp{lineto}
91 statement.  This tells the parser that the qualifiers are specified
92 by a structure-valued argument and not a set of name-value pairs.
93\seealso{qualifier, qualifier_exists}
94\done
95
96\function{qualifier_exists}
97\synopsis{Check for the existence of a qualifier}
98\usage{Int_Type qualifier_exists (String_Type name)}
99\description
100 This function will return 1 if a qualifier of the specified name
101 exists, or 0 otherwise.
102\seealso{qualifier, __qualifiers}
103\done
104
105