Return to macros.nr CVS log

Up to [CSRG BSD Unix] / 43BSD / ingres / doc / quel

Annotation of 43BSD/ingres/doc/quel/macros.nr, revision 1.1

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.