Coverage for pyVHDLModel/Instantiation.py: 100%

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 typing import List, Iterable, Optional as Nullable 

38 

39from pyTooling.Decorators import export, readonly 

40from pyTooling.MetaClasses import ExtendedType 

41 

42from pyVHDLModel import VHDLModelException 

43from pyVHDLModel.Base import ModelEntity 

44from pyVHDLModel.DesignUnit import Package, ContextUnion 

45from pyVHDLModel.Association import GenericAssociationItem, GenericMapAspectMixin 

46from pyVHDLModel.Subprogram import Procedure, Function, Subprogram 

47from pyVHDLModel.Symbol import PackageReferenceSymbol, SubprogramReferenceSymbol, SubtypeSymbol 

48 

49 

50@export 

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

52 """ 

53 A mixin-class for instantiations passing generic actuals. 

54 

55 .. seealso:: 

56 

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

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

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

60 """ 

61 def __init__(self) -> None: 

62 """ 

63 Initializes a generic instantiation. 

64 """ 

65 pass 

66 

67 

68@export 

69class GenericEntityInstantiationMixin(GenericInstantiationMixin, mixin=True): 

70 """ 

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

72 """ 

73 def __init__(self) -> None: 

74 """ 

75 Initializes a generic entity instantiation. 

76 """ 

77 pass 

78 

79 

80@export 

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

82 """ 

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

84 

85 .. seealso:: 

86 

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

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

89 """ 

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

91 

92 def __init__( 

93 self, 

94 subprogramReference: SubprogramReferenceSymbol, 

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

96 ) -> None: 

97 """ 

98 Initializes a subprogram instantiation. 

99 

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

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

102 """ 

103 super().__init__() 

104 GenericMapAspectMixin.__init__(self, genericAssociationItems) 

105 

106 self._subprogramReference = subprogramReference 

107 subprogramReference.Parent = self 

108 

109 @readonly 

110 def SubprogramReference(self) -> SubprogramReferenceSymbol: 

111 """ 

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

113 

114 :returns: The subprogram reference. 

115 """ 

116 return self._subprogramReference 

117 

118 

119 

120@export 

121class ProcedureInstantiation(Procedure, SubprogramInstantiationMixin): 

122 """ 

123 Represents the instantiation of a generic procedure. 

124 

125 .. admonition:: Example 

126 

127 .. code-block:: VHDL 

128 

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

130 -- ^ <- Identifier 

131 -- ^^ <- GenericProcedure 

132 """ 

133 

134 def __init__( 

135 self, 

136 identifier: str, 

137 subprogramReference: SubprogramReferenceSymbol, 

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

139 genericItems: Nullable[Iterable] = None, 

140 parameterItems: Nullable[Iterable] = None, 

141 declaredItems: Nullable[Iterable] = None, 

142 statements: Nullable[Iterable] = None, 

143 documentation: Nullable[str] = None, 

144 parent: Nullable[ModelEntity] = None 

145 ) -> None: 

146 """ 

147 Initializes a procedure instantiation. 

148 

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

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

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

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

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

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

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

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

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

158 """ 

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

160 SubprogramInstantiationMixin.__init__(self, subprogramReference, genericAssociationItems) 

161 

162 

163@export 

164class FunctionInstantiation(Function, SubprogramInstantiationMixin): 

165 """ 

166 Represents the instantiation of a generic function. 

167 

168 .. admonition:: Example 

169 

170 .. code-block:: VHDL 

171 

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

173 -- ^ <- Identifier 

174 -- ^^ <- GenericFunction 

175 """ 

176 

177 def __init__( 

178 self, 

179 identifier: str, 

180 subprogramReference: SubprogramReferenceSymbol, 

181 isPure: bool = True, 

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

183 genericItems: Nullable[Iterable] = None, 

184 parameterItems: Nullable[Iterable] = None, 

185 declaredItems: Nullable[Iterable] = None, 

186 statements: Nullable[Iterable] = None, 

187 documentation: Nullable[str] = None, 

188 parent: Nullable[ModelEntity] = None 

189 ) -> None: 

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

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

192 # the class docstring above). 

193 """ 

194 Initializes a function instantiation. 

195 

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

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

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

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

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

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

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

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

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

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

206 """ 

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

208 SubprogramInstantiationMixin.__init__(self, subprogramReference, genericAssociationItems) 

209 

210 self._returnType = None 

211 

212 @readonly 

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

214 """ 

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

216 

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

218 """ 

219 return self._returnType 

220 

221 

222@export 

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

224class PackageInstantiation(Package, GenericInstantiationMixin, GenericMapAspectMixin): 

225 """ 

226 Represents the instantiation of a generic package. 

227 

228 .. admonition:: Example 

229 

230 .. code-block:: VHDL 

231 

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

233 -- ^ <- Identifier 

234 -- ^^ <- PackageReference 

235 """ 

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

237 

238 def __init__( 

239 self, 

240 identifier: str, 

241 genericPackage: PackageReferenceSymbol, 

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

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

244 documentation: Nullable[str] = None, 

245 parent: Nullable[ModelEntity] = None 

246 ) -> None: 

247 """ 

248 Initializes a package instantiation. 

249 

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

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

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

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

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

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

256 """ 

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

258 GenericEntityInstantiationMixin.__init__(self) 

259 GenericMapAspectMixin.__init__(self, genericAssociationItems) 

260 

261 self._packageReference = genericPackage 

262 self._packageReference.Parent = self 

263 

264 @readonly 

265 def PackageReference(self) -> PackageReferenceSymbol: 

266 """ 

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

268 

269 :returns: The package reference. 

270 """ 

271 return self._packageReference 

272 

273 

274 def Instantiate(self) -> None: 

275 genericPackage: Package = self._packageReference.Package 

276 if genericPackage is None: 

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

278 

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

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

281 self._components[componentName] = component 

282 

283 # FIXME: handle other package members