From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: "Basil L. Contovounesios" Newsgroups: gmane.emacs.bugs Subject: bug#41571: 27.0.91; "(elisp) Interpolated Strings" is under "(elisp) Text" Date: Thu, 28 May 2020 00:57:34 +0100 Message-ID: <877dwxexsh.fsf@tcd.ie> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="87959"; mail-complaints-to="usenet@ciao.gmane.io" To: 41571@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu May 28 01:58:11 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1je5w3-000Mq6-92 for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 28 May 2020 01:58:11 +0200 Original-Received: from localhost ([::1]:55454 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1je5w1-0001aH-Rx for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 27 May 2020 19:58:09 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:59980) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1je5vv-0001a9-1u for bug-gnu-emacs@gnu.org; Wed, 27 May 2020 19:58:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:38785) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1je5vu-0006S5-Ow for bug-gnu-emacs@gnu.org; Wed, 27 May 2020 19:58:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1je5vu-0007a3-OQ for bug-gnu-emacs@gnu.org; Wed, 27 May 2020 19:58:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Basil L. Contovounesios" Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 27 May 2020 23:58:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 41571 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.159062386529111 (code B ref -1); Wed, 27 May 2020 23:58:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 27 May 2020 23:57:45 +0000 Original-Received: from localhost ([127.0.0.1]:50331 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1je5vc-0007ZS-8c for submit@debbugs.gnu.org; Wed, 27 May 2020 19:57:44 -0400 Original-Received: from lists.gnu.org ([209.51.188.17]:57774) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1je5va-0007ZL-ML for submit@debbugs.gnu.org; Wed, 27 May 2020 19:57:43 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:59964) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1je5va-0001YZ-Do for bug-gnu-emacs@gnu.org; Wed, 27 May 2020 19:57:42 -0400 Original-Received: from mail-wm1-x343.google.com ([2a00:1450:4864:20::343]:39677) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1je5vY-0006PK-HE for bug-gnu-emacs@gnu.org; Wed, 27 May 2020 19:57:42 -0400 Original-Received: by mail-wm1-x343.google.com with SMTP id k26so1357638wmi.4 for ; Wed, 27 May 2020 16:57:38 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=tcd-ie.20150623.gappssmtp.com; s=20150623; h=from:to:subject:date:message-id:mime-version; bh=unbdSy0OAg9x6Fvo3R1XO6497auQkOJejjFwRssFYB8=; b=SUF2jeIQnH0csI3SkBwpBonujb04lmUbVP1AY+kNtrK/FiJzP9p/i/hFvM9wPzGlvU wEGVwQ0R8vbc1qDJhzOxFWW/pxLqwkbFJYOv5RCQsyoburBF8OwghOf+mgQBC8Sd9ch0 uxV1+bDRn1w0ZTB9nd4G53DyJH3ahTxc4sTdkq1xnuOpOuokC2Ld0jWH7kGA2wK/b3gj SB7YeyF9H2l8ihKBDv50eSDQRNeEsqTKTwb/8IslWl9Xy8UzDuPcQXa/zT/5iOClbZn3 bWdq//JhP0IuNazx3kVacaH/JVWmcmBf6YcNvqbN+Pb4bZZ4KPtwL+8tAxEH6+yeMaks Udcg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:mime-version; bh=unbdSy0OAg9x6Fvo3R1XO6497auQkOJejjFwRssFYB8=; b=bwdy27POVDh9tiNRRsVk6vz4ovFzowgKjL5UysxGnc/rlqU4xarRyKQ0Ac9ALh5uhq RL3WKCrRwYY+rIyxdxU/wsIjsfL1Rb7H1y4bOmTHb74ExOd0mopTuvRTdNF/pKAumeOU hmpN09SxwdbbJnftGpqTPRHfgnhlxLCzA62XPfBTN9eIVRMCdMdw6dryd/pixtJupks4 6YcPpPQUr3F5gswVmcPH/20Zbv/dspWe/NN/Ywnh5VeRtCAWi0Qtt7SftyDS4RXyIcAP UUOMemXor7oQQBDHpA2twR6Tt+LmhhC21RQyJ3IEwwidBKPe4YrusGza+3Y1k2iLzQa3 bJRA== X-Gm-Message-State: AOAM532+e0ZhNbywQIQ54ZyeE8e//aeYETgJReGA1hwWzJllvJ7GME+Y SldRaQodNvbNjY0dvpqUiJR8ArI78S8= X-Google-Smtp-Source: ABdhPJxWnx6k8IPtZ4lwaT5hsQnc2ki8njYAuQyXvN4meDEo7GgBZR/GIdjLbUlS75Ldpc86Z8PJYA== X-Received: by 2002:a1c:64c1:: with SMTP id y184mr523759wmb.175.1590623856592; Wed, 27 May 2020 16:57:36 -0700 (PDT) Original-Received: from localhost ([2a02:8084:20e2:c380:92bd:1bfd:38fc:fae2]) by smtp.gmail.com with ESMTPSA id d4sm4079948wre.22.2020.05.27.16.57.35 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 27 May 2020 16:57:35 -0700 (PDT) Received-SPF: none client-ip=2a00:1450:4864:20::343; envelope-from=contovob@tcd.ie; helo=mail-wm1-x343.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, URIBL_BLOCKED=0.001 autolearn=_AUTOLEARN X-Spam_action: no action X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:181118 Archived-At: --=-=-= Content-Type: text/plain Severity: minor Tags: patch --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0001-Document-format-spec-under-Strings-and-Characters.patch >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 --=-=-= Content-Type: text/plain The Elisp manual node "(elisp) Interpolated Strings", which documents the function format-spec and is new in Emacs 27, is currently included under "(elisp) Text", which opens with: This chapter describes the functions that deal with the text in a buffer. Most examine, insert, or delete text in the current buffer, often operating at point or on text adjacent to point. Many are interactive. All the functions that change the text provide for undoing the changes (*note Undo). I think a more appropriate location would be following "(elisp) Formatting Strings", or at least under "(elisp) Strings and Characters". Patch for emacs-27 attached. WDYT? Thanks, -- Basil In GNU Emacs 27.0.91 (build 7, x86_64-pc-linux-gnu, X toolkit, Xaw3d scroll bars) of 2020-05-27 built on thunk Repository revision: 9d7fd78421a339f00892b3241845b1024e2eff7d Repository branch: emacs-27 Windowing system distributor 'The X.Org Foundation', version 11.0.12008000 System Description: Debian GNU/Linux bullseye/sid --=-=-=--