plpgsql-trigger.html: Format TG_ variables as table (patch)
Started by Christoph Bergover 3 years ago12 messages
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
Attachments:
0001-plpgsql-trigger.html-Format-TG_-variables-as-table.patchtext/x-diff; charset=us-asciiDownload
From 708c05277e6e2a93e9ceb1e52fda5991cef8b545 Mon Sep 17 00:00:00 2001
From: Christoph Berg <myon@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
Re: plpgsql-trigger.html: Format TG_ variables as table (patch)
On 30.08.22 15:16, Christoph Berg wrote:
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.
I find the new version even harder to read. The catalog_table_entry
stuff doesn't really make sense here, since what you have before is
already a definition list, and afterwards you have the same, just marked
up "incorrectly".
We could move the data type in the <term>, similar to how you did it in
your patch.
I agree the whitespace layout is weird, but that's a problem of the
website CSS stylesheet. I think it looks a bit better with the local
stylesheet, but that can all be tweaked.
Re: plpgsql-trigger.html: Format TG_ variables as table (patch)
On 31 Aug 2022, at 11:35, Peter Eisentraut <peter.eisentraut@enterprisedb.com> wrote:
On 30.08.22 15:16, Christoph Berg wrote:
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.I find the new version even harder to read. The catalog_table_entry stuff doesn't really make sense here, since what you have before is already a definition list, and afterwards you have the same, just marked up "incorrectly".
If we change variable lists they should get their own formatting in the xsl
and css stylesheets.
We could move the data type in the <term>, similar to how you did it in your patch.
That will make this look different from the trigger variable lists for other
languages (which typically don't list type), but I think it's worth it to avoid
the boilerplate which is a bit annoying.
Another thing we should change while there (but it's not directly related to
this patch) is that we document TG_RELID and $TG_relid as "object ID" but
TD["relid"] and $_TD->{relid} as "OID". Punctuation of item descriptions is
also not consistent.
--
Daniel Gustafsson https://vmware.com/
Re: plpgsql-trigger.html: Format TG_ variables as table (patch)
Re: Peter Eisentraut
I find the new version even harder to read. The catalog_table_entry stuff
doesn't really make sense here, since what you have before is already a
definition list, and afterwards you have the same, just marked up
"incorrectly".
Fair enough. For comparison, this is what yesterday's patch looked
like: https://www.df7cb.de/s/2022-08-31.115813.w5UvAS.png
We could move the data type in the <term>, similar to how you did it in your
patch.
The new version of the patch just moves up the data types, and removes
the extra clutter from the beginnings of each description:
https://www.df7cb.de/s/2022-08-31.115857.LkkKl8.png
Christoph
Attachments:
0001-plpgsql-trigger.html-Use-more-concise-wording-for-TG.patchtext/x-diff; charset=us-asciiDownload
From 61bcef4b3a0a8a17c86114ef9747c6e793a5b48f Mon Sep 17 00:00:00 2001
From: Christoph Berg <myon@debian.org>
Date: Wed, 31 Aug 2022 11:52:50 +0200
Subject: [PATCH] plpgsql-trigger.html: Use more concise wording for TG_
variables
To improve readability of the TG_ variables definition list, this moves
the datatypes up to the defined term to avoid having each entry start
with "Data type", and removes some more redundant clutter ("Variable
holding...") from the descriptions that didn't carry any information.
---
doc/src/sgml/plpgsql.sgml | 48 +++++++++++++++++++--------------------
1 file changed, 24 insertions(+), 24 deletions(-)
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index cf387dfc3f..b862af35a7 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -4032,10 +4032,10 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
<variablelist>
<varlistentry>
- <term><varname>NEW</varname></term>
+ <term><varname>NEW</varname> (record)</term>
<listitem>
<para>
- Data type <type>RECORD</type>; variable holding the new
+ 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.
@@ -4044,10 +4044,10 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>OLD</varname></term>
+ <term><varname>OLD</varname> (record)</term>
<listitem>
<para>
- Data type <type>RECORD</type>; variable holding the old
+ 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.
@@ -4056,20 +4056,20 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_NAME</varname></term>
+ <term><varname>TG_NAME</varname> (name)</term>
<listitem>
<para>
- Data type <type>name</type>; variable that contains the name of the trigger actually
+ name of the trigger actually
fired.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_WHEN</varname></term>
+ <term><varname>TG_WHEN</varname> (text)</term>
<listitem>
<para>
- Data type <type>text</type>; a string of
+ string
<literal>BEFORE</literal>, <literal>AFTER</literal>, or
<literal>INSTEAD OF</literal>, depending on the trigger's definition.
</para>
@@ -4077,10 +4077,10 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_LEVEL</varname></term>
+ <term><varname>TG_LEVEL</varname> (text)</term>
<listitem>
<para>
- Data type <type>text</type>; a string of either
+ string
<literal>ROW</literal> or <literal>STATEMENT</literal>
depending on the trigger's definition.
</para>
@@ -4088,10 +4088,10 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_OP</varname></term>
+ <term><varname>TG_OP</varname> (text)</term>
<listitem>
<para>
- Data type <type>text</type>; a string of
+ string
<literal>INSERT</literal>, <literal>UPDATE</literal>,
<literal>DELETE</literal>, or <literal>TRUNCATE</literal>
telling for which operation the trigger was fired.
@@ -4100,20 +4100,20 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_RELID</varname></term>
+ <term><varname>TG_RELID</varname> (oid, references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)</term>
<listitem>
<para>
- Data type <type>oid</type>; the object ID of the table that caused the
+ object ID of the table that caused the
trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_RELNAME</varname></term>
+ <term><varname>TG_RELNAME</varname> (name)</term>
<listitem>
<para>
- Data type <type>name</type>; the name of the table that caused the trigger
+ 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>
@@ -4121,40 +4121,40 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_TABLE_NAME</varname></term>
+ <term><varname>TG_TABLE_NAME</varname> (name)</term>
<listitem>
<para>
- Data type <type>name</type>; the name of the table that
+ name of the table that
caused the trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_TABLE_SCHEMA</varname></term>
+ <term><varname>TG_TABLE_SCHEMA</varname> (name)</term>
<listitem>
<para>
- Data type <type>name</type>; the name of the schema of the
+ name of the schema of the
table that caused the trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_NARGS</varname></term>
+ <term><varname>TG_NARGS</varname> (integer)</term>
<listitem>
<para>
- Data type <type>integer</type>; the number of arguments given to the trigger
+ number of arguments given to the trigger
function in the <command>CREATE TRIGGER</command> statement.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_ARGV[]</varname></term>
+ <term><varname>TG_ARGV[]</varname> (text[])</term>
<listitem>
<para>
- Data type array of <type>text</type>; the arguments from
+ 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>)
--
2.35.1
Re: plpgsql-trigger.html: Format TG_ variables as table (patch)
Re: To Peter Eisentraut
The new version of the patch just moves up the data types, and removes
the extra clutter from the beginnings of each description:
The last version had the brackets in TG_ARGV[] (text[]) duplicated.
Christoph
Attachments:
0001-plpgsql-trigger.html-Use-more-concise-wording-for-TG.patchtext/x-diff; charset=us-asciiDownload
From 1355794d56919a015bd1528f62428beaab0a681b Mon Sep 17 00:00:00 2001
From: Christoph Berg <myon@debian.org>
Date: Wed, 31 Aug 2022 11:52:50 +0200
Subject: [PATCH] plpgsql-trigger.html: Use more concise wording for TG_
variables
To improve readability of the TG_ variables definition list, this moves
the datatypes up to the defined term to avoid having each entry start
with "Data type", and removes some more redundant clutter ("Variable
holding...") from the descriptions that didn't carry any information.
---
doc/src/sgml/plpgsql.sgml | 48 +++++++++++++++++++--------------------
1 file changed, 24 insertions(+), 24 deletions(-)
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index cf387dfc3f..13b2ab8829 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -4032,10 +4032,10 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
<variablelist>
<varlistentry>
- <term><varname>NEW</varname></term>
+ <term><varname>NEW</varname> (record)</term>
<listitem>
<para>
- Data type <type>RECORD</type>; variable holding the new
+ 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.
@@ -4044,10 +4044,10 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>OLD</varname></term>
+ <term><varname>OLD</varname> (record)</term>
<listitem>
<para>
- Data type <type>RECORD</type>; variable holding the old
+ 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.
@@ -4056,20 +4056,20 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_NAME</varname></term>
+ <term><varname>TG_NAME</varname> (name)</term>
<listitem>
<para>
- Data type <type>name</type>; variable that contains the name of the trigger actually
+ name of the trigger actually
fired.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_WHEN</varname></term>
+ <term><varname>TG_WHEN</varname> (text)</term>
<listitem>
<para>
- Data type <type>text</type>; a string of
+ string
<literal>BEFORE</literal>, <literal>AFTER</literal>, or
<literal>INSTEAD OF</literal>, depending on the trigger's definition.
</para>
@@ -4077,10 +4077,10 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_LEVEL</varname></term>
+ <term><varname>TG_LEVEL</varname> (text)</term>
<listitem>
<para>
- Data type <type>text</type>; a string of either
+ string
<literal>ROW</literal> or <literal>STATEMENT</literal>
depending on the trigger's definition.
</para>
@@ -4088,10 +4088,10 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_OP</varname></term>
+ <term><varname>TG_OP</varname> (text)</term>
<listitem>
<para>
- Data type <type>text</type>; a string of
+ string
<literal>INSERT</literal>, <literal>UPDATE</literal>,
<literal>DELETE</literal>, or <literal>TRUNCATE</literal>
telling for which operation the trigger was fired.
@@ -4100,20 +4100,20 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_RELID</varname></term>
+ <term><varname>TG_RELID</varname> (oid, references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)</term>
<listitem>
<para>
- Data type <type>oid</type>; the object ID of the table that caused the
+ object ID of the table that caused the
trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_RELNAME</varname></term>
+ <term><varname>TG_RELNAME</varname> (name)</term>
<listitem>
<para>
- Data type <type>name</type>; the name of the table that caused the trigger
+ 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>
@@ -4121,40 +4121,40 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_TABLE_NAME</varname></term>
+ <term><varname>TG_TABLE_NAME</varname> (name)</term>
<listitem>
<para>
- Data type <type>name</type>; the name of the table that
+ name of the table that
caused the trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_TABLE_SCHEMA</varname></term>
+ <term><varname>TG_TABLE_SCHEMA</varname> (name)</term>
<listitem>
<para>
- Data type <type>name</type>; the name of the schema of the
+ name of the schema of the
table that caused the trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_NARGS</varname></term>
+ <term><varname>TG_NARGS</varname> (integer)</term>
<listitem>
<para>
- Data type <type>integer</type>; the number of arguments given to the trigger
+ number of arguments given to the trigger
function in the <command>CREATE TRIGGER</command> statement.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_ARGV[]</varname></term>
+ <term><varname>TG_ARGV</varname> (text[])</term>
<listitem>
<para>
- Data type array of <type>text</type>; the arguments from
+ 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>)
--
2.35.1
Re: plpgsql-trigger.html: Format TG_ variables as table (patch)
On 31 Aug 2022, at 13:55, Christoph Berg <myon@debian.org> wrote:
Re: To Peter Eisentraut
The new version of the patch just moves up the data types, and removes
the extra clutter from the beginnings of each description:The last version had the brackets in TG_ARGV[] (text[]) duplicated.
This, and the other string variables, now reads a bit strange IMO:
- Data type <type>text</type>; a string of
+ string
<literal>INSERT</literal>, <literal>UPDATE</literal>,
<literal>DELETE</literal>, or <literal>TRUNCATE</literal>Wouldn't it be better with "string containing <literal>INSERT.." or something
similar?
--
Daniel Gustafsson https://vmware.com/
Re: plpgsql-trigger.html: Format TG_ variables as table (patch)
Re: Daniel Gustafsson
This, and the other string variables, now reads a bit strange IMO:
- Data type <type>text</type>; a string of + string <literal>INSERT</literal>, <literal>UPDATE</literal>, <literal>DELETE</literal>, or <literal>TRUNCATE</literal>Wouldn't it be better with "string containing <literal>INSERT.." or something
similar?
Right, that felt strange to me as well, but I couldn't think of
something better.
"string containing" is again pretty boilerplatish, how about just
"contains"?
Christoph
Attachments:
0001-plpgsql-trigger.html-Use-more-concise-wording-for-TG.patchtext/x-diff; charset=us-asciiDownload
From b675a9e63ac663817cf90ca3aee2acf398b3fa97 Mon Sep 17 00:00:00 2001
From: Christoph Berg <myon@debian.org>
Date: Wed, 31 Aug 2022 11:52:50 +0200
Subject: [PATCH] plpgsql-trigger.html: Use more concise wording for TG_
variables
To improve readability of the TG_ variables definition list, this moves
the datatypes up to the defined term to avoid having each entry start
with "Data type", and removes some more redundant clutter ("Variable
holding...") from the descriptions that didn't carry any information.
---
doc/src/sgml/plpgsql.sgml | 52 +++++++++++++++++++--------------------
1 file changed, 26 insertions(+), 26 deletions(-)
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index cf387dfc3f..b5cfe3c63d 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -4032,10 +4032,10 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
<variablelist>
<varlistentry>
- <term><varname>NEW</varname></term>
+ <term><varname>NEW</varname> (record)</term>
<listitem>
<para>
- Data type <type>RECORD</type>; variable holding the new
+ 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.
@@ -4044,10 +4044,10 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>OLD</varname></term>
+ <term><varname>OLD</varname> (record)</term>
<listitem>
<para>
- Data type <type>RECORD</type>; variable holding the old
+ 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.
@@ -4056,20 +4056,20 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_NAME</varname></term>
+ <term><varname>TG_NAME</varname> (name)</term>
<listitem>
<para>
- Data type <type>name</type>; variable that contains the name of the trigger actually
+ name of the trigger actually
fired.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_WHEN</varname></term>
+ <term><varname>TG_WHEN</varname> (text)</term>
<listitem>
<para>
- Data type <type>text</type>; a string of
+ contains
<literal>BEFORE</literal>, <literal>AFTER</literal>, or
<literal>INSTEAD OF</literal>, depending on the trigger's definition.
</para>
@@ -4077,43 +4077,43 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_LEVEL</varname></term>
+ <term><varname>TG_LEVEL</varname> (text)</term>
<listitem>
<para>
- Data type <type>text</type>; a string of either
- <literal>ROW</literal> or <literal>STATEMENT</literal>
+ contains
+ <literal>ROW</literal> or <literal>STATEMENT</literal>,
depending on the trigger's definition.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_OP</varname></term>
+ <term><varname>TG_OP</varname> (text)</term>
<listitem>
<para>
- Data type <type>text</type>; a string of
+ contains
<literal>INSERT</literal>, <literal>UPDATE</literal>,
- <literal>DELETE</literal>, or <literal>TRUNCATE</literal>
+ <literal>DELETE</literal>, or <literal>TRUNCATE</literal>,
telling for which operation the trigger was fired.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_RELID</varname></term>
+ <term><varname>TG_RELID</varname> (oid, references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)</term>
<listitem>
<para>
- Data type <type>oid</type>; the object ID of the table that caused the
+ object ID of the table that caused the
trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_RELNAME</varname></term>
+ <term><varname>TG_RELNAME</varname> (name)</term>
<listitem>
<para>
- Data type <type>name</type>; the name of the table that caused the trigger
+ 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>
@@ -4121,40 +4121,40 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_TABLE_NAME</varname></term>
+ <term><varname>TG_TABLE_NAME</varname> (name)</term>
<listitem>
<para>
- Data type <type>name</type>; the name of the table that
+ name of the table that
caused the trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_TABLE_SCHEMA</varname></term>
+ <term><varname>TG_TABLE_SCHEMA</varname> (name)</term>
<listitem>
<para>
- Data type <type>name</type>; the name of the schema of the
+ name of the schema of the
table that caused the trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_NARGS</varname></term>
+ <term><varname>TG_NARGS</varname> (integer)</term>
<listitem>
<para>
- Data type <type>integer</type>; the number of arguments given to the trigger
+ number of arguments given to the trigger
function in the <command>CREATE TRIGGER</command> statement.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_ARGV[]</varname></term>
+ <term><varname>TG_ARGV</varname> (text[])</term>
<listitem>
<para>
- Data type array of <type>text</type>; the arguments from
+ 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>)
--
2.35.1
Re: plpgsql-trigger.html: Format TG_ variables as table (patch)
Re: To Daniel Gustafsson
"string containing" is again pretty boilerplatish, how about just
"contains"?
Actually, just omitting the whole prefix works best.
TG_WHEN (text)
BEFORE, AFTER, or INSTEAD OF, depending on the trigger's definition.
I also shortened some "name of table" to just "table". Since the data
type is "name", it's clear what "table" means.
Christoph
Attachments:
0001-plpgsql-trigger.html-Use-more-concise-wording-for-TG.patchtext/x-diff; charset=us-asciiDownload
From a281bbb3ba80e14645f83d464ca6df892a85c1bb Mon Sep 17 00:00:00 2001
From: Christoph Berg <myon@debian.org>
Date: Wed, 31 Aug 2022 11:52:50 +0200
Subject: [PATCH] plpgsql-trigger.html: Use more concise wording for TG_
variables
To improve readability of the TG_ variables definition list, this moves
the datatypes up to the defined term to avoid having each entry start
with "Data type", and removes some more redundant clutter ("Variable
holding...") from the descriptions that didn't carry any information.
---
doc/src/sgml/plpgsql.sgml | 52 +++++++++++++++++++--------------------
1 file changed, 26 insertions(+), 26 deletions(-)
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index cf387dfc3f..b5cfe3c63d 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -4032,10 +4032,10 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
<variablelist>
<varlistentry>
- <term><varname>NEW</varname></term>
+ <term><varname>NEW</varname> (record)</term>
<listitem>
<para>
- Data type <type>RECORD</type>; variable holding the new
+ 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.
@@ -4044,10 +4044,10 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>OLD</varname></term>
+ <term><varname>OLD</varname> (record)</term>
<listitem>
<para>
- Data type <type>RECORD</type>; variable holding the old
+ 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.
@@ -4056,20 +4056,20 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_NAME</varname></term>
+ <term><varname>TG_NAME</varname> (name)</term>
<listitem>
<para>
- Data type <type>name</type>; variable that contains the name of the trigger actually
+ name of the trigger actually
fired.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_WHEN</varname></term>
+ <term><varname>TG_WHEN</varname> (text)</term>
<listitem>
<para>
- Data type <type>text</type>; a string of
+ contains
<literal>BEFORE</literal>, <literal>AFTER</literal>, or
<literal>INSTEAD OF</literal>, depending on the trigger's definition.
</para>
@@ -4077,43 +4077,43 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_LEVEL</varname></term>
+ <term><varname>TG_LEVEL</varname> (text)</term>
<listitem>
<para>
- Data type <type>text</type>; a string of either
- <literal>ROW</literal> or <literal>STATEMENT</literal>
+ contains
+ <literal>ROW</literal> or <literal>STATEMENT</literal>,
depending on the trigger's definition.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_OP</varname></term>
+ <term><varname>TG_OP</varname> (text)</term>
<listitem>
<para>
- Data type <type>text</type>; a string of
+ contains
<literal>INSERT</literal>, <literal>UPDATE</literal>,
- <literal>DELETE</literal>, or <literal>TRUNCATE</literal>
+ <literal>DELETE</literal>, or <literal>TRUNCATE</literal>,
telling for which operation the trigger was fired.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_RELID</varname></term>
+ <term><varname>TG_RELID</varname> (oid, references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)</term>
<listitem>
<para>
- Data type <type>oid</type>; the object ID of the table that caused the
+ object ID of the table that caused the
trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_RELNAME</varname></term>
+ <term><varname>TG_RELNAME</varname> (name)</term>
<listitem>
<para>
- Data type <type>name</type>; the name of the table that caused the trigger
+ 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>
@@ -4121,40 +4121,40 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_TABLE_NAME</varname></term>
+ <term><varname>TG_TABLE_NAME</varname> (name)</term>
<listitem>
<para>
- Data type <type>name</type>; the name of the table that
+ name of the table that
caused the trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_TABLE_SCHEMA</varname></term>
+ <term><varname>TG_TABLE_SCHEMA</varname> (name)</term>
<listitem>
<para>
- Data type <type>name</type>; the name of the schema of the
+ name of the schema of the
table that caused the trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_NARGS</varname></term>
+ <term><varname>TG_NARGS</varname> (integer)</term>
<listitem>
<para>
- Data type <type>integer</type>; the number of arguments given to the trigger
+ number of arguments given to the trigger
function in the <command>CREATE TRIGGER</command> statement.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_ARGV[]</varname></term>
+ <term><varname>TG_ARGV</varname> (text[])</term>
<listitem>
<para>
- Data type array of <type>text</type>; the arguments from
+ 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>)
--
2.35.1
Re: plpgsql-trigger.html: Format TG_ variables as table (patch)
Christoph Berg <myon@debian.org> writes:
Re: To Daniel Gustafsson
"string containing" is again pretty boilerplatish, how about just
"contains"?Actually, just omitting the whole prefix works best.
TG_WHEN (text)
BEFORE, AFTER, or INSTEAD OF, depending on the trigger's definition.
The attached patch does not reflect this, did you attach an old version?
I also shortened some "name of table" to just "table". Since the data
type is "name", it's clear what "table" means.
I think it reads better with the definite article and initial capital,
e.g. "The table that triggered ….".
<variablelist> <varlistentry> - <term><varname>NEW</varname></term> + <term><varname>NEW</varname> (record)</term>
The type names should still be wrapped in <type>, like they were before.
- ilmari
Re: plpgsql-trigger.html: Format TG_ variables as table (patch)
Re: Dagfinn Ilmari Mannsåker
Actually, just omitting the whole prefix works best.
TG_WHEN (text)
BEFORE, AFTER, or INSTEAD OF, depending on the trigger's definition.
The attached patch does not reflect this, did you attach an old version?
Forgot to git commit before exporting the patch, thanks for catching!
I also shortened some "name of table" to just "table". Since the data
type is "name", it's clear what "table" means.I think it reads better with the definite article and initial capital,
e.g. "The table that triggered ….".
Since that's not a complete sentence anyway, I think "The" isn't
necessary.
- <term><varname>NEW</varname></term> + <term><varname>NEW</varname> (record)</term>The type names should still be wrapped in <type>, like they were before.
Updated.
Thanks,
Christoph
Attachments:
0001-plpgsql-trigger.html-Use-more-concise-wording-for-TG.patchtext/x-diff; charset=us-asciiDownload
From 9cec9ece0751910f48d56c0f0e1ac5343f6686fa Mon Sep 17 00:00:00 2001
From: Christoph Berg <myon@debian.org>
Date: Wed, 31 Aug 2022 11:52:50 +0200
Subject: [PATCH] plpgsql-trigger.html: Use more concise wording for TG_
variables
To improve readability of the TG_ variables definition list, this moves
the datatypes up to the defined term to avoid having each entry start
with "Data type", and removes some more redundant clutter ("Variable
holding...") from the descriptions that didn't carry any information.
---
doc/src/sgml/plpgsql.sgml | 51 ++++++++++++++++++---------------------
1 file changed, 24 insertions(+), 27 deletions(-)
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index cf387dfc3f..985aa4d6a5 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -4032,10 +4032,10 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
<variablelist>
<varlistentry>
- <term><varname>NEW</varname></term>
+ <term><varname>NEW</varname> <type>record</type></term>
<listitem>
<para>
- Data type <type>RECORD</type>; variable holding the new
+ 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.
@@ -4044,10 +4044,10 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>OLD</varname></term>
+ <term><varname>OLD</varname> <type>record</type></term>
<listitem>
<para>
- Data type <type>RECORD</type>; variable holding the old
+ 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.
@@ -4056,20 +4056,19 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_NAME</varname></term>
+ <term><varname>TG_NAME</varname> <type>name</type></term>
<listitem>
<para>
- Data type <type>name</type>; variable that contains the name of the trigger actually
+ name of the trigger
fired.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_WHEN</varname></term>
+ <term><varname>TG_WHEN</varname> <type>text</type></term>
<listitem>
<para>
- Data type <type>text</type>; a string of
<literal>BEFORE</literal>, <literal>AFTER</literal>, or
<literal>INSTEAD OF</literal>, depending on the trigger's definition.
</para>
@@ -4077,43 +4076,41 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_LEVEL</varname></term>
+ <term><varname>TG_LEVEL</varname> <type>text</type></term>
<listitem>
<para>
- Data type <type>text</type>; a string of either
- <literal>ROW</literal> or <literal>STATEMENT</literal>
+ <literal>ROW</literal> or <literal>STATEMENT</literal>,
depending on the trigger's definition.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_OP</varname></term>
+ <term><varname>TG_OP</varname> <type>text</type></term>
<listitem>
<para>
- Data type <type>text</type>; a string of
+ operation for which the trigger was fired:
<literal>INSERT</literal>, <literal>UPDATE</literal>,
- <literal>DELETE</literal>, or <literal>TRUNCATE</literal>
- telling for which operation the trigger was fired.
+ <literal>DELETE</literal>, or <literal>TRUNCATE</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_RELID</varname></term>
+ <term><varname>TG_RELID</varname> <type>oid</type> (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)</term>
<listitem>
<para>
- Data type <type>oid</type>; the object ID of the table that caused the
+ object ID of the table that caused the
trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_RELNAME</varname></term>
+ <term><varname>TG_RELNAME</varname> <type>name</type></term>
<listitem>
<para>
- Data type <type>name</type>; the name of the table that caused the trigger
+ 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>
@@ -4121,40 +4118,40 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_TABLE_NAME</varname></term>
+ <term><varname>TG_TABLE_NAME</varname> <type>name</type></term>
<listitem>
<para>
- Data type <type>name</type>; the name of the table that
+ table that
caused the trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_TABLE_SCHEMA</varname></term>
+ <term><varname>TG_TABLE_SCHEMA</varname> <type>name</type></term>
<listitem>
<para>
- Data type <type>name</type>; the name of the schema of the
+ schema of the
table that caused the trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_NARGS</varname></term>
+ <term><varname>TG_NARGS</varname> <type>integer</type></term>
<listitem>
<para>
- Data type <type>integer</type>; the number of arguments given to the trigger
+ number of arguments given to the trigger
function in the <command>CREATE TRIGGER</command> statement.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_ARGV[]</varname></term>
+ <term><varname>TG_ARGV</varname> <type>text[]</type></term>
<listitem>
<para>
- Data type array of <type>text</type>; the arguments from
+ 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>)
--
2.35.1
Re: plpgsql-trigger.html: Format TG_ variables as table (patch)
On 1 Sep 2022, at 15:07, Christoph Berg <myon@debian.org> wrote:
Re: Dagfinn Ilmari Mannsåker
I also shortened some "name of table" to just "table". Since the data
type is "name", it's clear what "table" means.I think it reads better with the definite article and initial capital,
e.g. "The table that triggered ….".Since that's not a complete sentence anyway, I think "The" isn't
necessary.
Looking at the docs for the other PLs there is quite a lot of variation on how
we spell this, fixing that inconsistency is for another patch though.
The patch missed to update the corresponding list for TG_ event trigger vars,
fixed in the attached.
--
Daniel Gustafsson https://vmware.com/
Attachments:
v2-0001-doc-Use-more-concise-wording-for-pl-pgSQL-TG_-var.patchapplication/octet-stream; name=v2-0001-doc-Use-more-concise-wording-for-pl-pgSQL-TG_-var.patch; x-unix-mode=0644Download
From 25b8be9f1f3ad499364be2a7ca506e6a26074fb4 Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <daniel@yesql.se>
Date: Fri, 2 Sep 2022 11:07:54 +0200
Subject: [PATCH v2] doc: Use more concise wording for pl/pgSQL TG_ variables
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
To improve readability of the TG_ variables definition lists, this moves
the datatypes up to the defined term to avoid having each entry start
with "Data type". This also removes redundant wording that that didn't
carry any information from the descriptions.
Author: Christoph Berg <myon@debian.org>
Reviewed-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
Discussion: https://postgr.es/m/Yw4Noe3A2s87A0qq@msg.df7cb.de
---
doc/src/sgml/plpgsql.sgml | 61 ++++++++++++++++++---------------------
1 file changed, 28 insertions(+), 33 deletions(-)
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index cf387dfc3f..86bc32ae88 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -4032,10 +4032,10 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
<variablelist>
<varlistentry>
- <term><varname>NEW</varname></term>
+ <term><varname>NEW</varname> <type>record</type></term>
<listitem>
<para>
- Data type <type>RECORD</type>; variable holding the new
+ 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.
@@ -4044,10 +4044,10 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>OLD</varname></term>
+ <term><varname>OLD</varname> <type>record</type></term>
<listitem>
<para>
- Data type <type>RECORD</type>; variable holding the old
+ 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.
@@ -4056,20 +4056,19 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_NAME</varname></term>
+ <term><varname>TG_NAME</varname> <type>name</type></term>
<listitem>
<para>
- Data type <type>name</type>; variable that contains the name of the trigger actually
+ name of the trigger
fired.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_WHEN</varname></term>
+ <term><varname>TG_WHEN</varname> <type>text</type></term>
<listitem>
<para>
- Data type <type>text</type>; a string of
<literal>BEFORE</literal>, <literal>AFTER</literal>, or
<literal>INSTEAD OF</literal>, depending on the trigger's definition.
</para>
@@ -4077,43 +4076,41 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_LEVEL</varname></term>
+ <term><varname>TG_LEVEL</varname> <type>text</type></term>
<listitem>
<para>
- Data type <type>text</type>; a string of either
- <literal>ROW</literal> or <literal>STATEMENT</literal>
+ <literal>ROW</literal> or <literal>STATEMENT</literal>,
depending on the trigger's definition.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_OP</varname></term>
+ <term><varname>TG_OP</varname> <type>text</type></term>
<listitem>
<para>
- Data type <type>text</type>; a string of
+ operation for which the trigger was fired:
<literal>INSERT</literal>, <literal>UPDATE</literal>,
- <literal>DELETE</literal>, or <literal>TRUNCATE</literal>
- telling for which operation the trigger was fired.
+ <literal>DELETE</literal>, or <literal>TRUNCATE</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_RELID</varname></term>
+ <term><varname>TG_RELID</varname> <type>oid</type> (references <link linkend="catalog-pg-class"><structname>pg_class</structname></link>.<structfield>oid</structfield>)</term>
<listitem>
<para>
- Data type <type>oid</type>; the object ID of the table that caused the
+ object ID of the table that caused the
trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_RELNAME</varname></term>
+ <term><varname>TG_RELNAME</varname> <type>name</type></term>
<listitem>
<para>
- Data type <type>name</type>; the name of the table that caused the trigger
+ 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>
@@ -4121,40 +4118,40 @@ ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <repl
</varlistentry>
<varlistentry>
- <term><varname>TG_TABLE_NAME</varname></term>
+ <term><varname>TG_TABLE_NAME</varname> <type>name</type></term>
<listitem>
<para>
- Data type <type>name</type>; the name of the table that
+ table that
caused the trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_TABLE_SCHEMA</varname></term>
+ <term><varname>TG_TABLE_SCHEMA</varname> <type>name</type></term>
<listitem>
<para>
- Data type <type>name</type>; the name of the schema of the
+ schema of the
table that caused the trigger invocation.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_NARGS</varname></term>
+ <term><varname>TG_NARGS</varname> <type>integer</type></term>
<listitem>
<para>
- Data type <type>integer</type>; the number of arguments given to the trigger
+ number of arguments given to the trigger
function in the <command>CREATE TRIGGER</command> statement.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_ARGV[]</varname></term>
+ <term><varname>TG_ARGV</varname> <type>text[]</type></term>
<listitem>
<para>
- Data type array of <type>text</type>; the arguments from
+ 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>)
@@ -4656,21 +4653,19 @@ CREATE TRIGGER emp_audit_del
<variablelist>
<varlistentry>
- <term><varname>TG_EVENT</varname></term>
+ <term><varname>TG_EVENT</varname> <type>text</type></term>
<listitem>
<para>
- Data type <type>text</type>; a string representing the event the
- trigger is fired for.
+ event the trigger is fired for.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>TG_TAG</varname></term>
+ <term><varname>TG_TAG</varname> <type>text</type></term>
<listitem>
<para>
- Data type <type>text</type>; variable that contains the command tag
- for which the trigger is fired.
+ command tag for which the trigger is fired.
</para>
</listitem>
</varlistentry>
--
2.32.1 (Apple Git-133)
Re: plpgsql-trigger.html: Format TG_ variables as table (patch)
On 2 Sep 2022, at 11:19, Daniel Gustafsson <daniel@yesql.se> wrote:
The patch missed to update the corresponding list for TG_ event trigger vars,
fixed in the attached.
I took another look at this, and pushed it with a few small tweaks. Thanks!
--
Daniel Gustafsson https://vmware.com/