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