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 IsBinaryHeader:
 128         Content += CommChar * 2 + TAB_SPACE_SPLIT + TAB_BINARY_HEADER_COMMENT + '\n'
 129     elif CommChar == TAB_COMMENT_EDK1_SPLIT:
 130         Content += CommChar + TAB_SPACE_SPLIT + TAB_COMMENT_EDK1_START + TAB_STAR + TAB_SPACE_SPLIT +\
 131          TAB_HEADER_COMMENT + '\n'
 132     else:
 133         Content += CommChar * 2 + TAB_SPACE_SPLIT + TAB_HEADER_COMMENT + '\n'
 134     if Abstract:
 135         Abstract = Abstract.rstrip('\n')
 136         Content += CommChar + TAB_SPACE_SPLIT + ('\n' + CommChar + TAB_SPACE_SPLIT).join(GetSplitValueList\
 137                                                                                                 (Abstract, '\n'))
 138         Content += '\n' + CommChar + '\n'
 139     else:
 140         Content += CommChar + '\n'
 141
 142     if Description:
 143         Description = Description.rstrip('\n')
 144         Content += CommChar + TAB_SPACE_SPLIT + ('\n' + CommChar + TAB_SPACE_SPLIT).join(GetSplitValueList\
 145                                                   (Description, '\n'))
 146         Content += '\n' + CommChar + '\n'
 147
 148     #
 149     # There is no '#\n' line to separate multiple copyright lines in code base
 150     #
 151     if Copyright:
 152         Copyright = Copyright.rstrip('\n')
 153         Content += CommChar + TAB_SPACE_SPLIT + ('\n' + CommChar + TAB_SPACE_SPLIT).join\
 154         (GetSplitValueList(Copyright, '\n'))
 155         Content += '\n' + CommChar + '\n'
 156
 157     if License:
 158         License = License.rstrip('\n')
 159         Content += CommChar + TAB_SPACE_SPLIT + ('\n' + CommChar + TAB_SPACE_SPLIT).join(GetSplitValueList\
 160                                                   (License, '\n'))
 161         Content += '\n' + CommChar + '\n'
 162
 163     if CommChar == TAB_COMMENT_EDK1_SPLIT:
 164         Content += CommChar + TAB_SPACE_SPLIT + TAB_STAR + TAB_COMMENT_EDK1_END + '\n'
 165     else:
 166         Content += CommChar * 2 + '\n'
 167
 168     return Content
 169
 170
 171 ## GenInfPcdTailComment
 172 #  Generate Pcd tail comment for Inf, this would be one line comment
 173 #
 174 # @param Usage:            Usage type
 175 # @param TailCommentText:  Comment text for tail comment
 176 #
 177 def GenInfPcdTailComment (Usage, TailCommentText):
 178     if (Usage == ITEM_UNDEFINED) and (not TailCommentText):
 179         return ''
 180
 181     CommentLine = TAB_SPACE_SPLIT.join([Usage, TailCommentText])
 182     return GenTailCommentLines(CommentLine)
 183
 184 ## GenInfProtocolPPITailComment
 185 #  Generate Protocol/PPI tail comment for Inf
 186 #
 187 # @param Usage:            Usage type
 188 # @param TailCommentText:  Comment text for tail comment
 189 #
 190 def GenInfProtocolPPITailComment (Usage, Notify, TailCommentText):
 191     if (not Notify) and (Usage == ITEM_UNDEFINED) and (not TailCommentText):
 192         return ''
 193
 194     if Notify:
 195         CommentLine = USAGE_ITEM_NOTIFY + " ## "
 196     else:
 197         CommentLine = ''
 198
 199     CommentLine += TAB_SPACE_SPLIT.join([Usage, TailCommentText])
 200     return GenTailCommentLines(CommentLine)
 201
 202 ## GenInfGuidTailComment
 203 #  Generate Guid tail comment for Inf
 204 #
 205 # @param Usage:            Usage type
 206 # @param TailCommentText:  Comment text for tail comment
 207 #
 208 def GenInfGuidTailComment (Usage, GuidTypeList, VariableName, TailCommentText):
 209     GuidType = GuidTypeList[0]
 210     if (Usage == ITEM_UNDEFINED) and (GuidType == ITEM_UNDEFINED) and \
 211         (not TailCommentText):
 212         return ''
 213
 214     FirstLine = Usage + " ## " + GuidType
 215     if GuidType == TAB_INF_GUIDTYPE_VAR:
 216         FirstLine += ":" + VariableName
 217
 218     CommentLine = TAB_SPACE_SPLIT.join([FirstLine, TailCommentText])
 219     return GenTailCommentLines(CommentLine)
 220
 221 ## GenDecGuidTailComment
 222 #
 223 # @param SupModuleList:  Supported module type list
 224 #
 225 def GenDecTailComment (SupModuleList):
 226     CommentLine = TAB_SPACE_SPLIT.join(SupModuleList)
 227     return GenTailCommentLines(CommentLine)
 228
 229
 230 ## _GetHelpStr
 231 #  get HelpString from a list of HelpTextObject, the priority refer to
 232 #  related HLD
 233 #
 234 #  @param HelpTextObjList: List of HelpTextObject
 235 #
 236 #  @return HelpStr: the help text string found, '' means no help text found
 237 #
 238 def _GetHelpStr(HelpTextObjList):
 239     ValueList = []
 240     for HelpObj in HelpTextObjList:
 241         ValueList.append((HelpObj.GetLang(), HelpObj.GetString()))
 242     return GetLocalValue(ValueList, True)