BaseTools/Source/Python/UPT/Library/CommentGenerating.py

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