Skip to content

Commit 4833106

Browse files
masatakemasatake
committed
docs(man): add a page for GDScript parser
Signed-off-by: Masatake YAMATO <[email protected]>
1 parent 7e06c76 commit 4833106

File tree

3 files changed

+389
-0
lines changed

3 files changed

+389
-0
lines changed

‎docs/man/ctags-lang-gdscript.7.rst‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
.. _ctags-lang-gdscript(7):
2+
3+
==============================================================
4+
ctags-lang-gdscript
5+
==============================================================
6+
7+
Random notes about tagging GDScript source code with Universal Ctags
8+
9+
:Version: 5.9.0
10+
:Manual group: Universal Ctags
11+
:Manual section: 7
12+
13+
SYNOPSIS
14+
--------
15+
| **ctags** ... --languages=+GDScript ...
16+
| **ctags** ... --language-force=GDScript ...
17+
| **ctags** ... --map-GDScript=+.gd ...
18+
19+
DESCRIPTION
20+
-----------
21+
This man page gathers random notes about tagging GDScript source code
22+
with Universal Ctags.
23+
24+
Storing Annotations
25+
-------------------
26+
Like the Python parser storing decorations to ``decorations`` field,
27+
the GDScript parser stores annotations
28+
starting from `@` to the language specific field, ``annotations``.
29+
Though the field is enabled explicitly in following examples, the
30+
field is enabled by default.
31+
32+
"input.gd"
33+
34+
.. code-block:: GDScript
35+
36+
@export
37+
var s = "Hello"
38+
39+
@master
40+
func f(msg):
41+
print(msg)
42+
43+
"output.tags"
44+
with "--options=NONE --sort=no --fields-GDScript=+{annotations} -o - input.gd"
45+
46+
.. code-block:: tags
47+
48+
s input.gd /^var s = "Hello"$/;" v annotations:export
49+
f input.gd /^func f(msg):$/;" m annotations:master
50+
51+
Extracting `func`
52+
-----------------
53+
A language object defined with `func` keyword is tagged with ``method`` kind.
54+
Like annotations, the parser stores keywords modifying `func` like `static` to
55+
the ``annotations`` field.
56+
57+
"input.gd"
58+
59+
.. code-block:: GDScript
60+
61+
func f(x):
62+
return x
63+
64+
static func f_s(x):
65+
reutrn x
66+
67+
remote func f_r(x):
68+
return x
69+
70+
71+
"output.tags"
72+
with "--options=NONE --sort=no --fields=+K --fields-GDScript=+{annotations} -o - input.gd"
73+
74+
.. code-block:: tags
75+
76+
f input.gd /^func f(x):$/;" method
77+
f_s input.gd /^static func f_s(x):$/;" method annotations:static
78+
f_r input.gd /^remote func f_r(x):$/;" method annotations:remote
79+
80+
Tagging implicitly defined classes
81+
----------------------------------
82+
"A file is a class!" in GDScript. A class is implicitly
83+
defined. Functions, variables, constants, and signals are parts of the
84+
class though the class is unnamed by default.
85+
86+
If the language specific extra, ``implicitClass``, is enabled, the
87+
parser makes a anonymous tag for the class. The parser fills the scope
88+
fields of the tags for all language objects defined in the file with
89+
the anonymous tag.
90+
91+
Let's see an example demonstrating the effect of the extra.
92+
93+
Turning off the extra:
94+
95+
"input.gd"
96+
97+
.. code-block:: GDScript
98+
99+
func f(x):
100+
return x
101+
102+
"output.tags"
103+
with "--options=NONE --fields=+KZ --extras-GDScript=-{implicitClass} -o - input.gd"
104+
105+
.. code-block:: tags
106+
107+
f input.gd /^func f(x):$/;" method
108+
109+
Turning on the extra:
110+
111+
"input.gd"
112+
113+
.. code-block:: GDScript
114+
115+
func g(x):
116+
return x
117+
118+
"output.tags"
119+
with "--options=NONE --fields=+KZ --extras-GDScript=+{implicitClass} -o - input.gd"
120+
121+
.. code-block:: tags
122+
123+
anon_class_84011bee0100 input.gd /^func g(x):$/;" class
124+
g input.gd /^func g(x):$/;" method scope:class:anon_class_84011bee0100
125+
126+
Tagging the name specified with `class_name`
127+
---------------------------------------------
128+
`class_name` is a keyword for giving a name to the implicitly defined
129+
class. If ``implicitClass`` is turned off, the parser just extract
130+
the name coming after the keyword with ``class`` kind. If
131+
``implicitClass`` is turned on, the parser converts the anonymous tag
132+
to a non-anonymous tag with the specified name. When converting,
133+
the parser also updates scope fields of the other tags in the file.
134+
135+
Turning off the extra:
136+
137+
"input.gd"
138+
139+
.. code-block:: GDScript
140+
141+
class_name c
142+
143+
func f(x):
144+
return x
145+
146+
"output.tags"
147+
with "--options=NONE --fields=+KZ --extras-GDScript=-{implicitClass} -o - input.gd"
148+
149+
.. code-block:: tags
150+
151+
c input.gd /^class_name c$/;" class
152+
f input.gd /^func f(x):$/;" method
153+
154+
Turning on the extra:
155+
156+
"input.gd"
157+
158+
.. code-block:: GDScript
159+
160+
class_name C
161+
func g(x):
162+
return x
163+
164+
"output.tags"
165+
with "--options=NONE --fields=+KZ --extras-GDScript=+{implicitClass} -o - input.gd"
166+
167+
.. code-block:: tags
168+
169+
C input.gd /^class_name C$/;" class
170+
g input.gd /^func g(x):$/;" method scope:class:C
171+
172+
Filling ``inherits`` field
173+
--------------------------
174+
`extends` keyword specifies the super class for the implicitly defined class.
175+
If `implicitClass` extra is turned on, the parser fills ``inherits`` field
176+
of the tag for the implicitly defined class with the name of super class.
177+
178+
"input.gd"
179+
180+
.. code-block:: GDScript
181+
182+
extends B
183+
class_name C
184+
185+
"output.tags"
186+
with "--options=NONE --fields=+Ki --extras-GDScript=+{implicitClass} -o - input.gd"
187+
188+
.. code-block:: tags
189+
190+
C input.gd /^class_name C$/;" class inherits:B
191+
192+
SEE ALSO
193+
--------
194+
:ref:`ctags(1) <ctags(1)>`

