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