From 6caec0249f6c353aba98e08aa650fef49ecdfb3a Mon Sep 17 00:00:00 2001
From: Ryan Culpepper <ryanc@racket-lang.org>
Date: Thu, 29 Sep 2016 15:53:02 -0400
Subject: [PATCH] syntax/parse: document ~post

---
 .../syntax/scribblings/parse/patterns.scrbl   | 34 ++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/pkgs/racket-doc/syntax/scribblings/parse/patterns.scrbl b/pkgs/racket-doc/syntax/scribblings/parse/patterns.scrbl
index f2af43fc33..0de49e896d 100644
--- a/pkgs/racket-doc/syntax/scribblings/parse/patterns.scrbl
+++ b/pkgs/racket-doc/syntax/scribblings/parse/patterns.scrbl
@@ -34,7 +34,7 @@ means specifically @tech{@Spattern}.
 
 @racketgrammar*[#:literals (_ ~var ~literal ~or ~and ~not ~rest ~datum
                             ~describe ~seq ~optional ~rep ~once ~between
-                            ~! ~bind ~fail ~parse ~peek ~peek-not ~do)
+                            ~! ~bind ~fail ~parse ~peek ~peek-not ~do ~post)
                 [S-pattern
                  pvar-id
                  pvar-id:syntax-class-id
@@ -60,6 +60,7 @@ means specifically @tech{@Spattern}.
                  (@#,ref[~describe s] maybe-opaque maybe-role expr S-pattern)
                  (@#,ref[~commit s] S-pattern)
                  (@#,ref[~delimit-cut s] S-pattern)
+                 (@#,ref[~post s] S-pattern)
                  A-pattern]
                 [L-pattern
                  ()
@@ -80,6 +81,7 @@ means specifically @tech{@Spattern}.
                  (@#,ref[~describe h] maybe-opaque maybe-role expr H-pattern)
                  (@#,ref[~commit h] H-pattern)
                  (@#,ref[~delimit-cut h] H-pattern)
+                 (@#,ref[~post h] H-patter)
                  (~peek H-pattern)
                  (~peek-not H-pattern)
                  proper-S-pattern]
@@ -95,6 +97,7 @@ means specifically @tech{@Spattern}.
                  (~fail maybe-fail-condition maybe-message-expr)
                  (~parse S-pattern stx-expr)
                  (@#,ref[~and a] A-pattern ...+)
+                 (@#,ref[~post a] A-pattern)
                  (~do defn-or-expr ...)]
                 [proper-S-pattern
                  #, @elem{a @svar{S-pattern} that is not a @svar{A-pattern}}]
@@ -158,6 +161,16 @@ One of @ref[~delimit-cut s] or @ref[~delimit-cut h]:
 ]
 }
 
+@defidform[~post]{
+
+One of @ref[~post s], @ref[~post h], or @ref[~post a]:
+@itemize[
+@item{@ref[~post a] if the subpattern is a @tech{proper @Apattern}}
+@item{@ref[~post h] if the subpattern is a @tech{proper @Hpattern}}
+@item{@ref[~post s] otherwise}
+]
+}
+
 @defidform[~optional]{
 
 One of @ref[~optional h] or @ref[~optional eh]:
@@ -640,6 +653,14 @@ pattern.}
 ]
 }
 
+@specsubform[(@#,def[~post s] S-pattern)]{
+
+Marks failures within the subpattern as occurring in a ``post-order
+check''; that is, they are considered to have made greater progress
+than a normal failure.
+}
+
+
 @specsubform[A-pattern]{
 
 An @tech{@Apattern} is considered a @Spattern when there is no
@@ -789,6 +810,12 @@ Like the @Spattern version, @ref[~delimit-cut s], but matches a head
 pattern instead.
 }
 
+@specsubform[(@#,def[~post h] H-pattern)]{
+
+Like the @Spattern version, @ref[~post s], but matches a head
+pattern instead.
+}
+
 @specsubform[(@#,defhere[~peek] H-pattern)]{
 
 Matches the @racket[H-pattern] but then resets the matching position,
@@ -1051,6 +1078,11 @@ definition in a @racket[~do] block.
 ]
 }
 
+@specsubform[(@#,def[~post a] A-pattern)]{
+
+Like the @Spattern version, @ref[~post s], but matches a head
+pattern instead.
+}
 
 
 @;{--------}