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 # 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 '''
  16 CommentGenerating
  17 '''
  18
  19 ##
  20 # Import Modules
  21 #
  22 from Library.StringUtils import GetSplitValueList
  23 from Library.DataType import TAB_SPACE_SPLIT
  24 from Library.DataType import TAB_INF_GUIDTYPE_VAR
  25 from Library.DataType import USAGE_ITEM_NOTIFY
  26 from Library.DataType import ITEM_UNDEFINED
  27 from Library.DataType import TAB_HEADER_COMMENT
  28 from Library.DataType import TAB_BINARY_HEADER_COMMENT
  29 from Library.DataType import TAB_COMMENT_SPLIT
  30 from Library.DataType import TAB_SPECIAL_COMMENT
  31 from Library.DataType import END_OF_LINE
  32 from Library.DataType import TAB_COMMENT_EDK1_SPLIT
  33 from Library.DataType import TAB_COMMENT_EDK1_START
  34 from Library.DataType import TAB_COMMENT_EDK1_END
  35 from Library.DataType import TAB_STAR
  36 from Library.DataType import TAB_PCD_PROMPT
  37 from Library.UniClassObject import ConvertSpecialUnicodes
  38 from 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 #
  45 def 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 #
  57 def 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 #
  73 def 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 #
 120 def 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 #
 181 def 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 #
 194 def 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 #
 212 def 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 #
 229 def 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 #
 242 def _GetHelpStr(HelpTextObjList):
 243     ValueList = []
 244     for HelpObj in HelpTextObjList:
 245         ValueList.append((HelpObj.GetLang(), HelpObj.GetString()))
 246     return GetLocalValue(ValueList, True)