File: index_transform.py

package info (click to toggle)
cppreference-doc 20170409-1
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 259,868 kB
  • sloc: xml: 570,184; python: 1,923; php: 520; makefile: 167; sh: 25; cpp: 9; ansic: 9
file content (208 lines) | stat: -rwxr-xr-x 7,567 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
#!/usr/bin/env python3
'''
    Copyright (C) 2011-2013  Povilas Kanapickas <povilas@radix.lt>

    This file is part of cppreference-doc

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see http://www.gnu.org/licenses/.
'''

'''
    This is a python script for various transformations of the index.

    Concrete transformations can be implemented by subclassing IndexTransform
    and overriding the provided hooks.

    process_item_hook:

    Called to output information of a feature and continue the processing of the
    children. By default just processes the children.
'''

import lxml.etree as e
import re

class IndexTransform:

    def __init__(self, ignore_typedefs=False, ignore_inherits=False):
        self.ignore_typedefs = ignore_typedefs
        self.ignore_inherits = ignore_inherits

    """ Returns the attribute 'attr' of 'el', raises exception on error
    """
    def get_attr(self, el, attr):
        a = el.get(attr)
        if not a:
            nm = el.get('name')
            if nm:
                nm_str = '( name: ' + nm + ' )'
            else:
                nm_str = ''
            raise Exception('Element \'' + el.tag + '\' does not have attribute \'' +
                             attr + '\' ' + nm_str)
        return str(a)

    """ Returns the relative link of 'el' to its parent, if any
    """
    def get_link(self, el, default = None):
        if not default:
            default = self.get_name(el)

        link = el.get('link')
        if link == None:
            return default
        if link == '.':
            return ''
        return str(link)

    """ Appends two possible empty relative links
    """
    def link_append(self, el, link, parent_link):
        if parent_link != '' and link != '':
            return parent_link + '/' + link
        return parent_link + link

    """ Returns the absolute link of el
    """
    def get_full_link(self, el, parent_link):

        if el.tag == 'typedef':
            alias_name = el.get('alias')
            if alias_name:
                return self.get_link(self.get_alias(el, alias_name))
            else:
                return self.link_append(el, self.get_link(el), parent_link)

        elif el.tag == 'constructor':
            d_link = parent_link.split('/')[-1]
            return self.link_append(el, self.get_link(el, default=d_link), parent_link)

        elif el.tag == 'destructor':
            d_link = '~' + parent_link.split('/')[-1]
            return self.link_append(el, self.get_link(el, default=d_link), parent_link)

        else:
            return self.link_append(el, self.get_link(el), parent_link)

    """ Returns the name of el """
    def get_name(self, el):
        return self.get_attr(el, 'name')

    """ Returns the full name (with the namespace qualification) of el """
    def get_full_name(self, el, parent_name):
        if not parent_name and el.tag in ['constructor', 'destructor',
                                          'overload', 'specialization']:
            raise Exception('element \'' + el.tag + '\' does not have a parent')

        if el.tag == 'constructor':
            return parent_name + '::' + parent_name.split('::')[-1]
        if el.tag == 'destructor':
            return parent_name + '::~' + parent_name.split('::')[-1]
        elif el.tag == 'specialization':
            return self.get_name(el) + '<' + parent_name + '>'
        elif el.tag == 'overload':
            return self.get_name(el) + '(' + parent_name + ')'
        else:
            name = ''
            if parent_name:
                name += parent_name + '::'
            name += self.get_name(el)
            return name

    """ Returns the element within the document that has a name that matches
        'name'
    """
    def get_alias(self, el, name):
        aliases = el.xpath('/index/class[@name = \'' + name + '\'] |' +
                            '/index/enum[@name = \'' + name + '\']')
        if len(aliases) == 0:
            raise Exception('No aliases found for \'' + name + '\'')
        if len(aliases) > 1:
            raise Exception('More than one alias found for \'' + name + '\'')
        return aliases[0]

    """ Processes one item """
    def process_item(self, el, parent_name, parent_link):
        if el.tag in ['const','function','class','enum','variable','typedef',
                      'constructor','destructor','specialization','overload']:

            full_name = self.get_full_name(el, parent_name)
            full_link = self.get_full_link(el, parent_link)

            self.process_item_hook(el, full_name, full_link)

        elif el.tag == 'inherits' and el.getparent().xpath('child::inherits')[0] == el:
            if self.ignore_inherits:
                return
            pending = el.getparent().xpath('child::inherits')
            self.inherits_worker(parent_name, pending, list())

    """ Processes children of an item """
    def process_children(self, el, parent_name, parent_link):

        if el.tag == 'class' or el.tag == 'enum':
            for child in el:
                self.process_item(child, parent_name, parent_link)
        elif el.tag == 'typedef':
            if self.ignore_typedefs:
                return

            alias_name = el.get('alias')
            if alias_name:
                target = self.get_alias(el, alias_name)
            else:
                return
            link = self.get_link(target)
            for target_ch in target:
                self.process_item(target_ch, parent_name, link)

    """ Pulls the contents of the inherited classes. Diamond inheritance is
        handled properly
    """
    def inherits_worker(self, parent_name, pending, finished):
        if len(pending) == 0:
            return

        current = pending.pop(0)

        # find the source class/enum
        source = self.get_alias(current, self.get_attr(current, 'name'))

        if not source in finished:
            finished.append(source)
            parent_link = self.get_attr(source, 'link')
            for source_ch in source:
                ignore_tags =  ['constructor', 'destructor', 'inherits', 'specialization', 'overload']
                if source_ch.tag in ignore_tags: pass
                elif source_ch.tag == 'function' and source_ch.get('name') == 'operator=': pass
                else:
                    self.process_item(source_ch, parent_name, parent_link)

        # append new elements
        more_pending = source.xpath('child::inherits')
        more_pending = [p for p in more_pending if not p is current]
        pending.extend(more_pending)

        self.inherits_worker(parent_name, pending, finished)

    """ Transforms the index """
    def transform(self, fn):
        root = e.parse(fn)
        elems = root.xpath('/index/*')
        for el in elems:
            self.process_item(el, '', '')

    """ Hooks """
    def process_item_hook(self, el, full_name, full_link):
        self.process_children(el, full_name, full_link)