1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
.. _ctags-lang-sql(7):
==============================================================
ctags-lang-sql
==============================================================
-------------------------------------------------------------------
The man page of the SQL parser for Universal Ctags
-------------------------------------------------------------------
:Version: @VERSION@
:Manual group: Universal Ctags
:Manual section: 7
SYNOPSIS
--------
| **@CTAGS_NAME_EXECUTABLE@** ... [--extras={guest}] --languages=+SQL ...
DESCRIPTION
-----------
The SQL parser supports various SQL dialects. PostgreSQL is one of them.
PostgreSQL allows user-defined functions to be written in other
languages (*procedural languages*) besides SQL and C [PL]_.
The SQL parser makes tags for language objects in the user-defined
functions written in the procedural languages if the ``guest`` extra
is enabled.
The SQL parser looks for a token coming after ``LANGUAGE`` keyword in
the source code to choose a proper guest parser.
.. code-block:: SQL
... LANGUAGE plpythonu AS '... user-defined function ' ...
... AS $$ user-defined function $$ LANGUAGE plv8 ...
In the above examples, ``plpythonu`` and ``plv8`` are the names of
procedural languages. The SQL parser trims `pl` at the start and `u`
at the end of the name before finding a ctags parser. For
``plpythonu`` and ``plv8``, the SQL parser extracts ``python`` and
``v8`` as the candidates of guest parsers.
For ``plpythonu``, ctags can run its Python parser. ctags doesn't
have a parser named ``v8``. However, the JavaScript parser in ctags has
``v8`` as an alias. So ctags can run the JavaScript parser as the
guest parser for ``plv8``.
EXAMPLES
--------
tagging code including a user-defined function in a string literal [GH3006]_:
"input.sql"
.. code-block:: SQL
CREATE OR REPLACE FUNCTION fun1() RETURNS VARCHAR AS '
DECLARE
test1_var1 VARCHAR(64) := $$ABC$$;
test1_var2 VARCHAR(64) := $xyz$XYZ$xyz$;
test1_var3 INTEGER := 1;
BEGIN
RETURN TO_CHAR(test_var3, ''000'') || test1_var1 || test1_var2;
END;
' LANGUAGE plpgsql;
"output.tags"
with "--options=NONE -o - --sort=no --extras=+{guest} input.sql"
.. code-block:: tags
fun1 input.sql /^CREATE OR REPLACE FUNCTION fun1() RETURNS VARCHAR AS '$/;" f
test1_var1 input.sql /^ test1_var1 VARCHAR(64) := $$ABC$$;$/;" v
test1_var2 input.sql /^ test1_var2 VARCHAR(64) := $xyz$XYZ$xyz$;$/;" v
test1_var3 input.sql /^ test1_var3 INTEGER := 1;$/;" v
tagging code including a user-defined function in a dollar quote [GH3006]_:
"input.sql"
.. code-block:: SQL
CREATE OR REPLACE FUNCTION fun2() RETURNS VARCHAR LANGUAGE plpgsql AS $$
DECLARE
test2_var1 VARCHAR(64) := 'ABC2';
test2_var2 VARCHAR(64) := 'XYZ2';
test2_var3 INTEGER := 2;
BEGIN
RETURN TO_CHAR(test2_var3, '000') || test2_var1 || test2_var2;
END;
$$;
"output.tags"
with "--options=NONE -o - --sort=no --extras=+{guest} input.sql"
.. code-block:: tags
fun2 input.sql /^CREATE OR REPLACE FUNCTION fun2() RETURNS VARCHAR LANGUAGE plpgsql AS $\$$/;" f
test2_var1 input.sql /^ test2_var1 VARCHAR(64) := 'ABC2';$/;" v
test2_var2 input.sql /^ test2_var2 VARCHAR(64) := 'XYZ2';$/;" v
test2_var3 input.sql /^ test2_var3 INTEGER := 2;$/;" v
tagging code including a user-defined written in JavaScript:
.. code-block:: SQL
-- Derived from https://github.com/plv8/plv8/blob/r3.0alpha/sql/plv8.sql
CREATE FUNCTION test(keys text[], vals text[]) RETURNS text AS
$$
var o = {};
for (var i = 0; i < keys.length; i++)
o[keys[i]] = vals[i];
return JSON.stringify(o);
$$
LANGUAGE plv8 IMMUTABLE STRICT;
"output.tags"
with "--options=NONE -o - --sort=no --extras=+{guest} input.sql"
.. code-block:: tags
test input.sql /^CREATE FUNCTION test(keys text[], vals text[]) RETURNS text AS$/;" f
o input.sql /^ var o = {};$/;" v
KNOWN BUGS
----------
Escape sequences (`''`) in a string literal may make a guest parser confused.
SEE ALSO
--------
ctags(1), ctags-client-tools(7)
REFERENCES
----------
.. [PL] PostgreSQL 9.5.25 Documentation, "Chapter 39. Procedural Languages", https://www.postgresql.org/docs/9.5/xplang.html
.. [GH3006] @bagl's comment submitted to https://github.com/universal-ctags/ctags/issues/3006
|
