32.26 Formatting Customizable Strings

It is, in some circumstances, useful to present users with a string to be customized that can then be expanded programmatically. For instance, erc-header-line-format is "%n on %t (%m,%l) %o", and each of those characters after the percent signs are expanded when the header line is computed. To do this, the format-spec function is used:

Function: format-spec format specification &optional only-present

format is the format specification string as in the example above. specification is an alist that has elements where the car is a character and the cdr is the substitution.

If ONLY-PRESENT is nil, errors will be signalled if a format character has been used that’s not present in specification. If it’s non-nil, that format specification is left verbatim in the result.

Here’s a trivial example:

(format-spec "su - %u %l"
             `((?u . ,(user-login-name))
               (?l . "ls")))
     ⇒ "su - foo ls"

In addition to allowing padding/limiting to a certain length, the following modifiers can be used:

‘0’

Use zero padding.

‘ ’

User space padding.

‘-’

Pad to the right.

‘^’

Use upper case.

‘_’

Use lower case.

‘<’

If the length needs to limited, remove characters from the left.

‘>’

Same as previous, but remove characters from the right.

If contradictory modifiers are used (for instance, both upper and lower case), then what happens is undefined.

As an example, ‘"%<010b"’ means “insert the ‘b’ expansion, but pad with leading zeroes if it’s less than ten characters, and if it’s more than ten characters, shorten by removing characters from the left”.