Debian Codegraph @

subprojects/meson-docs/docs/refman/generatorc.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 OBJ_MAP = {
25 'build_machine': 'machine',
26 'build_tgt': 'build_target',
27 'cfg_data': 'configuration_data',
28 'cmake': None,
29 'cmake_options': None,
30 'custom_idx': None,
31 'custom_tgt': 'custom_target',
32 'dep': 'dependency',
33 'env': 'environment',
34 'feature': 'feature_opt',
35 'int': 'number',
36 'list': 'array',
37 'runresult': 'run_result',
38 'str': 'string',
39 }
40
41 class GeneratorC(GeneratorBase):
42 def __init__(self, manual: ReferenceManual, out: Path, enable_modules: bool) -> None:
43 super().__init__(manual)
44 self.out = out
45 self.enable_modules = enable_modules
46
47 def _generate_type(self, typ: Type) -> T.List[J.Type]:
48 return [
49 {
50 'obj': x.data_type.name,
51 'holds': self._generate_type(x.holds) if x.holds else [],
52 }
53 for x in typ.resolved
54 ]
55
56 def _generate_type_str(self, typ: Type) -> str:
57 # Remove all whitespaces
58 return re.sub(r'[ \n\r\t]', '', typ.raw)
59
60 def _generate_arg(self, arg: T.Union[PosArg, VarArgs, Kwarg], isOptarg: bool = False) -> J.Argument:
61 return {
62 'name': arg.name,
63 'description': arg.description,
64 'since': arg.since if arg.since else None,
65 'deprecated': arg.deprecated if arg.deprecated else None,
66 'type': self._generate_type(arg.type),
67 'type_str': self._generate_type_str(arg.type),
68 'required': arg.required if isinstance(arg, Kwarg) else not isOptarg and not isinstance(arg, VarArgs),
69 'default': arg.default if isinstance(arg, (PosArg, Kwarg)) else None,
70 'min_varargs': arg.min_varargs if isinstance(arg, VarArgs) and arg.min_varargs > 0 else None,
71 'max_varargs': arg.max_varargs if isinstance(arg, VarArgs) and arg.max_varargs > 0 else None,
72
73 # Not yet supported
74 'notes': [],
75 'warnings': [],
76 }
77
78 def _cstr(self, s: str) -> str:
79 s = s.replace('\\', '\\\\')
80 s = s.replace('\n', '\\n')
81 s = s.replace('"', '\\"')
82 return f'"{s}"'
83
84 def _wrap(self, s):
85 return f"{{ {s} }}"
86
87 def _cstr_struct(self, d):
88 elems = []
89 for k, v in d.items():
90 if v is True:
91 s = "true"
92 elif v is False:
93 s = "false"
94 elif type(v) is int:
95 s = str(v)
96 else:
97 s = self._cstr(v)
98
99 elems.append(f".{k} = {s}")
100
101 return self._wrap(', '.join(elems))
102
103 def _generate_function(self, func: Function) -> str:
104 posargs = []
105 kwargs = []
106
107 for arg in func.posargs:
108 posargs.append({
109 'common.name': arg.name,
110 'common.description': arg.description,
111 'common.type': self._generate_type_str(arg.type),
112 })
113
114 for arg in func.optargs:
115 posargs.append({
116 'common.name': arg.name,
117 'common.description': arg.description,
118 'common.type': self._generate_type_str(arg.type),
119 'optional': True,
120 })
121
122 if func.varargs:
123 posargs.append({
124 'common.name': func.varargs.name,
125 'common.description': func.varargs.description,
126 'common.type': self._generate_type_str(func.varargs.type),
127 'glob': True,
128 })
129
130 for arg in self.sorted_and_filtered(list(func.kwargs.values())):
131 kwargs.append({
132 'common.name': arg.name,
133 'common.description': arg.description,
134 'optional': True,
135 })
136
137 return {
138 'common.name': func.name,
139 'common.description': func.description,
140 'common.type': self._generate_type_str(func.returns),
141 'posargs_len': len(posargs),
142 'kwargs_len': len(kwargs),
143 }, posargs, kwargs
144
145 # 'since': func.since if func.since else None,
146 # 'deprecated': func.deprecated if func.deprecated else None,
147 # 'notes': func.notes,
148 # 'warnings': func.warnings,
149 # 'example': func.example if func.example else None,
150 # 'returns': self._generate_type(func.returns),
151 # 'returns_str': self._generate_type_str(func.returns),
152 # 'posargs': {x.name: self._generate_arg(x) },
153 # 'optargs': {x.name: self._generate_arg(x, True) for x in func.optargs},
154 # 'kwargs': {x.name: self._generate_arg(x) for x in self.sorted_and_filtered(list(func.kwargs.values()))},
155 # 'varargs': self._generate_arg(func.varargs) if func.varargs else None,
156 # 'arg_flattening': func.arg_flattening,
157 # }
158
159 def _generate_objects(self, obj: Object) -> J.Object:
160 return {
161 'name': obj.name,
162 'description': obj.description,
163 'since': obj.since if obj.since else None,
164 'deprecated': obj.deprecated if obj.deprecated else None,
165 'notes': obj.notes,
166 'warnings': obj.warnings,
167 'defined_by_module': obj.defined_by_module.name if obj.defined_by_module else None,
168 'object_type': obj.obj_type.name,
169 'is_container': obj.is_container,
170 'example': obj.example if obj.example else None,
171 'extends': obj.extends if obj.extends else None,
172 'returned_by': [x.name for x in self.sorted_and_filtered(obj.returned_by)],
173 'extended_by': [x.name for x in self.sorted_and_filtered(obj.extended_by)],
174 'methods': {x.name: self._generate_function(x) for x in self.sorted_and_filtered(obj.methods)},
175 }
176
177 def generate(self) -> None:
178 prefix = 'meson_doc_'
179 text = ''
180
181 posargs = []
182 kwargs = []
183 funcs = { '0': [] }
184
185 def add_function(group_name, func):
186 f, p, k = self._generate_function(func)
187 f['posargs_start'] = len(posargs)
188 f['kwargs_start'] = len(kwargs)
189 funcs[group_name].append(self._cstr_struct(f))
190 posargs.extend([self._cstr_struct(x) for x in p])
191 kwargs.extend([self._cstr_struct(x) for x in k])
192
193 for x in self.sorted_and_filtered(self.functions):
194 add_function('0', x)
195
196 for x in self.sorted_and_filtered(self.objects):
197 if x.name in OBJ_MAP:
198 o = OBJ_MAP[x.name]
199 else:
200 o = x.name
201
202 if o is None:
203 continue
204
205 o = f'obj_{o}'
206
207 for y in self.sorted_and_filtered(x.methods):
208 if o not in funcs:
209 funcs[o] = []
210 add_function(o, y)
211
212 text += f'struct {prefix}entry_arg {prefix}posargs[] = {{\n'
213 for o in posargs:
214 text += f'\t{o},\n'
215
216 text += '};\n'
217
218 text += f'struct {prefix}entry_arg {prefix}kwargs[] = {{\n'
219 for o in kwargs:
220 text += f'\t{o},\n'
221
222 text += '};\n'
223
224 for o in funcs:
225 text += f'struct {prefix}entry_func {prefix}object_{o}[] = {{\n'
226
227 for f in funcs[o]:
228 text += '\t' + f + ',\n'
229
230 text += '\t{ 0 },\n'
231
232 text += '};\n\n'
233
234 text += f'struct {prefix}entry_func *{prefix}root[obj_type_count] = {{\n'
235
236 for o in funcs:
237 text += f'\t[{o}] = {prefix}object_{o},\n'
238
239 text += '};\n'
240
241 self.out.write_text(
242 text.lstrip(),
243 encoding='utf-8',
244 )
245
246 # data: J.Root = {
247 # 'version_major': J.VERSION_MAJOR,
248 # 'version_minor': J.VERSION_MINOR,
249 # 'meson_version': self._extract_meson_version(),
250 # 'functions': {x.name: self._generate_function(x) for x in self.sorted_and_filtered(self.functions)},
251 # 'objects': {x.name: self._generate_objects(x) for x in self.sorted_and_filtered(self.objects)},
252 # 'objects_by_type': {
253 # 'elementary': [x.name for x in self.elementary],
254 # 'builtins': [x.name for x in self.builtins],
255 # 'returned': [x.name for x in self.returned],
256 # 'modules': {
257 # x.name: [y.name for y in self.sorted_and_filtered(self.extract_returned_by_module(x))]
258 # for x in self.modules
259 # },
260 # },
261 # }
262
263 # self.out.write_text(json.dumps(data), encoding='utf-8')