Document: BTXHAK ["Designing BibTeX Styles" by Oren Patashnik]

5.3 The built-in functions

Before we get to the built-in functions, a few words about some other built-in objects. There is one built-in string entry variable, sort.key$, which the style program must set if the style is to do sorting. There is one built-in field, crossref, used for the cross referencing feature described in Section 4. And there are two built-in integer global variables, entry.max$ and global.max$, which are set by default to some internal constants; you should truncate strings to these lengths before you assign to string variables, so as to not generate any warning messages.

There are currently 37 built-in functions. Every built-in function with a letter in its name ends with a `$'. In what follows, ``first'', ``second'', and so on refer to the order popped. A ``literal'' is an element on the stack, and it will be either an integer value, a string value, a variable or function name, or a special value denoting a missing field. If any popped literal has an incorrect type, complains and pushes the integer 0 or the null string, depending on whether the function was supposed to push an integer or string.

>

Pops the top two (integer) literals, compares them, and pushes the integer 1 if the second is greater than the first, 0 otherwise.

<

Analogous.

=

Pops the top two (both integer or both string) literals, compares them, and pushes the integer 1 if they're equal, 0 otherwise.

+

Pops the top two (integer) literals and pushes their sum.

-

Pops the top two (integer) literals and pushes their difference (the first subtracted from the second).

*

Pops the top two (string) literals, concatenates them (in reverse order, that is, the order in which pushed), and pushes the resulting string.

:=

Pops the top two literals and assigns to the first (which must be a global or entry variable) the value of the second.

add.period$

Pops the top (string) literal, adds a `.' to it if the last non`}' character isn't a `.', `?', or `!', and pushes this resulting string.

call.type$

Executes the function whose name is the entry type of an entry. For example if an entry is of type book, this function executes the book function. When given as an argument to the ITERATE command, call.type$ actually produces the output for the entries. For an entry with an unknown type, it executes the function default.type. Thus you should define (before the READ command) one function for each standard entry type as well as a default.type function.

change.case$

Pops the top two (string) literals; it changes the case of the second according to the specifications of the first, as follows. (Note: The word `letters' in the next sentence refers only to those at brace-level 0, the top-most brace level; no other characters are changed, except perhaps for ``special characters'', described in Section 4.) If the first literal is the string `t', it converts to lower case all letters except the very first character in the string, which it leaves alone, and except the first character following any colon and then nonnull white space, which it also leaves alone; if it's the string `l', it converts all letters to lower case; and if it's the string `u', it converts all letters to upper case. It then pushes this resulting string. If either type is incorrect, it complains and pushes the null string; however, if both types are correct but the specification string (i.e., the first string) isn't one of the legal ones, it merely pushes the second back onto the stack, after complaining. (Another note: It ignores case differences in the specification string; for example, the strings t and T are equivalent for the purposes of this built-in function.)

chr.to.int$

Pops the top (string) literal, makes sure it's a single character, converts it to the corresponding ASCII integer, and pushes this integer.

cite$

Pushes the string that was the \cite-command argument for this entry.

duplicate$

Pops the top literal from the stack and pushes two copies of it.

empty$

Pops the top literal and pushes the integer 1 if it's a missing field or a string having no non-white-space characters, 0 otherwise.

format.name$

Pops the top three literals (they are a string, an integer, and a string literal). The last string literal represents a name list (each name corresponding to a person), the integer literal specifies which name to pick from this list, and the first string literal specifies how to format this name, as explained in the next subsection. Finally, this function pushes the formatted name.

if$

Pops the top three literals (they are two function literals and an integer literal, in that order); if the integer is greater than 0, it executes the second literal, else it executes the first.

int.to.chr$

Pops the top (integer) literal, interpreted as the ASCII integer value of a single character, converts it to the corresponding single-character string, and pushes this string.

int.to.str$

Pops the top (integer) literal, converts it to its (unique) string equivalent, and pushes this string.

missing$

Pops the top literal and pushes the integer 1 if it's a missing field, 0 otherwise.

newline$

Writes onto the bbl file what's accumulated in the output buffer. It writes a blank line if and only if the output buffer is empty. Since write$ does reasonable line breaking, you should use this function only when you want a blank line or an explicit line break.

num.names$

Pops the top (string) literal and pushes the number of names the string represents - one plus the number of occurrences of the substring ``and'' (ignoring case differences) surrounded by nonnull white-space at the top brace level.

pop$

Pops the top of the stack but doesn't print it; this gets rid of an unwanted stack literal.

preamble$

Pushes onto the stack the concatenation of all the @PREAMBLE strings read from the database files.

purify$

Pops the top (string) literal, removes nonalphanumeric characters except for white-space characters and hyphens and ties (these all get converted to a space), removes certain alphabetic characters contained in the control sequences associated with a ``special character'', and pushes the resulting string.

quote$

Pushes the string consisting of the double-quote character.

skip$

Is a no-op.

stack$

Pops and prints the whole stack; it's meant to be used for style designers while debugging.

substring$

Pops the top three literals (they are the two integers literals len and start, and a string literal, in that order). It pushes the substring of the (at most) len consecutive characters starting at the startth character (assuming 1-based indexing) if start is positive, and ending at the startth character from the end if start is negative (where the first character from the end is the last character).

swap$

Swaps the top two literals on the stack.

text.length$

Pops the top (string) literal, and pushes the number of text characters it contains, where an accented character (more precisely, a ``special character'', defined in Section 4) counts as a single text character, even if it's missing its matching right brace, and where braces don't count as text characters.

text.prefix$

Pops the top two literals (the integer literal len and a string literal, in that order). It pushes the substring of the (at most) len consecutive text characters starting from the beginning of the string. This function is similar to substring$, but this one considers a ``special character'', even if it's missing its matching right brace, to be a single text character (rather than however many ASCII characters it actually comprises), and this function doesn't consider braces to be text characters; furthermore, this function appends any needed matching right braces.

top$

Pops and prints the top of the stack on the terminal and log file. It's useful for debugging.

type$

Pushes the current entry's type (book, article, etc.), but pushes the null string if the type is either unknown or undefined.

warning$

Pops the top (string) literal and prints it following a warning message. This also increments a count of the number of warning messages issued.

while$

Pops the top two (function) literals, and keeps executing the second as long as the (integer) literal left on the stack by executing the first is greater than 0.

width$

Pops the top (string) literal and pushes the integer that represents its width in some relative units (currently, hundredths of a point, as specified by the June 1987 version of the font; the only white-space character with nonzero width is the space). This function takes the literal literally; that is, it assumes each character in the string is to be printed as is, regardless of whether the character has a special meaning to , except that ``special characters'' (even without their right braces) are handled specially. This is meant to be used for comparing widths of label strings.

write$

Pops the top (string) literal and writes it on the output buffer (which will result in stuff being written onto the bbl file when the buffer fills up).

Note that the built-in functions while$ and if$ require two function literals on the stack. You get them there either by immediately preceding the name of a function by a single quote, or, if you don't feel like defining a new function with the FUNCTION command, by simply giving its definition (that is, giving what would be the second argument to the FUNCTION command, including the surrounding braces). For example the following function fragment appends the character `a' if the string variable named label is nonnull:

    .  .  .
    label "" =
      'skip$
      { label "a" * 'label := }
    if$
    .  .  .

Document: BTXHAK ["Designing BibTeX Styles" by Oren Patashnik]