1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
|
<h3 class="section">Custom Format Strings</h3> <p>Sometimes it is useful to allow users and Lisp programs alike to control how certain text is generated via custom format control strings. For example, a format string could control how to display someone’s forename, surname, and email address. Using the function <code>format</code> described in the previous section, the format string could be something like <code>"%s %s <%s>"</code>. This approach quickly becomes impractical, however, as it can be unclear which specification character corresponds to which piece of information. </p> <p>A more convenient format string for such cases would be something like <code>"%f %l <%e>"</code>, where each specification character carries more semantic information and can easily be rearranged relative to other specification characters, making such format strings more easily customizable by the user. </p> <p>The function <code>format-spec</code> described in this section performs a similar function to <code>format</code>, except it operates on format control strings that use arbitrary specification characters. </p> <dl> <dt id="format-spec">Function: <strong>format-spec</strong> <em>template spec-alist &optional ignore-missing split</em>
</dt> <dd>
<p>This function returns a string produced from the format string <var>template</var> according to conversions specified in <var>spec-alist</var>, which is an alist (see <a href="association-lists">Association Lists</a>) of the form <code>(<var>letter</var> . <var>replacement</var>)</code>. Each specification <code>%<var>letter</var></code> in <var>template</var> will be replaced by <var>replacement</var> when formatting the resulting string. </p> <p>The characters in <var>template</var>, other than the format specifications, are copied directly into the output, including their text properties, if any. Any text properties of the format specifications are copied to their replacements. </p> <p>Using an alist to specify conversions gives rise to some useful properties: </p> <ul> <li> If <var>spec-alist</var> contains more unique <var>letter</var> keys than there are unique specification characters in <var>template</var>, the unused keys are simply ignored. </li>
<li> If <var>spec-alist</var> contains more than one association with the same <var>letter</var>, the closest one to the start of the list is used. </li>
<li> If <var>template</var> contains the same specification character more than once, then the same <var>replacement</var> found in <var>spec-alist</var> is used as a basis for all of that character’s substitutions. </li>
<li> The order of specifications in <var>template</var> need not correspond to the order of associations in <var>spec-alist</var>. </li>
</ul> <p>The optional argument <var>ignore-missing</var> indicates how to handle specification characters in <var>template</var> that are not found in <var>spec-alist</var>. If it is <code>nil</code> or omitted, the function signals an error; if it is <code>ignore</code>, those format specifications are left verbatim in the output, including their text properties, if any; if it is <code>delete</code>, those format specifications are removed from the output; any other non-<code>nil</code> value is handled like <code>ignore</code>, but any occurrences of ‘<samp>%%</samp>’ are also left verbatim in the output. </p> <p>If the optional argument <var>split</var> is non-<code>nil</code>, instead of returning a single string, <code>format-spec</code> will split the result into a list of strings, based on where the substitutions were performed. For instance: </p> <div class="example"> <pre class="example">(format-spec "foo %b bar" '((?b . "zot")) nil t)
⇒ ("foo " "zot" " bar")
</pre>
</div> </dd>
</dl> <p>The syntax of format specifications accepted by <code>format-spec</code> is similar, but not identical, to that accepted by <code>format</code>. In both cases, a format specification is a sequence of characters beginning with ‘<samp>%</samp>’ and ending with an alphabetic letter such as ‘<samp>s</samp>’. </p> <p>Unlike <code>format</code>, which assigns specific meanings to a fixed set of specification characters, <code>format-spec</code> accepts arbitrary specification characters and treats them all equally. For example: </p> <div class="example"> <pre class="example">(setq my-site-info
(list (cons ?s system-name)
(cons ?t (symbol-name system-type))
(cons ?c system-configuration)
(cons ?v emacs-version)
(cons ?e invocation-name)
(cons ?p (number-to-string (emacs-pid)))
(cons ?a user-mail-address)
(cons ?n user-full-name)))
(format-spec "%e %v (%c)" my-site-info)
⇒ "emacs 27.1 (x86_64-pc-linux-gnu)"
(format-spec "%n <%a>" my-site-info)
⇒ "Emacs Developers <emacs-devel@gnu.org>"
</pre>
</div> <p>A format specification can include any number of the following flag characters immediately after the ‘<samp>%</samp>’ to modify aspects of the substitution. </p> <dl compact> <dt>‘<samp>0</samp>’</dt> <dd>
<p>This flag causes any padding specified by the width to consist of ‘<samp>0</samp>’ characters instead of spaces. </p> </dd> <dt>‘<samp>-</samp>’</dt> <dd>
<p>This flag causes any padding specified by the width to be inserted on the right rather than the left. </p> </dd> <dt>‘<samp><</samp>’</dt> <dd>
<p>This flag causes the substitution to be truncated on the left to the given width and precision, if specified. </p> </dd> <dt>‘<samp>></samp>’</dt> <dd>
<p>This flag causes the substitution to be truncated on the right to the given width, if specified. </p> </dd> <dt>‘<samp>^</samp>’</dt> <dd>
<p>This flag converts the substituted text to upper case (see <a href="case-conversion">Case Conversion</a>). </p> </dd> <dt>‘<samp>_<span class="roman"> (underscore)</span></samp>’</dt> <dd><p>This flag converts the substituted text to lower case (see <a href="case-conversion">Case Conversion</a>). </p></dd> </dl> <p>The result of using contradictory flags (for instance, both upper and lower case) is undefined. </p> <p>As is the case with <code>format</code>, a format specification can include a width, which is a decimal number that appears after any flags, and a precision, which is a decimal-point ‘<samp>.</samp>’ followed by a decimal number that appears after any flags and width. </p> <p>If a substitution contains fewer characters than its specified width, it is padded on the left: </p> <div class="example"> <pre class="example">(format-spec "%8a is padded on the left with spaces"
'((?a . "alpha")))
⇒ " alpha is padded on the left with spaces"
</pre>
</div> <p>If a substitution contains more characters than its specified precision, it is truncated on the right: </p> <div class="example"> <pre class="example">(format-spec "%.2a is truncated on the right"
'((?a . "alpha")))
⇒ "al is truncated on the right"
</pre>
</div> <p>Here is a more complicated example that combines several aforementioned features: </p> <div class="example"> <pre class="example">(setq my-battery-info
(list (cons ?p "73") ; Percentage
(cons ?L "Battery") ; Status
(cons ?t "2:23") ; Remaining time
(cons ?c "24330") ; Capacity
(cons ?r "10.6"))) ; Rate of discharge
(format-spec "%>^-3L : %3p%% (%05t left)" my-battery-info)
⇒ "BAT : 73% (02:23 left)"
(format-spec "%>^-3L : %3p%% (%05t left)"
(cons (cons ?L "AC")
my-battery-info))
⇒ "AC : 73% (02:23 left)"
</pre>
</div> <p>As the examples in this section illustrate, <code>format-spec</code> is often used for selectively formatting an assortment of different pieces of information. This is useful in programs that provide user-customizable format strings, as the user can choose to format with a regular syntax and in any desired order only a subset of the information that the program makes available. </p><div class="_attribution">
<p class="_attribution-p">
Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
<a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Custom-Format-Strings.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Custom-Format-Strings.html</a>
</p>
</div>
|
