[Emacs-diffs] fix/bug-31311-pcase-doc 5e2eeee 17/18: transform ‘get-return-code’ example

[Thien-Thi Nguyen]

branch: fix/bug-31311-pcase-doc
commit 5e2eeeee075342b1b03fc9269e05c863f21840c3
Author: Thien-Thi Nguyen <address@hidden>
Commit: Thien-Thi Nguyen <address@hidden>

    transform ‘get-return-code’ example
    
    - move before other examples
    - add anchor/subheading
    - expand to compare against ‘cl-case’
    - add pre- and post- paras
    - remove FIXME comment (coverage now shared by all examples)
---
 doc/lispref/control.texi | 40 ++++++++++++++++++++++++++--------------
 1 file changed, 26 insertions(+), 14 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 3439916..95d5777 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -419,6 +419,32 @@ should all bind the same symbols.
 Matches if all the argument U-patterns match.
 @end table
 
address@hidden
address@hidden Example: Advantage Over @code{cl-case}
+
+Here's an example that highlights some advantages @code{pcase}
+has over @code{cl-case}.
+
address@hidden
+(pcase (get-return-code x)
+  ;; string
+  ((and (pred stringp) msg)
+   (message "%s" msg))
+  ;; symbol
+  ('success       (message "Done!"))
+  ('would-block   (message "Sorry, can't do it now"))
+  ('read-only     (message "The shmliblick is read-only"))
+  ('access-denied (message "You do not have the needed rights"))
+  ;; default
+  (code           (message "Unknown return code %S" code)))
address@hidden example
+
address@hidden
+With @code{cl-case}, you would need to explicitly declare a local
+variable @code{code} to hold the return value of @code{get-return-code}.
+Also @code{cl-case} is difficult to use with strings because it
+uses @code{eql} for comparison.
+
 @anchor{pcase-example-1}
 @subheading Example: Using @code{and}
 
@@ -607,20 +633,6 @@ Avoid.
 @c (what does it mean?)
 @end enumerate
 
address@hidden
-Here's an example of using U-patterns:
-
address@hidden FIXME: This example should use every one of the U-patterns 
described
address@hidden above at least once.
address@hidden
-(pcase (get-return-code x)
-  ('success       (message "Done!"))
-  ('would-block   (message "Sorry, can't do it now"))
-  ('read-only     (message "The shmliblick is read-only"))
-  ('access-denied (message "You do not have the needed rights"))
-  (code           (message "Unknown return code %S" code)))
address@hidden example
-
 In addition, you can use backquoted patterns that are more powerful.
 They allow matching @var{expval} against specifications of its
 @emph{structure}.  For example, you can specify that the value must be