diff options
Diffstat (limited to 'devdocs/elisp/custom-format-strings.html')
| -rw-r--r-- | devdocs/elisp/custom-format-strings.html | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/devdocs/elisp/custom-format-strings.html b/devdocs/elisp/custom-format-strings.html new file mode 100644 index 00000000..e67ab4fb --- /dev/null +++ b/devdocs/elisp/custom-format-strings.html @@ -0,0 +1,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> |