

		  LysKOM Extended String Formatting
			    By David Byers


CONTENTS

	1 .................................... The Format String
	2 .................................... Format Directives
	  2.1 ................................ Format Letters
	  2.2 ................................ Format Arguments
	  2.3 ................................ Format Flags
        3 .................................... Formatting Functions
	  3.1 ................................ Main Functions
	  3.2 ................................ Auxiliary functions
	  3.3 ................................ Related functions
	4 .................................... Format States



1. THE FORMAT STRING

The format string is a character string which is inserted verbatim
into the result string with the exception of special format directives
which cause values from the argument list to be inserted.


2. FORMAT DIRECTIVES

The syntax of all format directives is

		%[pad-length]#[arg-no][flags][format-letter]

pad-length is the length of the resulting string. If it is negative,
is will be left-justified in the length, otherwise
right-justified. This field is optional.

arg-no is the argument number from the argument list to insert, and
must be prefixed by a hash mark when it exists. This field is
mandatory for all format directives that use an argument.

flags are optional flags applicable to certain format letters. When
not applicable, the flags field is ignored. Flags are optional.

format-letter is one of the format letters given below. It determines
how the given argument is inserted.


2.1 Format Letters

% - Insert a percent character. This directive does not use an
    argument. 

s - Insert a string. If the argument is a character string it is
    inserted verbatim. If it is a symbol, the name of the symbol is
    inserted. 

d - Insert an integer in decimal format.

o - Insert an integer in octal format.

x - Insert an integer in hexadecimal format. 

c - Interpret and insert an integer as a single character.

@ - The argument must be a valid text property list, and will be
    inserted into the buffer at the point of this directive provided
    one of the lyskom-format-insert functions was called. The extent
    of the format in the buffer is to the end of the current subformat
    string or the entire format string if processing is at the top
    level.

$ - Start an overlay. The argument is a property list containing the
    properties to set on the overlay. Overlays are only available when
    calling lyskom-format-insert and lyskom-format-insert-at-point.
    The extent of the overlay in the buffer is to the end of the
    current subformat string or the entire format string if processing
    is at the top level.

[ - Begin subformat. This directive does not use an argument.

] - Exit subformat. This directive does not use an argument.

M - The argument must be a conf-stat, conf-no or character string.
    This directive inserts the name of the conference or the character
    string. If the argument is a conf-stat or integer, text properties
    appropriate for conferences are added.

m - The argument must be a conf-stat or an integer. The directive
    inserts the conference number or the integer in decimal format and 
    adds text properties as appropriate for conferences.

P - The argument must be a conf-stat or a character string. This
    direcive works similarly to %M, but assums the conf-stat, conf-no
    or string represents a LysKOM user, not a regular conference.

p - The argument must be a conf-stat or integer. This directive works
    similarly to %m, but assumes the conf-stat or integer representes
    a LysKOM user, not a regular conference.

t - The argument must be a character string or a text structure. The
    text is inserted and appropriate text properties added. The first
    line of the text is NOT assumed to be the subject line.

n - The argument must be an integer or a text-stat. The integer or
    text-no is inserted and appropriate text properties added.

r - The argument is a string and will be formatted as a subject line.



2.2 Format Arguments

The type of argument appropriate for each format directive is
presented above. In addition, all format directives accept a
format-props structure as an argument. The format-props structure
contains a regular argument as shown above and text properties to be
applied to the extent of the text inserted by the directive.

The format-props structure is constructed using the make-format-props
function which takes the regular format argument and the property list
as its two arguments.

The %[ direcive also accepts format-props structures as its (optional)
argument, but ignores the regular argument part of the structure, but
applies the text properties to the entire subformat result. Thus,

	(lyskom-format-insert "%[%#1@From: %#2P]\n" 
		(make-format-props nil '(face blue))
		pers-conf-stat)

would format the entire line blue.


2.3 Format Flags

The M, m, P, p, r and n directives accept the : character as a flag.
If it is supplied, the regular text properties are not inserted.

All format directives accept the = character as a flag. Using this
flag ensures that the result will be truncated to the field width.
