1"""Types, constants, and utility functions used by multiple sub-modules in spec_tools.""" 2 3# Copyright (c) 2018-2019 Collabora, Ltd. 4# 5# SPDX-License-Identifier: Apache-2.0 6# 7# Author(s): Ryan Pavlik <ryan.pavlik@collabora.com> 8 9import platform 10from collections import namedtuple 11from enum import Enum 12from inspect import getframeinfo 13from pathlib import Path 14from sys import stdout 15 16# if we have termcolor and we know our stdout is a TTY, 17# pull it in and use it. 18if hasattr(stdout, 'isatty') and stdout.isatty(): 19 try: 20 from termcolor import colored as colored_impl 21 HAVE_COLOR = True 22 except ImportError: 23 HAVE_COLOR = False 24elif platform.system() == 'Windows': 25 try: 26 from termcolor import colored as colored_impl 27 import colorama 28 colorama.init() 29 HAVE_COLOR = True 30 except ImportError: 31 HAVE_COLOR = False 32 33else: 34 HAVE_COLOR = False 35 36 37def colored(s, color=None, attrs=None): 38 """Call termcolor.colored with same arguments if this is a tty and it is available.""" 39 if HAVE_COLOR: 40 return colored_impl(s, color, attrs=attrs) 41 return s 42 43 44### 45# Constants used in multiple places. 46AUTO_FIX_STRING = 'Note: Auto-fix available.' 47EXTENSION_CATEGORY = 'extension' 48CATEGORIES_WITH_VALIDITY = set(('protos', 'structs')) 49NON_EXISTENT_MACROS = set(('plink', 'ttext', 'dtext')) 50 51### 52# MessageContext: All the information about where a message relates to. 53MessageContext = namedtuple('MessageContext', 54 ['filename', 'lineNum', 'line', 55 'match', 'group']) 56 57 58def getInterestedRange(message_context): 59 """Return a (start, end) pair of character index for the match in a MessageContext.""" 60 if not message_context.match: 61 # whole line 62 return (0, len(message_context.line)) 63 return (message_context.match.start(), message_context.match.end()) 64 65 66def getHighlightedRange(message_context): 67 """Return a (start, end) pair of character index for the highlighted range in a MessageContext.""" 68 if message_context.group is not None and message_context.match is not None: 69 return (message_context.match.start(message_context.group), 70 message_context.match.end(message_context.group)) 71 # no group (whole match) or no match (whole line) 72 return getInterestedRange(message_context) 73 74 75def toNameAndLine(context, root_path=None): 76 """Convert MessageContext into a simple filename:line string.""" 77 my_fn = Path(context.filename) 78 if root_path: 79 my_fn = my_fn.relative_to(root_path) 80 return '{}:{}'.format(str(my_fn), context.lineNum) 81 82 83def generateInclude(dir_traverse, generated_type, category, entity): 84 """Create an include:: directive for geneated api or validity from the various pieces.""" 85 return 'include::{directory_traverse}{generated_type}/{category}/{entity_name}.txt[]'.format( 86 directory_traverse=dir_traverse, 87 generated_type=generated_type, 88 category=category, 89 entity_name=entity) 90 91 92# Data stored per entity (function, struct, enumerant type, enumerant, extension, etc.) 93EntityData = namedtuple( 94 'EntityData', ['entity', 'macro', 'elem', 'filename', 'category', 'directory']) 95 96 97class MessageType(Enum): 98 """Type of a message.""" 99 100 WARNING = 1 101 ERROR = 2 102 NOTE = 3 103 104 def __str__(self): 105 """Format a MessageType as a lowercase string.""" 106 return str(self.name).lower() 107 108 def formattedWithColon(self): 109 """Format a MessageType as a colored, lowercase string followed by a colon.""" 110 if self == MessageType.WARNING: 111 return colored(str(self) + ':', 'magenta', attrs=['bold']) 112 if self == MessageType.ERROR: 113 return colored(str(self) + ':', 'red', attrs=['bold']) 114 return str(self) + ':' 115 116 117class MessageId(Enum): 118 """Enumerates the varieties of messages that can be generated. 119 120 Control over enabled messages with -Wbla or -Wno_bla is per-MessageId. 121 """ 122 123 MISSING_TEXT = 1 124 LEGACY = 2 125 WRONG_MACRO = 3 126 MISSING_MACRO = 4 127 BAD_ENTITY = 5 128 BAD_ENUMERANT = 6 129 BAD_MACRO = 7 130 UNRECOGNIZED_CONTEXT = 8 131 UNKNOWN_MEMBER = 9 132 DUPLICATE_INCLUDE = 10 133 UNKNOWN_INCLUDE = 11 134 API_VALIDITY_ORDER = 12 135 UNDOCUMENTED_MEMBER = 13 136 MEMBER_PNAME_MISSING = 14 137 MISSING_VALIDITY_INCLUDE = 15 138 MISSING_API_INCLUDE = 16 139 MISUSED_TEXT = 17 140 EXTENSION = 18 141 REFPAGE_TAG = 19 142 REFPAGE_MISSING_DESC = 20 143 REFPAGE_XREFS = 21 144 REFPAGE_XREFS_COMMA = 22 145 REFPAGE_TYPE = 23 146 REFPAGE_NAME = 24 147 REFPAGE_BLOCK = 25 148 REFPAGE_MISSING = 26 149 REFPAGE_MISMATCH = 27 150 REFPAGE_UNKNOWN_ATTRIB = 28 151 REFPAGE_SELF_XREF = 29 152 REFPAGE_XREF_DUPE = 30 153 REFPAGE_WHITESPACE = 31 154 REFPAGE_DUPLICATE = 32 155 UNCLOSED_BLOCK = 33 156 157 def __str__(self): 158 """Format as a lowercase string.""" 159 return self.name.lower() 160 161 def enable_arg(self): 162 """Return the corresponding Wbla string to make the 'enable this message' argument.""" 163 return 'W{}'.format(self.name.lower()) 164 165 def disable_arg(self): 166 """Return the corresponding Wno_bla string to make the 'enable this message' argument.""" 167 return 'Wno_{}'.format(self.name.lower()) 168 169 def desc(self): 170 """Return a brief description of the MessageId suitable for use in --help.""" 171 return MessageId.DESCRIPTIONS[self] 172 173 174MessageId.DESCRIPTIONS = { 175 MessageId.MISSING_TEXT: "a *text: macro is expected but not found", 176 MessageId.LEGACY: "legacy usage of *name: macro when *link: is applicable", 177 MessageId.WRONG_MACRO: "wrong macro used for an entity", 178 MessageId.MISSING_MACRO: "a macro might be missing", 179 MessageId.BAD_ENTITY: "entity not recognized, etc.", 180 MessageId.BAD_ENUMERANT: "unrecognized enumerant value used in ename:", 181 MessageId.BAD_MACRO: "unrecognized macro used", 182 MessageId.UNRECOGNIZED_CONTEXT: "pname used with an unrecognized context", 183 MessageId.UNKNOWN_MEMBER: "pname used but member/argument by that name not found", 184 MessageId.DUPLICATE_INCLUDE: "duplicated include line", 185 MessageId.UNKNOWN_INCLUDE: "include line specified file we wouldn't expect to exists", 186 MessageId.API_VALIDITY_ORDER: "saw API include after validity include", 187 MessageId.UNDOCUMENTED_MEMBER: "saw an apparent struct/function documentation, but missing a member", 188 MessageId.MEMBER_PNAME_MISSING: "pname: missing from a 'scope' operator", 189 MessageId.MISSING_VALIDITY_INCLUDE: "missing validity include", 190 MessageId.MISSING_API_INCLUDE: "missing API include", 191 MessageId.MISUSED_TEXT: "a *text: macro is found but not expected", 192 MessageId.EXTENSION: "an extension name is incorrectly marked", 193 MessageId.REFPAGE_TAG: "a refpage tag is missing an expected field", 194 MessageId.REFPAGE_MISSING_DESC: "a refpage tag has an empty description", 195 MessageId.REFPAGE_XREFS: "an unrecognized entity is mentioned in xrefs of a refpage tag", 196 MessageId.REFPAGE_XREFS_COMMA: "a comma was founds in xrefs of a refpage tag, which is space-delimited", 197 MessageId.REFPAGE_TYPE: "a refpage tag has an incorrect type field", 198 MessageId.REFPAGE_NAME: "a refpage tag has an unrecognized entity name in its refpage field", 199 MessageId.REFPAGE_BLOCK: "a refpage block is not correctly opened or closed.", 200 MessageId.REFPAGE_MISSING: "an API include was found outside of a refpage block.", 201 MessageId.REFPAGE_MISMATCH: "an API or validity include was found in a non-matching refpage block.", 202 MessageId.REFPAGE_UNKNOWN_ATTRIB: "a refpage tag has an unrecognized attribute", 203 MessageId.REFPAGE_SELF_XREF: "a refpage tag has itself in the list of cross-references", 204 MessageId.REFPAGE_XREF_DUPE: "a refpage cross-references list has at least one duplicate", 205 MessageId.REFPAGE_WHITESPACE: "a refpage cross-references list has non-minimal whitespace", 206 MessageId.REFPAGE_DUPLICATE: "a refpage tag has been seen for a single entity for a second time", 207 MessageId.UNCLOSED_BLOCK: "one or more blocks remain unclosed at the end of a file" 208} 209 210 211class Message(object): 212 """An Error, Warning, or Note with a MessageContext, MessageId, and message text. 213 214 May optionally have a replacement, a see_also array, an auto-fix, 215 and a stack frame where the message was created. 216 """ 217 218 def __init__(self, message_id, message_type, message, context, 219 replacement=None, see_also=None, fix=None, frame=None): 220 """Construct a Message. 221 222 Typically called by MacroCheckerFile.diag(). 223 """ 224 self.message_id = message_id 225 226 self.message_type = message_type 227 228 if isinstance(message, str): 229 self.message = [message] 230 else: 231 self.message = message 232 233 self.context = context 234 if context is not None and context.match is not None and context.group is not None: 235 if context.group not in context.match.groupdict(): 236 raise RuntimeError( 237 'Group "{}" does not exist in the match'.format(context.group)) 238 239 self.replacement = replacement 240 241 self.fix = fix 242 243 if see_also is None: 244 self.see_also = None 245 elif isinstance(see_also, MessageContext): 246 self.see_also = [see_also] 247 else: 248 self.see_also = see_also 249 250 self.script_location = None 251 if frame: 252 try: 253 frameinfo = getframeinfo(frame) 254 self.script_location = "{}:{}".format( 255 frameinfo.filename, frameinfo.lineno) 256 finally: 257 del frame 258