1#!/usr/bin/python3 -i 2# 3# Copyright 2013-2021 The Khronos Group Inc. 4# 5# SPDX-License-Identifier: Apache-2.0 6 7# Base class for working-group-specific style conventions, 8# used in generation. 9 10from enum import Enum 11 12# Type categories that respond "False" to isStructAlwaysValid 13# basetype is home to typedefs like ..Bool32 14CATEGORIES_REQUIRING_VALIDATION = set(('handle', 15 'enum', 16 'bitmask', 17 'basetype', 18 None)) 19 20# These are basic C types pulled in via openxr_platform_defines.h 21TYPES_KNOWN_ALWAYS_VALID = set(('char', 22 'float', 23 'int8_t', 'uint8_t', 24 'int32_t', 'uint32_t', 25 'int64_t', 'uint64_t', 26 'size_t', 27 'uintptr_t', 28 'int', 29 )) 30 31 32class ProseListFormats(Enum): 33 """A connective, possibly with a quantifier.""" 34 AND = 0 35 EACH_AND = 1 36 OR = 2 37 ANY_OR = 3 38 39 @classmethod 40 def from_string(cls, s): 41 if s == 'or': 42 return cls.OR 43 if s == 'and': 44 return cls.AND 45 return None 46 47 @property 48 def connective(self): 49 if self in (ProseListFormats.OR, ProseListFormats.ANY_OR): 50 return 'or' 51 return 'and' 52 53 def quantifier(self, n): 54 """Return the desired quantifier for a list of a given length.""" 55 if self == ProseListFormats.ANY_OR: 56 if n > 1: 57 return 'any of ' 58 elif self == ProseListFormats.EACH_AND: 59 if n > 2: 60 return 'each of ' 61 if n == 2: 62 return 'both of ' 63 return '' 64 65 66class ConventionsBase: 67 """WG-specific conventions.""" 68 69 def __init__(self): 70 self._command_prefix = None 71 self._type_prefix = None 72 73 def formatExtension(self, name): 74 """Mark up an extension name as a link the spec.""" 75 return '`apiext:{}`'.format(name) 76 77 @property 78 def null(self): 79 """Preferred spelling of NULL.""" 80 raise NotImplementedError 81 82 def makeProseList(self, elements, fmt=ProseListFormats.AND, with_verb=False, *args, **kwargs): 83 """Make a (comma-separated) list for use in prose. 84 85 Adds a connective (by default, 'and') 86 before the last element if there are more than 1. 87 88 Adds the right one of "is" or "are" to the end if with_verb is true. 89 90 Optionally adds a quantifier (like 'any') before a list of 2 or more, 91 if specified by fmt. 92 93 Override with a different method or different call to 94 _implMakeProseList if you want to add a comma for two elements, 95 or not use a serial comma. 96 """ 97 return self._implMakeProseList(elements, fmt, with_verb, *args, **kwargs) 98 99 @property 100 def struct_macro(self): 101 """Get the appropriate format macro for a structure. 102 103 May override. 104 """ 105 return 'slink:' 106 107 @property 108 def external_macro(self): 109 """Get the appropriate format macro for an external type like uint32_t. 110 111 May override. 112 """ 113 return 'code:' 114 115 def makeStructName(self, name): 116 """Prepend the appropriate format macro for a structure to a structure type name. 117 118 Uses struct_macro, so just override that if you want to change behavior. 119 """ 120 return self.struct_macro + name 121 122 def makeExternalTypeName(self, name): 123 """Prepend the appropriate format macro for an external type like uint32_t to a type name. 124 125 Uses external_macro, so just override that if you want to change behavior. 126 """ 127 return self.external_macro + name 128 129 def _implMakeProseList(self, elements, fmt, with_verb, comma_for_two_elts=False, serial_comma=True): 130 """Internal-use implementation to make a (comma-separated) list for use in prose. 131 132 Adds a connective (by default, 'and') 133 before the last element if there are more than 1, 134 and only includes commas if there are more than 2 135 (if comma_for_two_elts is False). 136 137 Adds the right one of "is" or "are" to the end if with_verb is true. 138 139 Optionally adds a quantifier (like 'any') before a list of 2 or more, 140 if specified by fmt. 141 142 Do not edit these defaults, override self.makeProseList(). 143 """ 144 assert(serial_comma) # did not implement what we did not need 145 if isinstance(fmt, str): 146 fmt = ProseListFormats.from_string(fmt) 147 148 my_elts = list(elements) 149 if len(my_elts) > 1: 150 my_elts[-1] = '{} {}'.format(fmt.connective, my_elts[-1]) 151 152 if not comma_for_two_elts and len(my_elts) <= 2: 153 prose = ' '.join(my_elts) 154 else: 155 prose = ', '.join(my_elts) 156 157 quantifier = fmt.quantifier(len(my_elts)) 158 159 parts = [quantifier, prose] 160 161 if with_verb: 162 if len(my_elts) > 1: 163 parts.append(' are') 164 else: 165 parts.append(' is') 166 return ''.join(parts) 167 168 @property 169 def file_suffix(self): 170 """Return suffix of generated Asciidoctor files""" 171 raise NotImplementedError 172 173 def api_name(self, spectype=None): 174 """Return API or specification name for citations in ref pages. 175 176 spectype is the spec this refpage is for. 177 'api' (the default value) is the main API Specification. 178 If an unrecognized spectype is given, returns None. 179 180 Must implement.""" 181 raise NotImplementedError 182 183 def should_insert_may_alias_macro(self, genOpts): 184 """Return true if we should insert a "may alias" macro in this file. 185 186 Only used by OpenXR right now.""" 187 return False 188 189 @property 190 def command_prefix(self): 191 """Return the expected prefix of commands/functions. 192 193 Implemented in terms of api_prefix.""" 194 if not self._command_prefix: 195 self._command_prefix = self.api_prefix[:].replace('_', '').lower() 196 return self._command_prefix 197 198 @property 199 def type_prefix(self): 200 """Return the expected prefix of type names. 201 202 Implemented in terms of command_prefix (and in turn, api_prefix).""" 203 if not self._type_prefix: 204 self._type_prefix = ''.join( 205 (self.command_prefix[0:1].upper(), self.command_prefix[1:])) 206 return self._type_prefix 207 208 @property 209 def api_prefix(self): 210 """Return API token prefix. 211 212 Typically two uppercase letters followed by an underscore. 213 214 Must implement.""" 215 raise NotImplementedError 216 217 @property 218 def api_version_prefix(self): 219 """Return API core version token prefix. 220 221 Implemented in terms of api_prefix. 222 223 May override.""" 224 return self.api_prefix + 'VERSION_' 225 226 @property 227 def KHR_prefix(self): 228 """Return extension name prefix for KHR extensions. 229 230 Implemented in terms of api_prefix. 231 232 May override.""" 233 return self.api_prefix + 'KHR_' 234 235 @property 236 def EXT_prefix(self): 237 """Return extension name prefix for EXT extensions. 238 239 Implemented in terms of api_prefix. 240 241 May override.""" 242 return self.api_prefix + 'EXT_' 243 244 def writeFeature(self, featureExtraProtect, filename): 245 """Return True if OutputGenerator.endFeature should write this feature. 246 247 Defaults to always True. 248 Used in COutputGenerator. 249 250 May override.""" 251 return True 252 253 def requires_error_validation(self, return_type): 254 """Return True if the return_type element is an API result code 255 requiring error validation. 256 257 Defaults to always False. 258 259 May override.""" 260 return False 261 262 @property 263 def required_errors(self): 264 """Return a list of required error codes for validation. 265 266 Defaults to an empty list. 267 268 May override.""" 269 return [] 270 271 def is_voidpointer_alias(self, tag, text, tail): 272 """Return True if the declaration components (tag,text,tail) of an 273 element represents a void * type. 274 275 Defaults to a reasonable implementation. 276 277 May override.""" 278 return tag == 'type' and text == 'void' and tail.startswith('*') 279 280 def make_voidpointer_alias(self, tail): 281 """Reformat a void * declaration to include the API alias macro. 282 283 Defaults to a no-op. 284 285 Must override if you actually want to use this feature in your project.""" 286 return tail 287 288 def category_requires_validation(self, category): 289 """Return True if the given type 'category' always requires validation. 290 291 Defaults to a reasonable implementation. 292 293 May override.""" 294 return category in CATEGORIES_REQUIRING_VALIDATION 295 296 def type_always_valid(self, typename): 297 """Return True if the given type name is always valid (never requires validation). 298 299 This is for things like integers. 300 301 Defaults to a reasonable implementation. 302 303 May override.""" 304 return typename in TYPES_KNOWN_ALWAYS_VALID 305 306 @property 307 def should_skip_checking_codes(self): 308 """Return True if more than the basic validation of return codes should 309 be skipped for a command.""" 310 311 return False 312 313 @property 314 def generate_index_terms(self): 315 """Return True if asiidoctor index terms should be generated as part 316 of an API interface from the docgenerator.""" 317 318 return False 319 320 @property 321 def generate_enum_table(self): 322 """Return True if asciidoctor tables describing enumerants in a 323 group should be generated as part of group generation.""" 324 return False 325 326 @property 327 def generate_max_enum_in_docs(self): 328 """Return True if MAX_ENUM tokens should be generated in 329 documentation includes.""" 330 return False 331 332 333 def extension_include_string(self, ext): 334 """Return format string for include:: line for an extension appendix 335 file. ext is an object with the following members: 336 - name - extension string string 337 - vendor - vendor portion of name 338 - barename - remainder of name 339 340 Must implement.""" 341 raise NotImplementedError 342 343 @property 344 def refpage_generated_include_path(self): 345 """Return path relative to the generated reference pages, to the 346 generated API include files. 347 348 Must implement.""" 349 raise NotImplementedError 350 351 def valid_flag_bit(self, bitpos): 352 """Return True if bitpos is an allowed numeric bit position for 353 an API flag. 354 355 Behavior depends on the data type used for flags (which may be 32 356 or 64 bits), and may depend on assumptions about compiler 357 handling of sign bits in enumerated types, as well.""" 358 return True 359