Coverage for pyVHDLModel/Object.py: 85%

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 

35Objects are constants, variables, signals and files. 

36""" 

37from typing import Iterable, Optional as Nullable 

38 

39from pyTooling.Decorators import export, readonly 

40from pyTooling.MetaClasses import ExtendedType 

41from pyTooling.Graph import Vertex 

42 

43from pyVHDLModel.Base import ModelEntity, MultipleNamedEntityMixin, DocumentedEntityMixin, ExpressionUnion 

44from pyVHDLModel.Symbol import Symbol 

45 

46 

47@export 

48class Obj(ModelEntity, MultipleNamedEntityMixin, DocumentedEntityMixin): 

49 """ 

50 Base-class for all objects (constants, signals, variables and files) in VHDL. 

51 

52 An object (syntax element) can define multiple objects (semantic elements) in a single declaration, thus 

53 :class:`~pyVHDLModel.Base.MultipleNamedEntityMixin` is inherited. All objects can be documented, thus 

54 :class:`~pyVHDLModel.Base.DocumentedEntityMixin` is inherited too. 

55 

56 Each object references a subtype via :data:`_subtype`. 

57 

58 Objects are elements in the type and object graph, thus a reference to a vertex in that graph is stored in 

59 :data:`__objectVertex`. 

60 """ 

61 

62 _subtype: Symbol 

63 _objectVertex: Nullable[Vertex] 

64 

65 def __init__(self, identifiers: Iterable[str], subtype: Symbol, documentation: Nullable[str] = None, parent: ModelEntity = None) -> None: 

66 super().__init__(parent) 

67 MultipleNamedEntityMixin.__init__(self, identifiers) 

68 DocumentedEntityMixin.__init__(self, documentation) 

69 

70 self._subtype = subtype 

71 subtype._parent = self 

72 

73 self._objectVertex = None 

74 

75 @readonly 

76 def Subtype(self) -> Symbol: 

77 return self._subtype 

78 

79 @readonly 

80 def ObjectVertex(self) -> Nullable[Vertex]: 

81 """ 

82 Read-only property to access the corresponding object vertex (:attr:`_objectVertex`). 

83 

84 The object vertex references this Object by its value field. 

85 

86 :returns: The corresponding object vertex. 

87 """ 

88 return self._objectVertex 

89 

90 

91@export 

92class WithDefaultExpressionMixin(metaclass=ExtendedType, mixin=True): 

93 """ 

94 A ``WithDefaultExpression`` is a mixin-class for all objects declarations accepting default expressions. 

95 

96 The default expression is referenced by :data:`__defaultExpression`. If no default expression is present, this field 

97 is ``None``. 

98 """ 

99 

100 _defaultExpression: Nullable[ExpressionUnion] 

101 

102 def __init__(self, defaultExpression: Nullable[ExpressionUnion] = None) -> None: 

103 self._defaultExpression = defaultExpression 

104 if defaultExpression is not None: 104 ↛ 105line 104 didn't jump to line 105 because the condition on line 104 was never true

105 defaultExpression._parent = self 

106 

107 @readonly 

108 def DefaultExpression(self) -> Nullable[ExpressionUnion]: 

109 return self._defaultExpression 

110 

111 

112@export 

113class BaseConstant(Obj): 

114 """ 

115 Base-class for all constants (normal and deferred constants) in VHDL. 

116 """ 

117 

118 

119@export 

120class Constant(BaseConstant, WithDefaultExpressionMixin): 

121 """ 

122 Represents a constant. 

123 

124 As constants (always) have a default expression, the class :class:`~pyVHDLModel.Object.WithDefaultExpressionMixin` is inherited. 

125 

126 .. admonition:: Example 

127 

128 .. code-block:: VHDL 

129 

130 constant BITS : positive := 8; 

131 """ 

132 

133 def __init__( 

134 self, 

135 identifiers: Iterable[str], 

136 subtype: Symbol, 

137 defaultExpression: Nullable[ExpressionUnion] = None, 

138 documentation: Nullable[str] = None, 

139 parent: ModelEntity = None 

140 ) -> None: 

141 super().__init__(identifiers, subtype, documentation, parent) 

142 WithDefaultExpressionMixin.__init__(self, defaultExpression) 

143 

144 

145@export 

146class DeferredConstant(BaseConstant): 

147 """ 

148 Represents a deferred constant. 

149 

150 Deferred constants are forward declarations for a (complete) constant declaration, thus it contains a 

151 field :data:`__constantReference` to the complete constant declaration. 

152 

153 .. admonition:: Example 

154 

155 .. code-block:: VHDL 

156 

157 constant BITS : positive; 

158 """ 

159 _constantReference: Nullable[Constant] 

160 

161 def __init__( 

162 self, 

163 identifiers: Iterable[str], 

164 subtype: Symbol, 

165 documentation: Nullable[str] = None, 

166 parent: ModelEntity = None 

167 ) -> None: 

168 super().__init__(identifiers, subtype, documentation, parent) 

169 

170 @readonly 

171 def ConstantReference(self) -> Nullable[Constant]: 

172 return self._constantReference 

173 

174 def __str__(self) -> str: 

175 return f"constant {', '.join(self._identifiers)} : {self._subtype}" 

176 

177 

178@export 

179class Variable(Obj, WithDefaultExpressionMixin): 

180 """ 

181 Represents a variable. 

182 

183 As variables might have a default expression, the class :class:`~pyVHDLModel.Object.WithDefaultExpressionMixin` is inherited. 

184 

185 .. admonition:: Example 

186 

187 .. code-block:: VHDL 

188 

189 variable result : natural := 0; 

190 """ 

191 

192 def __init__( 

193 self, 

194 identifiers: Iterable[str], 

195 subtype: Symbol, 

196 defaultExpression: Nullable[ExpressionUnion] = None, 

197 documentation: Nullable[str] = None, 

198 parent: ModelEntity = None 

199 ) -> None: 

200 super().__init__(identifiers, subtype, documentation, parent) 

201 WithDefaultExpressionMixin.__init__(self, defaultExpression) 

202 

203 

204@export 

205class SharedVariable(Obj): 

206 """ 

207 Represents a shared variable. 

208 

209 .. todo:: Shared variable object not implemented. 

210 """ 

211 

212 

213 

214@export 

215class Signal(Obj, WithDefaultExpressionMixin): 

216 """ 

217 Represents a signal. 

218 

219 As signals might have a default expression, the class :class:`~pyVHDLModel.Object.WithDefaultExpressionMixin` is inherited. 

220 

221 .. admonition:: Example 

222 

223 .. code-block:: VHDL 

224 

225 signal counter : unsigned(7 downto 0) := '0'; 

226 """ 

227 

228 def __init__( 

229 self, 

230 identifiers: Iterable[str], 

231 subtype: Symbol, 

232 defaultExpression: Nullable[ExpressionUnion] = None, 

233 documentation: Nullable[str] = None, 

234 parent: ModelEntity = None 

235 ) -> None: 

236 super().__init__(identifiers, subtype, documentation, parent) 

237 WithDefaultExpressionMixin.__init__(self, defaultExpression) 

238 

239 

240@export 

241class File(Obj): 

242 """ 

243 Represents a file. 

244 

245 .. todo:: File object not implemented. 

246 """