Debian Codegraph @

subprojects/meson-docs/docs/refman/generatorjson.py

raw
1 # SPDX-License-Identifier: Apache-2.0
2 # Copyright 2021 The Meson development team
3 from __future__ import annotations
4
5 from pathlib import Path
6 import json
7 import re
8
9 from .generatorbase import GeneratorBase
10 from . import jsonschema as J
11 from .model import (
12 ReferenceManual,
13 Function,
14 Object,
15 Type,
16
17 PosArg,
18 VarArgs,
19 Kwarg,
20 )
21
22 import typing as T
23
24 class GeneratorJSON(GeneratorBase):
25 def __init__(self, manual: ReferenceManual, out: Path, enable_modules: bool) -> None:
26 super().__init__(manual)
27 self.out = out
28 self.enable_modules = enable_modules
29
30 def _generate_type(self, typ: Type) -> T.List[J.Type]:
31 return [
32 {
33 'obj': x.data_type.name,
34 'holds': self._generate_type(x.holds) if x.holds else [],
35 }
36 for x in typ.resolved
37 ]
38
39 def _generate_type_str(self, typ: Type) -> str:
40 # Remove all whitespaces
41 return re.sub(r'[ \n\r\t]', '', typ.raw)
42
43 def _generate_arg(self, arg: T.Union[PosArg, VarArgs, Kwarg], isOptarg: bool = False) -> J.Argument:
44 return {
45 'name': arg.name,
46 'description': arg.description,
47 'since': arg.since if arg.since else None,
48 'deprecated': arg.deprecated if arg.deprecated else None,
49 'type': self._generate_type(arg.type),
50 'type_str': self._generate_type_str(arg.type),
51 'required': arg.required if isinstance(arg, Kwarg) else not isOptarg and not isinstance(arg, VarArgs),
52 'default': arg.default if isinstance(arg, (PosArg, Kwarg)) else None,
53 'min_varargs': arg.min_varargs if isinstance(arg, VarArgs) and arg.min_varargs > 0 else None,
54 'max_varargs': arg.max_varargs if isinstance(arg, VarArgs) and arg.max_varargs > 0 else None,
55
56 # Not yet supported
57 'notes': [],
58 'warnings': [],
59 }
60
61 def _generate_function(self, func: Function) -> J.Function:
62 return {
63 'name': func.name,
64 'description': func.description,
65 'since': func.since if func.since else None,
66 'deprecated': func.deprecated if func.deprecated else None,
67 'notes': func.notes,
68 'warnings': func.warnings,
69 'example': func.example if func.example else None,
70 'returns': self._generate_type(func.returns),
71 'returns_str': self._generate_type_str(func.returns),
72 'posargs': {x.name: self._generate_arg(x) for x in func.posargs},
73 'optargs': {x.name: self._generate_arg(x, True) for x in func.optargs},
74 'kwargs': {x.name: self._generate_arg(x) for x in self.sorted_and_filtered(list(func.kwargs.values()))},
75 'varargs': self._generate_arg(func.varargs) if func.varargs else None,
76 'arg_flattening': func.arg_flattening,
77 }
78
79 def _generate_objects(self, obj: Object) -> J.Object:
80 return {
81 'name': obj.name,
82 'description': obj.description,
83 'since': obj.since if obj.since else None,
84 'deprecated': obj.deprecated if obj.deprecated else None,
85 'notes': obj.notes,
86 'warnings': obj.warnings,
87 'defined_by_module': obj.defined_by_module.name if obj.defined_by_module else None,
88 'object_type': obj.obj_type.name,
89 'is_container': obj.is_container,
90 'example': obj.example if obj.example else None,
91 'extends': obj.extends if obj.extends else None,
92 'returned_by': [x.name for x in self.sorted_and_filtered(obj.returned_by)],
93 'extended_by': [x.name for x in self.sorted_and_filtered(obj.extended_by)],
94 'methods': {x.name: self._generate_function(x) for x in self.sorted_and_filtered(obj.methods)},
95 }
96
97 def generate(self) -> None:
98 data: J.Root = {
99 'version_major': J.VERSION_MAJOR,
100 'version_minor': J.VERSION_MINOR,
101 'meson_version': self._extract_meson_version(),
102 'functions': {x.name: self._generate_function(x) for x in self.sorted_and_filtered(self.functions)},
103 'objects': {x.name: self._generate_objects(x) for x in self.sorted_and_filtered(self.objects)},
104 'objects_by_type': {
105 'elementary': [x.name for x in self.elementary],
106 'builtins': [x.name for x in self.builtins],
107 'returned': [x.name for x in self.returned],
108 'modules': {
109 x.name: [y.name for y in self.sorted_and_filtered(self.extract_returned_by_module(x))]
110 for x in self.modules
111 },
112 },
113 }
114
115 self.out.write_text(json.dumps(data), encoding='utf-8')