Re: Undocumented optionality of handler_statements

On Friday, September 13, 2024, Philipp Salvisberg <
philipp(dot)salvisberg(at)gmail(dot)com> wrote:

> >> 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.
>
> I agree. Expressing the optionality in the synopsis/EBNF is the
> better way. Therefore I suggest adding the optionality also for the
> "statements" in this section (43.6.8. Trapping Errors). And of course,
> the optionality should be added for all related "statements" in other
> sections such as
>

This concept is already covered by:

https://www.postgresql.org/docs/16/plpgsql-statements.html#PLPGSQL-STATEMENTS-NULL

These placeholders indicate where a set of statements goes. That set is
not optional. The set can be empty - as documented at the link above -
though IMO it is better to encourage representing the empty set as the
one-element set with the NULL no-op statement. I would make all our
examples use NULL and the reader, if finding an example of an empty-set in
the wild, can be pointed to the above section for confirmation that it is
not a bug.

David J.