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