Lugaru's Epsilon Programmer's Editor 14.04
Context:
| Printf-style Format Strings
|
|
Previous
|
Up
|
Next
|
Displaying Status Messages |
Primitives and EEL Subroutines |
Other Display Primitives |
Epsilon User's Manual and Reference >
Primitives and EEL Subroutines >
Display Primitives >
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 |
Epsilon Programmer's Editor 14.04 manual. Copyright (C) 1984, 2021 by Lugaru Software Ltd. All rights reserved.
|