Re: Question on pcase

[Alan Mackenzie]

Hello, Michael.

On Fri, Oct 23, 2015 at 08:38:31PM +0200, Michael Heerdegen wrote:
> Eli Zaretskii <address@hidden> writes:

> > Sounds good to me, thanks.

> I wrote a step by step introduction for people who (1) are frightened by
> `pcase' and (2) are willing to invest some (not much, but some) time to
> learn it.  It is how I would describe `pcase' to a friend, maybe it is
> good for learning, maybe it is ugly, dunno.  Some errors included.

> Someone who wants to try to learn pcase (Oleh? Oleh!) can help by
> reading it and telling me if it is understandable, and send corrections
> - or write a better introduction ;-) - and format it nicely for
> inclusion into Elpa or Emacs when it turns out to help people.

Thanks for writing this.  I've enclosed some corrections - a few typos,
and some places where the English usage isn't quite correct.

Some notes:
1. The guide you have written is _not_ trivial.  :-)  It is detailed and
helpful.

2. "Semantics", as a noun, is always plural in English (a bit like
"Eltern" in German).  It is also a mass noun, so you couldn't write "one
of the semantics is ...."; you'd need to write something like "one part
of the semantics is ....".

3. "Else" can't come at the end of a sentence.  (It can't really come at
the start of a sentence either.)  If you're going to use "else" it needs
to come _before_ the clause it applies to.

4. In "How would you roughly describe ...", the "roughly" means doing the
describing without delicacy, perhaps with violence, without any finesse.
In "How, roughly, would you describe ...", it means "approximately".
:-)

5. "the `pred' pattern form allows to simplify ...." is a very common
solecism.  The verb "allow" needs a direct object, not an infinitive verb.
That object can either be the person (or thing) who is being allowed to do
something, or the thing (a noun or gerund) which is being allowed.  So
here, you'd want one of
  o - "the `pred' pattern form allows YOU to simplify ...." or
  o - "the `pred' pattern form allows THE SIMPLIFICATION OF ...." or even 
  o - "the `pred' pattern form allows SIMPLIFYING ...."
I think the first of these is marginally the best.

6. "Now, only one basic pattern form is missing:".  Well, it's not
missing, it's there.  There's no snappy translation of "es fehlt", in
this sense.  You'd have to qualify it with something like "Now, only one
basic pattern form is missing from our list so far:", which is a bit
clumsy.  What I've suggested in my patch is, perhaps, a little less
clumsy.

7. "If you are used to understand grammers ...".  "Used to" takes a
direct object (or gerund), not an infinitive verb.  "Grammar" doesn't
have an "e" in it.  :-)


Here's the patch (not guaranteed complete).



--- pcase-guide.el~     2015-10-24 07:16:29.000000000 +0000
+++ pcase-guide.el      2015-10-24 08:52:53.000000000 +0000
@@ -1,4 +1,4 @@
-;; Understand `pcase' now! - A trivial guide to a powerful tool
+;; Understand `pcase' now! - An easy guide to a powerful tool
 ;; ============================================================
 
 
@@ -23,24 +23,24 @@
 ;; specify PATTERNs instead of CONDITIONs, and the PATTERNS are tested
 ;; for whether they match the evaluated EXPRESSION, in order.  If one
 ;; PATTERN matches, it's CODE is evaluated.  Like in `cond', all
-;; branches are tested until one is found whose PATTERN matches.  All
+;; branches are tested until one whose PATTERN matches is found.  All
 ;; remaining branches are ignored.
 ;;
 ;; The PATTERNs are not lisp code, like `cl-loop' forms they are
-;; written with an own simple language.  There are a few simple basic
+;; written in their own simple language.  There are a few simple basic
 ;; patterns, and you can combine them.
 ;;
 ;; A very useful thing is that matching a pattern can bind variables
-;; as a side effect.  This bindings are in effect when the CODE of
+;; as a side effect.  These bindings are in effect when the CODE of
 ;; that branch is executed (actually, they are already in effect when
-;; then the remaining parts of the pattern are processed; that fact
+;; the remaining parts of the pattern are processed; that fact
 ;; will prove useful later in this guide).
 ;;
-;; All yet to understand is the semantic each of the basic PATTERNs.
+;; All that remains to understand are the semantics of each of the basic 
PATTERNs.
 ;; Since you can do quite a lot with `pcase' - e.g. you can use it
 ;; like `let*', like `cond', like `case', like `destructuring-bind',
-;; all in combination and more, it is clear that the semantic can't be
-;; absolutely trivial.  However, there are only very few basic forms
+;; all in combination and more, it is clear that the semantics can't be
+;; absolutely trivial.  However, there are only a very few basic forms
 ;; of patterns, and all are easy to understand.  And those forms can
 ;; be combined.  That's already it.  I will explain the basic patterns
 ;; one after the other, you may want to take one or two breaks in
@@ -80,7 +80,7 @@
   (_        3))
 
 ;; This will return 1 if x is bound to the symbol `a', 2 if x is bound
