Coverage for pyVHDLModel/Instantiation.py: 98%

1# ==================================================================================================================== # 

2# __ ___ _ ____ _ __ __ _ _ # 

3# _ __ _ \ \ / / | | | _ \| | | \/ | ___ __| | ___| | # 

4# | '_ \| | | \ \ / /| |_| | | | | | | |\/| |/ _ \ / _` |/ _ \ | # 

5# | |_) | |_| |\ V / | _ | |_| | |___| | | | (_) | (_| | __/ | # 

6# | .__/ \__, | \_/ |_| |_|____/|_____|_| |_|\___/ \__,_|\___|_| # 

7# |_| |___/ # 

8# ==================================================================================================================== # 

9# Authors: # 

10# Patrick Lehmann # 

11# # 

12# License: # 

13# ==================================================================================================================== # 

14# Copyright 2017-2026 Patrick Lehmann - Boetzingen, Germany # 

15# Copyright 2016-2017 Patrick Lehmann - Dresden, Germany # 

16# # 

17# Licensed under the Apache License, Version 2.0 (the "License"); # 

18# you may not use this file except in compliance with the License. # 

19# You may obtain a copy of the License at # 

20# # 

21# http://www.apache.org/licenses/LICENSE-2.0 # 

22# # 

23# Unless required by applicable law or agreed to in writing, software # 

24# distributed under the License is distributed on an "AS IS" BASIS, # 

25# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 

26# See the License for the specific language governing permissions and # 

27# limitations under the License. # 

28# # 

29# SPDX-License-Identifier: Apache-2.0 # 

30# ==================================================================================================================== # 

31# 

32""" 

33This module contains parts of an abstract document language model for VHDL. 

34 

35Instantiations of packages, procedures, functions and protected types. 

36""" 

37from __future__ import annotations 

38 

39from typing import TYPE_CHECKING, Iterable, Optional as Nullable 

40 

41from pyTooling.Decorators import export, readonly 

42from pyTooling.MetaClasses import ExtendedType 

43 

44from pyVHDLModel.Exception import VHDLModelException 

45from pyVHDLModel.Base import ModelEntity 

46from pyVHDLModel.DesignUnit import Package, ContextUnion 

47from pyVHDLModel.Association import GenericAssociationItem, GenericMapAspectMixin 

48from pyVHDLModel.Subprogram import Procedure, Function, Subprogram 

49from pyVHDLModel.Symbol import PackageReferenceSymbol, SubprogramReferenceSymbol, SubtypeSymbol 

50 

51if TYPE_CHECKING: 51 ↛ 52line 51 didn't jump to line 52 because the condition on line 51 was never true

52 from pyVHDLModel.Visitor import Visitor 

53 

54 

55@export 

56class GenericInstantiationMixin(metaclass=ExtendedType, mixin=True): 

57 """ 

58 A mixin-class for instantiations passing generic actuals. 

59 

60 .. seealso:: 

61 

62 * :class:`Generic entity instantiation mixin <pyVHDLModel.Instantiation.GenericEntityInstantiationMixin>` 

63 * :class:`Subprogram instantiation mixin <pyVHDLModel.Instantiation.SubprogramInstantiationMixin>` 

64 * :class:`Package instantiation <pyVHDLModel.Instantiation.PackageInstantiation>` 

65 """ 

66 def __init__(self) -> None: 

67 """ 

68 Initializes a generic instantiation. 

69 """ 

70 pass 

71 

72 

73@export 

74class GenericEntityInstantiationMixin(GenericInstantiationMixin, mixin=True): 

75 """ 

76 A mixin-class for instantiations of a design entity. 

77 """ 

78 def __init__(self) -> None: 

79 """ 

80 Initializes a generic entity instantiation. 

81 """ 

82 pass 

83 

84 

85@export 

86class SubprogramInstantiationMixin(GenericInstantiationMixin, GenericMapAspectMixin, mixin=True): 

87 """ 

88 A mixin-class for instantiations of a generic subprogram. 

89 

90 .. seealso:: 

91 

92 * :class:`Procedure instantiation <pyVHDLModel.Instantiation.ProcedureInstantiation>` 

93 * :class:`Function instantiation <pyVHDLModel.Instantiation.FunctionInstantiation>` 

94 """ 

95 _subprogramReference: SubprogramReferenceSymbol #: Reference to the instantiated generic subprogram. 

96 

97 def __init__( 

98 self, 

99 subprogramReference: SubprogramReferenceSymbol, 

100 genericAssociationItems: Nullable[Iterable[GenericAssociationItem]] = None 

101 ) -> None: 

