Hi,
I found the list of TG_ variables on
https://www.postgresql.org/docs/current/plpgsql-trigger.html#PLPGSQL-DML-TRIGGER
hard to read for several reasons: too much whitespace, all the lines
start with "Data type", and even after that, the actual content is
hiding behind some extra "variable that..." boilerplate.
The attached patch formats the list as a table, and removes some of
the clutter from the text.
I reused the catalog_table_entry table machinery, that is probably not
quite the correct thing, but I didn't find a better variant, and the
result looks ok.
Thanks to ilmari for the idea and some initial reviews.
Christoph
>From 708c05277e6e2a93e9ceb1e52fda5991cef8b545 Mon Sep 17 00:00:00 2001
From: Christoph Berg <m...@debian.org>
Date: Tue, 30 Aug 2022 15:09:39 +0200
Subject: [PATCH] plpgsql-trigger.html: Format TG_ variables as table
Format list as table, and remove redundant clutter ("viarable
holding...") that made the list hard to skim
---
doc/src/sgml/plpgsql.sgml | 221 ++++++++++++++++++++------------------
1 file changed, 114 insertions(+), 107 deletions(-)
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index cf387dfc3f..c73e81eff0 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -4028,142 +4028,149 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
<para>
When a <application>PL/pgSQL</application> function is called as a
trigger, several special variables are created automatically in the
- top-level block. They are:
+ top-level block. They are listed in <xref linkend="trigger-tg-variables"/>.
+ </para>
- <variablelist>
- <varlistentry>
- <term><varname>NEW</varname></term>
- <listitem>
+ <table id="trigger-tg-variables">
+ <title><structname>TG_</structname> special trigger function variables</title>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="catalog_table_entry"><para role="column_definition">
+ Variable Type
+ </para>
<para>
- Data type <type>RECORD</type>; variable holding the new
- database row for <command>INSERT</command>/<command>UPDATE</command> operations in row-level
- triggers. This variable is null in statement-level triggers
- and for <command>DELETE</command> operations.
+ Description
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="catalog_table_entry"><para role="column_definition">
+ <structfield>NEW</structfield> <type>record</type>
</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>OLD</varname></term>
- <listitem>
<para>
- Data type <type>RECORD</type>; variable holding the old
- database row for <command>UPDATE</command>/<command>DELETE</command> operations in row-level
+ new database row for <command>INSERT</command>/<command>UPDATE</command> operations in row-level
triggers. This variable is null in statement-level triggers
- and for <command>INSERT</command> operations.
- </para>
- </listitem>
- </varlistentry>
+ and for <command>DELETE</command> operations.
+ </para></entry>
+ </row>
- <varlistentry>
- <term><varname>TG_NAME</varname></term>
- <listitem>
+ <row>
+ <entry role="catalog_table_entry"><para role="column_definition">
+ <structfield>OLD</structfield> <type>record</type>
+ </para>
<para>
- Data type <type>name</type>; variable that contains the name of the trigger actually
- fired.
+ old database row for <command>UPDATE</command>/<command>DELETE</command> operations in row-level
+ triggers. This variable is null in statement-level triggers and for <command>INSERT</command>
+ operations.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="catalog_table_entry"><para role="column_definition">
+ <structfield>TG_NAME</structfield> <type>name</type>
</para>
- </listitem>
- </varlistentry>
+ <para>
+ name of the trigger fired.
+ </para></entry>
+ </row>
- <varlistentry>
- <term><varname>TG_WHEN</varname></term>
- <listitem>
+ <row>
+ <entry role="catalog_table_entry"><para role="column_definition">
+ <structfield>TG_WHEN</structfield> <type>text</type>
+ </para>
<para>
- Data type <type>text</type>; a string of
- <literal>BEFORE</literal>, <literal>AFTER</literal>, or
+ string <literal>BEFORE</literal>, <literal>AFTER</literal>, or
<literal>INSTEAD OF</literal>, depending on the trigger's definition.
- </para>
- </listitem>
- </varlistentry>
+ </para></entry>
+ </row>
- <varlistentry>
- <term><varname>TG_LEVEL</varname></term>
- <listitem>
+ <row>
+ <entry role="catalog_table_entry"><para role="column_definition">
+ <structfield>TG_LEVEL</structfield> <type>text</type>
+ </para>
<para>
- Data type <type>text</type>; a string of either
- <literal>ROW</literal> or <literal>STATEMENT</literal>
- depending on the trigger's definition.
+ string <literal>ROW</literal> or <literal>STATEMENT</literal> depending
+ on the trigger's definition.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="catalog_table_entry"><para role="column_definition">
+ <structfield>TG_OP</structfield> <type>text</type>
</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>TG_OP</varname></term>
- <listitem>
<para>
- Data type <type>text</type>; a string of
- <literal>INSERT</literal>, <literal>UPDATE</literal>,
+ string <literal>INSERT</literal>, <literal>UPDATE</literal>,
<literal>DELETE</literal>, or <literal>TRUNCATE</literal>
telling for which operation the trigger was fired.
- </para>
- </listitem>
- </varlistentry>
+ </para></entry>
+ </row>
- <varlistentry>
- <term><varname>TG_RELID</varname></term>
- <listitem>
- <para>
- Data type <type>oid</type>; the object ID of the table that caused the
- trigger invocation.
+ <row>
+ <entry role="catalog_table_entry"><para role="column_definition">
+ <structfield>TG_RELID</structfield> <type>oid</type>
+ (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)
</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>TG_RELNAME</varname></term>
- <listitem>
<para>
- Data type <type>name</type>; the name of the table that caused the trigger
- invocation. This is now deprecated, and could disappear in a future
- release. Use <literal>TG_TABLE_NAME</literal> instead.
- </para>
- </listitem>
- </varlistentry>
+ object ID of the table that caused the trigger invocation.
+ </para></entry>
+ </row>
- <varlistentry>
- <term><varname>TG_TABLE_NAME</varname></term>
- <listitem>
- <para>
- Data type <type>name</type>; the name of the table that
- caused the trigger invocation.
+ <row>
+ <entry role="catalog_table_entry"><para role="column_definition">
+ <structfield>TG_RELNAME</structfield> <type>name</type>
</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>TG_TABLE_SCHEMA</varname></term>
- <listitem>
<para>
- Data type <type>name</type>; the name of the schema of the
- table that caused the trigger invocation.
+ name of the table that caused the trigger invocation. This is now
+ deprecated, and could disappear in a future release. Use
+ <literal>TG_TABLE_NAME</literal> instead.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="catalog_table_entry"><para role="column_definition">
+ <structfield>TG_TABLE_NAME</structfield> <type>name</type>
</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>TG_NARGS</varname></term>
- <listitem>
<para>
- Data type <type>integer</type>; the number of arguments given to the trigger
- function in the <command>CREATE TRIGGER</command> statement.
+ name of the table that caused the trigger invocation.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="catalog_table_entry"><para role="column_definition">
+ <structfield>TG_TABLE_SCHEMA</structfield> <type>name</type>
</para>
- </listitem>
- </varlistentry>
+ <para>
+ name of the schema of the table that caused the trigger invocation.
+ </para></entry>
+ </row>
- <varlistentry>
- <term><varname>TG_ARGV[]</varname></term>
- <listitem>
+ <row>
+ <entry role="catalog_table_entry"><para role="column_definition">
+ <structfield>TG_NARGS</structfield> <type>integer</type>
+ </para>
<para>
- Data type array of <type>text</type>; the arguments from
- the <command>CREATE TRIGGER</command> statement.
- The index counts from 0. Invalid
- indexes (less than 0 or greater than or equal to <varname>tg_nargs</varname>)
- result in a null value.
+ number of arguments given to the trigger function in the
+ <command>CREATE TRIGGER</command> statement.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="catalog_table_entry"><para role="column_definition">
+ <structfield>TG_ARGV</structfield> <type>text[]</type>
</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
+ <para>
+ arguments from the <command>CREATE TRIGGER</command> statement. The
+ index counts from 0. Invalid indexes (less than 0 or greater than or
+ equal to <varname>tg_nargs</varname>) result in a null value.
+ </para></entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
<para>
A trigger function must return either <symbol>NULL</symbol> or a
--
2.35.1
