pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedFrom: 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
Date: Wed, 11 Sep 2024 15:37:17 +0900
Message-ID: <ZuE6ndanu0Z_9NWM@paquier.xyz> (raw)
In-Reply-To: <D88C77BC-7C03-4802-B1C3-B6BB83437184@gmail.com>
References: <172165655256.710.2097726158572647813@wrigleys.postgresql.org>
<Zp7tqLSTbBaBTUlP@paquier.xyz>
<D88C77BC-7C03-4802-B1C3-B6BB83437184@gmail.com>
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
Attachments:
[text/x-diff] doc-plpgsql-error.patch (1.5K, ../ZuE6ndanu0Z_9NWM@paquier.xyz/2-doc-plpgsql-error.patch)
download | inline diff:
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
[application/pgp-signature] signature.asc (832B, ../ZuE6ndanu0Z_9NWM@paquier.xyz/3-signature.asc)
download
view thread (9+ messages) latest in thread
Message-ID: <ZuE6ndanu0Z_9NWM@paquier.xyz>
Permalink: ../ZuE6ndanu0Z_9NWM@paquier.xyz/
Also on: postgresql.org/message-id/ZuE6ndanu0Z_9NWM@paquier.xyz
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: michael@paquier.xyz, philipp.salvisberg@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: Undocumented optionality of handler_statements
In-Reply-To: <ZuE6ndanu0Z_9NWM@paquier.xyz>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox