scripts/qapi/parser.py

1 # -*- coding: utf-8 -*-
6 # Copyright (c) 2013-2019 Red Hat Inc.
11 #  Marc-André Lureau <marcandre.lureau@redhat.com>
15 # See the COPYING file in the top-level directory.
38     # pylint: disable=cyclic-import
39     # TODO: Remove cycle. [schema -> expr -> parser -> schema]
48     # pylint: disable=too-few-public-methods
74     Parse a JSON-esque schema file and process directives.  See
75     qapi-code-gen.rst section "Schema Syntax" for the exact syntax.
87     :ivar docs: Resulting parsed documentation blocks.
111         self.docs: List[QAPIDoc] = []
116     def _parse(self) -> None:
120         :return: None.  Results are stored in ``.exprs`` and ``.docs``.
125         with open(self._fname, 'r', encoding='utf-8') as fp:
127         if self.src == '' or self.src[-1] != '\n':
139                 self.docs.append(cur_doc)
145                     info, "top-level expression must be an object")
162                     self.docs.extend(exprs_include.docs)
183                   doc: Optional['QAPIDoc'] = None) -> None:
187     def reject_expr_doc(doc: Optional['QAPIDoc']) -> None:
199                  ) -> Optional['QAPISchemaParser']:
221     def _pragma(name: str, value: object, info: QAPISourceInfo) -> None:
223         def check_list_str(name: str, value: object) -> List[str]:
233         if name == 'doc-required':
236                                    "pragma 'doc-required' must be boolean")
238         elif name == 'command-name-exceptions':
240         elif name == 'command-returns-exceptions':
242         elif name == 'documentation-exceptions':
244         elif name == 'member-name-exceptions':
249     def accept(self, skip_comment: bool = True) -> None:
260             - ``.tok`` represents the token type.  See below for values.
261             - ``.info`` describes the token's source location.
262             - ``.val`` is the token's value, if any.  See below.
263             - ``.pos`` is the buffer index of the first character of
266         * Single-character tokens:
271         * Multi-character tokens:
277             ``.val`` is a string including all chars until end-of-line,
354                                    self.src[self.cursor-1:])
357     def get_members(self) -> Dict[str, object]:
384     def get_values(self) -> List[object]:
401     def get_expr(self) -> _ExprValue:
418     def get_doc_line(self) -> Optional[str]:
436     def _match_at_name_colon(string: str) -> Optional[Match[str]]:
439     def get_doc_indented(self, doc: 'QAPIDoc') -> Optional[str]:
466                     "unexpected de-indent (expected at least %d spaces)" %
471     def get_doc_paragraph(self, doc: 'QAPIDoc') -> Optional[str]:
481     def get_doc(self) -> 'QAPIDoc':
495             symbol = line[1:-1]
510                 # Non-blank line, first of a section
560                     # See commit message for more markup suggestions O:-)
573                             "supported. Please use the '.. qmp-example::' "
597             # Free-form documentation
605                         "'@%s:' not allowed in free-form documentation"
624     A documentation comment block, either definition or free-form
636     * additional (non-argument) sections, possibly tagged
638     Free-form documentation blocks consist only of a body section.
651         def from_string(kind: str) -> 'QAPIDoc.Kind':
654         def __str__(self) -> str:
658         # pylint: disable=too-few-public-methods
671         def __repr__(self) -> str:
674         def append_line(self, line: str) -> None:
688         def connect(self, member: 'QAPISchemaMember') -> None:
694         # definition doc's symbol, None for free-form doc
713     def end(self) -> None:
720     def ensure_untagged_section(self, info: QAPISourceInfo) -> None:
723         if self.all_sections and self.all_sections[-1].kind == kind:
725             section = self.all_sections[-1]
741     ) -> None:
767     ) -> None:
776     def new_argument(self, info: QAPISourceInfo, name: str) -> None:
779     def new_feature(self, info: QAPISourceInfo, name: str) -> None:
782     def append_line(self, line: str) -> None:
783         self.all_sections[-1].append_line(line)
785     def connect_member(self, member: 'QAPISchemaMember') -> None:
792             # Insert stub documentation section for missing member docs.
799             # Determine where to insert stub doc - it should go at the
811     def connect_feature(self, feature: 'QAPISchemaFeature') -> None:
818     def check_expr(self, expr: QAPIExpression) -> None:
834     def check(self) -> None:
838         ) -> None: