English-Language Directives

Some of the handiest **FORMAT** directives for generating human-readable messages are the ones for emitting English text. These directives allow you to emit numbers as English words, to emit plural markers based on the value of a format argument, and to apply case conversions to sections of **FORMAT**‘s output.

The ~R directive, which I discussed in “Character and Integer Directives,” when used with no base specified, prints numbers as English words or Roman numerals. When used with no prefix parameter and no modifiers, it emits the number in words as a cardinal number.

(format nil "~r" 1234) ==> "one thousand two hundred thirty-four"

With the colon modifier, it emits the number as an ordinal.

(format nil "~:r" 1234) ==> "one thousand two hundred thirty-fourth"

And with an at-sign modifier, it emits the number as a Roman numeral; with both an at-sign and a colon, it emits “old-style” Roman numerals in which fours and nines are written as IIII and VIIII instead of IV and IX.

(format nil "~@r" 1234)  ==> "MCCXXXIV"
(format nil "~:@r" 1234) ==> "MCCXXXIIII"

For numbers too large to be represented in the given form, ~R behaves like ~D.

To help you generate messages with words properly pluralized, **FORMAT** provides the ~P directive, which simply emits an s unless the corresponding argument is 1.

(format nil "file~p" 1)  ==> "file"
(format nil "file~p" 10) ==> "files"
(format nil "file~p" 0)  ==> "files"

Typically, however, you’ll use ~P with the colon modifier, which causes it to reprocess the previous format argument.

(format nil "~r file~:p" 1)  ==> "one file"
(format nil "~r file~:p" 10) ==> "ten files"
(format nil "~r file~:p" 0)  ==> "zero files"

With the at-sign modifier, which can be combined with the colon modifier, ~P emits either y or ies.

(format nil "~r famil~:@p" 1)  ==> "one family"
(format nil "~r famil~:@p" 10) ==> "ten families"
(format nil "~r famil~:@p" 0)  ==> "zero families"

Obviously, ~P can’t solve all pluralization problems and is no help for generating messages in other languages, but it’s handy for the cases it does handle. And the ~[ directive, which I’ll discuss in a moment, gives you a more flexible way to conditionalize parts of **FORMAT**‘s output.

The last directive for dealing with emitting English text is ~(, which allows you to control the case of text in the output. Each ~( is paired with a ~), and all the output generated by the portion of the control string between the two markers will be converted to all lowercase.

(format nil "~(~a~)" "FOO") ==> "foo"
(format nil "~(~@r~)" 124)  ==> "cxxiv"

You can modify ~( with an at sign to make it capitalize the first word in a section of text, with a colon to make it to capitalize all words, and with both modifiers to convert all text to uppercase. (A word for the purpose of this directive is a sequence of alphanumeric characters delimited by nonalphanumeric characters or the ends of the text.)

(format nil "~(~a~)" "tHe Quick BROWN foX")   ==> "the quick brown fox"
(format nil "~@(~a~)" "tHe Quick BROWN foX")  ==> "The quick brown fox"
(format nil "~:(~a~)" "tHe Quick BROWN foX")  ==> "The Quick Brown Fox"
(format nil "~:@(~a~)" "tHe Quick BROWN foX") ==> "THE QUICK BROWN FOX"