1#!/usr/bin/env python3
2# -*- coding: utf-8; mode: python -*-
3# pylint: disable=C0330, R0903, R0912
4
5u"""
6    flat-table
7    ~~~~~~~~~~
8
9    Implementation of the ``flat-table`` reST-directive.
10
11    :copyright:  Copyright (C) 2016  Markus Heiser
12    :license:    GPL Version 2, June 1991 see linux/COPYING for details.
13
14    The ``flat-table`` (:py:class:`FlatTable`) is a double-stage list similar to
15    the ``list-table`` with some additional features:
16
17    * *column-span*: with the role ``cspan`` a cell can be extended through
18      additional columns
19
20    * *row-span*: with the role ``rspan`` a cell can be extended through
21      additional rows
22
23    * *auto span* rightmost cell of a table row over the missing cells on the
24      right side of that table-row.  With Option ``:fill-cells:`` this behavior
25      can changed from *auto span* to *auto fill*, which automaticly inserts
26      (empty) cells instead of spanning the last cell.
27
28    Options:
29
30    * header-rows:   [int] count of header rows
31    * stub-columns:  [int] count of stub columns
32    * widths:        [[int] [int] ... ] widths of columns
33    * fill-cells:    instead of autospann missing cells, insert missing cells
34
35    roles:
36
37    * cspan: [int] additionale columns (*morecols*)
38    * rspan: [int] additionale rows (*morerows*)
39"""
40
41# ==============================================================================
42# imports
43# ==============================================================================
44
45import sys
46
47from docutils import nodes
48from docutils.parsers.rst import directives, roles
49from docutils.parsers.rst.directives.tables import Table
50from docutils.utils import SystemMessagePropagation
51
52# ==============================================================================
53# common globals
54# ==============================================================================
55
56# The version numbering follows numbering of the specification
57# (Documentation/books/kernel-doc-HOWTO).
58__version__  = '1.0'
59
60PY3 = sys.version_info[0] == 3
61PY2 = sys.version_info[0] == 2
62
63if PY3:
64    # pylint: disable=C0103, W0622
65    unicode     = str
66    basestring  = str
67
68# ==============================================================================
69def setup(app):
70# ==============================================================================
71
72    app.add_directive("flat-table", FlatTable)
73    roles.register_local_role('cspan', c_span)
74    roles.register_local_role('rspan', r_span)
75
76    return dict(
77        version = __version__,
78        parallel_read_safe = True,
79        parallel_write_safe = True
80    )
81
82# ==============================================================================
83def c_span(name, rawtext, text, lineno, inliner, options=None, content=None):
84# ==============================================================================
85    # pylint: disable=W0613
86
87    options  = options if options is not None else {}
88    content  = content if content is not None else []
89    nodelist = [colSpan(span=int(text))]
90    msglist  = []
91    return nodelist, msglist
92
93# ==============================================================================
94def r_span(name, rawtext, text, lineno, inliner, options=None, content=None):
95# ==============================================================================
96    # pylint: disable=W0613
97
98    options  = options if options is not None else {}
99    content  = content if content is not None else []
100    nodelist = [rowSpan(span=int(text))]
101    msglist  = []
102    return nodelist, msglist
103
104
105# ==============================================================================
106class rowSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321
107class colSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321
108# ==============================================================================
109
110# ==============================================================================
111class FlatTable(Table):
112# ==============================================================================
113
114    u"""FlatTable (``flat-table``) directive"""
115
116    option_spec = {
117        'name': directives.unchanged
118        , 'class': directives.class_option
119        , 'header-rows': directives.nonnegative_int
120        , 'stub-columns': directives.nonnegative_int
121        , 'widths': directives.positive_int_list
122        , 'fill-cells' : directives.flag }
123
124    def run(self):
125
126        if not self.content:
127            error = self.state_machine.reporter.error(
128                'The "%s" directive is empty; content required.' % self.name,
129                nodes.literal_block(self.block_text, self.block_text),
130                line=self.lineno)
131            return [error]
132
133        title, messages = self.make_title()
134        node = nodes.Element()          # anonymous container for parsing
135        self.state.nested_parse(self.content, self.content_offset, node)
136
137        tableBuilder = ListTableBuilder(self)
138        tableBuilder.parseFlatTableNode(node)
139        tableNode = tableBuilder.buildTableNode()
140        # SDK.CONSOLE()  # print --> tableNode.asdom().toprettyxml()
141        if title:
142            tableNode.insert(0, title)
143        return [tableNode] + messages
144
145
146# ==============================================================================
147class ListTableBuilder(object):
148# ==============================================================================
149
150    u"""Builds a table from a double-stage list"""
151
152    def __init__(self, directive):
153        self.directive = directive
154        self.rows      = []
155        self.max_cols  = 0
156
157    def buildTableNode(self):
158
159        colwidths    = self.directive.get_column_widths(self.max_cols)
160        if isinstance(colwidths, tuple):
161            # Since docutils 0.13, get_column_widths returns a (widths,
162            # colwidths) tuple, where widths is a string (i.e. 'auto').
163            # See https://sourceforge.net/p/docutils/patches/120/.
164            colwidths = colwidths[1]
165        stub_columns = self.directive.options.get('stub-columns', 0)
166        header_rows  = self.directive.options.get('header-rows', 0)
167
168        table = nodes.table()
169        tgroup = nodes.tgroup(cols=len(colwidths))
170        table += tgroup
171
172
173        for colwidth in colwidths:
174            colspec = nodes.colspec(colwidth=colwidth)
175            # FIXME: It seems, that the stub method only works well in the
176            # absence of rowspan (observed by the html buidler, the docutils-xml
177            # build seems OK).  This is not extraordinary, because there exists
178            # no table directive (except *this* flat-table) which allows to
179            # define coexistent of rowspan and stubs (there was no use-case
180            # before flat-table). This should be reviewed (later).
181            if stub_columns:
182                colspec.attributes['stub'] = 1
183                stub_columns -= 1
184            tgroup += colspec
185        stub_columns = self.directive.options.get('stub-columns', 0)
186
187        if header_rows:
188            thead = nodes.thead()
189            tgroup += thead
190            for row in self.rows[:header_rows]:
191                thead += self.buildTableRowNode(row)
192
193        tbody = nodes.tbody()
194        tgroup += tbody
195
196        for row in self.rows[header_rows:]:
197            tbody += self.buildTableRowNode(row)
198        return table
199
200    def buildTableRowNode(self, row_data, classes=None):
201        classes = [] if classes is None else classes
202        row = nodes.row()
203        for cell in row_data:
204            if cell is None:
205                continue
206            cspan, rspan, cellElements = cell
207
208            attributes = {"classes" : classes}
209            if rspan:
210                attributes['morerows'] = rspan
211            if cspan:
212                attributes['morecols'] = cspan
213            entry = nodes.entry(**attributes)
214            entry.extend(cellElements)
215            row += entry
216        return row
217
218    def raiseError(self, msg):
219        error =  self.directive.state_machine.reporter.error(
220            msg
221            , nodes.literal_block(self.directive.block_text
222                                  , self.directive.block_text)
223            , line = self.directive.lineno )
224        raise SystemMessagePropagation(error)
225
226    def parseFlatTableNode(self, node):
227        u"""parses the node from a :py:class:`FlatTable` directive's body"""
228
229        if len(node) != 1 or not isinstance(node[0], nodes.bullet_list):
230            self.raiseError(
231                'Error parsing content block for the "%s" directive: '
232                'exactly one bullet list expected.' % self.directive.name )
233
234        for rowNum, rowItem in enumerate(node[0]):
235            row = self.parseRowItem(rowItem, rowNum)
236            self.rows.append(row)
237        self.roundOffTableDefinition()
238
239    def roundOffTableDefinition(self):
240        u"""Round off the table definition.
241
242        This method rounds off the table definition in :py:member:`rows`.
243
244        * This method inserts the needed ``None`` values for the missing cells
245        arising from spanning cells over rows and/or columns.
246
247        * recount the :py:member:`max_cols`
248
249        * Autospan or fill (option ``fill-cells``) missing cells on the right
250          side of the table-row
251        """
252
253        y = 0
254        while y < len(self.rows):
255            x = 0
256
257            while x < len(self.rows[y]):
258                cell = self.rows[y][x]
259                if cell is None:
260                    x += 1
261                    continue
262                cspan, rspan = cell[:2]
263                # handle colspan in current row
264                for c in range(cspan):
265                    try:
266                        self.rows[y].insert(x+c+1, None)
267                    except: # pylint: disable=W0702
268                        # the user sets ambiguous rowspans
269                        pass # SDK.CONSOLE()
270                # handle colspan in spanned rows
271                for r in range(rspan):
272                    for c in range(cspan + 1):
273                        try:
274                            self.rows[y+r+1].insert(x+c, None)
275                        except: # pylint: disable=W0702
276                            # the user sets ambiguous rowspans
277                            pass # SDK.CONSOLE()
278                x += 1
279            y += 1
280
281        # Insert the missing cells on the right side. For this, first
282        # re-calculate the max columns.
283
284        for row in self.rows:
285            if self.max_cols < len(row):
286                self.max_cols = len(row)
287
288        # fill with empty cells or cellspan?
289
290        fill_cells = False
291        if 'fill-cells' in self.directive.options:
292            fill_cells = True
293
294        for row in self.rows:
295            x =  self.max_cols - len(row)
296            if x and not fill_cells:
297                if row[-1] is None:
298                    row.append( ( x - 1, 0, []) )
299                else:
300                    cspan, rspan, content = row[-1]
301                    row[-1] = (cspan + x, rspan, content)
302            elif x and fill_cells:
303                for i in range(x):
304                    row.append( (0, 0, nodes.comment()) )
305
306    def pprint(self):
307        # for debugging
308        retVal = "[   "
309        for row in self.rows:
310            retVal += "[ "
311            for col in row:
312                if col is None:
313                    retVal += ('%r' % col)
314                    retVal += "\n    , "
315                else:
316                    content = col[2][0].astext()
317                    if len (content) > 30:
318                        content = content[:30] + "..."
319                    retVal += ('(cspan=%s, rspan=%s, %r)'
320                               % (col[0], col[1], content))
321                    retVal += "]\n    , "
322            retVal = retVal[:-2]
323            retVal += "]\n  , "
324        retVal = retVal[:-2]
325        return retVal + "]"
326
327    def parseRowItem(self, rowItem, rowNum):
328        row = []
329        childNo = 0
330        error   = False
331        cell    = None
332        target  = None
333
334        for child in rowItem:
335            if (isinstance(child , nodes.comment)
336                or isinstance(child, nodes.system_message)):
337                pass
338            elif isinstance(child , nodes.target):
339                target = child
340            elif isinstance(child, nodes.bullet_list):
341                childNo += 1
342                cell = child
343            else:
344                error = True
345                break
346
347        if childNo != 1 or error:
348            self.raiseError(
349                'Error parsing content block for the "%s" directive: '
350                'two-level bullet list expected, but row %s does not '
351                'contain a second-level bullet list.'
352                % (self.directive.name, rowNum + 1))
353
354        for cellItem in cell:
355            cspan, rspan, cellElements = self.parseCellItem(cellItem)
356            if target is not None:
357                cellElements.insert(0, target)
358            row.append( (cspan, rspan, cellElements) )
359        return row
360
361    def parseCellItem(self, cellItem):
362        # search and remove cspan, rspan colspec from the first element in
363        # this listItem (field).
364        cspan = rspan = 0
365        if not len(cellItem):
366            return cspan, rspan, []
367        for elem in cellItem[0]:
368            if isinstance(elem, colSpan):
369                cspan = elem.get("span")
370                elem.parent.remove(elem)
371                continue
372            if isinstance(elem, rowSpan):
373                rspan = elem.get("span")
374                elem.parent.remove(elem)
375                continue
376        return cspan, rspan, cellItem[:]
377