Coverage for pyVHDLModel/Association.py: 97%

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 

35Associations are used in generic maps, port maps and parameter maps. 

36""" 

37from typing import Iterable, List, Optional as Nullable, Union 

38 

39from pyTooling.Decorators import export, readonly 

40from pyTooling.MetaClasses import ExtendedType 

41 

42from pyVHDLModel.Base import ModelEntity 

43from pyVHDLModel.Symbol import Symbol 

44from pyVHDLModel.Expression import BaseExpression, QualifiedExpression, FunctionCall, TypeConversion, Literal 

45 

46 

47ExpressionUnion = Union[ 

48 BaseExpression, 

49 QualifiedExpression, 

50 FunctionCall, 

51 TypeConversion, 

52 # ConstantOrSymbol, TODO: ObjectSymbol 

53 Literal, 

54] 

55 

56 

57@export 

58class AssociationItem(ModelEntity): 

59 """ 

60 A base-class for all association items. 

61 

62 .. seealso:: 

63 

64 * :class:`Generic association item <pyVHDLModel.Association.GenericAssociationItem>` 

65 * :class:`Port association item <pyVHDLModel.Association.PortAssociationItem>` 

66 * :class:`Parameter association item <pyVHDLModel.Association.ParameterAssociationItem>` 

67 """ 

68 

69 _formal: Nullable[Symbol] #: Reference to the formal part, or ``None`` for a positional association. 

70 _actual: ExpressionUnion #: The actual part of this association. 

71 

72 def __init__(self, formal: Nullable[Symbol], actual: ExpressionUnion) -> None: 

73 """ 

74 Initializes an association item. 

75 

76 :param formal: Reference to the formal part, or ``None`` for a positional association. 

77 :param actual: The actual part of this association. 

78 """ 

79 super().__init__() 

80 

81 self._formal = formal 

82 if formal is not None: 

83 formal.Parent = self 

84 

85 self._actual = actual 

86 # actual._parent = self # FIXME: actual is provided as None 

87 

88 @readonly 

89 def Formal(self) -> Nullable[Symbol]: # TODO: can also be a conversion function !! 

90 """ 

91 Read-only property to access the formal (:attr:`_formal`). 

92 

93 :returns: The formal, or ``None`` if not set. 

94 """ 

95 return self._formal 

96 

97 @readonly 

98 def Actual(self) -> ExpressionUnion: 

99 """ 

100 Read-only property to access the actual (:attr:`_actual`). 

101 

102 :returns: The actual. 

103 """ 

104 return self._actual 

105 

106 def __str__(self) -> str: 

107 """ 

108 Formats the association item. 

109 

110 **Format:** ``formal => actual``, or ``actual`` alone when positional 

111 

112 :returns: Formatted association item. 

113 """ 

114 if self._formal is None: 114 ↛ 117line 114 didn't jump to line 117 because the condition on line 114 was always true

115 return str(self._actual) 

116 else: 

117 return f"{self._formal!s} => {self._actual!s}" 

118 

119 

120@export 

121class GenericAssociationItem(AssociationItem): 

122 """ 

123 A base-class for all generic association items used in generic map aspects. 

124 """ 

125 

126 

127@export 

128class PortAssociationItem(AssociationItem): 

129 """ 

130 A base-class for all port association items used in port map aspects. 

131 """ 

132 

133 

134@export 

135class ParameterAssociationItem(AssociationItem): 

136 """ 

137 A base-class for all parameter association items used in parameter map aspects. 

138 """ 

139 

140 

141@export 

142class GenericMapAspectMixin(metaclass=ExtendedType, mixin=True): 

143 """ 

144 A mixin-class for language constructs with a generic map aspect. 

145 

146 .. seealso:: 

147 

148 * :class:`Instantiation <pyVHDLModel.Concurrent.Instantiation>` 

149 * :class:`Concurrent block statement <pyVHDLModel.Concurrent.ConcurrentBlockStatement>` 

150 * :class:`Binding indication <pyVHDLModel.Configuration.BindingIndication>` 

151 * :class:`Port map aspect <pyVHDLModel.Association.PortMapAspectMixin>` 

152 """ 

153 

154 _genericAssociationItems: List[GenericAssociationItem] #: List of all generic associations. 

155 

156 def __init__(self, genericAssociationItems: Nullable[Iterable[GenericAssociationItem]] = None) -> None: 

157 """ 

158 Initializes a generic map aspect. 

159 

160 :param genericAssociationItems: List of all generic associations. 

161 """ 

162 self._genericAssociationItems = [] 

163 if genericAssociationItems is not None: 

164 for association in genericAssociationItems: 

165 self._genericAssociationItems.append(association) 

166 association.Parent = self 

167 

168 @readonly 

169 def GenericAssociationItems(self) -> List[GenericAssociationItem]: 

170 """ 

171 Read-only property to access the generic associations (:attr:`_genericAssociationItems`). 

172 

173 :returns: List of generic association items. 

174 """ 

175 return self._genericAssociationItems 

176 

177 

178@export 

179class PortMapAspectMixin(metaclass=ExtendedType, mixin=True): 

180 """ 

181 A mixin-class for language constructs with a port map aspect. 

182 

183 .. seealso:: 

184 

185 * :class:`Instantiation <pyVHDLModel.Concurrent.Instantiation>` 

186 * :class:`Concurrent block statement <pyVHDLModel.Concurrent.ConcurrentBlockStatement>` 

187 * :class:`Binding indication <pyVHDLModel.Configuration.BindingIndication>` 

188 * :class:`Generic map aspect <pyVHDLModel.Association.GenericMapAspectMixin>` 

189 """ 

190 

191 _portAssociationItems: List[PortAssociationItem] #: List of all port associations. 

192 

193 def __init__(self, portAssociationItems: Nullable[Iterable[PortAssociationItem]] = None) -> None: 

194 """ 

195 Initializes a port map aspect. 

196 

197 :param portAssociationItems: List of all port associations. 

198 """ 

199 self._portAssociationItems = [] 

200 if portAssociationItems is not None: 

201 for association in portAssociationItems: 

202 self._portAssociationItems.append(association) 

203 association.Parent = self 

204 

205 @readonly 

206 def PortAssociationItems(self) -> List[PortAssociationItem]: 

207 """ 

208 Read-only property to access the port associations (:attr:`_portAssociationItems`). 

209 

210 :returns: List of port association items. 

211 """ 

212 return self._portAssociationItems