From 9f63db1262683c1b7c58909d04bb2efa4ac2491a Mon Sep 17 00:00:00 2001 From: "Basil L. Contovounesios" Date: Thu, 28 May 2020 00:53:42 +0100 Subject: [PATCH] Document format-spec under Strings and Characters * doc/lispref/text.texi (Interpolated Strings): Move from here... * doc/lispref/strings.texi (Interpolating Strings): ...to here. --- doc/lispref/strings.texi | 62 ++++++++++++++++++++++++++++++++++++++ doc/lispref/text.texi | 64 ---------------------------------------- 2 files changed, 62 insertions(+), 64 deletions(-) diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 70c3b3cf4b..e1e40243fb 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -28,6 +28,7 @@ Strings and Characters * Text Comparison:: Comparing characters or strings. * String Conversion:: Converting to and from characters and strings. * Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. +* Interpolating Strings:: Formatting customizable strings. * Case Conversion:: Case conversion functions. * Case Tables:: Customizing case conversion. @end menu @@ -1122,6 +1123,67 @@ Formatting Strings NaNs and can lose precision and type, and @samp{#x%x} and @samp{#o%o} can mishandle negative integers. @xref{Input Functions}. +@node Interpolating 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 @var{only-present} is @code{nil}, errors will be signaled 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"))) + @result{} "su - foo ls" +@end example + +In addition to allowing padding/limiting to a certain length, the +following modifiers can be used: + +@table @asis +@item @samp{0} +Pad with zeros instead of the default spaces. + +@item @samp{-} +Pad to the right. + +@item @samp{^} +Use upper case. + +@item @samp{_} +Use lower case. + +@item @samp{<} +If the length needs to be 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 zeros if it's less than ten characters, and if +it's more than ten characters, shorten by removing characters from the +left.'' + @node Case Conversion @section Case Conversion in Lisp @cindex upper case diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index de436fa9e6..a14867e1d1 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -58,7 +58,6 @@ Text 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. @@ -4662,69 +4661,6 @@ Base 64 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 @var{only-present} is @code{nil}, errors will be signaled 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"))) - @result{} "su - foo ls" -@end example - -In addition to allowing padding/limiting to a certain length, the -following modifiers can be used: - -@table @asis -@item @samp{0} -Pad with zeros instead of the default spaces. - -@item @samp{-} -Pad to the right. - -@item @samp{^} -Use upper case. - -@item @samp{_} -Use lower case. - -@item @samp{<} -If the length needs to be 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 zeros 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 -- 2.26.2