102 """ 

103 Initializes a subprogram instantiation. 

104 

105 :param subprogramReference: Reference to the instantiated generic subprogram. 

106 :param genericAssociationItems: List of all generic associations in the generic map aspect. 

107 """ 

108 super().__init__() 

109 GenericMapAspectMixin.__init__(self, genericAssociationItems) 

110 

111 self._subprogramReference = subprogramReference 

112 subprogramReference.Parent = self 

113 

114 @readonly 

115 def SubprogramReference(self) -> SubprogramReferenceSymbol: 

116 """ 

117 Read-only property to access the subprogram reference (:attr:`_subprogramReference`). 

118 

119 :returns: The subprogram reference. 

120 """ 

121 return self._subprogramReference 

122 

123 

124 

125@export 

126class ProcedureInstantiation(Procedure, SubprogramInstantiationMixin): 

127 """ 

128 Represents the instantiation of a generic procedure. 

129 

130 .. admonition:: Example 

131 

132 .. code-block:: VHDL 

133 

134 procedure p is new gp generic map (N => 1); 

135 -- ^ <- Identifier 

136 -- ^^ <- GenericProcedure 

137 """ 

138 

139 def __init__( 

140 self, 

141 identifier: str, 

142 subprogramReference: SubprogramReferenceSymbol, 

143 genericAssociationItems: Nullable[Iterable[GenericAssociationItem]] = None, 

144 genericItems: Nullable[Iterable] = None, 

145 parameterItems: Nullable[Iterable] = None, 

146 declaredItems: Nullable[Iterable] = None, 

147 statements: Nullable[Iterable] = None, 

148 documentation: Nullable[str] = None, 

149 parent: Nullable[ModelEntity] = None 

150 ) -> None: 

151 """ 

152 Initializes a procedure instantiation. 

153 

154 :param identifier: The identifier of a model entity. 

155 :param subprogramReference: Reference to the instantiated generic subprogram. 

156 :param genericAssociationItems: List of all generic associations in the generic map aspect. 

157 :param genericItems: List of all generics, in declaration order. 

158 :param parameterItems: List of all parameters, in declaration order. 

159 :param declaredItems: List of all declared items in this sequential declaration region. 

160 :param statements: List of all sequential statements in the subprogram's body. 

161 :param documentation: The documentation comment associated with this declaration. 

162 :param parent: The parent model entity of this entity. 

163 """ 

164 super().__init__(identifier, genericItems, parameterItems, declaredItems, statements, documentation, parent) 

165 SubprogramInstantiationMixin.__init__(self, subprogramReference, genericAssociationItems) 

166 

167 def Visit(self, visitor: Visitor) -> None: 

168 """ 

169 Walk this procedure instantiation, its generic procedure and its generic map aspect with a visitor. 

170 

171 :param visitor: The visitor receiving the events. 

172 """ 

173 visitor.VisitProcedureInstantiation(self) 

174 self._subprogramReference.Visit(visitor) 

175 self._VisitGenericMapAspect(visitor) 

176 visitor.DepartProcedureInstantiation(self) 

177 

178 

179@export 

180class FunctionInstantiation(Function, SubprogramInstantiationMixin): 

181 """ 

182 Represents the instantiation of a generic function. 

183 

184 .. admonition:: Example 

185 

186 .. code-block:: VHDL 

187 

188 function f is new gf generic map (N => 1); 

189 -- ^ <- Identifier 

190 -- ^^ <- GenericFunction 

191 """ 

192 

193 def __init__( 

194 self, 

195 identifier: str, 

196 subprogramReference: SubprogramReferenceSymbol, 

197 isPure: bool = True, 

198 genericAssociationItems: Nullable[Iterable[GenericAssociationItem]] = None, 

199 genericItems: Nullable[Iterable] = None, 

200 parameterItems: Nullable[Iterable] = None, 

201 declaredItems: Nullable[Iterable] = None, 

202 statements: Nullable[Iterable] = None, 

203 documentation: Nullable[str] = None, 

204 parent: Nullable[ModelEntity] = None 

205 ) -> None: 

206 # NOTE: deliberately calls Subprogram.__init__ directly, not super().__init__() (which would 

207 # resolve to Function.__init__ and require a returnType that can never be known here - see 

208 # the class docstring above). 

