| 1 |
# SPDX-License-Identifier: Apache-2.0 |
| 2 |
# Copyright 2021 The Meson development team |
| 3 |
|
| 4 |
import typing as T |
| 5 |
|
| 6 |
# The following variables define the current version of |
| 7 |
# the JSON documentation format. This is different from |
| 8 |
# the Meson version |
| 9 |
|
| 10 |
VERSION_MAJOR = 1 # Changes here indicate breaking format changes (changes to existing keys) |
| 11 |
VERSION_MINOR = 1 # Changes here indicate non-breaking changes (only new keys are added to the existing structure) |
| 12 |
|
| 13 |
if T.TYPE_CHECKING: |
| 14 |
from typing_extensions import TypedDict |
| 15 |
|
| 16 |
class BaseObject(TypedDict): |
| 17 |
''' |
| 18 |
Base object for most dicts in the JSON doc. |
| 19 |
|
| 20 |
All objects inheriting from BaseObject will support |
| 21 |
the keys specified here: |
| 22 |
''' |
| 23 |
name: str |
| 24 |
description: str |
| 25 |
since: T.Optional[str] |
| 26 |
deprecated: T.Optional[str] |
| 27 |
notes: T.List[str] |
| 28 |
warnings: T.List[str] |
| 29 |
|
| 30 |
class Type(TypedDict): |
| 31 |
obj: str # References an object from `root.objects` |
| 32 |
holds: T.Sequence[object] # Mypy does not support recursive dicts, but this should be T.List[Type]... |
| 33 |
|
| 34 |
class Argument(BaseObject): |
| 35 |
''' |
| 36 |
Object that represents any type of a single function or method argument. |
| 37 |
''' |
| 38 |
type: T.List[Type] # A non-empty list of types that are supported. |
| 39 |
type_str: str # Formatted version of `type`. Is guaranteed to not contain any whitespaces. |
| 40 |
required: bool |
| 41 |
default: T.Optional[str] |
| 42 |
min_varargs: T.Optional[int] # Only relevant for varargs, must be `null` for all other types of arguments |
| 43 |
max_varargs: T.Optional[int] # Only relevant for varargs, must be `null` for all other types of arguments |
| 44 |
|
| 45 |
class Function(BaseObject): |
| 46 |
''' |
| 47 |
Represents a function or method. |
| 48 |
''' |
| 49 |
returns: T.List[Type] # A non-empty list of types that are supported. |
| 50 |
returns_str: str # Formatted version of `returns`. Is guaranteed to not contain any whitespaces. |
| 51 |
example: T.Optional[str] |
| 52 |
posargs: T.Dict[str, Argument] |
| 53 |
optargs: T.Dict[str, Argument] |
| 54 |
kwargs: T.Dict[str, Argument] |
| 55 |
varargs: T.Optional[Argument] |
| 56 |
arg_flattening: bool |
| 57 |
|
| 58 |
class Object(BaseObject): |
| 59 |
''' |
| 60 |
Represents all types of Meson objects. The specific object type is stored in the `object_type` field. |
| 61 |
''' |
| 62 |
example: T.Optional[str] |
| 63 |
object_type: str # Defines the object type: Must be one of: ELEMENTARY, BUILTIN, MODULE, RETURNED |
| 64 |
methods: T.Dict[str, Function] |
| 65 |
is_container: bool |
| 66 |
extends: T.Optional[str] |
| 67 |
returned_by: T.List[str] |
| 68 |
extended_by: T.List[str] |
| 69 |
defined_by_module: T.Optional[str] |
| 70 |
|
| 71 |
class ObjectsByType(TypedDict): |
| 72 |
''' |
| 73 |
References to other objects are stored here for ease of navigation / filtering |
| 74 |
''' |
| 75 |
elementary: T.List[str] |
| 76 |
builtins: T.List[str] |
| 77 |
returned: T.List[str] |
| 78 |
modules: T.Dict[str, T.List[str]] |
| 79 |
|
| 80 |
|
| 81 |
|
| 82 |
class Root(TypedDict): |
| 83 |
''' |
| 84 |
The root object of the JSON reference manual |
| 85 |
''' |
| 86 |
version_major: int # See the description above for |
| 87 |
version_minor: int # VERSION_MAJOR and VERSION_MINOR |
| 88 |
meson_version: str |
| 89 |
functions: T.Dict[str, Function] # A mapping of <name> to a `Function` object for *all* Meson functions |
| 90 |
objects: T.Dict[str, Object] # A mapping of <name> to a `Object` object for *all* Meson objects (including modules, elementary, etc.) |
| 91 |
objects_by_type: ObjectsByType |