Printf-style Format Strings

Primitives like say( ) along with several others take a particular pattern of arguments. The first argument is required. It is a character pointer called the format string. The contents of the format string determine what other arguments are necessary.

Characters in the format string are copied to the echo area except where a percent character "%" appears. The percent begins a sequence which interpolates the value of an additional argument into the text that will appear in the echo area. The sequence has the following pattern, in which square brackets [ ] enclose optional items:

% [ ' ] [ - ] [ number ] [ . number ] character

In this pattern number may be either a string of digits or the character "*". If the latter, the next argument provided to the primitive must be an int, and its value is used in place of the digits.

The meaning of the sequence depends on the final character:

c: The next argument must be an int. (As explained previously, a character argument is changed to an int when a function is called, so it's fine here too.) The character with that ASCII code is inserted in the displayed text. For example, if the argument is 65 or 'A', the letter A appears, since the code for A is 65.
d: The next argument must be an int. A sequence of characters for the decimal representation of that number is inserted in the displayed text. For example, if the argument is 65 the characters "6" and "5" are produced. With the ' modifier, values of more than four digits are shown with commas, as in 12,345,678.
x: The next argument must be an int. A sequence of characters for the hexadecimal (base 16) representation of that number is inserted in the displayed text. For example, if the argument is 65 the characters "4" and "1" are produced (since the hexadecimal number 0x41 is equal to 65 in base 10). No minus sign appears with this representation.
o: The next argument must be an int. A sequence of characters for the octal representation of that number is inserted in the displayed text. For example, if the argument is 65 the three characters "101" are produced (since the octal number 101 is equal to 65 in base 10). No minus sign appears with this representation.
s: The next argument, which must be a string, is copied to the displayed text.
q: The next argument, which must be a string, is copied to the displayed text, but quoted for inclusion in a regular expression. In other words, any characters from the original string that have a special meaning in regular expressions are copied with a percent character ("%") before them. See Regular Expressions for information on regular expressions.
r: The next argument (which must be a string containing a file name in absolute form) is copied to the displayed text, after being converted to relative form. Epsilon calls the relative( ) primitive, described in Manipulating File Names, to do this.
f: The next argument must be a string, typically the name of a file. This sequence is just like %s except when used in a primitive that displays text in the echo area, such as say( ), and the entire text to be displayed is too wide to fit in the available room. In that case, Epsilon calls the abbreviate_file_name( ) subroutine defined in disp.e to abbreviate the file name so the entire message fits in the available width. If the displayed message is also recorded in the #messages# buffer, where no width restriction applies, the unabbreviated form of the message will be used.
k: The next argument must be a number. Epsilon interprets it as a key code or Unicode character code, and interpolates the name of that key or character. If a number starting with zero appears after the % character, Epsilon uses the short form of the key name, if any. See the key_value( ) primitive to convert in the opposite direction, converting text (in the short form only) back to a key's numeric code.
p: The next argument must be a number. Epsilon interprets it as a color class, and any following text appears in that color. This only works on those primitives that insert text into a buffer; the numeric argument is ignored in a sprintf( ) or say( ) or similar.
e: The next argument must be a number. Epsilon interprets it as an Epsilon error code, one that Epsilon might store in the errno variable or return directly from certain primitives, and interpolates text describing the error.

The first number, if present, is the width of the field the argument will be printed in. At least that many characters will be produced, and more if the argument will not fit in the given width. If no number is present, exactly as many characters as are required will be used.

The extra space will normally be put before the characters generated from the argument. If a minus sign is present before the first number, however, the space will be put at the end instead.

If the first number begins with the digit 0, the extra space will be filled with zeros instead of spaces. A minus sign before the first number is ignored in this case.

The second number, if present, is the maximum number of characters from the string that will be displayed. For example, each of these lines displays the text, "Just an example":

say("Just %.2s example", "another"); say("Just %.*s example", 7-5, "another");
It may be tempting to substitute a string variable for the first parameter of say( ). For example, when writing a function that displays its argument msg and pauses, it may seem natural to write say(msg);. This will work fine unless msg contains a "%" character. In that case, you will probably get an error message. Use say("%s", msg); instead.

user char in_echo_area;
The in_echo_area variable controls whether the cursor is positioned at point in the buffer, or in the echo area at the bottom of the screen. The sayput( ) primitive sets this variable, say( ) resets it, and it is reset after each command.

Previous Up Next
Displaying Status Messages Primitives and EEL Subroutines Other Display Primitives