CTAGS-LANG-SQL(7)

💖 ctags-lang-sql — the SQL parser glow-up 💖

okay bestie, welcome to ctags-lang-sql(7), aka the man page of the SQL parser for Universal Ctags. this is the part of the Universal Ctags manual where the SQL parser gets its moment, and honestly? it ate. 💅

---

✨ NAME ✨

ctags-lang-sql — The man page of the SQL parser for Universal Ctags

---

🌸 SYNOPSIS 🌸

ctags ... [--extras={guest}] --languages=+SQL ...

---

🦋 DESCRIPTION 🦋

so the SQL parser? it's not just one dialect, it's giving variety. it supports various SQL dialects, and PostgreSQL is one of them. 👑

and here's the tea: PostgreSQL lets you write user-defined functions in other languages (we call those procedural languages) besides SQL and C [PL]. iconic behavior.

the SQL parser will make tags for language objects inside those user-defined functions written in procedural languages — but ONLY if the guest extra is enabled. no extra, no guest tags, periodt.

how does it know which language to hand off to? it looks for a token coming after the LANGUAGE keyword in the source code, and that token picks the proper guest parser. like a lil bouncer checking IDs. 🙈

... LANGUAGE plpythonu AS '... user-defined function ' ...
... AS $$ user-defined function $$ LANGUAGE plv8 ...

in the examples up there, 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 it goes looking for a ctags parser. so 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, easy. but ctags doesn't have a parser named v8 — no cap, that's just not a thing. HOWEVER, the JavaScript parser in ctags has v8 as an alias. so ctags can run the JavaScript parser as the guest parser for plv8. slay. 🔥

---

🎀 EXAMPLES 🎀

tagging code including a user-defined function in a string literal [GH3006] 💫

"input.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

fun1    input.sql       /^CREATE OR REPLACE FUNCTION fun1() RETURNS VARCHAR AS '$/;"    f       typeref:typename:VARCHAR
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"

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

fun2    input.sql       /^CREATE OR REPLACE FUNCTION fun2() RETURNS VARCHAR LANGUAGE plpgsql AS $\$$/;" f       typeref:typename:VARCHAR
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 🧚

-- 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

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. poor lil guy. 😭

heads up bestie: that's a real known bug, not a vibe. if your guest parser starts acting weird around escaped quotes, that's why. 🫶

---

🌈 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>

---

okay that's the whole page, you made it to the end, so proud of you 🥹🫶 this was Universal Ctags, version 6.2.1, and that's the CTAGS-LANG-SQL(7) manual — go tag something iconic, bestie. 💖✨🎀