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