209 """ 

210 Initializes a function instantiation. 

211 

212 :param identifier: The identifier of a model entity. 

213 :param subprogramReference: Reference to the instantiated generic subprogram. 

214 :param isPure: ``True`` if the subprogram was declared pure. 

215 :param genericAssociationItems: List of all generic associations in the generic map aspect. 

216 :param genericItems: List of all generics, in declaration order. 

217 :param parameterItems: List of all parameters, in declaration order. 

218 :param declaredItems: List of all declared items in this sequential declaration region. 

219 :param statements: List of all sequential statements in the subprogram's body. 

220 :param documentation: The documentation comment associated with this declaration. 

221 :param parent: The parent model entity of this entity. 

222 """ 

223 Subprogram.__init__(self, identifier, isPure, genericItems, parameterItems, declaredItems, statements, documentation, parent) 

224 SubprogramInstantiationMixin.__init__(self, subprogramReference, genericAssociationItems) 

225 

226 self._returnType = None 

227 

228 def Visit(self, visitor: Visitor) -> None: 

229 """ 

230 Walk this function instantiation, its generic function and its generic map aspect with a visitor. 

231 

232 :param visitor: The visitor receiving the events. 

233 """ 

234 visitor.VisitFunctionInstantiation(self) 

235 self._subprogramReference.Visit(visitor) 

236 self._VisitGenericMapAspect(visitor) 

237 visitor.DepartFunctionInstantiation(self) 

238 

239 @readonly 

240 def ReturnType(self) -> Nullable[SubtypeSymbol]: 

241 """ 

242 Read-only property to access the return type (:attr:`_returnType`). 

243 

244 :returns: The return type, or ``None`` if not set. 

245 """ 

246 return self._returnType 

247 

248 

249@export 

250# TODO: maybe a PackageBase class is needed to share members. 

251class PackageInstantiation(Package, GenericInstantiationMixin, GenericMapAspectMixin): 

252 """ 

253 Represents the instantiation of a generic package. 

254 

255 .. admonition:: Example 

256 

257 .. code-block:: VHDL 

258 

259 package p is new gp generic map (N => 1); 

260 -- ^ <- Identifier 

261 -- ^^ <- PackageReference 

262 """ 

263 _packageReference: PackageReferenceSymbol #: Reference to the instantiated generic package. 

264 

265 def __init__( 

266 self, 

267 identifier: str, 

268 genericPackage: PackageReferenceSymbol, 

269 contextItems: Nullable[Iterable[ContextUnion]] = None, 

270 genericAssociationItems: Nullable[Iterable[GenericAssociationItem]] = None, 

271 documentation: Nullable[str] = None, 

272 parent: Nullable[ModelEntity] = None 

273 ) -> None: 

274 """ 

275 Initializes a package instantiation. 

276 

277 :param identifier: The identifier of a model entity. 

278 :param genericPackage: Reference to the instantiated generic package. 

279 :param contextItems: List of all context items (library, use and context clauses). 

280 :param genericAssociationItems: List of all generic associations in the generic map aspect. 

281 :param documentation: The documentation comment associated with this declaration. 

282 :param parent: The parent model entity of this entity. 

283 """ 

284 super().__init__(identifier, contextItems, documentation=documentation, parent=parent) 

285 GenericEntityInstantiationMixin.__init__(self) 

286 GenericMapAspectMixin.__init__(self, genericAssociationItems) 

287 

288 self._packageReference = genericPackage 

289 self._packageReference.Parent = self 

290 

291 def Visit(self, visitor: Visitor) -> None: 

292 """ 

293 Walk this package instantiation, its context clause, its generic package and its generic map aspect with a visitor. 

294 

295 :param visitor: The visitor receiving the events. 

296 """ 

297 self._VisitContextClause(visitor) 

298 visitor.VisitPackageInstantiation(self) 

299 self._packageReference.Visit(visitor) 

300 self._VisitGenericMapAspect(visitor) 

301 visitor.DepartPackageInstantiation(self) 

302 

303 @readonly 

304 def PackageReference(self) -> PackageReferenceSymbol: 

305 """ 

306 Read-only property to access the package reference (:attr:`_packageReference`). 

307 

308 :returns: The package reference. 

309 """ 

310 return self._packageReference 

311 

312 

313 def Instantiate(self) -> None: 

314 genericPackage: Package = self._packageReference.Package 

315 if genericPackage is None: 

316 raise VHDLModelException(f"PackageInstantiation '{self.Identifier}' isn't linked to the generic package '{self._packageReference.Name}'.") 

317 

318 # TODO: components might need to be copied and derived 

319 for componentName, component in genericPackage._components.items(): 

320 self._components[componentName] = component 

321 

322 # FIXME: handle other package members