Debian Codegraph @

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

raw
1 # SPDX-License-Identifier: Apache-2.0
2 # Copyright 2021 The Meson development team
3
4 from abc import ABCMeta, abstractmethod
5 from pathlib import Path
6 import re
7 import typing as T
8
9 from .model import (
10 NamedObject,
11 FetureCheck,
12 ArgBase,
13 PosArg,
14 DataTypeInfo,
15 Type,
16 Function,
17 Method,
18 Object,
19 ObjectType,
20 ReferenceManual,
21 )
22
23 from mesonbuild import mlog
24
25 class _Resolver:
26 def __init__(self) -> None:
27 self.type_map: T.Dict[str, Object] = {}
28 self.func_map: T.Dict[str, T.Union[Function, Method]] = {}
29 self.processed_funcs: T.Set[str] = set()
30
31 def _validate_named_object(self, obj: NamedObject) -> None:
32 name_regex = re.compile(r'[a-zA-Z0-9_]+')
33 obj.name = obj.name.strip()
34 obj.description = obj.description.strip()
35 assert obj.name and obj.description, 'Both name and description must be set'
36 assert obj.name.islower(), f'Object names must be lower case ({obj.name})'
37 assert name_regex.match(obj.name) or obj.name == '[index]', f'Invalid name {obj.name}'
38
39 def _validate_feature_check(self, obj: FetureCheck) -> None:
40 meson_version_reg = re.compile(r'[0-9]+\.[0-9]+\.[0-9]+')
41 obj.since = obj.since.strip()
42 obj.deprecated = obj.deprecated.strip()
43 if obj.since:
44 assert meson_version_reg.match(obj.since)
45 if obj.deprecated:
46 assert meson_version_reg.match(obj.deprecated)
47
48 def _resolve_type(self, raw: str) -> Type:
49 typ = Type(raw)
50 # We can't use `types = raw.split('|')`, because of `list[str | env]`
51 types: T.List[str] = ['']
52 stack = 0
53 for c in raw:
54 if stack == 0 and c == '|':
55 types += ['']
56 continue
57 if c == '[':
58 stack += 1
59 if c == ']':
60 stack -= 1
61 types[-1] += c
62 types = [x.strip() for x in types]
63 for t in types:
64 t = t.strip()
65 idx = t.find('[')
66 base_type = t
67 held_type = None
68 if idx > 0:
69 base_type = t[:idx]
70 held_type = self._resolve_type(t[idx+1:-1])
71 assert base_type in self.type_map, f'No known object {t}'
72 obj = self.type_map[base_type]
73 typ.resolved += [DataTypeInfo(obj, held_type)]
74 return typ
75
76 def _validate_func(self, func: T.Union[Function, Method]) -> None:
77 # Always run basic checks, since they also slightly post-process (strip) some strings
78 self._validate_named_object(func)
79 self._validate_feature_check(func)
80
81 func_id = f'{func.obj.name}.{func.name}' if isinstance(func, Method) else func.name
82 if func_id in self.processed_funcs:
83 return
84
85 func.returns = self._resolve_type(func.returns.raw)
86
87 all_args: T.List[ArgBase] = []
88 all_args += func.posargs
89 all_args += func.optargs
90 all_args += func.kwargs.values()
91 all_args += [func.varargs] if func.varargs else []
92
93 for arg in all_args:
94 arg.type = self._resolve_type(arg.type.raw)
95
96 # Handle returned_by
97 for obj in func.returns.resolved:
98 obj.data_type.returned_by += [func]
99
100 # Handle kwargs inheritance
101 for base_name in func.kwargs_inherit:
102 base_name = base_name.strip()
103 assert base_name in self.func_map, f'Unknown base function `{base_name}` for {func.name}'
104 base = self.func_map[base_name]
105 if base_name not in self.processed_funcs:
106 self._validate_func(base)
107
108 curr_keys = set(func.kwargs.keys())
109 base_keys = set(base.kwargs.keys())
110
111 # Calculate the missing kwargs from the current set
112 missing = {k: v for k, v in base.kwargs.items() if k in base_keys - curr_keys}
113 func.kwargs.update(missing)
114
115 # Handle other args inheritance
116 _T = T.TypeVar('_T', bound=T.Union[ArgBase, T.List[PosArg]])
117 def resolve_inherit(name: str, curr: _T, resolver: T.Callable[[Function], _T]) -> _T:
118 if name and not curr:
119 name = name.strip()
120 assert name in self.func_map, f'Unknown base function `{name}` for {func.name}'
121 if name not in self.processed_funcs:
122 self._validate_func(self.func_map[name])
123 ref_args = resolver(self.func_map[name])
124 assert ref_args is not None, f'Inherited function `{name}` does not have inherited args set'
125 return ref_args
126 return curr
127
128 func.posargs = resolve_inherit(func.posargs_inherit, func.posargs, lambda x: x.posargs)
129 func.optargs = resolve_inherit(func.optargs_inherit, func.optargs, lambda x: x.optargs)
130 func.varargs = resolve_inherit(func.varargs_inherit, func.varargs, lambda x: x.varargs)
131
132 self.processed_funcs.add(func_id)
133
134 def validate_and_resolve(self, manual: ReferenceManual) -> ReferenceManual:
135 mlog.log('Validating loaded manual...')
136
137 # build type map and func map for methods
138 for obj in manual.objects:
139 assert obj.name not in self.type_map, f'Duplicate object name {obj.name}'
140 self.type_map[obj.name] = obj
141 for m in obj.methods:
142 mid = f'{obj.name}.{m.name}'
143 assert mid not in self.type_map, f'Duplicate method {mid}'
144 self.func_map[mid] = m
145
146 # Build func map for functions
147 for func in manual.functions:
148 assert func.name not in [*self.func_map.keys()], f'Duplicate function {func.name}'
149 self.func_map[func.name] = func
150
151 mlog.log('Validating functions...')
152 for func in manual.functions:
153 mlog.log(' -- validating', mlog.bold(func.name))
154 self._validate_func(func)
155
156 mlog.log('Validating objects...')
157 for obj in manual.objects:
158 mlog.log(' -- validating', mlog.bold(obj.name))
159 self._validate_named_object(obj)
160 self._validate_feature_check(obj)
161 # Resolve and validate inheritance
162 if obj.extends:
163 assert obj.extends in self.type_map, f'Unknown extends object {obj.extends} in {obj.name}'
164 obj.extends_obj = self.type_map[obj.extends]
165 obj.extends_obj.extended_by += [obj]
166 # Only returned objects can be associated with module
167 if obj.obj_type is not ObjectType.RETURNED:
168 assert obj.defined_by_module is None
169 for m in obj.methods:
170 assert m.obj is obj
171 self._validate_func(m)
172
173 # Resolve inherited methods
174 for obj in manual.objects:
175 inherited_methods = obj.inherited_methods
176 curr = obj.extends_obj
177 while curr is not None:
178 inherited_methods += curr.methods
179 curr = curr.extends_obj
180 return manual
181
182 class LoaderBase(metaclass=ABCMeta):
183 def __init__(self) -> None:
184 self._input_files: T.List[Path] = []
185
186 @property
187 def input_files(self) -> T.List[Path]:
188 return list(self._input_files)
189
190 def read_file(self, f: Path) -> str:
191 assert f.exists()
192 assert f.is_file()
193 self._input_files += [f.resolve()]
194 return f.read_text(encoding='utf-8')
195
196 @abstractmethod
197 def load_impl(self) -> ReferenceManual:
198 pass
199
200 def load(self) -> ReferenceManual:
201 self._input_files = [] # Reset input files
202 manual = self.load_impl()
203 resolver = _Resolver()
204 with mlog.nested():
205 return resolver.validate_and_resolve(manual)