new repository

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 &lt;%s&gt;"</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 &lt;%e&gt;"</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 &amp;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 &lt;%a&gt;" my-site-info)
+     ⇒ "Emacs Developers &lt;emacs-devel@gnu.org&gt;"
+</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>&lt;</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>&gt;</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 "%&gt;^-3L : %3p%% (%05t left)" my-battery-info)
+     ⇒ "BAT :  73% (02:23 left)"
+
+(format-spec "%&gt;^-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 &copy; 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>