1#!/usr/bin/env python3 2# -*- coding: utf-8; mode: python -*- 3# SPDX-License-Identifier: GPL-2.0 4# pylint: disable=C0330, R0903, R0912 5 6""" 7 flat-table 8 ~~~~~~~~~~ 9 10 Implementation of the ``flat-table`` reST-directive. 11 12 :copyright: Copyright (C) 2016 Markus Heiser 13 :license: GPL Version 2, June 1991 see linux/COPYING for details. 14 15 The ``flat-table`` (:py:class:`FlatTable`) is a double-stage list similar to 16 the ``list-table`` with some additional features: 17 18 * *column-span*: with the role ``cspan`` a cell can be extended through 19 additional columns 20 21 * *row-span*: with the role ``rspan`` a cell can be extended through 22 additional rows 23 24 * *auto span* rightmost cell of a table row over the missing cells on the 25 right side of that table-row. With Option ``:fill-cells:`` this behavior 26 can be changed from *auto span* to *auto fill*, which automatically inserts 27 (empty) cells instead of spanning the last cell. 28 29 Options: 30 31 * header-rows: [int] count of header rows 32 * stub-columns: [int] count of stub columns 33 * widths: [[int] [int] ... ] widths of columns 34 * fill-cells: instead of autospann missing cells, insert missing cells 35 36 roles: 37 38 * cspan: [int] additionale columns (*morecols*) 39 * rspan: [int] additionale rows (*morerows*) 40""" 41 42# ============================================================================== 43# imports 44# ============================================================================== 45 46from docutils import nodes 47from docutils.parsers.rst import directives, roles 48from docutils.parsers.rst.directives.tables import Table 49from docutils.utils import SystemMessagePropagation 50 51# ============================================================================== 52# common globals 53# ============================================================================== 54 55__version__ = '1.0' 56 57# ============================================================================== 58def setup(app): 59# ============================================================================== 60 61 app.add_directive("flat-table", FlatTable) 62 roles.register_local_role('cspan', c_span) 63 roles.register_local_role('rspan', r_span) 64 65 return dict( 66 version = __version__, 67 parallel_read_safe = True, 68 parallel_write_safe = True 69 ) 70 71# ============================================================================== 72def c_span(name, rawtext, text, lineno, inliner, options=None, content=None): 73# ============================================================================== 74 # pylint: disable=W0613 75 76 options = options if options is not None else {} 77 content = content if content is not None else [] 78 nodelist = [colSpan(span=int(text))] 79 msglist = [] 80 return nodelist, msglist 81 82# ============================================================================== 83def r_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 = [rowSpan(span=int(text))] 90 msglist = [] 91 return nodelist, msglist 92 93 94# ============================================================================== 95class rowSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321 96class colSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321 97# ============================================================================== 98 99# ============================================================================== 100class FlatTable(Table): 101# ============================================================================== 102 103 """FlatTable (``flat-table``) directive""" 104 105 option_spec = { 106 'name': directives.unchanged 107 , 'class': directives.class_option 108 , 'header-rows': directives.nonnegative_int 109 , 'stub-columns': directives.nonnegative_int 110 , 'widths': directives.positive_int_list 111 , 'fill-cells' : directives.flag } 112 113 def run(self): 114 115 if not self.content: 116 error = self.state_machine.reporter.error( 117 'The "%s" directive is empty; content required.' % self.name, 118 nodes.literal_block(self.block_text, self.block_text), 119 line=self.lineno) 120 return [error] 121 122 title, messages = self.make_title() 123 node = nodes.Element() # anonymous container for parsing 124 self.state.nested_parse(self.content, self.content_offset, node) 125 126 tableBuilder = ListTableBuilder(self) 127 tableBuilder.parseFlatTableNode(node) 128 tableNode = tableBuilder.buildTableNode() 129 # SDK.CONSOLE() # print --> tableNode.asdom().toprettyxml() 130 if title: 131 tableNode.insert(0, title) 132 return [tableNode] + messages 133 134 135# ============================================================================== 136class ListTableBuilder(object): 137# ============================================================================== 138 139 """Builds a table from a double-stage list""" 140 141 def __init__(self, directive): 142 self.directive = directive 143 self.rows = [] 144 self.max_cols = 0 145 146 def buildTableNode(self): 147 148 colwidths = self.directive.get_column_widths(self.max_cols) 149 if isinstance(colwidths, tuple): 150 # Since docutils 0.13, get_column_widths returns a (widths, 151 # colwidths) tuple, where widths is a string (i.e. 'auto'). 152 # See https://sourceforge.net/p/docutils/patches/120/. 153 colwidths = colwidths[1] 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 builder, 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 """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 """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[:] 366