![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to macros.nr CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 42BSD / ingres / doc / quel|
Return to macros.nr CVS log | Up to [CSRG BSD Unix] / 42BSD / ingres / doc / quel |
1.1 root 1: .th MACROS QUEL 2/19/79
2: .sh NAME
3: macros \- terminal monitor macro facility
4: .sh DESCRIPTION
5: The terminal monitor macro facility
6: provides the ability
7: to tailor the QUEL language
8: to the user's tastes.
9: The macro facility
10: allows strings of text
11: to be removed from the query stream
12: and replaced with other text.
13: Also,
14: some built in macros
15: change the environment
16: upon execution.
17: .s1
18: .bd "Basic Concepts"
19: .s2
20: All macros are composed of two parts,
21: the
22: .it template
23: part and the
24: .it replacement
25: part.
26: The template part defines when the macro
27: should be invoked.
28: For example,
29: the template
30: ``ret''
31: causes the corresponding macro
32: to be invoked upon encountering
33: the word
34: ``ret''
35: in the input stream.
36: When a macro is encountered,
37: the template part is removed
38: and replaced with the replacement part.
39: For example,
40: if the replacement part of the
41: ``ret'' macro
42: was ``retrieve'',
43: then all instances of the word
44: ``ret'' in the input text
45: would be replaced with the word
46: ``retrieve'',
47: as in the statement
48: .s3
49: ret (p.all)
50: .s3
51: Macros may have parameters,
52: indicated by a dollar sign.
53: For example,
54: the template
55: ``get $1''
56: causes the macro to be triggered by the word
57: ``get''
58: followed by any other word.
59: The word following ``get''
60: is remembered
61: for later use.
62: For example,
63: if the replacement part
64: of the ``get'' macro
65: where
66: .s3
67: retrieve (p.all) where p.pnum = $1
68: .s3
69: then typing ``get 35''
70: would retrieve all information about part number 35.
71: .s1
72: .bd "Defining Macros"
73: .s2
74: Macros can be defined
75: using the special macro called
76: ``define''.
77: The template for the define macro
78: is (roughly)
79: .s3
80: {define; $t; $r}
81: .s3
82: where $t and $r are the template and replacement
83: parts of the macro, respectively.
84: .s3
85: Let's look at a few examples.
86: To define the ``ret'' macro
87: discussed above,
88: we would type:
89: .s3
90: {define; ret; retrieve}
91: .s3
92: When this is read,
93: the macro processor
94: removes everything between the curly braces
95: and updates some tables
96: so that ``ret'' will be recognized
97: and replaced with the word ``retrieve''.
98: The define macro has the null string
99: as replacement text,
100: so that this macro seems to disappear.
101: .s3
102: A useful macro
103: is one which shortens range statements.
104: It can be defined
105: with
106: .s3
107: {define; rg $v $r; range of $v is $r}
108: .s3
109: This macro causes the word ``rg'' followed by the
110: next two words
111: to be removed and replaced
112: by the words
113: ``range of'',
114: followed by the first word which followed ``rg'',
115: followed by the word ``is'',
116: followed by the second word
117: which followed ``rg''.
118: For example,
119: the input
120: .s3
121: rg p parts
122: .s3
123: becomes the same as
124: .s3
125: range of p is parts
126: .s3
127: .s1
128: .bd "Evaluation Times"
129: .s2
130: When you type in a define statement,
131: it is not processed immediately,
132: just as queries are saved
133: rather than executed.
134: No macro processing is done
135: until the query buffer
136: is evaluated.
137: The commands
138: \ego,
139: \elist,
140: and \eeval
141: evaluate the query buffer.
142: \ego sends the results
143: to \*(II,
144: \elist prints them on your terminal,
145: and \eeval
146: puts the result back into the query buffer.
147: .s3
148: It is important to evaluate any define statements,
149: or it will be exactly like you did not type them in
150: at all.
151: A common way to define macros is to type
152: .s3
153: {define . . . }
154: .br
155: \eeval
156: .br
157: \ereset
158: .s3
159: If the \eeval was left out,
160: there is no effect at all.
161: .s1
162: .bd "Quoting"
163: .s2
164: Sometimes strings must be passed
165: through the macro processor
166: without being processed.
167: In such cases the grave and acute accent marks
168: (\*g and \*a)
169: can be used to surround the literal text.
170: For example,
171: to pass the word ``ret''
172: through without converting it to ``retrieve''
173: we could type
174: .s3
175: \*gret\*a
176: .s3
177: Another use for quoting is during parameter collection.
178: If we want to enter more than one word
179: where only one was expected,
180: we can surround the parameter with accents.
181: .s3
182: The backslash character
183: quotes only the next character
184: (like surrounding the character with accents).
185: In particular,
186: a grave accent can be used literally
187: by preceeding it
188: with a backslash.
189: .s3
190: Since macros can normally only be on one line,
191: it is frequently useful to use a backslash
192: at the end of the line
193: to hide the newline.
194: For example,
195: to enter the long ``get'' macro,
196: you might type:
197: .nf
198: {define; get $n; retrieve (e.all) \e
199: where e.name = "$n"}
200: .fi
201: .s3
202: The backslash always quotes
203: the next character
204: even when it is a backslash.
205: So, to get a real backslash,
206: use two backslashes.
207: .s1
208: .bd "More Parameters"
209: .s2
210: Parameters need not be limited
211: to the word following.
212: For example,
213: in the template descriptor
214: for define:
215: .s3
216: {define; $t; $r}
217: .s3
218: the $t parameter ends at the first semicolon
219: and the $r parameters ends at the first
220: right curly brace.
221: The rule is that the character
222: which follows the parameter
223: specifier
224: terminates the parameter;
225: if this character is a space,
226: tab,
227: newline,
228: or the end of the template
229: then one word is collected.
230: .s3
231: As with all good rules,
232: this one has an exception.
233: Since system macros are always surrounded by curly braces,
234: the macro processor knows that they must be properly nested.
235: Thus, in the statement
236: .s3
237: {define; x; {sysfn}}
238: .s3
239: The first right curly brace will close the ``sysfn''
240: rather than the ``define''.
241: Otherwise this would have to be typed
242: .s3
243: {define; x; \*g{sysfn}\*a}
244: .s3
245: .s3
246: Words are defined in the usual way,
247: as strings of letters and digits
248: plus the underscore character.
249: .s1
250: .bd "Other Builtin Macros"
251: .s2
252: There are several other macros
253: built in to the macro processor.
254: In the following description,
255: some of the parameter specifiers are marked
256: with two dollar signs rather than one;
257: this will be discussed in the section on prescanning below.
258: .s3
259: {define; $$t; $$r}
260: defines a macro as discussed above.
261: Special processing occurs on the template part
262: which will be discussed in a later section.
263: .s3
264: {rawdefine; $$t; $$r}
265: is another form of define,
266: where the special processing does not take place.
267: .s3
268: {remove; $$n}
269: removes the macro
270: with name $n.
271: It can remove more than one macro,
272: since it actually removes all macros
273: which might conflict
274: with $n
275: under some circumstance.
276: For example,
277: typing
278: .s3
279: {define; get part $n; . . . }
280: .br
281: {define; get emp $x; . . . }
282: .br
283: {remove; get}
284: .s3
285: would cause both the get macros to be removed.
286: A call to
287: .s3
288: {remove; get part}
289: .s3
290: would have only removed
291: the first macro.
292: .s3
293: {type $$s}
294: types $s onto the terminal.
295: .s3
296: {read $$s}
297: types $s and then reads a line
298: from the terminal.
299: The line which was typed
300: replaces the macro.
301: A macro called ``{readcount}''
302: is defined
303: containing the number of characters read.
304: A control-D
305: (end of file)
306: becomes \*-1,
307: a single newline becomes zero,
308: and so forth.
309: .s3
310: {readdefine; $$n; $$s}
311: also types $s and reads a line,
312: but puts the line
313: into a macro named $n.
314: The replacement text
315: is the count of the number
316: of characters
317: in the line.
318: {readcount} is still defined.
319: .s3
320: {ifsame; $$a; $$b; $t; $f}
321: compares the strings $a and $b.
322: If they match exactly
323: then the replacement text
324: becomes $t,
325: otherwise it becomes $f.
326: .s3
327: {ifeq; $$a; $$b; $t; $f}
328: is similar,
329: but the comparison is numeric.
330: .s3
331: {ifgt; $$a; $$b; $t; $f}
332: is like ifeq,
333: but the test is for $a
334: strictly greater than $b.
335: .s3
336: {substr; $$f; $$t; $$s}
337: returns the part of $s
338: between character positions $f and $t,
339: numbered from one.
340: If $f or $t are out of range,
341: they are moved in range as much as possible.
342: .s3
343: {dump; $$n}
344: returns the value of the macro
345: (or macros)
346: which match $n
347: (using the same algorithm as remove).
348: The output is a rawdefine
349: statement
350: so that it can be read back in.
351: {dump} without arguments
352: dumps all macros.
353: .s1
354: .bd "Metacharacters"
355: .s2
356: Certain characters
357: are used internally.
358: Normally you will not even see them,
359: but they can appear in the output of a dump command,
360: and can sometimes be used
361: to create very fancy macros.
362: .s3
363: \e\*|\*v matches any number of spaces,
364: tabs,
365: or newlines.
366: It will even match zero,
367: but only between words,
368: as can occur with punctuation.
369: For example,
370: \e\*|\*v will match the spot
371: between the last character of a word
372: and a comma following it.
373: .s3
374: \e^ matches exactly one space, tab, or newline.
375: .s3
376: \e& matches exactly zero spaces, tabs, or newlines,
377: but only between words.
378: .s1
379: .bd "The Define Process"
380: .s2
381: When you define a macro
382: using
383: define,
384: a lot of special processing happens.
385: This processing is such that
386: define
387: is not functionally complete,
388: but still adequate for most requirements.
389: If more power is needed,
390: rawdefine can be used;
391: however,
392: rawdefine is particularly difficult to use correctly,
393: and should only be used by gurus.
394: .s3
395: In define,
396: all sequences of spaces, tabs, and newlines
397: in the template,
398: as well as all ``non-spaces''
399: between words,
400: are turned into a single
401: \e\*|\*v character.
402: If the template ends with a parameter,
403: the \e& character is added at the end.
404: .s3
405: If you want to match a real tab or newline,
406: you can use \et or \en respectively.
407: For example,
408: a macro which reads an entire line
409: and uses it as the name of an employee
410: would be defined with
411: .s3
412: {define; get $n\en; \e
413: .br
414: ret (e.all) where e.name = "$n"}
415: .s3
416: This macro might be used by typing
417: .s3
418: get *Stan*
419: .s3
420: to get all information about everyone
421: with a name which included ``Stan''.
422: By the way,
423: notice that it is ok to nest the ``ret''
424: macro inside the ``get'' macro.
425: .s1
426: .bd "Parameter Prescan"
427: .s2
428: Sometimes it is useful to macro process a parameter
429: before using it in the replacement part.
430: This is particularly important
431: when using certain builtin macros.
432: .s3
433: For prescan to occur,
434: two things must be true:
435: first,
436: the parameter must be specified in the template
437: with two dollar signs instead of one,
438: and second,
439: the actual parameter must begin with an ``at'' sign
440: (``@'')
441: (which is stripped off).
442: .s3
443: For an example of the use of prescan,
444: see ``Special Macros'' below.
445: .s1
446: .bd "Special Macros"
447: .s2
448: Some special macros are used by the terminal monitor
449: to control the environment and return results
450: to the user.
451: .s3
452: {begintrap}
453: is executed at the beginning of a query.
454: .s3
455: {endtrap}
456: is executed after the body of a query
457: is passed to \*(II.
458: .s3
459: {continuetrap}
460: is executed after the query completes.
461: The difference between this and endtrap
462: is that endtrap occurs after the query is submitted,
463: but before the query executes,
464: whereas continuetrap is executed after the query executes.
465: .s3
466: {editor}
467: can be defined
468: to be the pathname of an editor to use
469: in the \eedit command.
470: .s3
471: {shell}
472: can be defined to be the pathname
473: of a shell to use in the \eshell command.
474: .s3
475: {tuplecount}
476: is set after every query
477: (but before continuetrap is sprung)
478: to be the count of the number of tuples which satisfied
479: the qualification of the query
480: in a retrieve,
481: or the number of tuples changed in an update.
482: It is not set for DBU functions.
483: If multiple queries are run at once,
484: it is set to the number of tuples which satisfied the
485: last query run.
486: .s3
487: For example,
488: to print out the number of tuples touched
489: automatically after each query,
490: you could enter:
491: .nf
492: {define; {begintrap}; {remove; {tuplecount}}}
493: {define; {continuetrap}; \e
494: {ifsame; @{tuplecount}; {tuplecount};; \e
495: {type @{tuplecount} tuples touched}}}
496: .fi
497: .sh "SEE ALSO"
498: monitor(quel)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.