From d57c7a7c506276597af619bdb8c62fa5b592745a Mon Sep 17 00:00:00 2001
From: Andrew Dunstan <andrew@dunslane.net>
Date: Thu, 21 Sep 2017 19:02:23 -0400
Subject: Provide a test for variable existence in psql

"\if :{?variable_name}" will be translated to "\if TRUE" if the variable
exists and "\if FALSE" otherwise. Thus it will be possible to execute code
conditionally on the existence of the variable, regardless of its value.

Fabien Coelho, with some review by Robins Tharakan and some light text
editing by me.

Discussion: https://postgr.es/m/alpine.DEB.2.20.1708260835520.3627@lancre
---
 doc/src/sgml/ref/psql-ref.sgml | 10 ++++++++++
 1 file changed, 10 insertions(+)

(limited to 'doc/src')

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 60bafa81754..e7a3e17c67b 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -783,6 +783,10 @@ testdb=&gt;
     The forms <literal>:'<replaceable>variable_name</>'</literal> and
     <literal>:"<replaceable>variable_name</>"</literal> described there
     work as well.
+    The <literal>:{?<replaceable>variable_name</>}</> syntax allows
+    testing whether a variable is defined. It is substituted by
+    TRUE or FALSE.
+    Escaping the colon with a backslash protects it from substitution.
     </para>
 
     <para>
@@ -3938,6 +3942,12 @@ testdb=&gt; <userinput>INSERT INTO my_table VALUES (:'content');</userinput>
     can escape a colon with a backslash to protect it from substitution.
     </para>
 
+    <para>
+    The <literal>:{?<replaceable>name</>}</> special syntax returns TRUE
+    or FALSE depending on whether the variable exists or not, and is thus
+    always substituted, unless the colon is backslash-escaped.
+    </para>
+
     <para>
     The colon syntax for variables is standard <acronym>SQL</acronym> for
     embedded query languages, such as <application>ECPG</application>.
-- 
cgit v1.2.3