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