NAME¶
yodlbuiltins - Builtins for the Yodl converters
SYNOPSIS¶
This manual page lists the standard builtins of the Yodl package.
DESCRIPTION¶
The following list shows the builtins defined by the Yodl converters define and
which can be used in Yodl documents. Refer to the Yodl user guide, distributed
with the Yodl package, for a full description.
The following list shows all builtins of the package in alphabetical order.
NOTE: Starting with Yodl version 3.00.0 Yodl’s default file
inclusion behavior has changed. The current working directory no longer
remains fixed at the directory in which Yodl is called, but is volatile,
changing to the directory in which a yodl-file is located. This has the
advantage that Yodl’s file inclusion behavior now matches the way
C’s #include directive operates; it has the disadvantage that it
may break some current documents. Conversion, however is simple but can be
avoided altogether if Yodl’s -L (--legacy-include) option is used. The
builtins INCLUDEFILE, NOEXPANDINCLUDE and NOEXPANDPATHINCLUDE are affected by
this new behavior.
- Yodl’s builtin commands
- As mentioned previously, YODL’s input consists of text and of
commands. YODL supports a number of built-in commands which may either be
used in a YODL document, or which can be used to create a macro
package.
- Don’t despair if you find that the description of this section is
too technical. Exactly for this reason, YODL supports the macro packages
to make the life of a documentation writer easier. E.g., see chapter
[MACROPACKAGE] that describes a macro package for YODL.
- Most built-in functions and macros expand the information they receive the
way they receive the information. I.e., the information itself is only
evaluated by the time it is eventually inserted into an output medium
(usually a file). However, some builtin functions will evaluate
their argument(s) once the argument is processed. They are:
- o
- The ERROR() built-in function (see section [ERROR]);
- o
- The EVAL() built-in function (see section [EVAL]);
- o
- The FPUTS() built-in function (see section [FPUTS]);
- o
- The INTERNALINDEX() built-in function (see section [INTERNALINDEX]);
- o
- The TYPEOUT() built-in function (see section [TYPEOUT]);
- o
- The UPPERCASE() built-in function (see section [UPPERCASE]);
- o
- The WARNING() built-in function (see section [WARNING]); All other
built-in functions will not evaluate their arguments. See the
mentioned functions for details, and in particular EVAL() for a
description of this evaluation process.
- ADDTOCOUNTER
- The ADDTOCOUNTER function adds a given value to a counter. It expects two
parameter lists: the counter name, and the value to add. The counter must
be previously created with DEFINECOUNTER.
- The value to add can be negative; in that case, a value is of course
subtracted from the counter.
- See further section [COUNTERS].
- ADDTOSYMBOL
- Since Yodl version 2.00 symbols can be manipulated. To add text to an
existing symbol the builtin ADDTOSYMBOL is available. It expects two
parameter lists: the symbol’s name, and the text to add to the
symbol. The symbol must have been created earlier using DEFINECOUNTER (see
section [DEFINECOUNTER]). The macro’s second argument is not
evaluated while ADDTOSYMBOL is processed. Therefore, it is easy to add the
text of another symbol or the expansion of a macro to a symbol value.
E.g.,
ADDTOSYMBOL(one)(SYMBOLVALUE(two)XXnl())
This will add the text of symbol two, followed by a new line, to the
contents of symbol one only when symbol one is evaluated, not when
ADDTOSYMBOL is evaluated.
- Example:
ADDTOSYMBOL(LOCATION)(this is appended to LOCATION)
- ATEXIT
- ATEXIT takes one parameter list as argument. The text of the parameter
list is appended to the output file. Note that this text is subject to
character table translations etc..
- An example using this function is the following. A document in the LaTeX
typesetting language requires \end{document} to occur at the end of the
document. To automatically append this string to the output file, the
following specification can be used:
ATEXIT(NOEXPAND(\end{document}))
Several ATEXIT lists can be defined. They are appended to the output file in
the reverse order of specification; i.e., the first ATEXIT list is
appended to the output file last. That means that in general the ATEXIT
text should be specified when a `matching’ starting command is sent
to the output file; as in:
COMMENT(Start the LaTeX document.)
NOEXPAND(\begin{document})
COMMENT(Ensure its proper ending.)
ATEXIT(NOEXPAND(\end{document}))
- CHAR
- The command CHAR takes one argument, a number or a character, and outputs
its corresponding ASCII character to the final output file. This command
is built for `emergency situations’, where you need to typeset a
character despite the fact that it may be redefined in the current
character table (for a discussion of character tables, see [CHARTABLES]).
Also, the CHAR function can be used to circumvent Yodl’s way of
matching parentheses in a parameter list.
- The following arguments may be specified with CHAR (attempted in this
order):
- o
- A decimal number indicating the number of the character in the ascii-table
(for example CHAR(41));
- o
- A plain, single character (for example CHAR(#)).
- So, when you’re sure that you want to send a printable character
that is not a closing parenthesis to the output file, you can use the form
CHAR(c), c being the character (as in, CHAR(;)). To send a non-printable
character or a closing parenthesis to the output file, look up the ASCII
number of the character, and supply that number as argument to the CHAR
command.
- Example: The following two statements send an A to the output file.
CHAR(65)
CHAR(A)
The following statement sends a closing parenthesis:
CHAR(41)
Another way to send a string to the output file without expansion by
character tables or by macro interpretation, is by using the function
NOTRANS (see section [NOTRANS]). If you want to send a string to the
output without macro interpretation, but with character
table translation, use NOEXPAND (see section [NOEXPAND]).
- CHDIR
- The command CHDIR takes one argument, a directory to change to. This
command is implemented to simplify the working with includefile (see
includefile in yodlmacros(7)). As a demonstration, consider the following
fragment:
includefile(subdir/onefile)
includefile(subdir/anotherfile)
includefile(subdir/yetanotherfile)
This fragment can be changed to:
CHDIR(subdir)
includefile(onefile)
includefile(anotherfile)
includefile(yetanotherfile)
CHDIR(..)
The current directory, as given to CHDIR, only affects how includefile will
search for its files.
- Note that this example assumes that the current working directory is a
member of Yodl’s include-path specification (cf., Yodl’s
--include option).
- COMMENT
- The COMMENT function takes one parameter list. The text in the list is
treated as comment. I.e., it is ignored. The text is not copied to the
final output file.
- COUNTERVALUE
- COUNTERVALUE expands to the value of a counter. Its single parameter list
must contain the name of a counter. The counter must have been created
earlier using the builtin DEFINECOUNTER.
Example:
The counter has value COUNTERVALUE(MYCOUNTER).
See also section [COUNTERS].
- DECWSLEVEL
- DECWSLEVEL requires one (empty) parameter list. It reduces the current
white-space level. The white-space level typically is used in files that
only define Yodl macros. When no output should be generated while
processing these files, the white-space level can be used to check for
this. If the white-space level exceeds zero, a warning will be generated
if the file produces non-whitespace output. The builtin function
DECWSLEVEL is used to reduce the whitespace level following a previous
call of INCWSLEVEL.
- Once the white space level exceeds zero, no output will be generated.
White space, therefore will effectively be ignored. The white space level
cannot be reduced to negative values. A warning is issued if that would
have happened if it were allowed.
- Example:
INCWSLEVEL()
DEFINESYMBOL(....)
DEFINEMACRO(...)(...)(...)
DECWSLEVEL()
Without the INCWSLEVEL and DECWSLEVEL, calls, the above definition would
generate four empty lines to the output stream.
- The INCWSLEVEL and DECWSLEVEL calls may be nested. The best approach is to
put an INCWSLEVEL at the first line of a macro-defining Yodl-file, and a
matching DECWSLEVEL call at the very last line.
- DEFINECHARTABLE
- DEFINECHARTABLE is used to define a character translation table. The
function expects two parameterlists, containing the name of the character
table and character table translations on separate lines. These character
table translations are of the form
character = quoted-string
Here, character is always a value within single quotes. It may be a single
character, an octal character value or a hexadecimal character value. The
single character may be prefixed by a \-character (e.g.,
’\\’). The octal character value must start with a
backslash, followed by three octal digits (e.g., ’\045’. The
hexadecimal character value starts with 0x, followed by two hexadecimal
characters. E.g., ’0xbe’. The double quoted string may
contain anything (but the string must be on one line), possibly containing
escape-sequences as well: in the double quoted string the standard
C escape sequences \a (alert), \b (beep), \f (formfeed), \n
(newline), \r (carriage return), \t (tab), and \v (vertical tab) are
recognized and automatically converted to their special meanings. Starting
with Yodl 2.14.0 octal and hexadecimal constants may also be used. E.g.,
character Y may also be specified using the octal value \131 or the
hexadecimal value \x59. Any other character following a defines itself: \\
represents a single backslash character.
- Example:
DEFINECHARTABLE(demotable)(
’&’ = "&"
’\\’ = "\\backslash"
’\045’ = "oct(45)"
’0xa4’ = "hex(a4)"
)
The builtin function DEFINECHARTABLE does not activate the table. The
table is merely defined. To activate the character translation table, use
USECHARTABLE. The discussion of character tables is postponed to section
[CHARTABLES].
- DEFINECOUNTER
- DEFINECOUNTER creates a new counter, to be subsequently used by, e.g, the
USECOUNTER function. DEFINECOUNTER expects two parameter list: the name of
the counter to create and an optional initial value. By default the
counter will be initialized to zero.
- Examples:
DEFINECOUNTER(YEAR)(1950)
DEFINECOUNTER(NTIMES)()
See also section [COUNTERS].
- DEFINEMACRO
- DEFINEMACRO is used to define new macros. This function requires three
parameter lists:
- o
- An identifier, being the name of the macro to define. This identifier may
only consist of uppercase or lowercase characters. Note that it can
not contain numbers, nor underscore characters.
- o
- A number, stating the number of arguments that the macro will require once
used. The number must be in the range 0 to 61.
- o
- The text that the macro will expand to, once used. This text may contain
the strings ARG x, x being 1, 2, etc.. At these places the
arguments to the macro will be pasted in. The numbers that identify the
arguments are 1 to 9, then A to Z and finally a to z. This gives a range
of 61 expandable arguments, which is enough for all real-life
applications. For example, the following fragment defines a macro bookref,
which can be used to typeset a reference to a book. It requires three
arguments; say, an author, a title and the name of a publisher:
DEFINEMACRO(bookref)(3)(
Author(s): ARG1
Book title: ARG2
Published by: ARG3
)
Such a macro could be used as follows:
bookref(Sobotta/Becher)
(Atlas der Anatomie des Menschen)
(Urban und Schwarzenberg, Berlin, 1972)
When called, it would produce the following output:
Author(s): Sobotta/Becher
Book title: Atlas der Anatomie des Menschen
Published by: Urban und Schwarzenberg, Berlin, 1972
While applying a macro, the three parameter lists are pasted to the places
where ARG1, ARG2 etc. occur in the definition.
- Note the following when defining new macros:
- o
- The parameter list containing the name of the new macro, (bookref) in the
above example, must occur right after DEFINEMACRO. No spaces are allowed
in between. Space characters and newlines may however occur following this
first parameter list.
- This behavior of the yodl program is similar to the usage of the defined
macro: the author information must, enclosed in parentheses, follow right
after the bookref identifier. I implemented this feature to improve the
distinguishing between macros and real text. E.g., a macro me might be
defined, but the text
I like me (but so do you)
still is simple text; the macro me only is activated when a parenthesis
immediately follows it.
- o
- Be careful when placing newlines or spaces in the definition of a new
macro. E.g., the definition, as given:
DEFINEMACRO(bookref)(3)(
Author(s): ARG1
Book title: ARG2
Published by: ARG3
)
introduces extra newlines at the beginning and ending of the macro, which
will be copied to the output each time the macro is used. The extra
newline occurs, of course, right before the sequence Author(s): and
following the evaluation of ARG3. A simple backslash character at the end
of the DEFINEMACRO line would prevent the insertion of extra newline
characters:
DEFINEMACRO(bookref)(3)(\
Author(s): ARG1
Book title: ARG2
Published by: ARG3
)
- o
- Note that when a macro is used which requires no arguments at all, one
empty parameter list still must be specified. E.g., my macro package (see
chapter [MACROPACKAGE]) defines a macro it that starts a bullet item in a
list. The macro takes no arguments, but still must be typed as it().
- This behavior is consistent: it helps distinguish which identifiers are
macros and which are simple text.
- o
- Macro arguments may evaluate to text. When a \ is appended to the
macro-argument, or in the default input handling within a non-zero
white-space level (see section [INCWSLEVEL]) this may invalidate a
subsequent macro call. E.g., the macro
DEFINEMACRO(oops)(1)(
ARG1
XXnl()
)
will, when called as oops(hello world), produce the output:
hello worldXXnl()
To prevent this gluing to arguments to subsequent macros, a single + should
be prepended to the macro call:
DEFINEMACRO(oops)(1)(
ARG1
+XXnl()
)
See also section [PLUSIDENT] obout the `+identifier’-sequence.
- o
- Note the preferred layout of macro definitions and macro calls. Adhere to
this form, to prevent drowning in too many parentheses. In
particular:
- o
- Put all elements of the macro definition on one line, except for the
macro-expansion itself. Each expansion element should be on a line by
itself.
- o
- When calling macros put the macro parameter lists underneath each other.
If the macrolists themselves contain macro-calls, put each call again on a
line of its own, indenting one tab-position beyond the location of the
opening parenthesis of the argument.
- o
- No continnuation backslashes are required between parameter lists. So, do
not use them there to prevent unnecessary clutter.
- o
- With complex calls, indent just the arguments, and put the parentheses in
their required of logical locations. Example of a complex call:
complex(
first(
ARG1
)(
ARG2
+XXnl()
)
ARG3
+nop()
ARG4
+XXnl()
)
- o
- Macro expansion proceeds as follows:
- o
- The parameter lists are read from the input
- o
- The contents of the parameters then replace their ARGx references in the
macro’s definition (in some exceptional cases, clearly indicated as
such when applicable, the arguments will themselves be evaluated first,
and then these evaluated arguments are used as replacements for their
corresponding ARGx references).
- o
- The now modified macro is read by Yodl’s lexical scanner. This may
result in yet another macro expansion, which will then be evaluated
recursively.
- o
- Eventually, all expansion is completed (well, should complete, since Yodl
doesn’t test for eternal recursion) and scanning of the input
continues beyond the original macro call. For example, assume we have the
following two macros:
DEFINEMACRO(First)(1)(
Hello ARG1
+XXnl()
)
DEFINEMACRO(Second)(1)(
First(ARG1)
First(ARG1)
)
and the following call is issued:
Second(Yodl)
then the following will happen:
- o
- Second(Yodl) is read as encountered.
- o
- ARG1 in Second is replaced by YODL, and the resulting macro body is sent
to the lexical scanner for evaluation: It will see:
First(Yodl)First(Yodl)
- o
- The first call to First() is now evaluated. This will put (after replacing
ARG1 by YODL) the following on the scanner’s input:
Hello Yodl+XXnl()First(Yodl)
- o
- Hello Yodl contains no macro call, so it is written to the output stream.
Remains:
+XXnl()First(Yodl)
- o
- Assume XXnl() merely contains a newline (represented by \n, here), so
+XXnl() is now replaced by \n. This results in the following input for the
lexical scanner:
\nFirst(Yodl)
- o
- The \n is now written to the output stream, and the scanner sees:
First(Yodl)
- o
- The second call to First() is now evaluated. This will put the following
on the scanner’s input:
Hello Yodl+XXnl()
- o
- Hello Yodl is written to the output stream. Remains:
+XXnl()
- o
- +XXnl() is now replaced by \n. The lexical scanner sees:
\n
- o
- The newline is printed and we’re done.
- DEFINESYMBOL
- NOTE: this function has changed at the release of Yodl 2.00. It now
expects two parameter lists, rather than one
- DEFINESYMBOL expects two arguments. An identifier, which is the name of
the symbol to define, and the textual value of the symbol. If the second
argument is empty, the symbol is defined, but has an empty value.
- The earlier interpretation of a Yodl symbol as a logical flag can still be
used, but allowing it to obtain textual values greatly simplifies various
Yodl macros.
- Example:
DEFINESYMBOL(Yodl)(Your own document language)
DEFINESYMBOL(Options)()
- DELETECHARTABLE
- DELETECHARTABLE removes a definition of a character table that was defined
by DEFINECHARTABLE. This function expects one argument: the name of the
character table remove.
- It’s an error to attempt to delete a character table that is
currently in use or to attempt to delete a non-existing character
table.
- Example:
DELETECHARTABLE(mytable)
- DELETECOUNTER
- DELETECOUNTER removes a definition of a counter that was defined by
DEFINECOUNTER. This function expects one argument: the name of the counter
to remove.
- If the counter does not exist, a warning is issued. It is not considered
an error to try to delete a counter that has not been defined
earlier.
- Example:
DELETECOUNTER(mycounter)
- DELETEMACRO
- DELETEMACRO removes a definition of a macro that was defined by
DEFINEMACRO. This function takes one argument: the macro name to
remove.
- There is no error condition (except for syntax errors): when no macro with
a matching name was previously defined, no action is taken.
- For example, the safe way to define a macro is by first undefining it.
This ensures that possible previous definitions are removed first:
- Example:
DELETEMACRO(mymacro)
- DELETENOUSERMACRO
- DELETENOUSERMACRO removes a `nousermacro’ definition. The function
expects one argument: the name of the `nousermacro’ identifier to
be removed from the nousermacro-set.
- There is no error condition (except for syntax errors): when the
identifier wasn’t stored as a `nousermacro’ no action is
taken.
- Example:
DELETENOUSERMACRO(mymacro)
- DELETESYMBOL
- DELETESYMBOL removes the definition of a symbol variable. It expects one
parameter list, holding the name of the variable to deleted.
- This macro has no error condition (except for syntax errors): the symbol
in question may be previously defined, but that is not necessary.
- Example:
DELETESYMBOL(Options)
- DUMMY
- This function is obsolete. It does nothing, and may be removed in future
versions of Yodl.
- ENDDEF
- ENDDEF is obsolete, and should be replaced by DECWSLEVEL. It may be
removed in future versions of Yodl.
- ERROR
- The ERROR function takes one argument: text to display to the standard
error stream. The current input file and line number are also displayed.
After displaying the text, the yodl program aborts with an exit status of
1.
- The text passed to the function is expanded first. See the example.
- The ERROR function is an example of a function that evaluates its
parameter list itself.
- This command can be used, e.g., in a macro package when an incorrect macro
is expanded. In my macro package (see chapter [MACROPACKAGE]) the ERROR
function is used when the sectioning command chapter() is used in an
article document (in the package, chapter’s are only available in
books or reports).
- An analogous builtin function is WARNING, which also prints a message but
does not exit (see section [WARNING]).
- Example: In the following call, COUNTERVALUE(NTRIES) is replaced by its
actual value:
ERROR(Stopping after COUNTERVALUE(NTRIES) attempts)
- EVAL
- The EVAL function takes one argument: the text to be evaluated. This
function allows you to perform an indirect evaluation of Yodl commands.
Assume that there is a symbol varnam containing the name of a counter
variable, then the following will display the value of the counter,
incrementing it first:
EVAL(NOTRANS(USECOUNTER)(SYMBOLVALUE(varnam)))
The actions of the EVAL function can be described as follows:
- o
- First, the NOTRANS(USECOUNTER) is evaluated, producing USECOUNTER.
- o
- Next, the open parentheses is processed, producing the open parenthesis
itself
- o
- Then, SYMBOLVALUE(varnam) is evaluated, producing the name of a counter,
e.g. `counter’.
- o
- Eventually the closing parentheis is processed, producing the closing
parenthesis itself.
- o
- All this results in the text
USECOUNTER(counter)
- o
- This text is now presented to Yodl’s lexical scanner, resulting in
incrementing the counter, and displaying its incremented value. It should
be realized that macro arguments themselves are usually not evaluated. So,
a construction like
USECOUNTER(EVAL(SYMBOLVALUE(varnam)))
will fail, since EVAL(SYMBOLVALUE(varnam)) is not a legal name for a
counter: the EVAL() call is used here as an argument, which is not
expanded. The distinction is subtle, and is caused by the fact that
builtin functions receive unprocessed arguments, and may impose certain
requirements on them (like USECOUNTER requiring the name of a
counter).
- Summarizing: EVAL acts as follows:
- o
- Its argument is presented to Yodl’s lexical scanner
- o
- The output produced by the processing of the argument is then inserted
into the input stream in lieu of the original EVAL call.
- Mosy built-in functions will not evaluate their arguments. In fact,
only ERROR, EVAL, FPUTS, INTERNALINDEX, TYPEOUT, UPPERCASE and WARNING()
will evaluate their arguments.
- Postponing evaluations allows you to write:
DEFINESYMBOL(later)(SYMBOLVALUE(earlier))
Eventually, and not when later is defined, a statement like
SYMBOLVALUE(later)
will produce the value of earlier at the moment SYMBOLVALUE(later) is
processed. This is, in all its complex consequences, what would be
expected in most cases. It allows us to write general macros producing
output that is only evaluated when the text of symbols and values of
arguments become eventually, rather than when the macro is defined,
available.
- Decisions like these invariably result in questions like `what if I have
to keep original values in some situation?’ In those situations
EVAL() must be used. The following example shows the definition of three
symbols: one receives an initial value, two will return one’s
actual value when two’s value is displayed, three will, using
EVAL(), store one’s initial value. The example also shows yet
another way to suppress macro calls. It uses the macro nop() which is
defined in the all standard conversion types.
DEFINESYMBOL(one)(This is one, before)
DEFINESYMBOL(two)(SYMBOLVALUE(one))
EVAL(DEFINESYMBOL+nop()(three)(SYMBOLVALUE(one)))
SETSYMBOL(one)(this is one, after)
SYMBOLVALUE(two)
SYMBOLVALUE(three)
- FILENAME
- The function FILENAME() produces an absolute path to the currently
processed Yodl file. This is not necessarily the canonical path
name, as it may contain current- and parent-path directories.
- FPUTS
- The function FPUTS expects two arguments: the first argment is information
to be appended to a file, whose name is given as the second argument. The
first argument is processed by Yodl before it is appended to the requested
filename, so it may contain macro calls.
- For example, the following statement will append a countervalue to the
mentioned file:
FPUTS(There have been COUNTERVALUE(attempts) attempts)(/tmp/logfile)
The second argument (name of the file) is not evaluated, but is used as
received.
- IFBUILTIN
- The IFBUILTIN function tests whether its first argument is the name of a
builtin function. If so, the second parameter list is evaluated, else, the
third parameter list is evaluated. All three parameter lists (the
variable, the true-list and the false-list) must be present; though the
true-list and/or the false-list may be empty parameter lists.
- Example:
IFBUILTIN(IFBUILTIN)(\
`BUILTIN’ is a builtin - function
)(\
`BUILTIN’ is NOT a builtin - function
)
Please note the preferred layout: The first argument immediately follows the
function name, then the second argument (the true list) is
indented, as is the false list. The layout closely follows the
preferred layout of if-else statements of many programming languages.
- IFCHARTABLE
- The IFCHARTABLE function tests whether its first argument is the name of a
character table. The character table needs not be active. If the name is
the name of a character table, the second parameter list is evaluated,
else, the third parameter list is evaluated. All three parameter lists
(the name, the true list and the false list) must be present; though the
true list and/or the false list may be empty parameter lists.
- Example:
IFCHARTABLE(standard)(\
`standard’ is a character tablebuiltin - function
)(\
`standard’ is NOT a character tablebuiltin - function
)
Please note the preferred layout: The first argument immediately follows the
function name, then the second argument (the true list) is
indented, as is the false list. The layout closely follows the
preferred layout of if-else statements of many programming languages.
- IFDEF
- The IFDEF function tests for the definition status of the argument in its
first parameter list. If it is a defined entity, the second parameter list
is evaluated, else, the third parameter list is evaluated. All three
parameter lists (the entity, the true list and the false list) must be
present; though the true list and/or the false list may be empty parameter
lists.
- The true list is evaluated if the first argument is the name of:
- o
- a built-in function, or
- o
- a character table, or
- o
- a counter, or
- o
- a no-user-macro symbol, or
- o
- a symbol, or
- o
- a user-defined macro, or Example:
IFDEF(someName)(\
`someName’ is a defined entity
)(\
`someName is not defined.
)
Please note the preferred layout: The first argument immediately follows the
function name, then the second argument (the true list) is
indented, as is the false list. The layout closely follows the
preferred layout of if-else statements of many programming languages.
- IFEMPTY
- IFEMPTY expects three arguments: a symbol, a true-list and a false-list.
IFEMPTY evaluates to the true-list if the symbol is an empty string;
otherwise, it evaluates to the false-list.
- The function does not further evaluate its argument. Its use is primarily
to test whether a macro has received an argument or not. If the intent is
to check whether a symbol’s value is empty or not, IFSTREQUAL
[IFSTREQUAL] should be used, where the first argument is the name of a
symbol, and the second argument is empty.
- Example:
IFEMPTY(something)(\
`something’ is empty...
)(\
`something’ is not an empty string
)
In the same way, IFEMPTY can be used to test whether an argument expands to
a non-empty string. A more elaborate example follows below. Say you want
to define a bookref macro to typeset information about an author, a book
title and about the publisher. The publisher information may be absent,
the macro then typesets unknown:
\
DEFINEMACRO(bookref)(3)(\
Author(s): ARG1
Title: ARG2
Published by: \
IFEMPTY(ARG3)
(\
Unknown\
)(\
ARG3\
)
)
Using the macro, as in:
\
bookref(Helmut Leonhardt)
(Histologie, Zytologie und Microanatomie des Menschen)
()
would now result in the text Unknown behind the Published by: line.
- Please note the preferred layout: The first argument immediately follows
the function name, then the second argument (the true list) is
indented, as is the false list. The layout closely follows the
preferred layout of if-else statements of many programming languages.
- IFEQUAL
- IFEQUAL expects four argument lists. It tests whether its first argument
is equal to its second argument. If so, the third parameter list is
evaluated, else, the fourth parameter list is evaluated. All four argument
lists must be present, though all can be empty lists.
- The first two arguments of IFEQUAL should be integral numerical arguments.
In order to determine whether the first two arguments are equal, their
values are determined:
- o
- If the argument starts with an integral numerical value, that value is the
value of the argument.
- o
- If the argument is the name of a counter, the counter’s value is
the value of the argument
- o
- If the values of the first two arguments van be determined accordingly,
their equality will determine whether the true list (when the values are
equal) or the false list (when the values are unequal) will be
evaluated.
- o
- Otherwise, IFEQUAL will evaluate the false list.
- Example:
IFEQUAL(0)()(\
0 and an empty string are equal
)(\
0 and an empty string are not equal
)
Please note the preferred layout: The first argument immediately follows the
function name, then the second argument (the true list) is
indented, as is the false list. The layout closely follows the
preferred layout of if-else statements of many programming languages.
- IFGREATER
- IFGREATER expects four argument lists. It tests whether its first argument
is greater to its second argument. If so, the third parameter list is
evaluated, else, the fourth parameter list is evaluated. All four argument
lists must be present, though all can be empty lists.
- The first two arguments of IFGREATER should be integral numerical
arguments. In order to determine whether the first two arguments are
equal, their values are determined:
- o
- If the argument starts with an integral numerical value, that value is the
value of the argument.
- o
- If the argument is the name of a counter, the counter’s value is
the value of the argument
- o
- If the values of the first two arguments van be determined accordingly,
their order relation will determine whether the true list (when the first
value is greater than the second value) or the false list (when the first
value is smaller or equal than the second value) will be evaluated.
- o
- Otherwise, IFGREATER will evaluate the false list.
- Example:
IFGREATER(counter)(5)(\
counter exceeds the value 5
)(\
counter does not exceeds the value 5, or counter is no Yodl-counter.
)
Please note the preferred layout: The first argument immediately follows the
function name, then the second argument (the true list) is
indented, as is the false list. The layout closely follows the
preferred layout of if-else statements of many programming languages.
- IFMACRO
- The IFMACRO function tests whether its first argument is the name of a
macro. If the name is the name of a macro, the second parameter list is
evaluated, else, the third parameter list is evaluated. All three
parameter lists (the name, the true list and the false list) must be
present; though the true list and/or the false list may be empty parameter
lists.
- Example:
IFMACRO(nested)(\
`nested’ is the name of a macro
)(\
There is no macro named `nested’
)
Please note the preferred layout: The first argument immediately follows the
function name, then the second argument (the true list) is
indented, as is the false list. The layout closely follows the
preferred layout of if-else statements of many programming languages.
- IFSMALLER
- IFSMALLER expects four argument lists. It tests whether its first argument
is smaller to its second argument. If so, the third parameter list is
evaluated, else, the fourth parameter list is evaluated. All four argument
lists must be present, though all can be empty lists.
- The first two arguments of IFSMALLER should be integral numerical
arguments. In order to determine whether the first two arguments are
equal, their values are determined:
- o
- If the argument starts with an integral numerical value, that value is the
value of the argument.
- o
- If the argument is the name of a counter, the counter’s value is
the value of the argument
- o
- If the values of the first two arguments van be determined accordingly,
their order relation will determine whether the true list (when the first
value is smaller than the second value) or the false list (when the first
value is greater than or equal to the second value) will be
evaluated.
- o
- Otherwise, IFSMALLER will evaluate the false list.
- Example:
IFSMALLER(counter)(5)(\
counter is smaller than the value 5, or counter is no Yodl-counter
)(\
counter exceeds the value 5
)
Please note the preferred layout: The first argument immediately follows the
function name, then the second argument (the true list) is
indented, as is the false list. The layout closely follows the
preferred layout of if-else statements of many programming languages.
- IFSTREQUAL
- IFSTREQUAL tests for the equality of two strings. It expects four
arguments: two strings to match, a true list and a false list. The true
list is only evaluated when the contents of the two string arguments
exactly match.
- The first two arguments of IFSTREQUAL are partially evaluated:
- o
- If the argument is the name of a symbol, the symbol’s value is the
value of the argument
- o
- Otherwise, the argument itself is used.
- In the degenerate case where the string to be compared is actually the
name of a SYMBOL, use a temporary SYMBOL variable containing the name of
that symbol, and compare it to whatever you want to compare it with.
Alternatively, write a blank space behind the arguments, since the
arguments are then interpreted `as is’. In practice, the need for
these constructions seem to arise seldomly, however.
- Example:
IFSTREQUAL(MYSYMBOL)(Hello world)(
The symbol `MYSYMBOL’ holds the value `Hello world’
)(
The symbol `MYSYMBOL’ doesn’t hold the value `Hello world’
)
- IFSTRSUB
- IFSTRSUB tests whether a string is a sub-string of another string. It acts
similar to IFSTREQUAL, but it tests whether the second string is part of
the first one.
- The first two arguments of IFSTREQULA are partially evaluated:
- o
- If the argument is the name of a symbol, the symbol’s value is the
value of the argument
- o
- Otherwise, the argument itself is used.
- In the degenerate case where the string to be compared is actually the
name of a SYMBOL, use a temporary SYMBOL variable containing the name of
that symbol, and compare it to whatever you want to compare it with.
Alternatively, write a blank space behind the arguments, since the
arguments are then interpreted `as is’. In practice, the need for
these constructions seem to arise seldomly, however.
- Example:
IFSTRSUB(haystack)(needle)(
`needle’ was found in `haystack’
)(
`needle’ was not found in `haystack’
)
Note that both `haystack’ and `needle’ may be the names of
symbols. If they are, their contents are is compared, rather than the
literal names `haystack’ and `needle’
- IFSYMBOL
- The IFSYMBOL function tests whether its first argument is the name of a
symbol. If it is the name of a symbol, the second parameter list is
evaluated, else, the third parameter list is evaluated. All three
parameter lists (the name, the true list and the false list) must be
present; though the true list and/or the false list may be empty parameter
lists.
- Example:
IFSYMBOL(nested)(\
`nested’ is the name of a symbol
)(\
There is no symbol named `nested’
)
Please note the preferred layout: The first argument immediately follows the
function name, then the second argument (the true list) is
indented, as is the false list. The layout closely follows the
preferred layout of if-else statements of many programming languages.
- IFZERO
- IFZERO expects three parameter lists. The first argument defines whether
the whole function expands to the true list or to the false list.
- The first argument of IFZERO should be an integral numerical value. Its
value is determined as follows:
- o
- If the argument starts with an integral numerical value, that value is the
value of the argument.
- o
- If the argument is the name of a counter, the counter’s value is
the value of the argument
- o
- Otherwise, IFZERO will evaluate the false list.
- Note that, starting with Yodl version 2.00 the first argument is not
evaluated any further. So, COUNTERVALUE(somecounter) will always be
evaluated as 0. If the value of a counter is required, simply provide its
name as the first argument of the IFZERO function.
- Example:
DEFINEMACRO(environment)(2)(\
IFZERO(ARG2)(\
NOEXPAND(\end{ARG1})\
)(\
NOEXPAND(\begin{ARG1})\
)\
)
Such a macro may be used as follows:
environment(center)(1)
Now comes centered text.
environment(center)(0)
which would of course lead to \begin and \end{center}. The numeric second
argument is used here as a on/off switch.
- INCLUDEFILE
- INCLUDEFILE takes one argument, a filename. The file is processed by Yodl.
If a file should be inserted without processing the builtin function
NOEXPANDINCLUDE [NOEXPANDINCLUDE] or NOEXPANDPATHINCLUDE
[NOEXPANDPATHINCLUDE] should be used.
- The yodl program supplies, when necessary, an extension to the filename.
The supplied extension is .yo, unless defined otherwise during the
compilation of the program.
- Furthermore, Yodl tries to locate the file in the Yodl’s include
path (which may be set using the --include option). The actual value of
the include path is shown in the usage information, displayed when Yodl is
started without arguments.
- NOTE: Starting with Yodl version 3.00.0 Yodl’s default file
inclusion behavior has changed. The current working directory no longer
remains fixed at the directory in which Yodl is called, but is volatile,
changing to the directory in which a yodl-file is located. This has the
advantage that Yodl’s file inclusion behavior now matches the way
C’s #include directive operates; it has the disadvantage
that it may break some current documents. Conversion, however is simple
and can be avoided altogether if Yodl’s -L (--legacy-include)
option is used.
- Example:
INCLUDEFILE(latex)
will try to include the file latex or latex.yo from the current include
parth. When the file is not found, Yodl aborts.
- INCLUDELIT, INCLUDELITERAL
- INCLUDELIT and INCLUDELITERAL are obsolete. NOEXPANDINCLUDE
[NOEXPANDINCLUDE] or NOEXPANDPATHINCLUDE [NOEXPANDPATHINCLUDE] should be
used instead.
- INCWSLEVEL
- INCWSLEVEL requires one (empty) parameter list. It increases the current
white-space level. The white-space level typically is used in files that
only define Yodl macros. When no output should be generated while
processing these files, the white-space level can be used to check for
this. If the white-space level exceeds zero, a warning will be generated
if the file produces non-whitespace output. The builtin function
DECWSLEVEL is used to reduce the whitespace level following a previous
call of INCWSLEVEL.
- Once the white space level exceeds zero, no output will be generated.
White space, therefore will effectively be ignored. The white space level
cannot be reduced to negative values. A warning is issued if that would
have happened if it were allowed.
- Example:
INCWSLEVEL()
DEFINESYMBOL(....)
DEFINEMACRO(...)(...)(...)
DECWSLEVEL()
Without the INCWSLEVEL and DECWSLEVEL, calls, the above definition would
generate four empty lines to the output stream.
- The INCWSLEVEL and DECWSLEVEL calls may be nested. The best approach is to
put an INCWSLEVEL at the first line of a macro-defining Yodl-file, and a
matching DECWSLEVEL call at the very last line.
- INTERNALINDEX
- INTERNALINDEX expects one argument list. The argument list is evaluated
and written to the index file.
- The index file is defined since Yodl version 2.00, and contains the fixup
information which was previously written to Yodl’s output as the
.YODLTAGSTART. ... .YODLTAGEND. sequence.
- The index file allows for greated processing speed, at the expense of an
additional file. The associated yodlpost postprocessing program will read
and process the index file, and will fixup the corresponding yodl-output
accordingly.
- The index file is not created when output is written to the standard
output name, since Yodl is unable to request the system for the current
file offset.
- The entries of the index file always fit on one line. INTERNALINDEX will
alter newline characters in its argument into single blank spaces. Each
line starts with the current offset of Yodl’s output file, thus
indicating the exact location where a fixup is requested. An example of a
produced fixup line could be
3004 ref MACROPACKAGE
indicating that at offset 3004 in the produced output file a reference to
the label MACROPACKAGE is requested. Assuming a html conversion, The
postprocessor will thereupon write something like
<a href="outfile04.html#MACROPACKAGE">4.3.2.</a>
into the actual output file while processing Yodl’s output up to
offset location 3004.
- Consequently, producing Yodl-output normally consists of two steps:
- o
- First, Yodl itself is started, producing, e.g., out.idx (the index file)
and out.yodl (Yodl’s raw output).
- o
- Then, Yodl’s post-processor processes out.idx and out.yodl,
producing one or more final output files, in which the elements of the
index file have been properly handled. This may result in multiple output
file, like report.html, report01.html, report02.html etc.
- NEWCOUNTER
- NEWCOUNTER is obsolete. DEFINECOUNTER [DEFINECOUNTER] should be used
instead.
- NOEXPAND
- NOEXPAND is used to send text to the final output file without being
expanded by Yodl (the other methods are the CHAR macro, see section
[CHAR], and the NOTRANS macro, see section [NOTRANS]). NOEXPAND takes one
parameter list, the text in question. Whatever occurs in the argument is
not subject to parsing or expansion by Yodl, but is simply copied to the
output file (except for CHAR functions in the argument, which are
expanded. If CHAR-expansion is not required either NOTRANS [NOTRANS] can
be used).
- Furthermore, the contents of the parameter list are also subject to
character table translations, using the currently active table. This
should come as no surprise. Ignoring character tables would make both the
processing of CHAR calls and the NOTRANS function superfluous.
- So, the following situations are recognized:
|
|
|
|
support chartables |
|
|
and CHAR |
|
|
|
|
Macro expansion |
yes |
no |
|
|
|
Yes |
(standard) |
Push chartable |
|
|
(standard) |
|
|
Pop chartable |
No |
NOEXPAND |
NOTRANS |
|
|
|
|
|
|
E.g., let’s assume that you need to write in your document the
following text:
INCLUDEFILE(something or the other)
IFDEF(onething)(
...
)(
....
)
NOEXPAND(whatever)
- The way to accomplish this is by prefixing the text by NOEXPAND followed
by an open parenthesis, and by postfixing it by a closing parenthesis.
Otherwise, the text would be expanded by Yodl while processing it (and
would lead to syntax errors, since the text isn’t correct in the
sence of the Yodl language).
- For this function, keep the following caveats in mind:
- o
- There is only one thing that a NOEXPAND cannot protect from expansion: an
ARG x in a macro definition. The argument specifier is always
processed. E.g., after
DEFINEMACRO(thatsit)(1)(
That is --> NOEXPAND(ARG1) <-- it!
)
thatsit(after all)
the ARG1 inside the NOEXPAND statement is replaced with after all.
- o
- The NOEXPAND function must, as all functions, be followed by a parameter
list. The parentheses of the list must therefore be `balanced’. For
unbalanced lists, use CHAR(40) to set an open parenthesis, or CHAR(41) to
typeset a closing parenthesis.
- NOEXPANDINCLUDE
- NOEXPANDINCLUDE takes one argument, a filename. The file is included.
- The filename is uses as specified. The include path is not used when
locating this file.
- NOTE: Starting with Yodl version 3.00.0 Yodl’s default file
inclusion behavior has changed. The current working directory no longer
remains fixed at the directory in which Yodl is called, but is volatile,
changing to the directory in which a yodl-file is located. This has the
advantage that Yodl’s file inclusion behavior now matches the way
C’s #include directive operates; it has the disadvantage
that it may break some current documents. Conversion, however is simple
and can be avoided altogether if Yodl’s -L (--legacy-include)
option is used.
- The argument to NOEXPANDINCLUDE is partially evaluated:
- o
- If the argument is the name of a symbol, the symbol’s value is the
value of the argument
- o
- Otherwise, the argument itself is used. The thus obtained file name is not
further evaluated: in particular, it will not be subject to character
translations.
- The contents of the file are included literally, not subject to macro
expansion. Character translations are performed, though. If character
translations are not appropriate, PUSHCHARTABLE can be used to suppress
character table translations temporarily.
- The purpose of NOEXPANDINCLUDE is to include source code literally in the
document, as in:
NOEXPANDINCLUDE(literal.c)
The function NOEXPANDPATHINCLUDE can be used to insert a file which
is located in one of the directories specified in Yodl’s
include path.
- NOEXPANDPATHINCLUDE
- NOEXPANDPATHINCLUDE takes one argument, a filename. The file is included.
The file is searched for in the directories specified in Yodl’s
includepath.
- NOTE: Starting with Yodl version 3.00.0 Yodl’s default file
inclusion behavior has changed. The current working directory no longer
remains fixed at the directory in which Yodl is called, but is volatile,
changing to the directory in which a yodl-file is located. This has the
advantage that Yodl’s file inclusion behavior now matches the way
C’s #include directive operates; it has the disadvantage
that it may break some current documents. Conversion, however is simple
and can be avoided altogether if Yodl’s -L (--legacy-include)
option is used.
- The argument to NOEXPANDPATHINCLUDE is partially evaluated:
- o
- If the argument is the name of a symbol, the symbol’s value is the
value of the argument
- o
- Otherwise, the argument itself is used. The thus obtained file name is not
further evaluated: in particular, it will not be subject to character
translations.
- Like the NOEXPANDINCLUDE function, the contents of the file are included
literally, not subject to macro expansion. Character translations are
performed, though. If character translations are not appropriate,
PUSHCHARTABLE [PUSHCHARTABLE] can be used to suppress character table
translations temporarily.
- The purpose of NOEXPANDPATHINCLUDE is to include source code as defined in
a macro package literally into the document, as in:
NOEXPANDPATHINCLUDE(rug-menubegin.xml)
- NOTRANS
- NOTRANS copies its one argument literally to the output file, without
expanding macros in it and without translating the characters with the
current translation table. The NOTRANS function is typically used to send
commands for the output format to the output file.
- For example, consider the following code fragment:
COMMENT(--- Define character translations for \, { and } in LaTeX. ---)
DEFINECHARTABLE(standard)(
’\\’ = "$\\backslash$"
’{’ = "\\verb+{+"
’}’ = "\\verb+}+"
)
COMMENT(--- Activate the translation table. ---)
USECHARTABLE(standard)
COMMENT(--- Now two tests: ---)
NOEXPAND(\input{epsf.tex})
NOTRANS(\input{epsf.tex})
NOEXPAND will send
$\backslash$input\verb+{+epsf.tex\verb+}+
since the characters in its argument are translated with the standard
translation table. In contrast, NOTRANS will send \input{epsf.tex}.
- The parameter list of NOTRANS must be balanced with respect to its
parentheses. When using an unbalanced set of parentheses, use CHAR(40) to
send a literal (, or CHAR(41) to send a ).
- The NOEXPAND description summarizes all combinations of character
translations and/or macro expansion, and how they are handled and realized
by Yodl.
- NOUSERMACRO
- NOUSERMACRO controls yodl’s warnings in the following way: When
Yodl is started with the -w flag on the command line, then warnings are
generated when Yodl encounters a possible macro name, followed by a
parameter list, without finding a macro by that name. Yodl then prints
something like cannot expand possible user macro.
- Examples of such sequences are, The necessary file(s) are in
/usr/local/lib/yodl, or see the manual page for sed(1). The candidate
macros are file and sed; these names could just as well be `valid’
user macros followed by their parameter list.
- When a corresponding NOUSERMACRO statement appears before yodl
encounters the candidate macros, no warning is generated. A fragment might
therefore be:
NOUSERMACRO(file sed)
The necessary file(s) are in ...
See the manual page for sed(1).
The NOUSERMACRO accepts one or more names in its argument, separated by
white space, commas, colons, or semi-colons.
- OUTBASE
- OUTBASE inserts the current basename of the output file into the output
file. The basename is the name of the file of which the directory
components and extension were stripped.
- If the output file is the standard output file, - is inserted.
- OUTDIR
- OUTDIR inserts the current path name of the output file into the output
file. The path name is a, not necessarily absolute, designator of the
directory in which the output file is located. If the output file is
indicated as, e.g., -o out, then OUTDIR simply inserts a dot.
- If the output file is the standard output file, a dot is inserted
too.
- OUTFILENAME
- OUTFILENAME inserts the current filename of the output file into the
output file. The filename is the name of the file of which the directory
components were stripped.
- If the output file is the standard output file, - is inserted.
- PARAGRAPH
- PARAGRAPH isn’t really a builtin function, but as it is handled
especially by Yodl, it is described here nonetheless. Starting with Yodl
2.00 PARAGRAPH operates as follows:
- If the macro is not defined, new paragraphs, defined as series of
consecutive empty lines written to the output stream, are not handled
different from any other series of characters sent to the output stream.
I.e., they are inserted into that stream.
- However, if the macro has been defined, Yodl will call it whenever a new
paragraph (defined as a series of at least two blank lines) was
recognized.
- The empty lines that were actually recognized may be obtained inside the
PARAGRAPH macro from the XXparagraph symbol, if this symbol has
been be defined by that time. If defined, it will contain the white space
that caused Yodl to call the PARAGRAPH macro.
- Note that, in order to inspect XXparagraph it must have been defined
first. Yodl itself will not define this symbol itself.
- The PARAGRAPH macro should be defined as a macro not expecting arguments.
The macro is thus given a chance to process the paragraph in a way
that’s fitting for the particular conversion type. If the PARAGRAPH
macro produces series of empty lines itself, then those empty lines will
not cause Yodl to activate PARAGRAPH. So, Yodl itself will not
recursively call PARAGRAPH, although the macro could call itself
recursively. Of course, such recursive activcation of PARAGRAPH is then
the sole responsibility of the macro’s author, and not
Yodl’s.
- Some document languages do not need paragraph starts; e.g., LaTeX handles
its own paragraphs. Other document languages do need it: typically,
PARAGRAPH is then defined in a macro file to trigger some special action.
E.g., a HTML converter might define a paragraph as:
DEFINEMACRO(PARAGRAPH)(0)(
XXnl()
NOTRANS(<p>)
)
A sytem like xml has more strict requirements. Paragraphs here must be
opened and closed using pairs of <p> and </p> tags. In those
cases an auxiliary counter can be used to indicate whether there is an
open paragraph or not. The PARAGRAPH macro could check for this as
follows, assuming the availability of a counter XXp:
DEFINEMACRO(PARAGRAPH)(0)(
XXnl()
IFZERO(XXp)(
)(
NOTRANS(</p>)
)
NOTRANS(<p>)
SETCOUNTER(XXp)(1)
)
Note that the above fragment exemplifies an approach, not necessarily
the implementation of the PARAGRAPH macro for an
xml-convertor.
- PIPETHROUGH
- The builtin function PIPETHROUGH is, besides SYSTEM, the second function
with which a Yodl document can affect its environment. Therefore, the
danger of `live data’ exists which is also described in the section
about SYSTEM (see section [SYSTEM]). Nevertheless, PIPETHROUGH can be very
useful. It is intended to use external programs to accomplish special
features. The idea is that an external command is started, to which a
block of text from within a Yodl document is `piped’. The output of
that child program is piped back into the Yodl document; hence, a block of
text is `piped through’ an external program. Whatever is received
again in the Yodl run, is further processed.
- The PIPETHROUGH function takes two arguments:
- o
- the command to run, and
- o
- the text to send to that command.
- Functionally, the occurrence of the PIPETHROUGH function and of its two
arguments is replaced by whatever the child program produces on its
standard output.
- An example might be the inclusion of the current date, as in:
-
The current date is:
PIPETHROUGH(date)()
- In this example the command is date and the text to send to that program
is empty.
- The main purpose of this function is to provide a way by which external
programs can be used to create, e.g., tables or figures for a given output
format. Further releases of Yodl may contain such dedicated programs for
the output formats.
- POPCHARTABLE
- Character tables which are pushed onto the table stack using
PUSHCHARTABLE() are restored (popped) using POPCHARTABLE(). For a
description of this mechanism please refer to section
[PUSHINGTABLES].
- POPCOUNTER
- POPCOUNTER is used to remove the topmost counter from the counter stack.
The values of counters may be pushed on a stack using PUSHCOUNTER
[PUSHCOUNTER]. To remove the topmost element of a counter’s stack
POPCOUNTER is available. POPCOUNTER expects one argument: the name of the
counter to pop. The previously pushed value then becomes the new value of
the counter. A counter’s value may be popped after defining it,
whereafter the stack will be empty, but the counter will still be defined.
In that case, using the counter’s value is considered an
error.
- Examples:
DEFINECOUNTER(YEAR)(1950)
POPCOUNTER(YEAR)
COMMENT(YEAR now has an undefined value)
See also section [COUNTERS].
- POPMACRO
- POPMACRO is used to remove the actual macro definition, restoring a
previously pushed definition. The values of macros may be pushed on a
stack using PUSHMACRO. To remove the topmost element of a macro’s
stack POPMACRO is available. POPMACRO expects one argument: the name of
the macro to pop. The previously pushed value then becomes the new value
of the macro.
- A macro’s value may be popped after defining it, whereafter the
stack will be empty, but the macro will still be defined. In that case,
using the macro is considered an error.
- Example:
DEFINEMACRO(Hello)(1)(Hello, ARG1, this is a macro definition)
Hello(Karel)
PUSHMACRO(Hello)(1)(Hello, ARG1, this is the new definition)
Hello(Karel)
POPMACRO(Hello)
Hello(Karel)
COMMENT(The third activation of Hello() produces the same output
as the first activation)
- POPSYMBOL
- POPSYMBOL is used to remove the topmost symbol from the symbol stack. The
values of symbols may be pushed on a stack using PUSHSYMBOL [PUSHSYMBOL].
To remove the topmost element of a symbol’s stack POPSYMBOL is
available.
- POPSYMBOL expects one argument: the name of the symbol to pop. The
previously pushed value then becomes the new value of the symbol. A
symbol’s value may be popped after defining it, whereafter the
stack will be empty, but the symbol will still be defined. In that case,
using the symbol’s value is considered an error.
- Example:
DEFINESYMBOL(YEAR)(This happened in 1950)
POPSYMBOL(YEAR)
COMMENT(YEAR now has an undefined value)
- POPWSLEVEL
- POPWSLEVEL is used to remove the topmost wslevel from the wslevel stack.
The values of wslevels may be pushed on a stack using PUSHWSLEVEL
[PUSHWSLEVEL]. See also section DECWSLEVEL [DECWSLEVEL]
- To remove the topmost element of a wslevel’s stack POPWSLEVEL is
available. POPWSLEVEL expects one argument: the name of the wslevel to
pop. The previously pushed value then becomes the new value of the
wslevel. A wslevel’s value may be popped after defining it,
whereafter the stack will be empty, but the wslevel will still be defined.
In that case, using the wslevel’s value is considered an
error.
- Example:
COMMENT(Assume WS level is zero)
PUSHWSLEVEL(1)
COMMENT(WS level now equals 1)
POPWSLEVEL()
COMMENT(WS level now equals 0 again)
- PUSHCHARTABLE
- Once a character table has been defined, it can be pushed onto a
stack using PUSHCHARTABLE. The pushed chartable may be popped
later. PUSHCHARTABLE is described in more detail in section
[PUSHINGTABLES].
- PUSHCOUNTER
- PUSHCOUNTER is used to start another lifetime for a counter, pushing its
current value on a stack. A stack is available for each individual
counter.
- PUSHCOUNTER expects two arguments: the name of the counter to push and its
new value after pushing. When the second argument is an empty parameter
list, the new value will be zero. The new value may be specified as a
numerical value, or as the name of an existing counter. Specify the name
of the counter twice to merely push its value, without modifying its
current value.
- Examples:
DEFINECOUNTER(YEAR)(1950)
PUSHCOUNTER(YEAR)(1962)
COMMENT(YEAR now has the value 1962, and a pushed value of 1950)
See also section [COUNTERS].
- PUSHMACRO
- PUSHMACRO is used to start another lifetime for a macro, pushing its
current definition on a stack. A stack is available for each individual
macro.
- PUSHMACRO expects three arguments: the name of the macro to push, the
number of its arguments after pushing (which may be different from the
number of arguments interpreted by the pushed macro) and its new
definition.
- So, PUSHMACRO is used exactly like DEFINEMACRO, but will redefine a
current macro (or define a new macro if no macro was defined by the name
specified as its first argument.
- Example:
DEFINEMACRO(Hello)(1)(Hello, ARG1, this is a macro definition)
Hello(Karel)
PUSHMACRO(Hello)(1)(Hello, ARG1, this is the new definition)
Hello(Karel)
POPMACRO(Hello)
Hello(Karel)
COMMENT(The third activation of Hello() produces the same output
as the first activation)
- PUSHSYMBOL
- PUSHSYMBOL is used to start another lifetime for a symbol, pushing its
current value on a stack. A stack is available for each individual
symbol.
- PUSHSYMBOL expects two arguments: the name of the symbol to push and its
new value after pushing. When the second argument is an empty parameter
list, the new value will be zero. The new value may be specified as a
numerical value, or as the name of an existing symbol. Specify the name of
the symbol twice to merely push its value, without modifying its current
value.
- Examples:
DEFINESYMBOL(YEAR)(This happened in 1950)
PUSHSYMBOL(YEAR)(This happended in 1962)
COMMENT(YEAR now has the value `This happended in 1962’ and a
pushed value of `This happened in 1950’)
- PUSHWSLEVEL
- PUSHWSLEVEL is used to start another lifetime of the white-space level
pushing the level’s current value on a stack. See also section
INCWSLEVEL [INCWSLEVEL]
- PUSHWSLEVEL expects one argument, the new value of the white-space level.
This value may be specified as a numerical value or as the name of a
counter. The argument may be empty, in which the new value will be
zero.
- Example:
COMMENT(Assume WS level is zero)
PUSHWSLEVEL(1)
COMMENT(WS level now equals 1)
POPWSLEVEL()
COMMENT(WS level now equals 0 again)
- RENAMEMACRO
- RENAMEMACRO takes two arguments: the name of a built-in macro (such as
INCLUDEFILE) and its new name.
- E.g., after
RENAMEMACRO(INCLUDEFILE)(include)
- a file must be included by include(file). INCLUDEFILE can no longer
be used for this: following the RENAMEMACRO action, the old name can no
longer be used; it becomes an undefined symbol.
- If you want to make an alias for a built-in command, do it with
DEFINEMACRO. E.g., after:
DEFINEMACRO(include)(1)(INCLUDEFILE(ARG1))
both INCLUDEFILE and include can be used to include a file.
- SETCOUNTER
- SETCOUNTER expects two parameter lists: the name of a counter, and a
numeric value or the name of another counter.
- The corresponding counter (which must be previously created with
NEWCOUNTER) is set to, respectively, the numeric value or the value of the
other counter.
- See also section [COUNTERS].
- SETSYMBOL
- SETSYMBOL expects two parameter lists: the name of a symbol, and the text
to assign to the named symbol.
- STARTDEF
- STARTDEF is obsolete. Instead, INCWSLEVEL [INCWSLEVEL] should be
used.
- SUBST
- SUBST is a general-purpose substitution mechanism for strings in the
input. SUBST takes two arguments: a search string and a substitution
string. E.g., after
SUBST(VERSION)(1.00)
YODL will transorm all occurrences of VERSION in its input into 1.00.
- SUBST is also useful in situations where multi-character sequences should
be converted to accent characters. E.g., a LaTeX converter might define:
SUBST(’e)(NOTRANS(\’{e}))
Each ’e in the input will then be converted to e.
- SUBST may be useed in combination with the command line flag -P, as in a
invocation
yodl2html -P’SUBST(VERSION)(1.00)’ myfile.yo
- Another useful substitution might be:
SUBST(_OP_)(CHAR(40))
SUBST(_CP_)(CHAR(41))
- which defines an opening parenthesis (_OP_) and a closing parenthesis
(_CP_) as mapped to the CHAR function. The strings _OP_ and _CP_ might
then be used to produce unbalanced parameter lists.
- Note that:
- o
- The first argument of the SUBST command, the search string, is taken
literally. Yodl does not expand it; the string must be literally matched
in the input.
- o
- The second argument, the replacement, is further processed by Yodl.
Protect this text by NOTRANS or NOEXPAND where appropriate.
- Substitutions occur extremely early while YODL processes its input files.
In order to processs its input files, YODL takes the following basic
steps:
- 1.
- It requests input from its lexical scanner (so-called tokens)
- 2.
- Its parser processes the tokens produced by the lexical scanner
- 3.
- Its parser may send text to an output `object’, which will
eventually appear in the output file generated by YODL. YODL will perform
all macro substitutions in step 2, and all character table conversions in
step 3. However, the lexical scanner has access to the SUBST definitions:
as soon as its lexical analyzer detects a series of characters matching
the defining sequence of a SUBST definition, it will replace that defining
sequence by its definition. That definition is then again read by the
lexical scanner. Of course, this definition may, in turn, contain defining
sequences of other SUBST definitions: these will then be replaced by their
definitions as well. This implies:
- o
- Circular definitions may cause the lexical scanner to get stuck in a
replacement loop. It is the responsibility of the author defining SUBST
definitions to make sure that this doesn’t happen.
- o
- Neither the parser, nor the output object ever sees the SUBST defining
character sequences: they will only see their definitions.
- SYMBOLVALUE
- SYMBOLVALUE expands to the value of a symbol. Its single parameter list
must contain the name of a symbol. The symbol must have been created
earlier using the builtin DEFINESYMBOL.
Example:
The symbol has value SYMBOLVALUE(MYSYMBOL).
- SYSTEM
- SYSTEM takes one argument: a command to execute. The command is run via
the standard C function system. The presence of this function in the Yodl
language introduces the danger of live data. Imagine someone
sending you a document containing
SYSTEM(rm *)
To avoid such malevolent side effects, YODL has a flag -l to define the
`live data policy’. By default, -l0 is implied which suppresses the
SYSTEM function and the related PIPETHROUGH function. See also section
[USING].
- Despite the potential danger, SYSTEM can be useful in many ways. E.g., you
might want to log when someone processes your document, as in:
SYSTEM(echo Document processed! | mail myself@my.host)
Note that SYSTEM merely performs an system-related task. It’s a
process that is separated from the YODL process itself. One of the
consequences of this is that any output generated by SYSTEM will not
normally appear into YODL’s output file. If the output of a
subprocess should be inserted into YODL’s output file, either use
PIPETHROUGH [PIPETHROUGH], or insert a temporary file as shown in the
following example:
SYSTEM(date > datefile)
The current date is:
INCLUDEFILE(datefile)
SYSTEM(rm datefile)
- TYPEOUT
- TYPEOUT requires one parameter list. The text of the list is sent to the
standard error stream, followed by a newline. This feature can be handy to
show, e.g., messages such as version numbers in macro package files.
- Example: The following macro includes a file and writes to the screen that
this file is currently processed.
DEFINEMACRO(includefile)(1)(
TYPEOUT(About to process document: ARG1)
INCLUDEFILE(ARG1)
)
- UNDEFINEMACRO
- UNDEFINEMACRO is deprecated. Use DELETEMACRO [DELETEMACRO] instead.
- UPPERCASE
- UPPERCASE converts a string or a part of it to upper case. It has two
arguments:
- o
- The string to convert;
- o
- A length, indicating how many characters (starting from the beginning of
the string) should be converted. The length indicator can be smaller than
one or larger than the length of the string; in that case, the whole
string is convertered.
- Example:
UPPERCASE(hello world)(1)
UPPERCASE(hello world)(5)
UPPERCASE(hello world)(0)
This code sample expands to:
Hello world
HELLO world
HELLO WORLD
- USECHARTABLE
- USECHARTABLE takes one parameter list: the name of a translation table to
activate. The table must previously have been defined using
DEFINECHARTABLE. See section [CHARTABLES] for a description of character
translation tables.
- Alternatively, the name may be empty in which case the default character
mapping is restored.
- USECOUNTER
- USECOUNTER is a combination of ADDTOCOUNTER and COUNTERVALUE. It expects
one parameter list: the name of an defined counter (see DEFINECOUNTER
[DEFINECOUNTER]).
- The counter is first incremented by 1. Then the function expands to the
counter’s value.
- See also section [COUNTERS].
- VERBOSITY
- VERBOSITY expects two arguments, and may be used to change the verbosity
level inside YODL files. The function may be used profitably for debugging
purposes, to debug the expansion of a macro or the processing of a YODL
input file.
- The first argument indicates the procesing mode of the second argument,
and it may be:
- o
- Empty, in which case the message-level is set to the value specified in
the second argument;
- o
- +, in which case the value specified in the second argument augments the
current message level;
- o
- -, in which case the value specified in the second argument augments is
removed from the current message level
- The second argument specifies one or more, separated by blanks, message
level names or it may be set to a hexadecimal value (starting with 0x),
using hexadecimal values to represent message levels. Also, NONE may be
used, to specify no message level, or ALL can be used to specify all
message levels.
- The following message levels are defined:
- o
- ALERT (0x40). When an alert-error occurs, Yodl terminates. Here Yodl
requests something of the system (like a get_cwd()), but the system
fails.
- o
- CRITICAL (0x20). When a critical error occurs, Yodl terminates. The
message itself can be suppressed, but exiting can’t. A critical
condition is, e.g., the omission of an open parenthesis at a location
where a parameter list should appear, or a non-existing file in an
INCLUDEFILE specification (as this file should be parsed). A non-existing
file with a NOEXPANDINCLUDE specification is a plain (non-critical)
error.
- o
- DEBUG (0x01). Probably too much info, like getting information about each
character that was read by Yodl.
- o
- ERROR (0x10). An error (like doubly defined symbols). Error messages will
not stop the parsing of the input (up to a maximum number of errors), but
no output is generated.
- o
- INFO (0x02). Not as detailed as `debug’, but still very much info,
like information about media switches.
- o
- NOTICE (0x04). Information about, e.g., calls to the builtin function
calls.
- o
- WARNING (0x08). Something you should know about, but probably not
affecting Yodl’s proper functioning
- There also exists a level EMERG (0x80) which cannot be suppressed.
- The value 0x00 represents NONE, the value 0xff represents ALL.
- When specifying multiple message levels using the hexadecimal form, their
hexadecimal values should be binary-or-ed: adding them is ok, as long as
you don’t specify ALL:
VERBOSITY()(0x06)
COMMENT(this specifies `INFO’ and `NOTICE’)
When specifying message levels by their names, the names may be truncated at
a unique point. However, the message level names are interpreted case
sensitively, so INF for INFO is recognized as such, but info for INFO
isn’t. The following examples all specify verbosity levels INFO and
NOTICE:
VERBOSITY()(I N)
VERBOSITY()(N I)
VERBOSITY()(NOT IN)
VERBOSITY()(INFO NOTICE)
- WARNING
- WARNING takes one argument: text to display as a warning. The yodl program
makes sure that before showing the text, the current file and line number
are printed. Other than this, WARNING works just as TYPEOUT (see section
[TYPEOUT]).
- Note that an analogous function ERROR exists, which prints a message and
then terminates the program (see section [ERROR]).
- WRITEOUT
- WRITEOUT is deprecated, use FPUTS [FPUTS] instead.
FILES¶
The files in
tmp/wip/macros define the converter’s macro packages.
The scripts
yodl2tex,
yodl2html,
yodl2man etc. perform
the conversions.
SEE ALSO¶
yodlstriproff(1),
yodl(1),
yodlconverters(1),
yodlletter(7),
yodlmacros(7),
yodlmanpage(7),
yodlpost(1),
yodlverbinsert(1).
BUGS¶
--
AUTHOR¶
Frank B. Brokken (f.b.brokken@rug.nl),