Debian Codegraph @

blueprintcompiler/language/gobject_signal.py

raw
1 # gobject_signal.py
2 #
3 # Copyright 2022 James Westman <[email protected]>
4 #
5 # This file is free software; you can redistribute it and/or modify it
6 # under the terms of the GNU Lesser General Public License as
7 # published by the Free Software Foundation; either version 3 of the
8 # License, or (at your option) any later version.
9 #
10 # This file is distributed in the hope that it will be useful, but
11 # WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 # Lesser General Public License for more details.
14 #
15 # You should have received a copy of the GNU Lesser General Public
16 # License along with this program. If not, see <http://www.gnu.org/licenses/>.
17 #
18 # SPDX-License-Identifier: LGPL-3.0-or-later
19
20 import typing as T
21
22 from .common import *
23 from .contexts import ScopeCtx
24 from .gobject_object import Object
25
26
27 class SignalFlag(AstNode):
28 grammar = AnyOf(
29 UseExact("flag", "swapped"),
30 UseExact("flag", "not-swapped"),
31 UseExact("flag", "after"),
32 )
33
34 @property
35 def flag(self) -> str:
36 return self.tokens["flag"]
37
38 @validate()
39 def unique(self):
40 self.validate_unique_in_parent(
41 f"Duplicate flag '{self.flag}'", lambda x: x.flag == self.flag
42 )
43
44 @validate()
45 def swapped_exclusive(self):
46 if self.flag in ["swapped", "not-swapped"]:
47 self.validate_unique_in_parent(
48 "'swapped' and 'not-swapped' flags cannot be used together",
49 lambda x: x.flag in ["swapped", "not-swapped"],
50 )
51
52 @validate()
53 def swapped_unnecessary(self):
54 if self.flag == "not-swapped" and self.parent.object_id is None:
55 raise CompileWarning(
56 "'not-swapped' is the default for handlers that do not specify an object",
57 actions=[CodeAction("Remove 'not-swapped' flag", "")],
58 )
59 elif self.flag == "swapped" and self.parent.object_id is not None:
60 raise CompileWarning(
61 "'swapped' is the default for handlers that specify an object",
62 actions=[CodeAction("Remove 'swapped' flag", "")],
63 )
64
65 @docs()
66 def ref_docs(self):
67 return get_docs_section("Syntax Signal")
68
69
70 class Signal(AstNode):
71 grammar = Statement(
72 UseIdent("name"),
73 Optional(
74 [
75 "::",
76 UseIdent("detail_name").expected("a signal detail name"),
77 ]
78 ),
79 Keyword("=>"),
80 Mark("detail_start"),
81 Optional(["$", UseLiteral("extern", True)]),
82 UseIdent("handler").expected("the name of a function to handle the signal"),
83 Match("(").expected("argument list"),
84 Optional(UseIdent("object")).expected("object identifier"),
85 Match(")").expected(),
86 ZeroOrMore(SignalFlag),
87 Mark("detail_end"),
88 )
89
90 @property
91 def name(self) -> str:
92 return self.tokens["name"]
93
94 @property
95 def detail_name(self) -> T.Optional[str]:
96 return self.tokens["detail_name"]
97
98 @property
99 def full_name(self) -> str:
100 if self.detail_name is None:
101 return self.name
102 else:
103 return self.name + "::" + self.detail_name
104
105 @property
106 def handler(self) -> str:
107 return self.tokens["handler"]
108
109 @property
110 def object_id(self) -> T.Optional[str]:
111 return self.tokens["object"]
112
113 @property
114 def object(self) -> T.Optional[Object]:
115 return self.context[ScopeCtx].objects.get(self.object_id)
116
117 @property
118 def flags(self) -> T.List[SignalFlag]:
119 return self.children[SignalFlag]
120
121 # Returns True if the "swapped" flag is present, False if "not-swapped" is present, and None if neither are present.
122 # GtkBuilder's default if swapped is not specified is to not swap the arguments if no object is specified, and to
123 # swap them if an object is specified.
124 @property
125 def is_swapped(self) -> T.Optional[bool]:
126 for flag in self.flags:
127 if flag.flag == "swapped":
128 return True
129 elif flag.flag == "not-swapped":
130 return False
131 return None
132
133 @property
134 def is_after(self) -> bool:
135 return any(x.flag == "after" for x in self.flags)
136
137 @property
138 def gir_signal(self) -> T.Optional[gir.Signal]:
139 if self.gir_class is not None and not isinstance(self.gir_class, ExternType):
140 return self.gir_class.signals.get(self.tokens["name"])
141 else:
142 return None
143
144 @property
145 def gir_class(self):
146 return self.parent.parent.gir_class
147
148 @property
149 def document_symbol(self) -> DocumentSymbol:
150 detail = self.ranges["detail_start", "detail_end"]
151 return DocumentSymbol(
152 self.full_name,
153 SymbolKind.Event,
154 self.range,
155 self.group.tokens["name"].range,
156 detail.text if detail is not None else None,
157 )
158
159 def get_reference(self, idx: int) -> T.Optional[LocationLink]:
160 if self.object_id is not None and idx in self.group.tokens["object"].range:
161 obj = self.context[ScopeCtx].objects.get(self.object_id)
162 if obj is not None:
163 return LocationLink(
164 self.group.tokens["object"].range, obj.range, obj.ranges["id"]
165 )
166
167 return None
168
169 @docs("object")
170 def object_docs(self):
171 if self.object is not None:
172 return f"```\n{self.object.signature}\n```"
173 else:
174 return None
175
176 @validate("handler")
177 def old_extern(self):
178 if not self.tokens["extern"]:
179 if self.handler is not None:
180 raise UpgradeWarning(
181 "Use the '$' extern syntax introduced in blueprint 0.8.0",
182 actions=[CodeAction("Use '$' syntax", "$" + self.handler)],
183 )
184
185 @validate("name")
186 def signal_exists(self):
187 if self.gir_class is None or self.gir_class.incomplete:
188 # Objects that we have no gir data on should not be validated
189 # This happens for classes defined by the app itself
190 return
191
192 if self.gir_signal is None:
193 raise CompileError(
194 f"Class {self.gir_class.full_name} does not contain a signal called {self.tokens['name']}",
195 did_you_mean=(self.tokens["name"], self.gir_class.signals.keys()),
196 )
197
198 @validate("object")
199 def object_exists(self):
200 object_id = self.tokens["object"]
201 if object_id is None:
202 return
203
204 if self.context[ScopeCtx].objects.get(object_id) is None:
205 raise CompileError(f"Could not find object with ID '{object_id}'")
206
207 @validate("name")
208 def deprecated(self) -> None:
209 if self.gir_signal is not None and self.gir_signal.deprecated:
210 hints = []
211 if self.gir_signal.deprecated_doc:
212 hints.append(self.gir_signal.deprecated_doc)
213 raise DeprecatedWarning(
214 f"{self.gir_signal.signature} is deprecated",
215 hints=hints,
216 )
217
218 @docs("name")
219 def signal_docs(self):
220 if self.gir_signal is not None:
221 return self.gir_signal.doc
222
223 @docs("detail_name")
224 def detail_docs(self):
225 if self.name == "notify":
226 if self.gir_class is not None and not isinstance(
227 self.gir_class, ExternType
228 ):
229 prop = self.gir_class.properties.get(self.tokens["detail_name"])
230 if prop is not None:
231 return prop.doc
232
233 @docs("=>")
234 def ref_docs(self):
235 return get_docs_section("Syntax Signal")
236
237
238 @decompiler("signal")
239 def decompile_signal(
240 ctx: DecompileCtx, gir, name, handler, swapped=None, after="false", object=None
241 ):
242 object_name = object or ""
243
244 if object_name == ctx.template_class:
245 object_name = "template"
246
247 name = name.replace("_", "-")
248 line = f"{name} => ${handler}({object_name})"
249
250 if decompile.truthy(swapped):
251 if not object_name:
252 line += " swapped"
253 elif swapped is not None:
254 if object_name:
255 line += " not-swapped"
256
257 if decompile.truthy(after):
258 line += " after"
259
260 line += ";"
261 ctx.print(line)
262 return gir