1## @file
2# This file is used to define comment generating interface
3#
4# Copyright (c) 2011 - 2014, Intel Corporation. All rights reserved.<BR>
5#
6# This program and the accompanying materials are licensed and made available
7# under the terms and conditions of the BSD License which accompanies this
8# distribution. The full text of the license may be found at
9# http://opensource.org/licenses/bsd-license.php
10#
11# THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12# WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13#
14
15'''
16CommentGenerating
17'''
18
19##
20# Import Modules
21#
22from Library.String import GetSplitValueList
23from Library.DataType import TAB_SPACE_SPLIT
24from Library.DataType import TAB_INF_GUIDTYPE_VAR
25from Library.DataType import USAGE_ITEM_NOTIFY
26from Library.DataType import ITEM_UNDEFINED
27from Library.DataType import TAB_HEADER_COMMENT
28from Library.DataType import TAB_BINARY_HEADER_COMMENT
29from Library.DataType import TAB_COMMENT_SPLIT
30from Library.DataType import TAB_SPECIAL_COMMENT
31from Library.DataType import END_OF_LINE
32from Library.DataType import TAB_COMMENT_EDK1_SPLIT
33from Library.DataType import TAB_COMMENT_EDK1_START
34from Library.DataType import TAB_COMMENT_EDK1_END
35from Library.DataType import TAB_STAR
36from Library.DataType import TAB_PCD_PROMPT
37from Library.UniClassObject import ConvertSpecialUnicodes
38from Library.Misc import GetLocalValue
39## GenTailCommentLines
40#
41# @param TailCommentLines:  the tail comment lines that need to be generated
42# @param LeadingSpaceNum:   the number of leading space needed for non-first
43#                            line tail comment
44#
45def GenTailCommentLines (TailCommentLines, LeadingSpaceNum = 0):
46    TailCommentLines = TailCommentLines.rstrip(END_OF_LINE)
47    CommentStr = TAB_SPACE_SPLIT*2 + TAB_SPECIAL_COMMENT + TAB_SPACE_SPLIT + \
48    (END_OF_LINE + LeadingSpaceNum * TAB_SPACE_SPLIT + TAB_SPACE_SPLIT*2 + TAB_SPECIAL_COMMENT + \
49     TAB_SPACE_SPLIT).join(GetSplitValueList(TailCommentLines, END_OF_LINE))
50
51    return CommentStr
52
53## GenGenericComment
54#
55# @param CommentLines:   Generic comment Text, maybe Multiple Lines
56#
57def GenGenericComment (CommentLines):
58    if not CommentLines:
59        return ''
60    CommentLines = CommentLines.rstrip(END_OF_LINE)
61    CommentStr = TAB_SPECIAL_COMMENT + TAB_SPACE_SPLIT + (END_OF_LINE + TAB_COMMENT_SPLIT + TAB_SPACE_SPLIT).join\
62    (GetSplitValueList(CommentLines, END_OF_LINE)) + END_OF_LINE
63    return CommentStr
64
65## GenGenericCommentF
66#
67#  similar to GenGenericComment but will remove <EOL> at end of comment once,
68#  and for line with only <EOL>, '#\n' will be generated instead of '# \n'
69#
70# @param CommentLines:   Generic comment Text, maybe Multiple Lines
71# @return CommentStr:    Generated comment line
72#
73def GenGenericCommentF (CommentLines, NumOfPound=1, IsPrompt=False, IsInfLibraryClass=False):
74    if not CommentLines:
75        return ''
76    #
77    # if comment end with '\n', then remove it to prevent one extra line
78    # generate later on
79    #
80    if CommentLines.endswith(END_OF_LINE):
81        CommentLines = CommentLines[:-1]
82    CommentStr = ''
83    if IsPrompt:
84        CommentStr += TAB_COMMENT_SPLIT * NumOfPound + TAB_SPACE_SPLIT + TAB_PCD_PROMPT + TAB_SPACE_SPLIT + \
85        CommentLines.replace(END_OF_LINE, '') + END_OF_LINE
86    else:
87        CommentLineList = GetSplitValueList(CommentLines, END_OF_LINE)
88        FindLibraryClass = False
89        for Line in CommentLineList:
90            # If this comment is for @libraryclass and it has multiple lines
91            # make sure the second lines align to the first line after @libraryclass as below
92            #
93            # ## @libraryclass XYZ FIRST_LINE
94            # ##               ABC SECOND_LINE
95            #
96            if IsInfLibraryClass and Line.find(u'@libraryclass ') > -1:
97                FindLibraryClass = True
98            if Line == '':
99                CommentStr += TAB_COMMENT_SPLIT * NumOfPound + END_OF_LINE
100            else:
101                if FindLibraryClass and Line.find(u'@libraryclass ') > -1:
102                    CommentStr += TAB_COMMENT_SPLIT * NumOfPound + TAB_SPACE_SPLIT + Line + END_OF_LINE
103                elif FindLibraryClass:
104                    CommentStr += TAB_COMMENT_SPLIT * NumOfPound + TAB_SPACE_SPLIT * 16 + Line + END_OF_LINE
105                else:
106                    CommentStr += TAB_COMMENT_SPLIT * NumOfPound + TAB_SPACE_SPLIT + Line + END_OF_LINE
107
108    return CommentStr
109
110
111## GenHeaderCommentSection
112#
113# Generate Header comment sections
114#
115# @param Abstract      One line of abstract
116# @param Description   multiple lines of Description
117# @param Copyright     possible multiple copyright lines
118# @param License       possible multiple license lines
119#
120def GenHeaderCommentSection(Abstract, Description, Copyright, License, IsBinaryHeader=False, \
121                            CommChar=TAB_COMMENT_SPLIT):
122    Content = ''
123
124    #
125    # Convert special character to (c), (r) and (tm).
126    #
127    if isinstance(Abstract, unicode):
128        Abstract = ConvertSpecialUnicodes(Abstract)
129    if isinstance(Description, unicode):
130        Description = ConvertSpecialUnicodes(Description)
131    if IsBinaryHeader:
132        Content += CommChar * 2 + TAB_SPACE_SPLIT + TAB_BINARY_HEADER_COMMENT + '\r\n'
133    elif CommChar == TAB_COMMENT_EDK1_SPLIT:
134        Content += CommChar + TAB_SPACE_SPLIT + TAB_COMMENT_EDK1_START + TAB_STAR + TAB_SPACE_SPLIT +\
135         TAB_HEADER_COMMENT + '\r\n'
136    else:
137        Content += CommChar * 2 + TAB_SPACE_SPLIT + TAB_HEADER_COMMENT + '\r\n'
138    if Abstract:
139        Abstract = Abstract.rstrip('\r\n')
140        Content += CommChar + TAB_SPACE_SPLIT + ('\r\n' + CommChar + TAB_SPACE_SPLIT).join(GetSplitValueList\
141                                                                                                (Abstract, '\n'))
142        Content += '\r\n' + CommChar + '\r\n'
143    else:
144        Content += CommChar + '\r\n'
145
146    if Description:
147        Description = Description.rstrip('\r\n')
148        Content += CommChar + TAB_SPACE_SPLIT + ('\r\n' + CommChar + TAB_SPACE_SPLIT).join(GetSplitValueList\
149                                                  (Description, '\n'))
150        Content += '\r\n' + CommChar + '\r\n'
151
152    #
153    # There is no '#\n' line to separate multiple copyright lines in code base
154    #
155    if Copyright:
156        Copyright = Copyright.rstrip('\r\n')
157        Content += CommChar + TAB_SPACE_SPLIT + ('\r\n' + CommChar + TAB_SPACE_SPLIT).join\
158        (GetSplitValueList(Copyright, '\n'))
159        Content += '\r\n' + CommChar + '\r\n'
160
161    if License:
162        License = License.rstrip('\r\n')
163        Content += CommChar + TAB_SPACE_SPLIT + ('\r\n' + CommChar + TAB_SPACE_SPLIT).join(GetSplitValueList\
164                                                  (License, '\n'))
165        Content += '\r\n' + CommChar + '\r\n'
166
167    if CommChar == TAB_COMMENT_EDK1_SPLIT:
168        Content += CommChar + TAB_SPACE_SPLIT + TAB_STAR + TAB_COMMENT_EDK1_END + '\r\n'
169    else:
170        Content += CommChar * 2 + '\r\n'
171
172    return Content
173
174
175## GenInfPcdTailComment
176#  Generate Pcd tail comment for Inf, this would be one line comment
177#
178# @param Usage:            Usage type
179# @param TailCommentText:  Comment text for tail comment
180#
181def GenInfPcdTailComment (Usage, TailCommentText):
182    if (Usage == ITEM_UNDEFINED) and (not TailCommentText):
183        return ''
184
185    CommentLine = TAB_SPACE_SPLIT.join([Usage, TailCommentText])
186    return GenTailCommentLines(CommentLine)
187
188## GenInfProtocolPPITailComment
189#  Generate Protocol/PPI tail comment for Inf
190#
191# @param Usage:            Usage type
192# @param TailCommentText:  Comment text for tail comment
193#
194def GenInfProtocolPPITailComment (Usage, Notify, TailCommentText):
195    if (not Notify) and (Usage == ITEM_UNDEFINED) and (not TailCommentText):
196        return ''
197
198    if Notify:
199        CommentLine = USAGE_ITEM_NOTIFY + " ## "
200    else:
201        CommentLine = ''
202
203    CommentLine += TAB_SPACE_SPLIT.join([Usage, TailCommentText])
204    return GenTailCommentLines(CommentLine)
205
206## GenInfGuidTailComment
207#  Generate Guid tail comment for Inf
208#
209# @param Usage:            Usage type
210# @param TailCommentText:  Comment text for tail comment
211#
212def GenInfGuidTailComment (Usage, GuidTypeList, VariableName, TailCommentText):
213    GuidType = GuidTypeList[0]
214    if (Usage == ITEM_UNDEFINED) and (GuidType == ITEM_UNDEFINED) and \
215        (not TailCommentText):
216        return ''
217
218    FirstLine = Usage + " ## " + GuidType
219    if GuidType == TAB_INF_GUIDTYPE_VAR:
220        FirstLine += ":" + VariableName
221
222    CommentLine = TAB_SPACE_SPLIT.join([FirstLine, TailCommentText])
223    return GenTailCommentLines(CommentLine)
224
225## GenDecGuidTailComment
226#
227# @param SupModuleList:  Supported module type list
228#
229def GenDecTailComment (SupModuleList):
230    CommentLine = TAB_SPACE_SPLIT.join(SupModuleList)
231    return GenTailCommentLines(CommentLine)
232
233
234## _GetHelpStr
235#  get HelpString from a list of HelpTextObject, the priority refer to
236#  related HLD
237#
238#  @param HelpTextObjList: List of HelpTextObject
239#
240#  @return HelpStr: the help text string found, '' means no help text found
241#
242def _GetHelpStr(HelpTextObjList):
243    ValueList = []
244    for HelpObj in HelpTextObjList:
245        ValueList.append((HelpObj.GetLang(), HelpObj.GetString()))
246    return GetLocalValue(ValueList, True)
247