First Commit
This commit is contained in:
563
externals/vulkan-headers/registry/spec_tools/conventions.py
vendored
Normal file
563
externals/vulkan-headers/registry/spec_tools/conventions.py
vendored
Normal file
@@ -0,0 +1,563 @@
|
||||
#!/usr/bin/env python3 -i
|
||||
#
|
||||
# Copyright 2013-2024 The Khronos Group Inc.
|
||||
#
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
# Base class for working-group-specific style conventions,
|
||||
# used in generation.
|
||||
|
||||
from enum import Enum
|
||||
import abc
|
||||
import re
|
||||
|
||||
# Type categories that respond "False" to isStructAlwaysValid
|
||||
# basetype is home to typedefs like ..Bool32
|
||||
CATEGORIES_REQUIRING_VALIDATION = set(('handle',
|
||||
'enum',
|
||||
'bitmask',
|
||||
'basetype',
|
||||
None))
|
||||
|
||||
# These are basic C types pulled in via openxr_platform_defines.h
|
||||
TYPES_KNOWN_ALWAYS_VALID = set(('char',
|
||||
'float',
|
||||
'int8_t', 'uint8_t',
|
||||
'int16_t', 'uint16_t',
|
||||
'int32_t', 'uint32_t',
|
||||
'int64_t', 'uint64_t',
|
||||
'size_t',
|
||||
'intptr_t', 'uintptr_t',
|
||||
'int',
|
||||
))
|
||||
|
||||
# Split an extension name into vendor ID and name portions
|
||||
EXT_NAME_DECOMPOSE_RE = re.compile(r'(?P<prefix>[A-Za-z]+)_(?P<vendor>[A-Za-z]+)_(?P<name>[\w_]+)')
|
||||
|
||||
# Match an API version name.
|
||||
# Match object includes API prefix, major, and minor version numbers.
|
||||
# This could be refined further for specific APIs.
|
||||
API_VERSION_NAME_RE = re.compile(r'(?P<apivariant>[A-Za-z]+)_VERSION_(?P<major>[0-9]+)_(?P<minor>[0-9]+)')
|
||||
|
||||
class ProseListFormats(Enum):
|
||||
"""A connective, possibly with a quantifier."""
|
||||
AND = 0
|
||||
EACH_AND = 1
|
||||
OR = 2
|
||||
ANY_OR = 3
|
||||
|
||||
@classmethod
|
||||
def from_string(cls, s):
|
||||
if s == 'or':
|
||||
return cls.OR
|
||||
if s == 'and':
|
||||
return cls.AND
|
||||
raise RuntimeError("Unrecognized string connective: " + s)
|
||||
|
||||
@property
|
||||
def connective(self):
|
||||
if self in (ProseListFormats.OR, ProseListFormats.ANY_OR):
|
||||
return 'or'
|
||||
return 'and'
|
||||
|
||||
def quantifier(self, n):
|
||||
"""Return the desired quantifier for a list of a given length."""
|
||||
if self == ProseListFormats.ANY_OR:
|
||||
if n > 1:
|
||||
return 'any of '
|
||||
elif self == ProseListFormats.EACH_AND:
|
||||
if n > 2:
|
||||
return 'each of '
|
||||
if n == 2:
|
||||
return 'both of '
|
||||
return ''
|
||||
|
||||
|
||||
class ConventionsBase(abc.ABC):
|
||||
"""WG-specific conventions."""
|
||||
|
||||
def __init__(self):
|
||||
self._command_prefix = None
|
||||
self._type_prefix = None
|
||||
|
||||
def formatVersionOrExtension(self, name):
|
||||
"""Mark up an API version or extension name as a link in the spec."""
|
||||
|
||||
# Is this a version name?
|
||||
match = API_VERSION_NAME_RE.match(name)
|
||||
if match is not None:
|
||||
return self.formatVersion(name,
|
||||
match.group('apivariant'),
|
||||
match.group('major'),
|
||||
match.group('minor'))
|
||||
else:
|
||||
# If not, assumed to be an extension name. Might be worth checking.
|
||||
return self.formatExtension(name)
|
||||
|
||||
def formatVersion(self, name, apivariant, major, minor):
|
||||
"""Mark up an API version name as a link in the spec."""
|
||||
return '`<<{}>>`'.format(name)
|
||||
|
||||
def formatExtension(self, name):
|
||||
"""Mark up an extension name as a link in the spec."""
|
||||
return '`<<{}>>`'.format(name)
|
||||
|
||||
def formatSPIRVlink(self, name):
|
||||
"""Mark up a SPIR-V extension name as an external link in the spec.
|
||||
Since these are external links, the formatting probably will be
|
||||
the same for all APIs creating such links, so long as they use
|
||||
the asciidoctor {spirv} attribute for the base path to the SPIR-V
|
||||
extensions."""
|
||||
|
||||
(vendor, _) = self.extension_name_split(name)
|
||||
|
||||
return f'{{spirv}}/{vendor}/{name}.html[{name}]'
|
||||
|
||||
@property
|
||||
@abc.abstractmethod
|
||||
def null(self):
|
||||
"""Preferred spelling of NULL."""
|
||||
raise NotImplementedError
|
||||
|
||||
def makeProseList(self, elements, fmt=ProseListFormats.AND, with_verb=False, *args, **kwargs):
|
||||
"""Make a (comma-separated) list for use in prose.
|
||||
|
||||
Adds a connective (by default, 'and')
|
||||
before the last element if there are more than 1.
|
||||
|
||||
Adds the right one of "is" or "are" to the end if with_verb is true.
|
||||
|
||||
Optionally adds a quantifier (like 'any') before a list of 2 or more,
|
||||
if specified by fmt.
|
||||
|
||||
Override with a different method or different call to
|
||||
_implMakeProseList if you want to add a comma for two elements,
|
||||
or not use a serial comma.
|
||||
"""
|
||||
return self._implMakeProseList(elements, fmt, with_verb, *args, **kwargs)
|
||||
|
||||
@property
|
||||
def struct_macro(self):
|
||||
"""Get the appropriate format macro for a structure.
|
||||
|
||||
May override.
|
||||
"""
|
||||
return 'slink:'
|
||||
|
||||
@property
|
||||
def external_macro(self):
|
||||
"""Get the appropriate format macro for an external type like uint32_t.
|
||||
|
||||
May override.
|
||||
"""
|
||||
return 'code:'
|
||||
|
||||
@property
|
||||
def allows_x_number_suffix(self):
|
||||
"""Whether vendor tags can be suffixed with X and a number to mark experimental extensions."""
|
||||
return False
|
||||
|
||||
@property
|
||||
@abc.abstractmethod
|
||||
def structtype_member_name(self):
|
||||
"""Return name of the structure type member.
|
||||
|
||||
Must implement.
|
||||
"""
|
||||
raise NotImplementedError()
|
||||
|
||||
@property
|
||||
@abc.abstractmethod
|
||||
def nextpointer_member_name(self):
|
||||
"""Return name of the structure pointer chain member.
|
||||
|
||||
Must implement.
|
||||
"""
|
||||
raise NotImplementedError()
|
||||
|
||||
@property
|
||||
@abc.abstractmethod
|
||||
def xml_api_name(self):
|
||||
"""Return the name used in the default API XML registry for the default API"""
|
||||
raise NotImplementedError()
|
||||
|
||||
@abc.abstractmethod
|
||||
def generate_structure_type_from_name(self, structname):
|
||||
"""Generate a structure type name, like XR_TYPE_CREATE_INSTANCE_INFO.
|
||||
|
||||
Must implement.
|
||||
"""
|
||||
raise NotImplementedError()
|
||||
|
||||
def makeStructName(self, name):
|
||||
"""Prepend the appropriate format macro for a structure to a structure type name.
|
||||
|
||||
Uses struct_macro, so just override that if you want to change behavior.
|
||||
"""
|
||||
return self.struct_macro + name
|
||||
|
||||
def makeExternalTypeName(self, name):
|
||||
"""Prepend the appropriate format macro for an external type like uint32_t to a type name.
|
||||
|
||||
Uses external_macro, so just override that if you want to change behavior.
|
||||
"""
|
||||
return self.external_macro + name
|
||||
|
||||
def _implMakeProseList(self, elements, fmt, with_verb, comma_for_two_elts=False, serial_comma=True):
|
||||
"""Internal-use implementation to make a (comma-separated) list for use in prose.
|
||||
|
||||
Adds a connective (by default, 'and')
|
||||
before the last element if there are more than 1,
|
||||
and only includes commas if there are more than 2
|
||||
(if comma_for_two_elts is False).
|
||||
|
||||
Adds the right one of "is" or "are" to the end if with_verb is true.
|
||||
|
||||
Optionally adds a quantifier (like 'any') before a list of 2 or more,
|
||||
if specified by fmt.
|
||||
|
||||
Do not edit these defaults, override self.makeProseList().
|
||||
"""
|
||||
assert serial_comma # did not implement what we did not need
|
||||
if isinstance(fmt, str):
|
||||
fmt = ProseListFormats.from_string(fmt)
|
||||
|
||||
my_elts = list(elements)
|
||||
if len(my_elts) > 1:
|
||||
my_elts[-1] = '{} {}'.format(fmt.connective, my_elts[-1])
|
||||
|
||||
if not comma_for_two_elts and len(my_elts) <= 2:
|
||||
prose = ' '.join(my_elts)
|
||||
else:
|
||||
prose = ', '.join(my_elts)
|
||||
|
||||
quantifier = fmt.quantifier(len(my_elts))
|
||||
|
||||
parts = [quantifier, prose]
|
||||
|
||||
if with_verb:
|
||||
if len(my_elts) > 1:
|
||||
parts.append(' are')
|
||||
else:
|
||||
parts.append(' is')
|
||||
return ''.join(parts)
|
||||
|
||||
@property
|
||||
@abc.abstractmethod
|
||||
def file_suffix(self):
|
||||
"""Return suffix of generated Asciidoctor files"""
|
||||
raise NotImplementedError
|
||||
|
||||
@abc.abstractmethod
|
||||
def api_name(self, spectype=None):
|
||||
"""Return API or specification name for citations in ref pages.
|
||||
|
||||
spectype is the spec this refpage is for.
|
||||
'api' (the default value) is the main API Specification.
|
||||
If an unrecognized spectype is given, returns None.
|
||||
|
||||
Must implement."""
|
||||
raise NotImplementedError
|
||||
|
||||
def should_insert_may_alias_macro(self, genOpts):
|
||||
"""Return true if we should insert a "may alias" macro in this file.
|
||||
|
||||
Only used by OpenXR right now."""
|
||||
return False
|
||||
|
||||
@property
|
||||
def command_prefix(self):
|
||||
"""Return the expected prefix of commands/functions.
|
||||
|
||||
Implemented in terms of api_prefix."""
|
||||
if not self._command_prefix:
|
||||
self._command_prefix = self.api_prefix[:].replace('_', '').lower()
|
||||
return self._command_prefix
|
||||
|
||||
@property
|
||||
def type_prefix(self):
|
||||
"""Return the expected prefix of type names.
|
||||
|
||||
Implemented in terms of command_prefix (and in turn, api_prefix)."""
|
||||
if not self._type_prefix:
|
||||
self._type_prefix = ''.join(
|
||||
(self.command_prefix[0:1].upper(), self.command_prefix[1:]))
|
||||
return self._type_prefix
|
||||
|
||||
@property
|
||||
@abc.abstractmethod
|
||||
def api_prefix(self):
|
||||
"""Return API token prefix.
|
||||
|
||||
Typically two uppercase letters followed by an underscore.
|
||||
|
||||
Must implement."""
|
||||
raise NotImplementedError
|
||||
|
||||
@property
|
||||
def extension_name_prefix(self):
|
||||
"""Return extension name prefix.
|
||||
|
||||
Typically two uppercase letters followed by an underscore.
|
||||
|
||||
Assumed to be the same as api_prefix, but some APIs use different
|
||||
case conventions."""
|
||||
|
||||
return self.api_prefix
|
||||
|
||||
def extension_short_description(self, elem):
|
||||
"""Return a short description of an extension for use in refpages.
|
||||
|
||||
elem is an ElementTree for the <extension> tag in the XML.
|
||||
The default behavior is to use the 'type' field of this tag, but not
|
||||
all APIs support this field."""
|
||||
|
||||
ext_type = elem.get('type')
|
||||
|
||||
if ext_type is not None:
|
||||
return f'{ext_type} extension'
|
||||
else:
|
||||
return ''
|
||||
|
||||
@property
|
||||
def write_contacts(self):
|
||||
"""Return whether contact list should be written to extension appendices"""
|
||||
return False
|
||||
|
||||
@property
|
||||
def write_extension_type(self):
|
||||
"""Return whether extension type should be written to extension appendices"""
|
||||
return True
|
||||
|
||||
@property
|
||||
def write_extension_number(self):
|
||||
"""Return whether extension number should be written to extension appendices"""
|
||||
return True
|
||||
|
||||
@property
|
||||
def write_extension_revision(self):
|
||||
"""Return whether extension revision number should be written to extension appendices"""
|
||||
return True
|
||||
|
||||
@property
|
||||
def write_refpage_include(self):
|
||||
"""Return whether refpage include should be written to extension appendices"""
|
||||
return True
|
||||
|
||||
@property
|
||||
def api_version_prefix(self):
|
||||
"""Return API core version token prefix.
|
||||
|
||||
Implemented in terms of api_prefix.
|
||||
|
||||
May override."""
|
||||
return self.api_prefix + 'VERSION_'
|
||||
|
||||
@property
|
||||
def KHR_prefix(self):
|
||||
"""Return extension name prefix for KHR extensions.
|
||||
|
||||
Implemented in terms of api_prefix.
|
||||
|
||||
May override."""
|
||||
return self.api_prefix + 'KHR_'
|
||||
|
||||
@property
|
||||
def EXT_prefix(self):
|
||||
"""Return extension name prefix for EXT extensions.
|
||||
|
||||
Implemented in terms of api_prefix.
|
||||
|
||||
May override."""
|
||||
return self.api_prefix + 'EXT_'
|
||||
|
||||
def writeFeature(self, featureName, featureExtraProtect, filename):
|
||||
"""Return True if OutputGenerator.endFeature should write this feature.
|
||||
|
||||
Defaults to always True.
|
||||
Used in COutputGenerator.
|
||||
|
||||
May override."""
|
||||
return True
|
||||
|
||||
def requires_error_validation(self, return_type):
|
||||
"""Return True if the return_type element is an API result code
|
||||
requiring error validation.
|
||||
|
||||
Defaults to always False.
|
||||
|
||||
May override."""
|
||||
return False
|
||||
|
||||
@property
|
||||
def required_errors(self):
|
||||
"""Return a list of required error codes for validation.
|
||||
|
||||
Defaults to an empty list.
|
||||
|
||||
May override."""
|
||||
return []
|
||||
|
||||
def is_voidpointer_alias(self, tag, text, tail):
|
||||
"""Return True if the declaration components (tag,text,tail) of an
|
||||
element represents a void * type.
|
||||
|
||||
Defaults to a reasonable implementation.
|
||||
|
||||
May override."""
|
||||
return tag == 'type' and text == 'void' and tail.startswith('*')
|
||||
|
||||
def make_voidpointer_alias(self, tail):
|
||||
"""Reformat a void * declaration to include the API alias macro.
|
||||
|
||||
Defaults to a no-op.
|
||||
|
||||
Must override if you actually want to use this feature in your project."""
|
||||
return tail
|
||||
|
||||
def category_requires_validation(self, category):
|
||||
"""Return True if the given type 'category' always requires validation.
|
||||
|
||||
Defaults to a reasonable implementation.
|
||||
|
||||
May override."""
|
||||
return category in CATEGORIES_REQUIRING_VALIDATION
|
||||
|
||||
def type_always_valid(self, typename):
|
||||
"""Return True if the given type name is always valid (never requires validation).
|
||||
|
||||
This is for things like integers.
|
||||
|
||||
Defaults to a reasonable implementation.
|
||||
|
||||
May override."""
|
||||
return typename in TYPES_KNOWN_ALWAYS_VALID
|
||||
|
||||
@property
|
||||
def should_skip_checking_codes(self):
|
||||
"""Return True if more than the basic validation of return codes should
|
||||
be skipped for a command."""
|
||||
|
||||
return False
|
||||
|
||||
@property
|
||||
def generate_index_terms(self):
|
||||
"""Return True if asiidoctor index terms should be generated as part
|
||||
of an API interface from the docgenerator."""
|
||||
|
||||
return False
|
||||
|
||||
@property
|
||||
def generate_enum_table(self):
|
||||
"""Return True if asciidoctor tables describing enumerants in a
|
||||
group should be generated as part of group generation."""
|
||||
return False
|
||||
|
||||
@property
|
||||
def generate_max_enum_in_docs(self):
|
||||
"""Return True if MAX_ENUM tokens should be generated in
|
||||
documentation includes."""
|
||||
return False
|
||||
|
||||
def extension_name_split(self, name):
|
||||
"""Split an extension name, returning (vendor, rest of name).
|
||||
The API prefix of the name is ignored."""
|
||||
|
||||
match = EXT_NAME_DECOMPOSE_RE.match(name)
|
||||
vendor = match.group('vendor')
|
||||
bare_name = match.group('name')
|
||||
|
||||
return (vendor, bare_name)
|
||||
|
||||
@abc.abstractmethod
|
||||
def extension_file_path(self, name):
|
||||
"""Return file path to an extension appendix relative to a directory
|
||||
containing all such appendices.
|
||||
- name - extension name
|
||||
|
||||
Must implement."""
|
||||
raise NotImplementedError
|
||||
|
||||
def extension_include_string(self, name):
|
||||
"""Return format string for include:: line for an extension appendix
|
||||
file.
|
||||
- name - extension name"""
|
||||
|
||||
return 'include::{{appendices}}/{}[]'.format(
|
||||
self.extension_file_path(name))
|
||||
|
||||
@property
|
||||
def provisional_extension_warning(self):
|
||||
"""Return True if a warning should be included in extension
|
||||
appendices for provisional extensions."""
|
||||
return True
|
||||
|
||||
@property
|
||||
def generated_include_path(self):
|
||||
"""Return path relative to the generated reference pages, to the
|
||||
generated API include files."""
|
||||
|
||||
return '{generated}'
|
||||
|
||||
@property
|
||||
def include_extension_appendix_in_refpage(self):
|
||||
"""Return True if generating extension refpages by embedding
|
||||
extension appendix content (default), False otherwise
|
||||
(OpenXR)."""
|
||||
|
||||
return True
|
||||
|
||||
def valid_flag_bit(self, bitpos):
|
||||
"""Return True if bitpos is an allowed numeric bit position for
|
||||
an API flag.
|
||||
|
||||
Behavior depends on the data type used for flags (which may be 32
|
||||
or 64 bits), and may depend on assumptions about compiler
|
||||
handling of sign bits in enumerated types, as well."""
|
||||
return True
|
||||
|
||||
@property
|
||||
def duplicate_aliased_structs(self):
|
||||
"""
|
||||
Should aliased structs have the original struct definition listed in the
|
||||
generated docs snippet?
|
||||
"""
|
||||
return False
|
||||
|
||||
@property
|
||||
def protectProtoComment(self):
|
||||
"""Return True if generated #endif should have a comment matching
|
||||
the protection symbol used in the opening #ifdef/#ifndef."""
|
||||
return False
|
||||
|
||||
@property
|
||||
def extra_refpage_headers(self):
|
||||
"""Return any extra headers (preceding the title) for generated
|
||||
reference pages."""
|
||||
return ''
|
||||
|
||||
@property
|
||||
def extra_refpage_body(self):
|
||||
"""Return any extra text (following the title) for generated
|
||||
reference pages."""
|
||||
return ''
|
||||
|
||||
def is_api_version_name(self, name):
|
||||
"""Return True if name is an API version name."""
|
||||
|
||||
return API_VERSION_NAME_RE.match(name) is not None
|
||||
|
||||
@property
|
||||
def docgen_language(self):
|
||||
"""Return the language to be used in docgenerator [source]
|
||||
blocks."""
|
||||
|
||||
return 'c++'
|
||||
|
||||
@property
|
||||
def docgen_source_options(self):
|
||||
"""Return block options to be used in docgenerator [source] blocks,
|
||||
which are appended to the 'source' block type.
|
||||
Can be empty."""
|
||||
|
||||
return '%unbreakable'
|
||||
Reference in New Issue
Block a user