scripts/spec_tools/conventions.py

#!/usr/bin/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
    @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

    @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, 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++'