1 # This file is part of NIT ( http://www.nitlanguage.org ).
3 # Licensed under the Apache License, Version 2.0 (the "License");
4 # you may not use this file except in compliance with the License.
5 # You may obtain a copy of the License at
7 # http://www.apache.org/licenses/LICENSE-2.0
9 # Unless required by applicable law or agreed to in writing, software
10 # distributed under the License is distributed on an "AS IS" BASIS,
11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 # See the License for the specific language governing permissions and
13 # limitations under the License.
15 # Graphs and basic entities.
19 import more_collections
24 # All the nodes in the graph.
25 var all_nodes
: SimpleCollection[NeoNode] = new Array[NeoNode]
27 # All the edges in the graph.
28 var all_edges
: SimpleCollection[NeoEdge] = new Array[NeoEdge]
30 # Add a relationship between two nodes.
32 # Parameters are the same than for the constructor of `NeoEdge`.
33 fun add_edge
(from
: NeoNode, rel_type
: String, to
: NeoNode) do
34 all_edges
.add
(new NeoEdge(from
, rel_type
, to
))
40 # Here is the usual steps to build a project graph:
43 # <li>Instantiate `ProjectGraph` by giving the name that will label the project.</li>
44 # <li>For each compound:
46 # <li>Instantiate the compound.</li>
47 # <li>Provide all the related data.</li>
48 # <li>Call the `put_in_graph` method of the compound.</li>
50 # <li>Call the `add_global_modules` method of the project’s graph (defined in
51 # the `module_compound` module). This permits to take global classes into
52 # account correctly.</li>
53 # <li>Call the `put_edges` method of the project’s graph.</li>
59 var project_name
: String
61 # The node reperesenting the project.
63 # Once the project’s graph is initialized, this node must not be edited.
64 var project
= new NeoNode
66 # Entities by `model_id`.
67 var by_id
: Map[String, Entity] = new HashMap[String, Entity]
69 # Namespaces by `full_name`.
70 var namespaces
: Map[String, Namespace] = new HashMap[String, Namespace]
72 # For each `ClassCompound` in the graph, the mapping between its `model_id` and its namespace.
74 # Defaults to the root namespace. An entry is added each time
75 # `Namespace.declare_class` is called.
77 # Note: In the graph, there is no direct link between a namespace and a
78 # class. It is the role of a module (created internally by a `FileCompound`)
79 # to link a class with its namespace. So, this collection is used by modules
80 # to know which class in a file belong to their related namespace. It is
81 # also used by `FileCompound` to detect classes in the root namespace.
82 var class_to_ns
: Map[String, Namespace] is noinit
84 # Initialize a new project graph using the specified project name.
86 # The specified name will label all nodes of the project’s graph.
88 project
.labels
.add
(project_name
)
89 project
.labels
.add
("MEntity")
90 project
.labels
.add
("MProject")
91 project
["name"] = project_name
92 all_nodes
.add
(project
)
94 var root
= new RootNamespace(self)
97 class_to_ns
= new DefaultMap[String, Namespace](root
)
100 # Request to all nodes in the graph to add their related edges.
102 # Note: For the rare cases where a node need to wait the `put_edges` to add
103 # an implicit node, this method makes sure to call the `put_edges` method
104 # of the newly added nodes only after processing all the nodes that was
108 add_edge
(project
, "ROOT", by_id
[""])
109 for n
in all_nodes
do
119 # In practice, this is the base class of every node in a `ProjectGraph`.
120 abstract class Entity
123 # Graph that will embed the entity.
124 var graph
: ProjectGraph
126 # ID of the entity in the model.
128 # Is empty for entities without an ID.
129 var model_id
: String = "" is writable
131 # The full (qualified) name, as presented by the original model.
133 # Fully independant of `name`. By default, equals to `""` for the root
135 var full_name
: nullable String = null is writable
137 # Associated documentation.
138 var doc
= new JsonArray is writable
141 self.labels
.add
(graph
.project_name
)
142 self.labels
.add
("MEntity")
145 # The short (unqualified) name.
146 fun name
=(name
: String) do
150 # The short (unqualified) name.
152 var name
= self["name"]
153 assert name
isa String
157 # Include the documentation of `self` in the graph.
158 protected fun set_mdoc
do
162 # The namespace separator of Nit/C++.
164 # Used to join two or more names when we need to work around some
165 # limitations of the Nit model.
166 fun ns_separator
: String do return "::"
168 # Set the location of the entity in the source code.
169 fun location
=(location
: nullable Location) do
170 self["location"] = location
173 # Get the location of the entity in the source code.
174 fun location
: nullable Location do
175 return self["location"].as(nullable Location)
178 # Put the entity in the graph.
180 # Called by the loader when it has finished to read the entity.
182 if doc
.length
> 0 then
185 graph
.all_nodes
.add
(self)
186 if model_id
!= "" then graph
.by_id
[model_id
] = self
189 # Put the related edges in the graph.
191 # This method is called on each node by `ProjectGraph.put_edges`.
193 # Note: Even at this step, the entity may modify its own attributes and
194 # inner entities’ ones because some values are only known once the entity
195 # know its relationships with the rest of the graph.
199 # An entity whose the location is mandatory.
200 abstract class CodeBlock
204 self["location"] = new Location
207 redef fun location
=(location
: nullable Location) do
208 if location
== null then
218 # Usually corresponds to a `<compounddef>` element in of the XML output of
220 abstract class Compound
223 # Set the declared visibility (the proctection) of the compound.
224 fun visibility
=(visibility
: String) do
225 self["visibility"] = visibility
228 # Set the specific kind of the compound.
229 fun kind
=(kind
: String) do
233 # Declare an inner namespace.
235 # Note: Althought Doxygen indicates that the name is optional,
236 # declarations with an empty name are not supported yet, except for the root
237 # namespace. For the root namespace, both arguments are empty.
241 # * `id`: `model_id` of the inner namespace. May be empty.
242 # * `full_name`: qualified name of the inner namespace. Use an empty name
243 # for the root namespace.
244 fun declare_namespace
(id
: String, full_name
: String) do end
246 # Declare an inner class.
248 # Note: Althought Doxygen indicates that both arguments are optional,
249 # declarations with an empty ID are not supported yet.
253 # * `id`: `model_id` of the inner class.
254 # * `name`: short name of the inner class.
255 # * `prot`: visibility (proctection).
256 fun declare_class
(id
: String, name
: String, prot
: String) do end
258 # Declare a base compound (usually, a base class).
262 # * `id`: `model_id` of the base compound. May be empty.
263 # * `full_name`: qualified name of the base compound. May be empty.
264 # * `prot`: visibility (proctection) of the relationship.
265 # * `virt`: level of virtuality of the relationship.
266 fun declare_super
(id
: String, full_name
: String, prot
: String,
270 # An unrecognized compound.
272 # Used to simplify the handling of ignored entities.
273 class UnknownCompound
276 redef fun put_in_graph
do end
277 redef fun put_edges
do end
282 # Corresponds to a group in Nit.
286 # The inner namespaces.
287 var inner_namespaces
: SimpleCollection[NamespaceRef] = new Array[NamespaceRef]
291 self.labels
.add
("MGroup")
294 redef fun declare_namespace
(id
: String, full_name
: String) do
295 inner_namespaces
.add
new NamespaceRef(id
, full_name
)
298 redef fun declare_class
(id
, name
, prot
) do
299 assert not id
.is_empty
else
300 sys
.stderr
.write
"Inner class declarations without ID are not yet supported.\n"
302 graph
.class_to_ns
[id
] = self
305 redef fun put_in_graph
do
307 var full_name
= self.full_name
308 if full_name
isa String then graph
.namespaces
[full_name
] = self
311 redef fun put_edges
do
313 graph
.add_edge
(self, "PROJECT", graph
.project
)
314 for ns
in inner_namespaces
do
315 var node
= ns
.seek_in
(graph
)
316 graph
.add_edge
(node
, "PARENT", self)
317 graph
.add_edge
(self, "NESTS", node
)
322 # A reference to a namespace.
324 # The `model_id` of the target.
326 # Empty when unknown or for the root namespace.
329 # The `full_name` of the target.
331 # Empty only for the root namespace.
332 var full_name
: String
334 # Look for the targeted namespace in the specified graph.
335 fun seek_in
(graph
: ProjectGraph): Namespace do
336 var ns_compound
: Namespace
338 if model_id
.is_empty
and not full_name
.is_empty
then
339 # ID unspecified. => We have to look by name
340 assert graph
.namespaces
.has_key
(full_name
) else
341 sys
.stderr
.write
"Namespace `{full_name}` not found."
343 ns_compound
= graph
.namespaces
[full_name
]
345 ns_compound
= graph
.by_id
[model_id
].as(Namespace)
351 # The root namespace of a `ProjectGraph`.
353 # This the only entity in the graph whose `model_id` is really `""`.
354 # Added automatically at the initialization of a `ProjectGraph`.
361 name
= graph
.project_name