From: Chapman Flack <chap@anastigmatix.net>
Subject: Documentation about PL transforms
To: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
Message-ID: <61FDBCFE.3090800@anastigmatix.net>
Date: Fri, 4 Feb 2022 18:55:42 -0500
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101
 Thunderbird/38.7.0
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
Archived-At: 
 <https://www.postgresql.org/message-id/61FDBCFE.3090800%40anastigmatix.net>
Precedence: bulk

Hi,

It looks to me as if the transforms feature for PLs was added in
cac7658, and support was added to plperl and plpython at that time,
with documentation added for CREATE FUNCTION, CREATE/DROP TRANSFORM,
and the catalogs, but nothing was added at that time to plhandler.sgml
to clarify that a PL handler itself must add code to look up and apply
such transforms, or nothing happens.

Without that information, a reader not in the know (it happened to me)
could get the idea from the CREATE TRANSFORM docs that the support
is more general than it is, and an incoming argument could already
contain the 'internal' something-specific-to-the-language-implementation
returned by a specified transform. (Which does lead to follow-on questions
like "who says an arbitrary language implementation's transform result
could be safely represented in an mmgr-managed argument list?"—it really
does make better sense upon learning the PL handler has to do the deed.
But I haven't spotted any place where the docs *say* that.)

I'm thinking plhandler.sgml is the only place that really needs to be
said; readers looking up CREATE TRANSFORM and using an existing PL that
supports it don't need to know how the sausage is made. (Maybe it is
worth mentioning there, though, that it isn't possible to develop
transforms for an arbitrary PL unless that PL applies transforms.)

I noticed the CREATE TRANSFORM docs show the argument list as
(argument_type [, ...]) even though check_transform_function will reject
any argument list of length other than 1 or with type other than internal.
Is that an overly-generic way to show the syntax, or is that a style
with precedent elsewhere in the docs? (I checked a couple obvious places
like CREATE OPERATOR, CREATE FUNCTION, CREATE TYPE but did not see similar
examples).

As long as a PL handler has the sole responsibility for invoking
its transforms, I wonder if it would make sense to allow a PL to
define what its transforms should look like, maybe replacing
check_transform_function with a transform_validator for the PL.
I'm not proposing such a patch here, but I am willing to prepare
one for plhandler.sgml and maybe pltemplate.c documenting the current
situation, if nobody tells me I'm wrong about something here.

Regards,
-Chap