Document format-spec and expand the modifiers it supports

* doc/lispref/text.texi (Interpolated Strings): New section.
* lisp/format-spec.el (format-spec--parse-modifiers)
(format-spec--pad): New functions.
(format-spec): Support more format modifiers (bug#32931).

1 files changed, 67 insertions, 0 deletions

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 94b94eaba7e..df9fce066f0 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -58,6 +58,7 @@ the character after point.
                        of another buffer.
 * Decompression::    Dealing with compressed data.
 * Base 64::          Conversion to or from base 64 encoding.
+* Interpolated Strings:: Formatting Customizable Strings.
 * Checksum/Hash::    Computing cryptographic hashes.
 * GnuTLS Cryptography:: Cryptographic algorithms imported from GnuTLS.
 * Parsing HTML/XML:: Parsing HTML and XML.
@@ -4626,6 +4627,72 @@ If optional argument @var{base64url} is is non-@code{nil}, then padding
 is optional, and the URL variant of base 64 encoding is used.
 @end defun
 
+
+@node Interpolated Strings
+@section Formatting Customizable Strings
+
+It is, in some circumstances, useful to present users with a string to
+be customized that can then be expanded programmatically.  For
+instance, @code{erc-header-line-format} is @code{"%n on %t (%m,%l)
+%o"}, and each of those characters after the percent signs are
+expanded when the header line is computed.  To do this, the
+@code{format-spec} function is used:
+
+@defun format-spec format specification &optional only-present
+@var{format} is the format specification string as in the example
+above.  @var{specification} is an alist that has elements where the
+@code{car} is a character and the @code{cdr} is the substitution.
+
+If @code{ONLY-PRESENT} is @code{nil}, errors will be signalled if a
+format character has been used that's not present in
+@var{specification}.  If it's non-@code{nil}, that format
+specification is left verbatim in the result.
+@end defun
+
+Here's a trivial example:
+
+@example
+(format-spec "su - %u %l"
+             `((?u . ,(user-login-name))
+               (?l . "ls")))
+=> "su - foo ls"
+@end example
+
+In addition to allowing padding/limiting to a certain length, the
+following modifiers are can be used:
+
+@table @asis
+@item @samp{0}
+Use zero padding.
+
+@item @samp{@ }
+User space padding.
+
+@item @samp{-}
+Pad to the right.
+
+@item @samp{^}
+Use upper case.
+
+@item @samp{_}
+Use lower case.
+
+@item @samp{<}
+If the length needs to limited, remove characters from the left.
+
+@item @samp{>}
+Same as previous, but remove characters from the right.
+@end table
+
+If contradictory modifiers are used (for instance, both upper- and
+lower case), then what happens is undefined.
+
+As an example, @samp{"%<010b"} means ``insert the @samp{b} expansion,
+but pad with leading zeroes if it's less than ten characters, and if
+it's more than ten characters, shorten by removing characters from the
+left''.
+
+
 @node Checksum/Hash
 @section Checksum/Hash
 @cindex MD5 checksum