```
## Formatting directives
The formatting directives supported by library `(lispkit format)` are based on the directives specified in [Common Lisp the Language, 2nd Edition](https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node1.html) by Guy L. Steele Jr. Some directives have been extended to meet today's formatting requirements (e.g. to support localization) and to enable a powerful usage throughout LispKit. Extensions were introduced in a way to not impact backward compatibility.
| Directive | Explanation | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------- | ---------- | ---------------------------- | ------------------------ | -------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------ | ---------- | ---------------------------------------------------- | -------------------- | ------------------ | ---------- | ---------------------------- | --------------------- | ------------------ | ---------- | ---------------------------------------------------- | --------------------- | ------------------ | ---------- | ---------------------------- | ---------------------- | ------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ---- | ---- | ---------------------------- | ------ | ---------- | ---------- | ------------------------------------------------- | ------- | --- | --- | ---------------------------- | ------ | ---------- | ---------- | ------------------------------------------------- | ------- | --------- | --------- | ----------- |
| \~a \~A
| ASCII: \~ mincol,colinc,minpad,padchar,maxcol,elchar A
The next argument arg is output as if procedure display was used, i.e. the output is without escape characters and if arg is a string, its characters will be output verbatim without surrounding quotes.
mincol (default: 0) specifies the minimal "width" of the output of the directive in characters, maxcol (default: ∞) specifies the maximum width. padchar (default: ' ') defines the character that is used to pad the output to make sure it is at least mincol characters long. By default, the output is padded on the right with at least minpad (default: 0) copies of padchar . Padding characters are then inserted colinc (default: 1) characters at a time until the total width is at least mincol . Padding is capped such that the output never exceeds maxcol characters. If, without padding, the output is already longer than maxcol , the output is truncated at width maxcol - 1 and the ellipsis character elchar (default: '…') is inserted at the end.
Modifier @ enables padding on the left to right-align the output.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| \~w \~W
| WRITE: \~ mincol,colinc,minpad,padchar,maxcol,elchar W
The next argument arg is output as if procedure write was used, i.e. the output is with escape characters and if arg is a string, its characters will be output surrounded by quotes.
Parameters mincol (default: 0), colinc (default: 1), minpad (default: 0), padchar (default: ' '), maxcol (default: ∞), and elchar (default: '…') are used just as described for the ASCII directive \~A. Modifier @ enables padding on the left to right-align the output.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| \~s \~S
| SOURCE: \~ mincol,colinc,minpad,padchar,maxcol,elchar S
The next argument arg is output using a type-specific control string. If no control string is registered for the type of arg , then \~S behaves like \~W for arg .
Parameters mincol (default: 0), colinc (default: 1), minpad (default: 0), padchar (default: ' '), maxcol (default: ∞), and elchar (default: '…') are used just as described for the ASCII directive \~A. Modifier @ enables padding on the left to right-align the output.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| \~c \~C
| CHARACTER: ~~C
The next argument arg should be a character or a string consisting of one character. Directive ~~C outputs arg in a form dependent on the modifiers used. Without any modifiers, arg is output as if the character was used in a string without any escaping.
If the @ modifier is provided alone, the character is output using Scheme's syntax for character literals. The modifier combination @: will lead to arg being output as Unicode code points. The combination @:+ will output arg as a sequence of Unicode scalar property names, separated by comma.
If the : modifier is used (without @), a representation of arg for the usage in XML documents is chosen. By default, a Unicode-based XML character encoding is used, unless : is combined with +, in which case the character is represented as a XML named character entity when possible, otherwise, the character is output in raw form.
If the + modifiers is used alone, the character is output as if it is a character of a string, escaped if necessary, and surrounded by quotes.
(format "~~C" #\A) ⟹ A(format "~~+C" #\A) ⟹ "A"(format "~~+C" #\newline) ⟹ "\n"(format "~~@C" "A") ⟹ #\A(format "~~@C" "\t") ⟹ #\tab(format "~~@:C" "©") ⟹ U+00A9(format "~~@:+C" "©") ⟹ COPYRIGHT SIGN(format "~~:C" "©") ⟹ \©(format "\~:+C" "©") ⟹ \©
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| \~d \~D
| DECIMAL: \~ mincol,padchar,groupchar,groupcol D
The next argument arg is output in decimal radix. arg should be an integer, in which case no decimal point is printed. For floating-point numbers which do not represent an integer, a decimal point and a fractional part are output.
mincol (default: 0) specifies the minimal "width" of the output of the directive in characters with padchar (default: ' ') defining the character that is used to pad the output on the left to make sure it is at least mincol characters long.
(format "Number: \~D" 8273) ⟹ Number: 8273(format "Number: \~6D" 8273) ⟹ Number: 8273(format "Number: \~6,'0D" 8273) ⟹ Number: 008273
By default, the number is output without grouping separators. groupchar specifies which character should be used to separate sequences of groupcol digits in the output. Grouping of digits gets enabled with the : modifier.
(format " | \~10:D | " 1734865) ⟹ | 1,734,865 | (format " | \~10,,'.:D | " 1734865) ⟹ | 1.734.865 |
A sign is output only if the number is negative. With the modifier @ it is possible to force output also of positive signs. To facilitate the localization of output, procedure format supports a locale parameter, which is also available via format config objects. Locale-specific output can be enabled for the ~~D directive by using the + modifier.
(format 'de\_CH "~~+D" 14321) ⟹ 14'321
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| \~b \~B
| BINARY: \~ mincol,padchar,groupchar,groupcol B
Binary directive \~B is just like decimal directive \~D but it outputs the next argument in binary radix (radix 2) instead of decimal. It uses the space character as the default for groupchar and has a default grouping size of 4 as the default for groupcol .
(format "bin(\~D) = ~~B" 178 178) ⟹ bin(178) = 10110010(format "~~:B" 59701) ⟹ 1110 1001 0011 0101(format "\~19,'0,'.:B" 31912) ⟹ 0111.1100.1010.1000
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| \~o \~O
| OCTAL: \~ mincol,padchar,groupchar,groupcol O
Octal directive \~O is just like decimal directive \~D but it outputs the next argument in octal radix (radix 8) instead of decimal. It uses the space character as the default for groupchar and has a default grouping size of 4 as the default for groupcol .
(format "bin(\~D) = ~~O" 178 178) ⟹ bin(178) = 262(format "~~:O" 59701) ⟹ 16 4465(format "\~9,'0,',:O" 31912) ⟹ 0007,6250
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| \~x \~X
| HEXADECIMAL: \~ mincol,padchar,groupchar,groupcol X
Hexadecimal directive \~X is just like decimal directive \~D but it outputs the next argument in hexadecimal radix (radix 16) instead of decimal. It uses the colon character as the default for groupchar and has a default grouping size of 2 as the default for groupcol . With modifier +, upper case characters are used for representing hexadecimal digits.
(format "bin(~~D) = ~~X" 9968 9968) ⟹ bin(9968) = 26f0(format "~~:X" 999701) ⟹ f:41:15(format "~~+X" 999854) ⟹ F41AE
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| \~r \~R
| RADIX: \~ radix,mincol,padchar,groupchar,groupcol R
The next argument arg is expected to be a fixnum number. It will be output with radix radix (default: 10). mincol (default: 0) specifies the minimal "width" of the output of the directive in characters with padchar (default: ' ') defining the character that is used to pad the output on the left to make it at least mincol characters long.
(format "Number: \~10R" 1272) ⟹ Number: 1272(format "Number: \~16,8,'0R" 7121972) ⟹ Number: 006cac34(format "Number: ~~2R" 173) ⟹ Number: 10101101
By default, the number is output without grouping separators. groupchar specifies which character should be used to separate sequences of groupcol digits in the output. Grouping of digits is enabled with the : modifier.
(format "~~16,8,,':,2:R" 7121972) ⟹ 6c:ac:34(format "~~2,14,'0,'.,4:R" 773) ⟹ 0011.0000.0101
A sign is output only if the number is negative. With the modifier @ it is possible to force output also of positive signs.
If parameter radix is not specified at all, then an entirely different interpretation is given. ~~R outputs arg as a cardinal number in natural language. The form ~~:R outputs arg as an ordinal number in natural language. ~~@R outputs arg as a Roman numeral.
(format "~~R" 572) ⟹ five hundred seventy-two(format "~~:R" 3) ⟹ 3rd(format "~~@R" 1272) ⟹ MCCLXXII
Whenever output is provided in natural language, English is used as the language by default. By specifying the + modifier, it is possible to switch the language to the language of the locale provided to procedure format. In fact, modifier + plays two different roles: If the given radix is greater than 10, upper case characters are used for representing alphabetic digits. If the radix is omitted, usage of modifier + enables locale-specific output determined by the locale: parameter of procedure format.
(format 'de\_DE "~~+R" 572) ⟹ fünfhundertzweiundsiebzig(format 'de\_CH "\~10+R" 14321) ⟹ 14'321(format "\~16R vs \~16+R" 900939 900939) ⟹ dbf4b vs DBF4B
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| \~f \~F
| FIXED FLOAT: ~~ w,d,k,overchar,padchar,groupchar,groupcol F
The next argument arg is output as a floating-point number in a fixed format (ideally without exponent) of exactly w characters, if w is specified. First, leading padchar characters (default: ' ') are output, if necessary, to pad the field on the left. If arg is negative, then a minus sign is printed. If arg is not negative, then a plus sign is printed if and only if the @ modifier was specified. Then a sequence of digits, containing a single embedded decimal point, is printed. If parameter d is provided, then exactly d decimal places are output. This represents the magnitude of the value of arg times 10k , rounded to d fractional digits. There are no leading zeros, except that a single zero digit is output before the decimal point if the printed value is less than 1.0, and this single zero digit is not output after all if w = d + 1.
If it is impossible to print the value in the required format in a field of width w , then one of two actions is taken: If the parameter overchar is specified, then w copies of this character are printed. If overchar is omitted, then the scaled value of arg is printed using more than w characters.
If the width parameter w is omitted, then the output is of variable width and a value is chosen for w in such a way that no leading padding characters are needed and exactly d characters will follow the decimal point. For example, the directive ~~,2F will output exactly two digits after the decimal point and as many as necessary before the decimal point.
If d is omitted, then there is no constraint on the number of digits to appear after the decimal point. A value is chosen for d in such a way that as many digits as possible may be printed subject to the width constraint imposed by w and the constraint that no trailing zero digits may appear in the fraction, except that if the fraction is zero, then a single zero digit should appear after the decimal point if permitted by the width constraint.
If w is omitted, then if the magnitude of arg is so large (or, if d is also omitted, so small) that more than 100 digits would have to be printed, then arg is output using exponential notation instead.
The \~F directive also supports grouping of the integer part of arg ; this can be enabled via the : modifier. groupchar (default: ',') specifies which character should be used to separate sequences of groupcol (default: 3) digits in the integer part of the output. If locale-specific settings should be used, the + modifier needs to be set.
(format "\~F" 123.1415926) ⟹ 123.1415926(format "~~8F" 123.1415926) ⟹ 123.1416(format "~~8,,,'-F" 123.1415926) ⟹ 123.1416(format "~~8,,,'-F" 123456789.12) ⟹ --------(format "~~8,,,,'0F" 123.14) ⟹ 00123.14(format "~~8,3,,,'0F" 123.1415926) ⟹ 0123.142(format "~~,4F" 123.1415926) ⟹ 123.1416(format "~~,2\@F" 123.1415926) ⟹ +123.14(format "~~,2,-2\@F" 314.15926) ⟹ +3.14(format "~~,2:F" 1234567.891) ⟹ 1,234,567.89(format "~~,2,,,,'',3:F" 1234567.891) ⟹ 1'234'567.89
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| \~e \~E
| EXPONENTIAL FLOAT: ~~ w,d,e,k,overchar,padchar,expchar E
The next argument arg is output as a floating-point number in an exponential format of exactly w characters, if w is specified. Parameter d is the number of digits to print after the decimal point, e is the number of digits to use when printing the exponent, and k is a scale factor that defaults to 1.
First, leading padchar (default: ' ') characters are output, if necessary, to pad the output on the left. If arg is negative, then a minus sign is printed. If arg is not negative, then a plus sign is printed if and only if the @ modifier was specified. Then a sequence of digits, containing a single embedded decimal point, is output. The form of this sequence of digits depends on the scale factor k . If k is zero, then d digits are printed after the decimal point, and a single zero digit appears before the decimal point. If k is positive, then it must be strictly less than d + 2 and k significant digits are printed before the decimal point, and d − k + 1 digits are printed after the decimal point. If k is negative, then it must be strictly greater than −d . A single zero digit appears before the decimal point and after the decimal point, first −k zeros are output followed by d + k significant digits.
Following the digit sequence, the exponent is output following character expchar (default: 'E') and the sign of the exponent, i.e. either the plus or the minus sign. The exponent consists of e digits representing the power of 10 by which the fraction must be multiplied to properly represent the rounded value of arg .
If it is impossible to print the value in the required format in a field of width w , then one of two actions is taken: If the parameter overchar is specified, then w copies of this character are printed instead of arg . If overchar is omitted, then arg is printed using more than w characters, as many more as may be needed. If d is too small for the specified k or e is too small, then a larger value is used for d or e as may be needed.
If the w parameter is omitted, then the output is of variable width and a value is chosen for w in such a way that no leading padding characters are needed.
(format "~~E" 31.415926) ⟹ 3.1415926E+1(format "~~,5E" 0.0003141592) ⟹ 3.14159E-4(format "~~,4,2E" 0.0003141592) ⟹ 3.1416E-04(format "\~9E" 31.415926) ⟹ 3.1416E+1(format "\~10,3,,,,'#E" 31.415926) ⟹ ##3.142E+1(format "\~10,4,,3,,'#E" 31.415926) ⟹ #314.16E-1(format "\~7,3,2,,'-E" 31.415926) ⟹ -------(format "\~10,4,,4,,'#@E" 31.415926) ⟹ +3141.6E-2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| \~g \~G
| GENERAL FLOAT: \~ w,d,e,k,overchar,padchar,expchar G
The next argument arg is output as a floating-point number in either fixed-format or exponential notation as appropriate. The format in which to print arg depends on the magnitude (absolute value) of arg . Let n be an integer such that 10n−1 ≤ arg < 10n. If arg is zero, let n be 0. Let ee equal e + 2, or 4 if e is omitted. Let ww equal w − ee , or nil if w is omitted. If d is omitted, first let q be the number of digits needed to print arg with no loss of information and without leading or trailing zeros; then let d equal max(q, min(n, 7)) . Let dd equal d − n .
If 0 ≤ dd ≤ d , then arg is output as if by the format directives:~~ww,dd,,overchar,padcharF~~ee\@Tk is not passed to the \~F directive. For all other values of dd , arg is printed as if by the format directive:\~w,d,e,k,overchar,padchar,expcharE@ modifier is specified to the \~F or \~E directive if and only if one was specified to the \~G directive.
(format " | \~G | " 712.72) ⟹ | 712.72 | (format " | \~12G | " 712.72) ⟹ | 712.72 | (format " | \~9,2G | \~9,3,2,3G | \~9,3,2,0G | " 0.031415 0.031415 0.031415) | 3.14E-2 | 314.2E-04 | 0.314E-01 | (format " | \~9,2G | \~9,3,2,3G | \~9,3,2,0G | " 0.314159 0.314159 0.314159) | 0.31 | 0.314 | 0.314 | (format " | \~9,2G | \~9,3,2,3G | \~9,3,2,0G | " 3.14159 3.14159 3.14159) | 3.1 | 3.14 | 3.14 | (format " | \~9,2G | \~9,3,2,3G | \~9,3,2,0G | " 314.159 314.159 314.159) | 3.14E+2 | 314 | 314 | (format " | \~9,2G | \~9,3,2,3G | \~9,3,2,0G | " 3141.59 3141.59 3141.59) | 3.14E+3 | 314.2E+01 | 0.314E+04 |
|
| **\~$** | DOLLARS FLOAT: ~~ d,n,w,padchar,curchar,groupchar,groupcol $
The next argument arg is output as a floating-point number in a fixed-format notation that is particularly well suited for outputting monetary values. Parameter d (default: 2) defines the number of digits to print after the decimal point. Parameter n (default: 1) defines the minimum number of digits to print before the decimal point. Parameter w (default: 0) is the minimum total width of the output.
First, padding and the sign are output. If arg is negative, then a minus sign is printed. If arg is not negative, then a plus sign is printed if and only if the @ modifier was specified. If the : modifier is used, the sign appears before any padding, and otherwise after the padding. If the number of characters, including the sign and a potential currency symbol is below width w , then character padchar (default: ' ') is used for padding the number in front of the integer part such that the overall output has w characters. After the padding, the currency symbol curchar is inserted, if available, followed by n digits representing the integer part of arg , prefixed by the right amount of '0' characters. If either parameter groupchar or groupcol is provided, the integer part is output in groups of groupcol characters (default: 3) separated by groupchar (default: ','). After the integer part, a decimal point is output followed by d digits of fraction, properly rounded.
If the magnitude of arg is so large that the integer part of arg cannot be output with at most n characters, then more characters are generated, as needed, and the total width might overrun as well.
For cases where a simple currency symbol is not sufficient, it is possible to use a numeric currency code as defined by ISO 4217 for parameter curchar . For positive codes, the shortest currency symbol is being used. For negative currency codes, the corresponding alphabetic code (ignoring the sign) is being used. Library (lispkit system) provides a conventient API to access currency codes.
By specifying the + modifier, it is possible to enable locale-specific output of the monetary value using the locale provided to format. In this case, also the currency associated with this locale is being used.
(format "~~$" 4930.351) ⟹ 4930.35(format "~~3$" 4930.351) ⟹ 4930.351(format "~~,6$" 4930.351) ⟹ 004930.35(format "~~,6,12,'\_$" 4930.351) ⟹ \_\_\_004930.35(format "~~,6,12,'*@$" 4930.351) ⟹ \_\_+004930.35(format "~~,6,12,'\_@:$" 4930.351) ⟹ +\_\_004930.35(format "~~,6,12,'*,'€$" 4930.351) ⟹ \_\_€004930.35(format "~~,6,12,'*,'€@$" 4930.351) ⟹ *+€004930.35(format "~~,,,,,,3$" 4930.351) ⟹ 4,930.35(format "~~,6,,,,,3$" 4930.351) ⟹ 004,930.35(format "~~,,,,208$" 1234.567) ⟹ kr 1234.57(format "~~,,,,-208$" 1234.567) ⟹ DKK 1234.57(format 'de\_CH "~~+$" 4930.351) ⟹ CHF 4930.35(format 'en\_US "~~,,,,,,3+$" 4930.351) ⟹ $4,930.35(format 'de\_DE "~~,6,14,'\_,,,3+$" 4930.351) ⟹ \_\_004.930,35 €
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| **\~%** | NEWLINE: ~~ n %
This directive outputs n (default: 1) newline characters, thereby terminating the current output line and beginning a new one. No arguments are being consumed. Simply putting n newline escape characters into the control string would also work, but ~~% is often used because it makes the control string look nicer and more consistent.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| **\~&** | FRESHLINE: \~ n &
Unless it can be determined that the output is already at the beginning of a line, this directive outputs a newline if n > 0. This conditional newline is followed by n − 1 newlines, it n > 1. Nothing is output if n = 0.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| **\~\|** | PAGE SEPARATOR: \~ n |
This directive outputs n (default: 1) page separator characters #\page.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| **\~\~** | TILDE: ~~ n ~~
This directive outputs n (default: 1) tilde characters.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| \~p \~P
| PLURAL: \~P
Depending on the next argument arg , which is expected to be an integer value, a different string is output. If arg is not equal to 1, a lowercase s is output. If arg is equal to 1, nothing is output.
If the : modifier is provided, the last argument is used instead for arg . This is useful after outputting a number using \~D. With the @ modifier, y is output if arg is 1, or ies if it is not.
(format "~~D tr~~:@P/~~D win~~:P" 7 1) ⟹ 7 tries/1 win(format "~~D tr~~:@P/~~D win~~:P" 1 0) ⟹ 1 try/0 wins
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| \~t \~T
| TABULATE: \~ colnum,colinc T
This directive will output sufficient spaces to move the cursor to column colnum (default: 1). If the cursor is already at or beyond column colnum , the directive will output spaces to move the cursor to column colnum + k × colinc for the smallest positive integer k possible, unless colinc (default: 1) is zero, in which case no spaces are output if the cursor is already at or beyond column colnum .
If modifier @ is provided, relative tabulation is performed. In this case, the directive outputs colnum spaces and then outputs the smallest non-negative number of additional spaces necessary to move the cursor to a column that is a multiple of colinc . For example, the directive \~3,8\@T outputs three spaces and then moves the cursor to a "standard multiple-of-eight tab stop" if not at one already. If the current output column cannot be determined, however, then colinc is ignored, and exactly colnum spaces are output.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| **\~\*** | IGNORE ARGUMENT: ~~ n \*
The next n (default: 1) arguments are ignored. If the : modifier is provided, arguments are "ignored backwards", i.e. ~~:* backs up in the list of arguments so that the argument last processed will be processed again. ~~n:\* backs up n arguments. When within a ~~{ construct, the ignoring (in either direction) is relative to the list of arguments being processed by the iteration.
The form ~~n@\* is an "absolute goto" rather than a "relative goto": the directive goes to the n -th argument, where 0 means the first one. n defaults to 0 for this form, so ~~@* goes back to the first argument. Directives after a ~~n@\* will take arguments in sequence beginning with the one gone to. When within a ~~{ construct, the "goto" is relative to the list of arguments being processed by the iteration.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| **\~?** | INDIRECTION: ~~?
The next argument arg must be a string, and the one after it lst must be a sequence (e.g. an array). Both arguments are consumed by the directive. arg is processed as a format control string, with the elements of the list lst as the arguments. Once the recursive processing of the control string has been finished, then processing of the control string containing the ~~? directive is resumed.
(format "\~? \~D" "\[\~A ~~D]" '("Foo" 5) 7) ⟹ \[Foo 5] 7(format "~~? \~D" "\[\~A ~~D]" '("Foo" 5 14) 7) ⟹ \[Foo 5] 7
Note that in the second example, three arguments are supplied to the control string "(~~A ~~D)", but only two are processed and the third is therefore ignored.
With the @ modifier, only one argument is directly consumed. The argument must be a string. It is processed as part of the control string as if it had appeared in place of the ~~@? directive, and any directives in the recursively processed control string may consume arguments of the control string containing the ~~@? directive.
(format "~~@? \~D" "\[\~A ~~D]" "Foo" 5 7) ⟹ \[Foo 5] 7(format "~~@? \~D" "\[\~A \~D]" "Foo" 5 14 7) ⟹ \[Foo 5] 14
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| **\~(…\~)** | CONVERSION: ~~( str ~~)
The contained control string str is processed, and what it produces is subject to a conversion. Without the + modifier, a case conversion is performed. ~~( converts every uppercase character to the corresponding lowercase character, ~~:( capitalizes all words, ~~@( capitalizes just the first word and forces the rest to lowercase, and ~~:@( converts every lowercase character to the corresponding uppercase character. In the following example, ~~@( is used to cause the first word produced by ~~R to be capitalized:
(format "~~@(~~R~~) error~~:P" 0) ⟹ Zero errors(format "~~@(~~R~~) error~~:P" 1) ⟹ One error(format "~~@(~~R~~) error~~:P" 23) ⟹ Twenty-three errors
If the + modifier is provided together with the : modifier, all characters corresponding to named XML entities are being converted into names XML entities. If modifier @ is added, then only those characters are converted which conflict with XML syntax. The modifier combination +@ converts the output by stripping off all diacritics. Modifier + only will escape characters such that the result can be used as a Scheme string literal.
(format "~~+:(~~A~~)" "© 2021–2023 TÜV")\© 2021\–2023 T\ÜV(format "~~+:@(~~A~~)" "\© TÜV\ ")\<a href=\"t.html\"\>© TÜV\</a\>(format "~~+@(~~A~~)" "épistèmê")episteme(format "~~+(~~A~~)" "Hello "World"\n")Hello "World"
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| **\~\[…\~]** | CONDITIONAL: ~~\[ str0 ~~; str1 ~~;…~~; strn ~~]
This is a set of control strings, called clauses, one of which is chosen and used. The clauses are separated by ~~; and the construct is terminated by ~~].
Without default: From a conditional directive ~~\[str0 ~~;str1 ~~;…~~;strn ~~], the arg -th clause is selected, where the first clause is number 0. If a prefix parameter is given as ~~n\[, then the parameter n is used instead of an argument. This is useful only if the parameter is specified by #, to dispatch on the number of arguments remaining to be processed. If arg or n is out of range, then no clause is selected and no error is signaled. After the selected alternative has been processed, the control string continues after the ~~].
With default: Whenever the directive has the form ~~\[str0 ~~;str1 ~~;…~~:;default ~~], i.e. the last clause is separated via ~~:;, then the conditional directive has a default clause which gets performed whenever no other clause could be selected.
Optional selector: Whenever the directive has the form ~~:\[none ~~;some ~~] the none control string is chosen if arg is nil, otherwise the some control string is chosen.
Boolean selector: Whenever the directive has the form ~~+\[false ~~;true ~~] the false control string is chosen if arg is the boolean value false, otherwise the some control string is chosen.
Selector test: Whenever the directive has the form ~~@\[true ~~], the next argument arg is tested for being non-nil. If arg is not nil, then the argument is not used up by the \~@\[ directive but remains as the next one to be processed, and the one clause true is processed. If arg is nil, then the argument is used up, and the clause is not processed. The clause therefore should normally use exactly one argument, and may expect it to be non-nil.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| **\~{…\~}** | ITERATION: ~~ n { str ~~}
The iteration directive is used to control how a sequence is output. Thus, the next argument arg should be a sequence which is used as a list of arguments as if for a recursive call to format. The string str is used repeatedly as the control string until all elements from arg are consumed. Each iteration can absorb as many elements of arg as it needs. For instance, if str uses up two arguments by itself, then two elements of arg will get used up each time around the loop. If before any iteration step the sequence is empty, then the iteration is terminated. Also, if a prefix parameter n is given, then there will be at most n repetitions of processing of str . Finally, the ~~^ directive can be used to terminate the iteration prematurely. If the iteration is terminated before all the remaining arguments are consumed, then any arguments not processed by the iteration remain to be processed by any directives following the iteration construct.
(format "Winners:~~{ ~~A~~}." '("Fred" "Harry" "Jill"))Winners: Fred Harry Jill.(format "Winners: ~~{~~#\[~~;~~A~~:;~~A, ~~]~~}." '("Fred" "Harry" "Jill"))Winners: Fred, Harry, Jill.(format "Pairs:~~{ <~~A,~~S>~~}." '("A" 1 "B" 2 "C" 3))Pairs: \ \ \.
~~:n,m{str~~} is similar, but the argument should be a list of sublists. At each repetition step (capped by n ), one sublist is used as the list of arguments for processing str with an iteration cap of m . On the next repetition, a new sublist is used, whether or not all elements of the last sublist had been processed.
(format "Pairs:~~:{ <~~A,~~S>~~}." '(("A" 1) ("B" 2) ("C" 3)))Pairs: \ \ \.
~~@{str~~} is similar to ~~{str~~}, but instead of using one argument that is a sequence, all the remaining arguments are used as the list of arguments for the iteration.
(format "Pairs:~~@{ <~~A,~~S>~~}." "A" 1 "B" 2 "C" 3)Pairs: \ \ \.
~~:@{str~~} combines the features of ~~:{str~~} and ~~@{str~~}. All the remaining arguments are used, and each one must be a sequence. On each iteration, the next argument is used as a list of arguments to str .
(format "Pairs:~~:@{ <~~A,~~S>~~}." '("A" 1) '("B" 2) '("C" 3))Pairs: \ \ \.
Terminating the repetition directive with ~~:} instead of ~~} forces str to be processed at least once, even if the initial sequence is empty. However, it will not override an explicit prefix parameter of zero. If str is empty, then an argument is used as str . It must be a string and precede any arguments processed by the iteration.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| **\~<…\~>** | JUSTIFICATION: ~~ mincol,colinc,minpad,padchar,maxcol,elchar < str ~~>
This directive justifies the text produced by processing control string str within a field which is at least mincol columns wide (default: 0). str may be divided up into segments via directive \~;, in which case the spacing is evenly divided between the text segments.
With no modifiers, the leftmost text segment is left-justified in the field and the rightmost text segment is right-justified. If there is only one text element, it is right-justified. The : modifier causes spacing to be introduced before the first text segment. The @ modifier causes spacing to be added after the last text segment. The minpad parameter (default: 0) is the minimum number of padding characters to be output between each segment. Whenever padding is needed, the padding character padchar (default: ' ') is used. If the total width needed to satisfy the constraints is greater than mincol , then the width used is mincol + k × colinc for the smallest possible non-negative integer k with colinc defaulting to 1.
(format " | ~~10,,,'.\ | ") ⟹ | foo....bar | (format " | ~~10,,,'.:\ | ") ⟹ | ..foo..bar | (format " | ~~10,,,'.:@\ | ") ⟹ | ..foo.bar. | (format " | ~~10,,,'.\ | ") ⟹ | ....foobar | (format " | ~~10,,,'.:\ | ") ⟹ | ....foobar | (format " | ~~10,,,'.@\ | ") ⟹ | foobar.... | (format " | ~~10,,,'.:@\ | ") ⟹ | ..foobar.. |
Note that str may include format directives. All the clauses in str are processed in order. It is the resulting pieces of text that are justified. The ~~^ directive may be used to terminate processing of the clauses prematurely, in which case only the completely processed clauses are justified.
If the first clause of a ~~< directive is terminated with ~~:; instead of ~~;, then it is used in a special way. All of the clauses are processed, but the first one is not used in performing the spacing and padding. When the padded result has been determined, then, if it fits on the current line of output, it is output, and the text for the first clause is discarded. If, however, the padded text does not fit on the current line, then the text segment for the first clause is output before the padded text. The first clause ought to contain a newline (such as a ~~% directive). The first clause is always processed, and so any arguments it refers to will be used. The decision is whether to use the resulting segment of text, not whether to process the first clause. If the ~~:; has a prefix parameter n , then the padded text must fit on the current line with n character positions to spare to avoid outputting the first clause’s text.
For example, the control string in the following example can be used to print a list of items separated by comma without breaking items over line boundaries, beginning each line with ;;. The prefix parameter 1 in ~~1:; accounts for the width of the comma that will follow the justified item if it is not the last element in the list, or the period if it is. If ~~:; has a second prefix parameter, like below, then it is used as the width of the line, overriding the line width as specified by format's linewidth: parameter (default: 80).
(format "~~%;; ~~{~~<~~%;; ~~1,30:; ~~S~~>~~^,~~}.~~%"'("first line" "second" "a long third line""fourth" "fifth"));; "first line", "second",;; "a long third line",;; "fourth", "fifth".
If there is only one text segment str and parameter maxcol is provided and the length of the output of str is exceeding maxcol , then the output is truncated at width maxcol - 1 and the ellipsis character elchar (default: '…') is inserted at the end.
| | | | | | | | | | | | | | | | | | | | |
| **\~^** | UP AND OUT: ~~^
Continue: The ~~^ directive is an escape construct. If there are no more arguments remaining to be processed, then the immediately enclosing ~~{ or ~~< directive is terminated. If there is no such enclosing directive, then the entire formatting operation is terminated. In the case of ~~<, the formatting is performed, but no more segments are processed before doing the justification. The ~~^ directive should appear only at the beginning of a ~~< clause, because it aborts the entire clause it appears in, as well as all following clauses. ~~^ may appear anywhere in a ~~{ construct.
(format "Done.~~^ ~~D warning~~:P.~~^ ~~D error~~:P.")Done.(format "Done.~~^ ~~D warning~~:P.~~^ ~~D error~~:P." 3)Done. 3 warnings.(format "Done.~~^ ~~D warning~~:P.~~^ ~~D error~~:P." 1 5)Done. 1 warning. 5 errors.
If the directive has the form ~~n^, then termination occurs if n is zero. If the directive has the form ~~n,m^, termination occurs if the value of n equals the value of m . If the directive has the form ~~n,m,o^, termination occurs if n ≤ m ≤ o . Of course, this is useless if all the prefix parameters are literals. At least one of them should be a # or a v parameter.
Break: If ~~^ is used within a ~~:{ directive, then it merely terminates the current iteration step because in the standard case, it tests for remaining arguments of the current step only and the next iteration step commences immediately. To terminate the entire iteration process, use ~~:^. ~~:^ may only be used if the directive it would terminate is ~~:{ or ~~:@{. The entire iteration process is terminated if and only if the sublist that is supplying the arguments for the current iteration step is the last sublist (in the case of terminating a ~~:{ directive) or the last argument to that call to format (in the case of terminating a ~~:@{ directive).
Note that while ~~^ is equivalent to ~~#^ in all circumstances, ~~:^ is not equivalent to ~~#:^ because the latter terminates the entire iteration if and only if no arguments remain for the current iteration step, as opposed to no arguments remaining for the entire iteration process.
(format "~~:{/~~A~~^ …~~}",'(("hot" "dog") ("hamburger") ("ice" "cream") ("french" "fries")))/hot …/hamburger/ice …/french …(format "~~:{/~~A~~:^ …~~}"'(("hot" "dog") ("hamburger") ("ice" "cream") ("french" "fries")))/hot …/hamburger …/ice …/french(format "~~:{/~~A~~#:^ …~~}"'(("hot" "dog") ("hamburger") ("ice" "cream") ("french" "fries")))/hot …/hamburger
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
| **\~\`…\~‘** | UPACK: \~` str ~‘
This directive is used to format composite objects, such as rational numbers, complex numbers, colors, date-time objects, error objects, records, etc. Such objects get decomposed into a sequence of individual values which are formatted by the str control string.
The next argument arg can be any Scheme object. If there is a decomposition predefined for this type of objects, it is applied to arg and str is used to format the resulting sequence of values. If no decomposition is possible, str is output assuming there is one argument arg .
(format "~S~:* = ~`(~~S, ~~S)~~‘" 17/3) ⟹ 17/3 = (17, 3)(format "Bits =~~`~*~{ ~D~}~‘" (bitset 1 2 7)) ⟹ Bits = 1 2 7(format "Color: ~`R=\~F, G=\~F, B=~~F~~‘" (color 0.3 1.0 0.74))Color: R=0.3, G=1.0, B=0.74
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
## Formatting configurations
A few formatting directives provided by procedure `format` require access to environment variables such as the locale, the width of tab characters, the length of lines, etc. Also the type-specific customization of the formatting of native and user-defined objects, e.g. via the `~S` directive, is based on a formatting control registry defined by an environment variable.
All relevant environment variables are bundled together into *format config* objects. Format configurations are organized hierarchically. Each format configuration optionally refers to a parent configuration. It inherits all environment variables and allows their values to be overridden.
The root of this format configuration hierarchy constitutes `base-format-config`. Typically, changes to this object impact all invocations of `format`, unless format is called with a custom format config object which is not derived from `base-format-config`. Without a custom format config, `format` reads the environment variables from the *current format config* parameter `current-format-config` (which, by default, inherits from `base-format-config`). Like every other parameter object, it is possible to define a new config dynamically via `parameterize`.
Format config objects are also used in combination with type-specific formatting as provided by the `~S` directive, as explained in the next section.
## Type-specific formatting
Procedure `format` provides great means to format numbers, characters, strings, as well as sequences, i.e. lists and vectors. But as soon as values of data types encapsulating their state have to be output, only the default textual representation is supported, which is also used when a value is output via procedure `write`.
For this reason, procedure `format` supports the customization of how composite objects are formatted. The approach for doing this is simple: Internally, a composite object can be mapped ("unpacked") into a vector of "field values". These field values are then interpreted as arguments for an object type-specific control string which defines how the field values of such objects are formatted. If there is no object type-specific control string available, the object is output as if it was written via procedure `write`.
The following example shows how to customize the formatting of objects defined by a record type. The following record is used to model colored 2-dimensional points:
```scheme
(define-record-type
(make-point x y c)
point?
(x point-x)
(y point-y)
(c point-color))
```
By default, objects of type `` are output in the following way:
```scheme
(define pt (make-point 7 13 (color 0.5 0.9 0)))
(format "~S" pt)
⇒ "#: x=7, y=13, c=#>"
```
LispKit defines a type tag for every type. This type tag will later be used to define a custom format for records of type ``. We can retrieve the type tag for type `` via procedure `record-type-tag`:
```scheme
(define point-type-tag (record-type-tag ))
```
Now we can define a custom format for objects of type `` in which we refer to the unpacked fields in the order as defined in the `` record type definition following a fixnum value denoting the identity of the record. The following control string formats `` records in this way: `point{x=?,y=?,color=?}`. Note that it skips the record identity via the `~*` directive.
```scheme
"point{x=~*~S,y=~S,c=~S}"
```
`format` refers to a number of environment variables via a formatting configuration (see previous section). The default configuration is defined by definition `base-format-config` and it includes custom type-specific formats. With procedure `format-config-control-set!` we can declare that all objects of type `` should be formatted with the control string shown above:
```scheme
(format-config-control-set!
base-format-config
point-type-tag
"point{x=~*~S,y=~S,c=~S}")
```
Formatting records of type `` via the `~S` directive is now based on this new control string.
```scheme
(format "~S" pt)
⇒ "point{x=7,y=13,c=#}"
```
If we wanted to also change how colors are formatted, we could do that in a similar way:
```scheme
(format-config-control-set!
base-format-config
color-type-tag
"color{~S, ~S, ~S}")
```
Now colors are formatted differently:
```scheme
(format "~S" pt) ⇒ "point{x=7,y=13,c=#}"
(format "~S" (color 1.0 0.3 0.7)) ⇒ "color{1.0, 0.3, 0.7}"
```
If we wanted to change the way how colors are formatted only in the context of formatting points, we could do that by creating a formatting configuration for colors and associate it only with the formatting control string for points. The following code first removes the global color format so that colors are formatted again using the default mechanism. Then it redefines the formatting control for points by also specifying a format configuration that is used while applying the point formatting control string.
```scheme
(format-config-control-remove! base-format-config color-type-tag)
(format-config-control-set!
base-format-config
point-type-tag
"point{x=~*~S,y=~S,c=~S}"
(format-config (list color-type-tag "color{~S, ~S, ~S}")))
(format "~S" (color 1.0 0.3 0.7)) ⇒ "#"
(format "~S" pt) ⇒ "point{x=7,y=13,c=color{0.5, 0.9, 0.0}}"
```
## API
**format-config-type-tag** Graph g
(make-abstract-image "dir/pt.jpg") ⇒
(make-abstract-image image #t) ⇒
```
**(image->abstract-image *****image*****)**
```
**(abstract-image->image *****aimage*****)**
(abstract-image->image ai 144 #t) ⇒
```
**(abstract-image-bounds *****aimage*****)**
(image-coefficients '(1.0 2.0) '(3 4)) ⇒ #
(image-coefficients #(1 2) '(3) 4) ⇒ #
(image-coefficients (rect 1 2 3 4)) ⇒ #
```
**(image-coefficients->vector *****coeffs*****)**
(image-coefficients->rect c)
⇒ ((1.0 . 2.0) 3.0 . 4.0)
```
## Image Processing Pipelines
**(apply-image-filter *****aimage filter ...*****)**
;; Apply multiple filters in sequence
(apply-image-filter img
'(gaussian-blur (input-radius . 2.0))
'(color-controls (input-brightness . 0.1) (input-contrast . 1.2))
(make-image-filter 'vignette))
⇒ #
```
## Coordinate Mapping
**(map-image-point *****pnt image*****)** *i* is a refinement of *b**i* holds for every i ∈ \[0; *n*\[,
3. If *a* and *b* are objects, for every member *m* of *b* with value *b**m* , there is a member *m* of *a* with value *a**m* such that *a**m* is a refinement of *b**m* ,
4. For all other types, *a* and *b* are the same.
This relationship intuitively models that whenever it is possible to read a value at a given location from *b*, it is also possible to read a value at the same location from *a* and the value that is read for *a* is a refinement of the value read from *b*. The following example showcases this relationship:
```scheme
(define a
(string->json "{ \"a\": [1, { \"b\": 2 }], \"c\": { \"d\": [{}] }}"))
(define b
(string->json "{ \"a\": [1, { \"b\": 2, \"e\": 4 }], \"c\": { \"d\": [{\"f\": 5}] }}"))
(json-refinement? a b) ⇒ #f
(json-refinement? b a) ⇒ #t
```
**(string->json *****str*****)** "store" "book" 2 "title")
(# "store" "book" 0 "title"))
```
**(json-path? *****str*****)**
(match '(1 . 2) ((1 . (get! g)) (g))) ⇒ 2
```
The new operator `***` can be used to search a tree for subpatterns. A pattern of the form `(x *** y)` represents the subpattern `y` located somewhere in a tree where the path from the current object to \var{y} can be seen as a list of the form `(x ...)`. `y` can immediately match the current object in which case the path is the empty list. In a sense, it is a two-dimensional version of the `...` pattern. As a common case the pattern `(_ *** y)` can be used to search for `y` anywhere in a tree, regardless of the path used.
```scheme
(match '(a (a (a b))) ((x *** 'b) x)) ⇒ (a a a)
(match '(a (b) (c (d e) (f g)))
((x *** 'g) x)) ⇒ (a c f)
```
## Pattern grammar
```scheme
pat = patvar ;; anything, and binds pattern var
| _ ;; anything
| () ;; the empty list
| #t ;; #t
| #f ;; #f
| string ;; a string
| number ;; a number
| character ;; a character
| 'sexp ;; an s-expression
| 'symbol ;; a symbol (special case of s-expr)
| (pat1 ... patN) ;; list of n elements
| (pat1 ... patN . patN+1) ;; list of n or more
| (pat1 ... patN patN+1 ooo) ;; list of n or more, each element
;; of remainder must match patN+1
| #(pat1 ... patN) ;; vector of n elements
| #(pat1 ... patN patN+1 ooo) ;; vector of n or more, each element
;; of remainder must match patN+1
| ($ record-type pat1 ... patN) ;; a record (patK matches in slot order)
| (struct struct-type pat1 ... patN) ;; ditto
| (@ record-type (slot1 pat1) ...) ;; a record (using slot names)
| (object struct-type (slot1 pat1) ...) ;; ditto
| (= proc pat) ;; apply proc, match the result to pat
| (and pat ...) ;; if all of pats match
| (or pat ...) ;; if any of pats match
| (not pat ...) ;; if no pats match
| (? predicate pat ...) ;; if predicate true and all pats match
| (set! patvar) ;; anything, and binds setter
| (get! patvar) ;; anything, and binds getter
| (pat1 *** pat2) ;; tree subpattern (*)
| `qp ;; a quasi-pattern
patvar = a symbol except _, quote, $, struct, @, object, =, and, or,
not, ?, set!, get!, quasiquote, ..., ___, ..1, ..=, ..*.
ooo = ... ;; zero or more
| ___ ;; zero or more
| ..1 ;; one or more
| ..= k ;; exactly k where k is an integer. (*)
;; Example: ..= 1, ..= 2 ...
| ..* k j ;; between k and j, where k and j are (*)
;; integers. Example: ..* 3 4, match 3
;; or 4 of a pattern ..* 1 5 match from
;; 1 to 5 of a pattern
qp = () ;; the empty list
| #t ;; #t
| #f ;; #f
| string ;; a string
| number ;; a number
| character ;; a character
| identifier ;; a symbol
| (qp_1 ... qp_n) ;; list of n elements
| (qp_1 ... qp_n . qp_{n+1}) ;; list of n or more
| (qp_1 ... qp_n qp_n+1 ooo) ;; list of n or more, each element
;; of remainder must match qp_n+1
| #(qp_1 ... qp_n) ;; vector of n elements
| #(qp_1 ... qp_n qp_n+1 ooo) ;; vector of n or more, each element
;; of remainder must match qp_n+1
| ,pat ;; a pattern
| ,@pat ;; a pattern
```
## Matching API
**(match *****expr***** (*****pat***** . *****body*****) *****...*****)**
(object->string pt) => "25/37"
(point-coordinates pt) => (25 . 37)
(set-point-coordinates! pt 5 6)
(object->string pt) => "5/6"
(point-coordinates pt) => (5 . 6)
```
### Inheritance
The LispKit object system supports inheritance via delegation. The following code shows how colored points can be implemented by delegating all point functionality to the previous implementation and by simply adding only color-related logic.
```scheme
(define-generic (point-color self) #f)
(define (make-colored-point x y color)
(object ((super (make-point x y)))
((point-color self) color)
((object->string self)
(string-append (object->string color) ":" (invoke (super object->string) self)))))
```
The object created in function `make-colored-point` inherits all methods from object `super` which gets set to a new point object. It adds a new method to generic procedure `point-color` and redefines the `object->string` method. The redefinition is implemented in terms of the inherited `object->string` method for points. The form `invoke` can be used to refer to overridden methods in delegatee objects. Thus, `(invoke (super object->string) self)` calls the `object->string` method of the `super` object but with the identity (`self`) of the colored point.
The following interaction illustrates the behavior:
```scheme
(define cpt (make-colored-point 100 50 'red))
(point-color cpt) => red
(point-coordinates cpt) => (100 . 50)
(set-point-coordinates! cpt 101 51)
(object->string cpt) => "red:101/51"
```
Objects can delegate functionality to multiple delegatees. The order in which they are listed determines the methods which are being inherited in case there are conflicts, i.e. multiple delegatees implement a method for the same generic procedure.
### Classes
Classes add syntactic sugar, simplying the creation and management of objects. They play the following role in the object-system of LispKit:
1. A class defines a constructor for objects represented by this class.
2. Each class defines an object type, which can be used to distinguish objects created by the same constructor and supporting the same methods.
3. A class can inherit functionality from several other classes, making it easy to reuse functionality.
4. Classes are first-class objects supporting a number of class-related procedures.
The following code defines a `point` class with similar functionality as above:
```scheme
(define-class (point x y) ()
(object ()
((point-coordinates self) (cons x y))
((set-point-coordinates! self nx ny) (set! x nx) (set! y ny))
((object->string self) (string-append (object->string x) "/" (object->string y)))))
```
Instances of this class are created by using the generic procedure `make-instance` which is implemented by all class objects:
```scheme
(define pt2 (make-instance point 82 10))
pt2 => #point:#
(object->string pt2) => "82/10"
```
Each object created by a class implements a generic procedure `object-class` referring to the class of the object. Since classes are objects themselves we can obtain their name with generic procedure `class-name`:
```scheme
(object-class pt2) => #class:#
(class-name (object-class pt2)) => point
(instance-of? point pt2) => #t
(instance-of? point pt) => #f
```
Generic procedure `instance-of?` can be used to determine whether an object is a direct or indirect instance of a given class. The last two lines above show that `pt2` is an instance of `point`, but `pt` is not, even though it is functionally equivalent.
The following definition re-implements the colored point example from above using a class:
```scheme
(define-class (colored-point x y color) (point)
(if (or (< x 0) (< y 0))
(error "coordinates are negative: ($0; $1)" x y))
(object ((super (make-instance point x y)))
((point-color self) color)
((object->string self)
(string-append (object->string color) ":" (invoke (super object->string) self)))))
```
The following lines illustrate the behavior of `colored-point` objects vs `point` objects:
```scheme
(point-color cpt2) => blue
(point-coordinates cpt2) => (128 . 256)
(set-point-coordinates! cpt2 64 32)
(object->string cpt2) => "blue:64/32"
(instance-of? point cpt2) => #t
(instance-of? colored-point cpt2) => #t
(instance-of? colored-point cpt) => #f
(class-name (object-class cpt2)) => colored-point
```
## Procedural object interface
**object-type-tag** \ \ \ ...*****)** * defines the name of the new record type and potentially the supertype if the new type is an extension of an existing record type. Thus, it has one of the two possible forms, where *\* is an identifier and *\* an arbitrary expression evaluating to a record type descriptor:
*\*, or\
(*\ \*).
The *\* is of one of the two possible forms:
*\, or*\
*(*\ \ ...\_)
When a constructor is of the form (*\ \ ...*), the following holds:
* Each of the field names can be either a field name declared in the same `define-record-type` form, or any of its ancestors' field names.
* If the record definition contains the same field name as one of its ancestors, it shadows the ancestor's field name for the purposes of the constructor. The constructor's argument initializes the child's slot, and the ancestor's slot of the same name is left uninitialized.
* It is an error if the same identifier appears more than once in the field names of the constructor spec.
*\* is the identifier denoting the type predicate that recognizes instances of the new record type and its subtypes. Each *\* is either of the form:
(*\ \*), or\
(*\ \ \*).
It is an error for the same identifier to occur more than once as a field name. It is also an error for the same identifier to occur more than once as an accessor or mutator name.
The `define-record-type` construct is generative: each use creates a new record type that is distinct from all existing types, including the predefined types and other record types - even record types of the same name or structure.
An instance of `define-record-type` is equivalent to the following definitions:
* *\* is bound to a representation of the record type itself. If a \ expression is specified, then it must evaluate to a record type descriptor that serves as the parent record type for the record type being defined.
* *\* is bound to a procedure that takes as many arguments as there are *\* elements in the (*\ ...*) subexpression and returns a new record of type *\*. Fields whose names are listed with *\* have the corresponding argument as their initial value. The initial values of all other fields are unspecified. It is an error for a field name to appear in *\* but not as a *\*.
* *\* is bound to a predicate that returns `#t` when given a value returned by the procedure bound to *\* or any constructor of a subtype. It returns `#f` for everything else.
* Each *\* is bound to a procedure that takes a record of type *\* and returns the current value of the corresponding field. It is an error to pass an accessor a value which is not a record of the appropriate type.
* Each *\* is bound to a procedure that takes a record of type *\* and a value which becomes the new value of the corresponding field. It is an error to pass a modifier a first argument which is not a record of the appropriate type.
### Examples
The following record-type definition:
```scheme
(define-record-type
(kons x y)
pare?
(x kar set-kar!)
(y kdr))
```
defines `kons` to be a constructor, `kar` and `kdr` to be accessors, `set-kar!` to be a modifier, and `pare?` to be a type predicate for instances of ``.
```scheme
(pare? (kons 1 2)) ⇒ #t
(pare? (cons 1 2)) ⇒ #f
(kar (kons 1 2)) ⇒ 1
(kdr (kons 1 2)) ⇒ 2
(let ((k (kons 1 2)))
(set-kar! k 3) (kar k)) ⇒ 3
```
Below is another example showcasing how record types can be extended. First a new record type `` is defined:
```scheme
(define-record-type
(make-point x y)
point?
(x point-x set-point-x!)
(y point-y set-point-y!))
```
Next, a new record type `` is defined to extend record type ``:
```scheme
(define-record-type ( )
(make-color-point x y color)
color-point?
(color point-color))
```
The following transcript shows that `` objects are also considered `` objects which inherit all fields from ``:
```scheme
(define cp (make-color-point 12 3 red))
(color-point? cp) ⇒ #t
(point? cp) ⇒ #t
(color-point?
(make-point 1 2)) ⇒ #f
(point-x cp) ⇒ 12
(set-point-x! cp 1)
(point-x cp) ⇒ 1
(point-color cp) ⇒ #
```
## Procedural API
Besides the syntactical `define-record-type` abstraction for defining record types in a declarative fashion, LispKit provides a low-level, procedural API for creating and instantiating records and record types. Record types are represented in form of *record type descriptor* objects which itself are records.
**(record? *****obj*****)** Character Description \aMatch a bell (\u0007) \AMatch at the beginning of the input. Differs from ^ in that \A will not match after a new line within the input. \bOutside of a [Set], match if the current position is a word boundary. Boundaries occur at the transitions between word (\w) and non-word (\W) characters, with combining marks ignored. Inside of a [Set], match a backspace (\u0008). \BMatch if the current position is not a word boundary. \cXMatch a control-X character. \dMatch any character with the unicode general category of Nd, i.e. numbers and decimal digits. \DMatch any character that is not a decimal digit. \eMatch an escape (\u001B). \ETerminates a \Q ... \E quoted sequence. \fMatch a form feed (\u000C). \GMatch if the current position is at the end of the previous match. Match a line feed (\u000A). \N{unicode character}Match the named character. \p{unicode property}Match any character with the specified unicode property. \P{unicode property}Match any character not having the specified unicode property. \QQuotes all following characters until \E. Match a carriage return (\u000D). \sMatch a whitespace character. Whitespace is defined as [\t\n\f\r\p{Z}]. \SMatch a non-whitespace character. Match a horizontal tabulation (\u0009). \uhhhhMatch the character with the hex value hhhh. \UhhhhhhhhMatch the character with the hex value hhhhhhhh. Exactly eight hex digits must be provided, even though the largest Unicode code point is \U0010ffff. \wMatch a word character. Word characters are [\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}]. \WMatch a non-word character. \x{hhhh}Match the character with hex value hhhh. From one to six hex digits may be supplied. \xhhMatch the character with two digit hex value hh. \XMatch a grapheme cluster. \ZMatch if the current position is at the end of input, but before the final line terminator, if one exists. \zMatch if the current position is at the end of input. \n Back Reference. Match whatever the n -th capturing group matched. n must be a number ≥ 1 and ≤ total number of capture groups in the pattern. \0oooMatch an octal character. ooo is from one to three octal digits. 0377 is the largest allowed octal character. The leading zero is required and distinguishes octal constants from back references. [pattern]Match any one character from the pattern. .Match any character. ^Match at the beginning of a line. $Match at the end of a line. \ Quotes the following character. Characters that must be quoted to be treated as literals are `* ? + [ ( ) { } ^ $
### Regular expression operators
Character Description ` ` *Match 0 or more times, as many times as possible. +Match 1 or more times, as many times as possible. ?Match zero or one times, preferring one time if possible. {n}Match exactly n times. {n,}Match at least n times, as many times as possible. {n,m}Match between n and m times, as many times as possible, but not more than m times. *?Match zero or more times, as few times as possible. +?Match one or more times, as few times as possible. ??Match zero or one times, preferring zero. {n}?Match exactly n times. {n,}?Match at least n times, but no more than required for an overall pattern match. {n,m}?Match between n and m times, as few times as possible, but not less than n. *+Match zero or more times, as many times as possible when first encountered, do not retry with fewer even if overall match fails (possessive match). ++Match one or more times (possessive match). ?+Match zero or one times (possessive match). {n}+Match exactly n times. {n,}+Match at least n times (possessive match). {n,m}+Match between n and m times (possessive match). (...)Capturing parentheses; the range of input that matched the parenthesized subexpression is available after the match. (?:...)Non-capturing parentheses; groups the included pattern, but does not provide capturing of matching text (more efficient than capturing parentheses). (?>...)Atomic-match parentheses; first match of the parenthesized subexpression is the only one tried. If it does not lead to an overall pattern match, back up the search for a match to a position before the "(?>". (?# ... )Free-format comment (?# comment). (?= ... )Look-ahead assertion. True, if the parenthesized pattern matches at the current input position, but does not advance the input position. (?! ... )Negative look-ahead assertion. True, if the parenthesized pattern does not match at the current input position. Does not advance the input position. (?<= ... )Look-behind assertion. True, if the parenthesized pattern matches text preceding the current input position, with the last character of the match being the input character just before the current position. Does not alter the input position. The length of possible strings matched by the look-behind pattern must not be unbounded (no * or + operators). (?<! ... )Negative look-behind assertion . True, if the parenthesized pattern does not match text preceding the current input position, with the last character of the match being the input character just before the current position. Does not alter the input position. The length of possible strings matched by the look-behind pattern must not be unbounded (no * or + operators). (?ismwx-ismwx: ... )Flag settings. Evaluate the parenthesized expression with the specified flags enabled or disabled. (?ismwx-ismwx)Flag settings. Change the flag settings. Changes apply to the portion of the pattern following the setting. For example, (?i) changes to a case insensitive match.
### Template Matching
Character Description $nThe text of capture group n will be substituted for $n. n must be ≥ 0 and not greater than the number of capture groups. A $ not followed by a digit has no special meaning, and will appear in the substitution text as itself, i.e. $. \ Treat the following character as a literal, suppressing any special meaning. Backslash escaping in substitution text is only required for $ and \, but may be used on any other character.
### Flag options
The following flags control various aspects of regular expression matching. These flags get specified within the pattern using the `(?ismx-ismx)` pattern options.
Character Description iIf set, matching will take place in a case-insensitive manner. xIf set, allow use of white space and #comments within patterns. sIf set, a "." in a pattern will match a line terminator in the input text. By default, it will not. Note that a carriage-return/line-feed pair in text behave as a single line terminator, and will match a single "." in a regular expression pattern. mControl the behavior of ^ and $ in a pattern. By default these will only match at the start and end, respectively, of the input text. If this flag is set, ^ and $ will also match at the start and end of each line within the input text. wControls the behavior of \b in a pattern. If set, word boundaries are found according to the definitions of word found in Unicode UAX 29, Text Boundaries . By default, word boundaries are identified by means of a simple classification of characters as either word or non-word , which approximates traditional regular expression behavior.
## API
**(regexp? *****obj*****)** " 10)
⟹ "Contact ma or "
(define series
(regexp "Season\\s+(\\d+)\\s+Episode\\s+(\\d+)"))
(regexp-replace series "New Season 3 Episode 12: Pilot" "Series")
⟹ "New Series: Pilot"
```
**(regexp-replace! *****x*****)** " 10) ⟹ 2
str ⟹ "Contact ma or "
```
**(regexp-fold *****regexp kons knil str*****)** & two = 3")
⇒ "<one> & two = 3"
(string-encode-named-chars " & two = 3" #t)
⇒ "<one> & two = 3"
```
**(string-decode-named-chars *****str*****)** )
(obliqueness . 1.2)
(foreground-color . #))
```
## Text block styles
Text block style objects encapsulate attributes describing how text is layed out in a box. Text block styles are currently only used for defining the layout of cells in a table. The following text block style attributes are supported:
* `width`: The width of the text block in points or as a percentage.
* `height`: The height of the text block in points or as a percentage.
* `margin`: The margin around the text block. This is either one value representing the same margin in points or as a percentage for all four sides, or it is a list of four values `(left right top bottom)`.
* `border`: The "thickness"/size of the border in points or as a percentage. This is either one value representing the same border size for all four sides, or it is a list of four values `(left right top bottom)`. 0 means "no border".
* `padding`: The padding within the text block in points or as a percentage. This is either one value representing the same padding for all four sides, or it is a list of four values `(left right top bottom)`.
* `background-color`: The background color of the text block.
* `border-color`: The color of the border of the text block.
* `vertical-alignment`: The vertical alignment of the text within the block. Supported are the following four alignment values: `top`, `middle`, `bottom`, and `baseline`.
Text block style objects are mutable. They define values for all attributes, i.e. there are defaults for all attributes set for newly created text block style objects.
**(percent *****num*****)** not-abandoned)
```
**(mutex-lock! *****mutex*****)**
```
This is also the reason why function `interval-tag` gets access to two unwrapped values, `bounds` and `tag`: one (`bounds`) corresponds to the value associated with type `interval`, and the other one (`tag`) corresponds to the value associated with type `tagged-interval`.
## Type introspection
LispKit defines a type tag for every different type of object. The type of objects created with the `make-type` facility are represented with unintered symbols whose string representation matches the type label provided to `make-type`. Enum and record objects come with a corresponding type tag as well. All standard, built-in types use interned symbols as type tags. Procedure `type-of` returns the type tag associated with the value of the argument of `type-of`.
**(type-of *****obj*****)** ".
```scheme
(apply-applescript-proc script "setSafariFrontURL" '("http://lisppad.objecthub.net"))
```
Library `(lisppad applescript)` provides a means to quickly create Scheme functions matching AppleScript subroutines. This is shown in the following code:
```scheme
(define safari-front-url (applescript-proc script "safariFrontURL"))
(define set-safari-front-url! (applescript-proc script "setSafariFrontURL"))
(display (safari-front-url))
(newline)
(set-safari-front-url! "http://lisppad.objecthub.net")
```
## Marshaling data
This is how library `(lisppad applescript)` is marshaling/unmarshaling data when data is exchanged between Scheme and AppleScript:
Scheme type AppleScript type void null boolean boolean fixnum int32 flonum double proper list list string unicode text date-time date
If other data is attempted to be exchanged, it might lead to failure.
## API
**(applescript? *****obj*****)**