‎man/Makefile.am‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ GEN_IN_MAN_FILES = \
2727
ctags-client-tools.7 \
2828
ctags-faq.7 \
2929
\
30+
ctags-lang-gdscript.7 \
3031
ctags-lang-iPythonCell.7 \
3132
ctags-lang-julia.7 \
3233
ctags-lang-python.7 \

‎man/ctags-lang-gdscript.7.rst.in‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
.. _ctags-lang-gdscript(7):
2+
3+
==============================================================
4+
ctags-lang-gdscript
5+
==============================================================
6+
--------------------------------------------------------------------
7+
Random notes about tagging GDScript source code with Universal Ctags
8+
--------------------------------------------------------------------
9+
:Version: @VERSION@
10+
:Manual group: Universal Ctags
11+
:Manual section: 7
12+
13+
SYNOPSIS
14+
--------
15+
| **@CTAGS_NAME_EXECUTABLE@** ... --languages=+GDScript ...
16+
| **@CTAGS_NAME_EXECUTABLE@** ... --language-force=GDScript ...
17+
| **@CTAGS_NAME_EXECUTABLE@** ... --map-GDScript=+.gd ...
18+
19+
DESCRIPTION
20+
-----------
21+
This man page gathers random notes about tagging GDScript source code
22+
with Universal Ctags.
23+
24+
Storing Annotations
25+
-------------------
26+
Like the Python parser storing decorations to ``decorations`` field,
27+
the GDScript parser stores annotations
28+
starting from `@` to the language specific field, ``annotations``.
29+
Though the field is enabled explicitly in following examples, the
30+
field is enabled by default.
31+
32+
"input.gd"
33+
34+
.. code-block:: GDScript
35+
36+
@export
37+
var s = "Hello"
38+
39+
@master
40+
func f(msg):
41+
print(msg)
42+
43+
"output.tags"
44+
with "--options=NONE --sort=no --fields-GDScript=+{annotations} -o - input.gd"
45+
46+
.. code-block:: tags
47+
48+
s input.gd /^var s = "Hello"$/;" v annotations:export
49+
f input.gd /^func f(msg):$/;" m annotations:master
50+
51+
Extracting `func`
52+
-----------------
53+
A language object defined with `func` keyword is tagged with ``method`` kind.
54+
Like annotations, the parser stores keywords modifying `func` like `static` to
55+
the ``annotations`` field.
56+
57+
"input.gd"
58+
59+
.. code-block:: GDScript
60+
61+
func f(x):
62+
return x
63+
64+
static func f_s(x):
65+
reutrn x
66+
67+
remote func f_r(x):
68+
return x
69+
70+
71+
"output.tags"
72+
with "--options=NONE --sort=no --fields=+K --fields-GDScript=+{annotations} -o - input.gd"
73+
74+
.. code-block:: tags
75+
76+
f input.gd /^func f(x):$/;" method
77+
f_s input.gd /^static func f_s(x):$/;" method annotations:static
78+
f_r input.gd /^remote func f_r(x):$/;" method annotations:remote
79+
80+
Tagging implicitly defined classes
81+
----------------------------------
82+
"A file is a class!" in GDScript. A class is implicitly
83+
defined. Functions, variables, constants, and signals are parts of the
84+
class though the class is unnamed by default.
85+
86+
If the language specific extra, ``implicitClass``, is enabled, the
87+
parser makes a anonymous tag for the class. The parser fills the scope
88+
fields of the tags for all language objects defined in the file with
89+
the anonymous tag.
90+
91+
Let's see an example demonstrating the effect of the extra.
92+
93+
Turning off the extra:
94+
95+
"input.gd"
96+
97+
.. code-block:: GDScript
98+
99+
func f(x):
100+
return x
101+
102+
"output.tags"
103+
with "--options=NONE --fields=+KZ --extras-GDScript=-{implicitClass} -o - input.gd"
104+
105+
.. code-block:: tags
106+
107+
f input.gd /^func f(x):$/;" method
108+
109+
Turning on the extra:
110+
111+
"input.gd"
112+
113+
.. code-block:: GDScript
114+
115+
func g(x):
116+
return x
117+
118+
"output.tags"
119+
with "--options=NONE --fields=+KZ --extras-GDScript=+{implicitClass} -o - input.gd"
120+
121+
.. code-block:: tags
122+
123+
anon_class_84011bee0100 input.gd /^func g(x):$/;" class
124+
g input.gd /^func g(x):$/;" method scope:class:anon_class_84011bee0100
125+
126+
Tagging the name specified with `class_name`
127+
---------------------------------------------
128+
`class_name` is a keyword for giving a name to the implicitly defined
129+
class. If ``implicitClass`` is turned off, the parser just extract
130+
the name coming after the keyword with ``class`` kind. If
131+
``implicitClass`` is turned on, the parser converts the anonymous tag
132+
to a non-anonymous tag with the specified name. When converting,
133+
the parser also updates scope fields of the other tags in the file.
134+
135+
Turning off the extra:
136+
137+
"input.gd"
138+
139+
.. code-block:: GDScript
140+
141+
class_name c
142+
143+
func f(x):
144+
return x
145+
146+
"output.tags"
147+
with "--options=NONE --fields=+KZ --extras-GDScript=-{implicitClass} -o - input.gd"
148+
149+
.. code-block:: tags
150+
151+
c input.gd /^class_name c$/;" class
152+
f input.gd /^func f(x):$/;" method
153+
154+
Turning on the extra:
155+
156+
"input.gd"
157+
158+
.. code-block:: GDScript
159+
160+
class_name C
161+
func g(x):
162+
return x
163+
164+
"output.tags"
165+
with "--options=NONE --fields=+KZ --extras-GDScript=+{implicitClass} -o - input.gd"
166+
167+
.. code-block:: tags
168+
169+
C input.gd /^class_name C$/;" class
170+
g input.gd /^func g(x):$/;" method scope:class:C
171+
172+
Filling ``inherits`` field
173+
--------------------------
174+
`extends` keyword specifies the super class for the implicitly defined class.
175+
If `implicitClass` extra is turned on, the parser fills ``inherits`` field
176+
of the tag for the implicitly defined class with the name of super class.
177+
178+
"input.gd"
179+
180+
.. code-block:: GDScript
181+
182+
extends B
183+
class_name C
184+
185+
"output.tags"
186+
with "--options=NONE --fields=+Ki --extras-GDScript=+{implicitClass} -o - input.gd"
187+
188+
.. code-block:: tags
189+
190+
C input.gd /^class_name C$/;" class inherits:B
191+
192+
SEE ALSO
193+
--------
194+
ctags(1)

0 commit comments

Comments
 (0)