Feedback-ID: i0fe9450f:Fastmail
Date: Wed, 11 Sep 2024 15:37:17 +0900
From: Michael Paquier <michael@paquier.xyz>
To: Philipp Salvisberg <philipp.salvisberg@gmail.com>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Undocumented optionality of handler_statements
Message-ID: <ZuE6ndanu0Z_9NWM@paquier.xyz>
References: <172165655256.710.2097726158572647813@wrigleys.postgresql.org>
 <Zp7tqLSTbBaBTUlP@paquier.xyz>
 <D88C77BC-7C03-4802-B1C3-B6BB83437184@gmail.com>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha512;
	protocol="application/pgp-signature"; boundary="tDCxDAb1Q78I9qDG"
Content-Disposition: inline
In-Reply-To: <D88C77BC-7C03-4802-B1C3-B6BB83437184@gmail.com>
Archived-At: 
 <https://www.postgresql.org/message-id/ZuE6ndanu0Z_9NWM%40paquier.xyz>
Precedence: bulk


--tDCxDAb1Q78I9qDG
Content-Type: multipart/mixed; boundary="Za4dOZB3PZqN3QEg"
Content-Disposition: inline


--Za4dOZB3PZqN3QEg
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On Tue, Jul 23, 2024 at 01:25:39PM +0200, Philipp Salvisberg wrote:
> read "optional" as "mandatory".

They're optional, like in empty being optional.  If not specified, the
block goes to its END.

> Therefore, I suggest to change this example by adding a NULL
> statement as in other examples. This change would make the
> documentation consistent and handle the optionality of
> handler_statements as an implementation detail. I created a patch
> for plpgsql.sgml based on the master branch, adding a NULL statement
> in empty exception handlers (see attached file
> doc_patch_using_null_stmt_instead_of_empty_exception_handler_v1.diff).

These examples have been around for 20 years with, and I think that it
is helpful to show this pattern as well.  So if I were to do something
about that, I would suggest the attached.
--
Michael

--Za4dOZB3PZqN3QEg
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="doc-plpgsql-error.patch"

diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 78e4983139..3a5e7bc296 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -2804,9 +2804,9 @@ BEGIN
     <replaceable>statements</replaceable>
 EXCEPTION
     WHEN <replaceable>condition</replaceable> <optional> OR <replaceable>condition</replaceable> ... </optional> THEN
-        <replaceable>handler_statements</replaceable>
+        <optional> <replaceable>handler_statements</replaceable> </optional>
     <optional> WHEN <replaceable>condition</replaceable> <optional> OR <replaceable>condition</replaceable> ... </optional> THEN
-          <replaceable>handler_statements</replaceable>
+          <optional> <replaceable>handler_statements</replaceable> </optional>
       ... </optional>
 END;
 </synopsis>
@@ -2821,8 +2821,8 @@ END;
      abandoned, and control passes to the <literal>EXCEPTION</literal> list.
      The list is searched for the first <replaceable>condition</replaceable>
      matching the error that occurred.  If a match is found, the
-     corresponding <replaceable>handler_statements</replaceable> are
-     executed, and then control passes to the next statement after
+     corresponding <replaceable>handler_statements</replaceable>, if
+     specified are executed, and then control passes to the next statement after
      <literal>END</literal>.  If no match is found, the error propagates out
      as though the <literal>EXCEPTION</literal> clause were not there at all:
      the error can be caught by an enclosing block with

--Za4dOZB3PZqN3QEg--

--tDCxDAb1Q78I9qDG
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQIzBAABCgAdFiEEG72nH6vTowiyblFKnvQgOdbyQH0FAmbhOp0ACgkQnvQgOdby
QH1SEhAAmYzNnz2wSqllIxc1fCxRasljpHxNvsogBEsr1IFG4Rtdjg2C8BFTkbOu
4UqqcSSl5QF07jBiXPYsNA+w8El5isxYj1mXL9xwIDkTzt+3UrRYwZ6kkstZc9Qe
QmDXqF/Flyyv0DVwKNaajXNLy/cImmjMeyGe1OEoB2GUo5SSU4QqKvS/u04iHHED
V3yHSCRQ1AhS1MOSgv264vhY83bjsxnPPzU/LDGKH03frHg6/u0+B7CYlR/s6oRi
140lJBmwbQ1OyxNPREfdTfZeX+Di9MS8tBDkE6Z+6tsfn+BQEEiFkGfCz7dSd6HN
1hiupNTl80Y6OcVnx1bMjyip+usZgs25MFZVYR3j28wYgknN5EpZ3UiMDOXMVeo/
6NwJni2brhBQBRz/oVp4YwNo5E69lgFMrjtD44W4G+WpgZtHPE1i6kibLQLGXfIU
H0ZUWrhd6locYv12TAHsMJhaYGd7wrEZJBPXIDLs3HJyXzbJXfnv5O91SXEbp7XT
rWe5K56Fks3r/14Gml0XmAFsKNe7x9+EFXlNdLRarn2OQu7d1Qi6qeIBcrsct3H8
3zlhSW1fqVCTgPQ9MEnQIbwVuvL+1ucflCGwyXoGGcG7267yIxVoYSqjzbH/HhWN
67NtIeZa9TEJMafptIKrkwEqvpiV0wDV1ikxB+8QgNFybRBgq9g=
=x5Hy
-----END PGP SIGNATURE-----

--tDCxDAb1Q78I9qDG--