-;; to a string equal to "Hallo", and 3 else.  Hey, already two pattern
+;; to a string equal to "Hallo", and 3 otherwise.  Hey, already two pattern
 ;; types learned!
 ;;
 ;; A SYMBOL (different from `_') "matches anything and binds it to
@@ -129,7 +129,7 @@
                                       3))
 
 ;; This will return 1 if x is bound to a list, 2 if what x is bound to
-;; fulfils eihter `arrayp' or `numberp'.  And 3 if the binding of x is
+;; fulfils either `arrayp' or `numberp'.  And 3 if the binding of x is
 ;; a string that contains "blue".  If none of that is true, no branch
 ;; matches, and `pcase' returns nil.
 
@@ -155,7 +155,7 @@
 ;; strange special case of matching via the `guard' pattern.
 
 ;; Exercise: We noted that `pcase' can be used to substitute `let*',
-;; `cond' or `case' in your code.  How would you roughly describe how
+;; `cond' or `case' in your code.  How, roughly, would you describe how
 ;; one can rewrite an arbitrary `let*', `cond' or `case' form using
 ;; `pcase'? (Hint: It's not hard.)
 
@@ -166,7 +166,7 @@
 ;;
 ;; This is a pattern form that allows you to match a pattern PAT
 ;; against an _arbitrary_ expression EXP.  This is not special,
-;; matching PAT is done as you have learned, just against the EXP you
+;; matching PAT is done as you have learned, just on the EXP you
 ;; specify there, and not the EXPRESSION given to pcase at top level.
 ;;
 ;; Example:
@@ -178,7 +178,7 @@
   (_ nil))
 
 ;; This will return t if x is bound to a number whose absolute value
-;; is larger than 5, like 7 or -13, and nil else, e.g. for 0 or -2 or
+;; is larger than 5, like 7 or -13, and nil otherwise, e.g. for 0 or -2 or
 ;; "Hallo".
 
 ;; Why is it called `let' then?  Because you can use it to
@@ -192,9 +192,9 @@
   l)
 
 ;; will return the string length of STRING if it is bound to a string
-;; of non-zero length, and nil else.
+;; of non-zero length, and nil otherwise.
 
-;; BTW, the `pred' pattern form allows to simplify things like
+;; BTW, the `pred' pattern form allows one to simplify things like
 
 (pred (lambda (x) (< 5 x)))
 
@@ -226,7 +226,7 @@
    abs-val))
 
 ;; will return the absolute value of x if x is a number and its
-;; absolute value is larger than 5, and nil else.
+;; absolute value is larger than 5, and nil otherwise.
 
 ;; (app FUN PAT) matches if FUN applied to the object matches PAT.
 
@@ -240,7 +240,7 @@
 ;; will return t if and only if x is bound to a string with length
 ;; smaller than 60 chars.
 
-;; Now, only one basic pattern form is missing:
+;; Now, only one basic pattern form remains to be described:
 ;;
 ;;   `QPAT         Backquote-style pcase patterns.
 ;;
@@ -263,7 +263,7 @@
 
   (1 2 3)  (1 . (2 3))
 
-;; desribe the same list structure using two different reader
+;; describe the same list structure using two different reader
 ;; syntaxes.  When being read by the Lisp reader, those forms are
 ;; equal.  So, in the above description, the
   
@@ -272,14 +272,14 @@
 ;; form can be used to match any kind of arbitrary list, and you don't
 ;; need to use the read syntax using dot.
 ;;
-;; If you are used to understand grammers: the above description of
-;; `QPAT describes a quite simpel grammer.  You make like to try it
+;; If you are used to understanding grammars: the above description of
+;; `QPAT describes a quite simple grammar.  You might like to try it
 ;; out with some examples yourself, it's simple, though the results
-;; might look unfamiliar.  It doesn't take long to familiarize with
+;; might look unfamiliar.  It doesn't take long to familiarize yourself with
 ;; it, though.
 ;;
 ;; Note that though the backquote _syntax_ is used here, the backquote
-;; macro is never called (!), just it's syntax is used to describe
+;; macro is never called (!), just its syntax is used to describe
 ;; patterns for destructuring because it is convenient to write, and
 ;; also a bit related to how backquote works.
 
@@ -297,17 +297,17 @@
 ;; to "foo", it returns the second element.
 ;;
 ;; If x is bound to a cons whose car equals "foo", and the cdr is
-;; listp, this cdr is returned.  Else, nil is returned.
+;; listp, this cdr is returned.  Otherwise, nil is returned.
 ;;
 ;; For destructuring, the `_' pattern is handy to match anything.
 ;; Pitfall: Be sure to unquote `_' if you don't want to match the
 ;; symbol `_' literally, because _ is not a QPAT.
 ;;
-;; Example: The ;; pattern
+;; Example: The pattern
 
 `(1 ,_ . ,_)
 
-;; matches any list whoose first element is 1, and which has at least
+;; matches any list whose first element is 1, and which has at least
 ;; one more element.
 
 ;; Just like with the "real" backquote, you can use "unquote" in lower
@@ -321,7 +321,7 @@
 ;; element is 1, and the second argument is a list of two elements;
 ;; the first element is bound to the variable `x', and the second
 ;; element is bound to `y', and it is tested whether x + y is smaller
-;; than 10.  Only then the whole pattern matches.
+;; than 10.  Only then does the whole pattern match.
 
 ;; Example:
 

> Thanks,

> Michael.

-- 
Alan Mackenzie (Nuremberg, Germany).