From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: Replace trivial pcase occurrences in the Emacs sources Date: Tue, 30 Oct 2018 13:16:33 -0400 Message-ID: References: <83tvlcsnee.fsf@gnu.org> <86mur137n8.fsf@gmail.com> <20181029130132.GB4195@ACM> <20181029134722.GC4195@ACM> <87lg6gifnb.fsf@web.de> <87muqwxs7m.fsf@ericabrahamsen.net> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1540919700 10269 195.159.176.226 (30 Oct 2018 17:15:00 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 30 Oct 2018 17:15:00 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) Cc: Michael Heerdegen , emacs-devel@gnu.org To: Eric Abrahamsen Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Oct 30 18:14:55 2018 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gHXbR-0002ZI-Dz for ged-emacs-devel@m.gmane.org; Tue, 30 Oct 2018 18:14:53 +0100 Original-Received: from localhost ([::1]:54574 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gHXdY-00017G-37 for ged-emacs-devel@m.gmane.org; Tue, 30 Oct 2018 13:17:04 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:41458) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gHXdJ-00016A-S0 for emacs-devel@gnu.org; Tue, 30 Oct 2018 13:16:56 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gHXdE-0003KU-Hb for emacs-devel@gnu.org; Tue, 30 Oct 2018 13:16:49 -0400 Original-Received: from pruche.dit.umontreal.ca ([132.204.246.22]:46196) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gHXdE-0003Gg-2K for emacs-devel@gnu.org; Tue, 30 Oct 2018 13:16:44 -0400 Original-Received: from pastel.home (lechon.iro.umontreal.ca [132.204.27.242]) by pruche.dit.umontreal.ca (8.14.7/8.14.1) with ESMTP id w9UHGXfW023917; Tue, 30 Oct 2018 13:16:33 -0400 Original-Received: by pastel.home (Postfix, from userid 20848) id 6AC8064B97; Tue, 30 Oct 2018 13:16:33 -0400 (EDT) In-Reply-To: (Stefan Monnier's message of "Tue, 30 Oct 2018 08:30:06 -0400") X-NAI-Spam-Flag: NO X-NAI-Spam-Threshold: 5 X-NAI-Spam-Score: 0 X-NAI-Spam-Rules: 2 Rules triggered EDT_SA_DN_PASS=0, RV6407=0 X-NAI-Spam-Version: 2.3.0.9418 : core <6407> : inlines <6948> : streams <1802828> : uri <2741169> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 132.204.246.22 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:230833 Archived-At: >> I wonder if the manual shouldn't have a section somewhere making >> explicit the difference between `pcase' -- where a single value is >> matched against many patterns, and may fail to match altogether, and >> destructuring is only one of the use-cases -- and the other > Yes, I'll send a patch for that, How 'bout... Stefan diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 5be4b298b4..819f486f4e 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -477,6 +477,7 @@ Pattern-Matching Conditional * The @code{pcase} macro: pcase Macro. Plus examples and caveats. * Extending @code{pcase}: Extending pcase. Define new kinds of patterns. * Backquote-Style Patterns: Backquote Patterns. Structural matching. +* Destructuring patterns:: Using pcase patterns to extract subfields. @end menu @node pcase Macro @@ -1168,6 +1169,81 @@ Backquote Patterns (evaluate '(sub 1 2) nil) @result{} error @end example +@node Destructuring patterns +@subsection Destructuring Patterns +@cindex Destructuring patterns + +Pcase patterns not only express a condition on the form of the objects +they can match but they can also extract sub-fields of those objects. +Say we have a list and want to extract 2 elements from it with the +following code: + +@example + (pcase l + (`(add ,x ,y) (message "Contains %S and %S" x y))) +@end example + +This will not only extract @code{x} and @code{y} but will additionally +test that @code{l} is a list containing exactly 3 elements and whose +first element is the symbol @code{add}. If any of those tests fail, +@code{pcase} will directly return @code{nil} without calling +@code{message}. + +The macros described in this section use @emph{destructuring} +patterns, which are normal Pcase patterns used in a context where we +presume that the object does match the pattern, and we only want +to extract some subfields. For example: + +@example + (pcase-let ((`(add ,x ,y) l)) + (message "Contains %S and %S" x y)) +@end example + +Does the same as the previous example, except that it directly tries +to extract @code{x} and @code{y} from @code{l} without first verifying +if @code{l} is a list which has the right number of elements and has +@code{add} as its first element. +The precise behavior when the object does not actually match the +pattern is undefined, although the body will not be silently skipped: +either an error is signaled or the body is run with some of the +variables potentially bound to arbitrary values like @code{nil}. + +@defmac pcase-let bindings body@dots{} +Bind variables according to @var{bindings} and then eval @var{body}. + +@var{bindings} is a list of bindings of the form @code{(@var{pattern} +@var{exp})}, where @var{exp} is an expression to evaluate and +@var{pattern} is a destructuring pattern. + +All @var{exp}s are evaluated first after which they are matched +against their respective @var{pattern}, introducing new variable +bindings which can then be used inside @var{body}. +@end defmac + +@defmac pcase-let* bindings body@dots{} +Bind variables according to @var{bindings} and then eval @var{body}. + +@var{bindings} is a list of bindings of the form @code{(@var{pattern} +@var{exp})}, where @var{exp} is an expression to evaluate and +@var{pattern} is a destructuring pattern. + +Unlike @code{pcase-let}, but like @code{let*}, each @var{exp} is +matched against its corresponding @var{pattern} before passing to the +next element of @var{bindings}, so the variables introduced in each +binding are available in the @var{exp}s that follow it, additionally +to being available in @var{body}. +@end defmac + +@findex dolist +@defmac pcase-dolist (pattern list) body@dots{} +This construct executes @var{body} once for each element of +@var{list}, in a context where the destructuring pattern +@var{pattern} was matched against the element. +When @var{pattern} is a simple variable, this ends up being equivalent +to @code{dolist}. +@end defmac + + @node Iteration @section Iteration @cindex iteration