Coverage for pyVHDLModel/Symbol.py: 94%

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

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

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

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

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

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

7# |_| |___/ # 

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

9# Authors: # 

10# Patrick Lehmann # 

11# # 

12# License: # 

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

14# Copyright 2017-2024 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 

35Symbols are entity specific wrappers for names that reference VHDL language entities. 

36""" 

37from enum import Flag, auto 

38from typing import Any, Optional as Nullable, Iterable, List, Dict, Mapping 

39 

40from pyTooling.Decorators import export, readonly 

41from pyTooling.MetaClasses import ExtendedType 

42 

43from pyVHDLModel.Base import Range 

44from pyVHDLModel.Name import Name, AllName 

45 

46 

47@export 

48class PossibleReference(Flag): 

49 """ 

50 Is an enumeration, representing possible targets for a reference in a :class:`~pyVHDLModel.Symbol`. 

51 """ 

52 

53 Unknown = 0 

54 Library = auto() #: Library 

55 Entity = auto() #: Entity 

56 Architecture = auto() #: Architecture 

57 Component = auto() #: Component 

58 Package = auto() #: Package 

59 Configuration = auto() #: Configuration 

60 Context = auto() #: Context 

61 Type = auto() #: Type 

62 Subtype = auto() #: Subtype 

63 ScalarType = auto() #: ScalarType 

64 ArrayType = auto() #: ArrayType 

65 RecordType = auto() #: RecordType 

66 RecordElement = auto() #: RecordElement 

67 AccessType = auto() #: AccessType 

68 ProtectedType = auto() #: ProtectedType 

69 FileType = auto() #: FileType 

70# Alias = auto() # TODO: Is this needed? 

71 Attribute = auto() #: Attribute 

72 TypeAttribute = auto() #: TypeAttribute 

73 ValueAttribute = auto() #: ValueAttribute 

74 SignalAttribute = auto() #: SignalAttribute 

75 RangeAttribute = auto() #: RangeAttribute 

76 ViewAttribute = auto() #: ViewAttribute 

77 Constant = auto() #: Constant 

78 Variable = auto() #: Variable 

79 Signal = auto() #: Signal 

80 File = auto() #: File 

81# Object = auto() # TODO: Is this needed? 

82 EnumLiteral = auto() #: EnumLiteral 

83 Procedure = auto() #: Procedure 

84 Function = auto() #: Function 

85 Label = auto() #: Label 

86 View = auto() #: View 

87 

88 AnyType = ScalarType | ArrayType | RecordType | ProtectedType | AccessType | FileType | Subtype #: Any possible type incl. subtypes. 

89 Object = Constant | Variable | Signal # | File #: Any object 

90 SubProgram = Procedure | Function #: Any subprogram 

91 PackageMember = AnyType | Object | SubProgram | Component #: Any member of a package 

92 SimpleNameInExpression = Constant | Variable | Signal | ScalarType | EnumLiteral | Function #: Any possible item in an expression. 

93 

94 

95@export 

96class Symbol(metaclass=ExtendedType): 

97 """ 

98 Base-class for all symbol classes. 

99 """ 

100 

101 _name: Name #: The name to reference the langauge entity. 

102 _possibleReferences: PossibleReference #: An enumeration to filter possible references. 

103 _reference: Nullable[Any] #: The resolved language entity, otherwise ``None``. 

104 

105 def __init__(self, name: Name, possibleReferences: PossibleReference) -> None: 

106 self._name = name 

107 self._possibleReferences = possibleReferences 

108 self._reference = None 

109 

110 @readonly 

111 def Name(self) -> Name: 

112 return self._name 

113 

114 @readonly 

115 def Reference(self) -> Nullable[Any]: 

116 return self._reference 

117 

118 @readonly 

119 def IsResolved(self) -> bool: 

120 return self._reference is not None 

121 

122 def __bool__(self) -> bool: 

123 return self._reference is not None 

124 

125 def __repr__(self) -> str: 

126 if self._reference is not None: 

127 return f"{self.__class__.__name__}: '{self._name!s}' -> {self._reference!s}" 

128 

129 return f"{self.__class__.__name__}: '{self._name!s}' -> unresolved" 

130 

131 def __str__(self) -> str: 

132 if self._reference is not None: 

133 return str(self._reference) 

134 

135 return f"{self._name!s}?" 

136 

137 

138@export 

139class LibraryReferenceSymbol(Symbol): 

140 """ 

141 Represents a reference (name) to a library. 

142 

143 The internal name will be a :class:`~pyVHDLModel.Name.SimpleName`. 

144 

145 .. admonition:: Example 

146 

147 .. code-block:: VHDL 

148 

149 library ieee; 

150 -- ^^^^ 

