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