• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1#!/usr/bin/env python3
2# Copyright (C) 2022 The Android Open Source Project
3#
4# Licensed under the Apache License, Version 2.0 (the 'License');
5# you may not use this file except in compliance with the License.
6# You may obtain a copy of the License at
7#
8#      http://www.apache.org/licenses/LICENSE-2.0
9#
10# Unless required by applicable law or agreed to in writing, software
11# distributed under the License is distributed on an 'AS IS' BASIS,
12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13# See the License for the specific language governing permissions and
14# limitations under the License.
15
16from dataclasses import dataclass
17from re import Match
18from typing import List, Optional, Tuple
19
20from python.generators.sql_processing.utils import ObjKind
21from python.generators.sql_processing.utils import extract_comment
22from python.generators.sql_processing.utils import match_pattern
23from python.generators.sql_processing.utils import PATTERN_BY_KIND
24
25
26class DocsExtractor:
27  """Extracts documentation for views/tables/functions from SQL."""
28  path: str
29  module_name: str
30  sql: str
31
32  @dataclass
33  class Annotation:
34    key: str
35    value: str
36
37  @dataclass
38  class Extract:
39    """Extracted documentation for a single view/table/function."""
40    obj_kind: ObjKind
41    obj_match: Match
42
43    description: str
44    annotations: List['DocsExtractor.Annotation']
45
46  def __init__(self, path: str, module_name: str, sql: str):
47    self.path = path
48    self.module_name = module_name
49    self.sql = sql
50
51    self.sql_lines = sql.split("\n")
52    self.errors = []
53
54  def extract(self) -> List[Extract]:
55    extracted = []
56    extracted += self._extract_for_kind(ObjKind.table_view)
57    extracted += self._extract_for_kind(ObjKind.function)
58    extracted += self._extract_for_kind(ObjKind.table_function)
59    extracted += self._extract_for_kind(ObjKind.macro)
60    return extracted
61
62  def _extract_for_kind(self, kind: ObjKind) -> List[Extract]:
63    line_number_to_matches = match_pattern(PATTERN_BY_KIND[kind], self.sql)
64    extracts = []
65    for line_number, match in sorted(list(line_number_to_matches.items())):
66      comment_lines = extract_comment(self.sql_lines, line_number)
67      e = self._extract_from_comment(kind, match, comment_lines)
68      if e:
69        extracts.append(e)
70    return extracts
71
72  def _extract_from_comment(self, kind: ObjKind, match: Match,
73                            comment_lines: List[str]) -> Optional[Extract]:
74    extract = DocsExtractor.Extract(kind, match, '', [])
75    for line in comment_lines:
76      assert line.startswith('--')
77
78      # Remove the comment.
79      comment_stripped = line.lstrip('--')
80      stripped = comment_stripped.lstrip()
81
82      # Check if the line is an annotation.
83      if not stripped.startswith('@'):
84        # We are not in annotation: if we haven't seen an annotation yet, we
85        # must be still be parsing the description. Just add to that
86        if not extract.annotations:
87          extract.description += comment_stripped + "\n"
88          continue
89
90        # Otherwise, add to the latest annotation.
91        extract.annotations[-1].value += " " + stripped
92        continue
93
94      # This line is an annotation: find its name and add a new entry
95      annotation, rest = stripped.split(' ', 1)
96      extract.annotations.append(DocsExtractor.Annotation(annotation, rest))
97    return extract
98