151 """ 

152 

153 def __init__(self, name: Name) -> None: 

154 super().__init__(name, PossibleReference.Library) 

155 

156 @readonly 

157 def Library(self) -> Nullable['Library']: 

158 return self._reference 

159 

160 @Library.setter 

161 def Library(self, value: 'Library') -> None: 

162 self._reference = value 

163 

164 

165@export 

166class PackageReferenceSymbol(Symbol): 

167 """ 

168 Represents a reference (name) to a package. 

169 

170 The internal name will be a :class:`~pyVHDLModel.Name.SelectedName`. 

171 

172 .. admonition:: Example 

173 

174 .. code-block:: VHDL 

175 

176 use ieee.numeric_std; 

177 -- ^^^^^^^^^^^^^^^^ 

178 """ 

179 

180 def __init__(self, name: Name) -> None: 

181 super().__init__(name, PossibleReference.Package) 

182 

183 @property 

184 def Package(self) -> Nullable['Package']: 

185 return self._reference 

186 

187 @Package.setter 

188 def Package(self, value: 'Package') -> None: 

189 self._reference = value 

190 

191 

192@export 

193class ContextReferenceSymbol(Symbol): 

194 """ 

195 Represents a reference (name) to a context. 

196 

197 The internal name will be a :class:`~pyVHDLModel.Name.SelectedName`. 

198 

199 .. admonition:: Example 

200 

201 .. code-block:: VHDL 

202 

203 context ieee.ieee_std_context; 

204 -- ^^^^^^^^^^^^^^^^^^^^^ 

205 """ 

206 

207 def __init__(self, name: Name) -> None: 

208 super().__init__(name, PossibleReference.Context) 

209 

210 @property 

211 def Context(self) -> 'Context': 

212 return self._reference 

213 

214 @Context.setter 

215 def Context(self, value: 'Context') -> None: 

216 self._reference = value 

217 

218 

219@export 

220class PackageMemberReferenceSymbol(Symbol): 

221 """ 

222 Represents a reference (name) to a package member. 

223 

224 The internal name will be a :class:`~pyVHDLModel.Name.SelectedName`. 

225 

226 .. admonition:: Example 

227 

228 .. code-block:: VHDL 

229 

230 use ieee.numeric_std.unsigned; 

231 -- ^^^^^^^^^^^^^^^^^^^^^^^^^ 

232 """ 

233 

234 def __init__(self, name: Name) -> None: 

235 super().__init__(name, PossibleReference.PackageMember) 

236 

237 @property 

238 def Member(self) -> Nullable['Package']: # TODO: typehint 

239 return self._reference 

240 

241 @Member.setter 

242 def Member(self, value: 'Package') -> None: # TODO: typehint 

243 self._reference = value 

244 

245 

246@export 

247class AllPackageMembersReferenceSymbol(Symbol): 

248 """ 

249 Represents a reference (name) to all package members. 

250 

251 The internal name will be a :class:`~pyVHDLModel.Name.AllName`. 

252 

253 .. admonition:: Example 

254 

255 .. code-block:: VHDL 

256 

257 use ieee.numeric_std.all; 

258 -- ^^^^^^^^^^^^^^^^^^^^ 

259 """ 

260 

261 def __init__(self, name: AllName) -> None: 

262 super().__init__(name, PossibleReference.PackageMember) 

263 

264 @property 

265 def Members(self) -> 'Package': # TODO: typehint 

266 return self._reference 

267 

268 @Members.setter 

269 def Members(self, value: 'Package') -> None: # TODO: typehint 

270 self._reference = value 

271 

272 

273@export 

274class EntityInstantiationSymbol(Symbol): 

275 """ 

276 Represents a reference (name) to an entity in a direct entity instantiation. 

277 

278 The internal name will be a :class:`~pyVHDLModel.Name.SimpleName` or :class:`~pyVHDLModel.Name.SelectedName`. 

279 

280 .. admonition:: Example 

281 

282 .. code-block:: VHDL 

283 

284 inst : entity work.Counter; 

285 -- ^^^^^^^^^^^^ 

286 """ 

287 

288 def __init__(self, name: Name) -> None: 

289 super().__init__(name, PossibleReference.Entity) 

290 

291 @property 

292 def Entity(self) -> 'Entity': 

293 return self._reference 

294 

295 @Entity.setter 

296 def Entity(self, value: 'Entity') -> None: 

297 self._reference = value 

298 

299 

300@export 

301class ComponentInstantiationSymbol(Symbol): 

302 """ 

303 Represents a reference (name) to an entity in a component instantiation. 

304 

305 The internal name will be a :class:`~pyVHDLModel.Name.SimpleName` or :class:`~pyVHDLModel.Name.SelectedName`. 

306 

307 .. admonition:: Example 

308 

309 .. code-block:: VHDL 

310 

311 inst : component Counter; 

312 -- ^^^^^^^ 

313 """ 

314 

315 def __init__(self, name: Name) -> None: 

316 super().__init__(name, PossibleReference.Component) 

317 

318 @property 

319 def Component(self) -> 'Component': 

320 return self._reference 

321 

322 @Component.setter 

323 def Component(self, value: 'Component') -> None: 

324 self._reference = value 

325 

326 

327@export 

328class ConfigurationInstantiationSymbol(Symbol): 

329 """ 

330 Represents a reference (name) to an entity in a configuration instantiation. 

331 

332 The internal name will be a :class:`~pyVHDLModel.Name.SimpleName` or :class:`~pyVHDLModel.Name.SelectedName`. 

333 

334 .. admonition:: Example 

335 

336 .. code-block:: VHDL 

337 

338 inst : configuration Counter; 

339 -- ^^^^^^^ 

340 """ 

341 

342 def __init__(self, name: Name) -> None: 

343 super().__init__(name, PossibleReference.Configuration) 

344 

345 @property 

346 def Configuration(self) -> 'Configuration': 

347 return self._reference 

348 

349 @Configuration.setter 

350 def Configuration(self, value: 'Configuration') -> None: 

351 self._reference = value 

352 

353 

354@export 

355class EntitySymbol(Symbol): 

356 """ 

357 Represents a reference (name) to an entity in an architecture declaration. 

358 

359 The internal name will be a :class:`~pyVHDLModel.Name.SimpleName` or :class:`~pyVHDLModel.Name.SelectedName`. 

360 

361 .. admonition:: Example 

362 

363 .. code-block:: VHDL 

364 

365 architecture rtl of Counter is 

366 -- ^^^^^^^ 

367 begin 

368 end architecture; 

369 """ 

370 

371 def __init__(self, name: Name) -> None: 

372 super().__init__(name, PossibleReference.Entity) 

373 

374 @property 

375 def Entity(self) -> 'Entity': 

376 return self._reference 

377 

378 @Entity.setter 

379 def Entity(self, value: 'Entity') -> None: 

380 self._reference = value 

381 

382 

383@export 

384class ArchitectureSymbol(Symbol): 

385 """An entity reference in an entity instantiation with architecture name.""" 

386 

387 def __init__(self, name: Name) -> None: 

388 super().__init__(name, PossibleReference.Architecture) 

389 

390 @property 

391 def Architecture(self) -> 'Architecture': 

392 return self._reference 

393 

394 @Architecture.setter 

395 def Architecture(self, value: 'Architecture') -> None: 

396 self._reference = value 

397 

398 

399@export 

400class PackageSymbol(Symbol): 

401 """ 

402 Represents a reference (name) to a package in a package body declaration. 

403 

404 The internal name will be a :class:`~pyVHDLModel.Name.SimpleName` or :class:`~pyVHDLModel.Name.SelectedName`. 

405 

406 .. admonition:: Example 

407 

408 .. code-block:: VHDL 

409 

410 package body Utilities is 

411 -- ^^^^^^^^^ 

412 end package body; 

413 """ 

414 

415 def __init__(self, name: Name) -> None: 

416 super().__init__(name, PossibleReference.Package) 

417 

418 @property 

419 def Package(self) -> 'Package': 

420 return self._reference 

421 

422 @Package.setter 

423 def Package(self, value: 'Package') -> None: 

424 self._reference = value 

425 

426 

427@export 

428class RecordElementSymbol(Symbol): 

429 def __init__(self, name: Name) -> None: 

430 super().__init__(name, PossibleReference.RecordElement) 

431 

432 

433@export 

434class SubtypeSymbol(Symbol): 

435 def __init__(self, name: Name) -> None: 

436 super().__init__(name, PossibleReference.Type | PossibleReference.Subtype) 

437 

438 @property 

439 def Subtype(self) -> 'Subtype': 

440 return self._reference 

441 

442 @Subtype.setter 

443 def Subtype(self, value: 'Subtype') -> None: 

444 self._reference = value 

445 

446 

447@export 

448class SimpleSubtypeSymbol(SubtypeSymbol): 

449 pass 

450 

451 

452@export 

453class ConstrainedScalarSubtypeSymbol(SubtypeSymbol): 

454 pass 

455 

456 

457@export 

458class ConstrainedCompositeSubtypeSymbol(SubtypeSymbol): 

459 pass 

460 

461 

462@export 

463class ConstrainedArraySubtypeSymbol(ConstrainedCompositeSubtypeSymbol): 

464 pass 

465 

466 

467@export 

468class ConstrainedRecordSubtypeSymbol(ConstrainedCompositeSubtypeSymbol): 

469 pass 

470 

471 

472@export 

473class SimpleObjectOrFunctionCallSymbol(Symbol): 

474 def __init__(self, name: Name) -> None: 

475 super().__init__(name, PossibleReference.SimpleNameInExpression) 

476 

477 

478@export 

479class IndexedObjectOrFunctionCallSymbol(Symbol): 

480 def __init__(self, name: Name) -> None: 

481 super().__init__(name, PossibleReference.Object | PossibleReference.Function)