[thirdparty/kernel/stable.git] / Documentation / sphinx / rstFlatTable.py

#!/usr/bin/env python3
# -*- coding: utf-8; mode: python -*-
# pylint: disable=C0330, R0903, R0912

u"""
    flat-table
    ~~~~~~~~~~

    Implementation of the ``flat-table`` reST-directive.

    :copyright:  Copyright (C) 2016  Markus Heiser
    :license:    GPL Version 2, June 1991 see linux/COPYING for details.

    The ``flat-table`` (:py:class:`FlatTable`) is a double-stage list similar to
    the ``list-table`` with some additional features:

    * *column-span*: with the role ``cspan`` a cell can be extended through
      additional columns

    * *row-span*: with the role ``rspan`` a cell can be extended through
      additional rows

    * *auto span* rightmost cell of a table row over the missing cells on the
      right side of that table-row.  With Option ``:fill-cells:`` this behavior
      can changed from *auto span* to *auto fill*, which automaticly inserts
      (empty) cells instead of spanning the last cell.

    Options:

    * header-rows:   [int] count of header rows
    * stub-columns:  [int] count of stub columns
    * widths:        [[int] [int] ... ] widths of columns
    * fill-cells:    instead of autospann missing cells, insert missing cells

    roles:

    * cspan: [int] additionale columns (*morecols*)
    * rspan: [int] additionale rows (*morerows*)
"""

# ==============================================================================
# imports
# ==============================================================================

import sys

from docutils import nodes
from docutils.parsers.rst import directives, roles
from docutils.parsers.rst.directives.tables import Table
from docutils.utils import SystemMessagePropagation

# ==============================================================================
# common globals
# ==============================================================================

__version__  = '1.0'

PY3 = sys.version_info[0] == 3
PY2 = sys.version_info[0] == 2

if PY3:
    # pylint: disable=C0103, W0622
    unicode     = str
    basestring  = str

# ==============================================================================
def setup(app):
# ==============================================================================

    app.add_directive("flat-table", FlatTable)
    roles.register_local_role('cspan', c_span)
    roles.register_local_role('rspan', r_span)

    return dict(
        version = __version__,
        parallel_read_safe = True,
        parallel_write_safe = True
    )

# ==============================================================================
def c_span(name, rawtext, text, lineno, inliner, options=None, content=None):
# ==============================================================================
    # pylint: disable=W0613

    options  = options if options is not None else {}
    content  = content if content is not None else []
    nodelist = [colSpan(span=int(text))]
    msglist  = []
    return nodelist, msglist

# ==============================================================================
def r_span(name, rawtext, text, lineno, inliner, options=None, content=None):
# ==============================================================================
    # pylint: disable=W0613

    options  = options if options is not None else {}
    content  = content if content is not None else []
    nodelist = [rowSpan(span=int(text))]
    msglist  = []
    return nodelist, msglist


# ==============================================================================
class rowSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321
class colSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321
# ==============================================================================

# ==============================================================================
class FlatTable(Table):
# ==============================================================================

    u"""FlatTable (``flat-table``) directive"""

    option_spec = {
        'name': directives.unchanged
        , 'class': directives.class_option
        , 'header-rows': directives.nonnegative_int
        , 'stub-columns': directives.nonnegative_int
        , 'widths': directives.positive_int_list
        , 'fill-cells' : directives.flag }

    def run(self):

        if not self.content:
            error = self.state_machine.reporter.error(
                'The "%s" directive is empty; content required.' % self.name,
                nodes.literal_block(self.block_text, self.block_text),
                line=self.lineno)
            return [error]

        title, messages = self.make_title()
        node = nodes.Element()          # anonymous container for parsing
        self.state.nested_parse(self.content, self.content_offset, node)

        tableBuilder = ListTableBuilder(self)
        tableBuilder.parseFlatTableNode(node)
        tableNode = tableBuilder.buildTableNode()
        # SDK.CONSOLE()  # print --> tableNode.asdom().toprettyxml()
        if title:
            tableNode.insert(0, title)
        return [tableNode] + messages


# ==============================================================================
class ListTableBuilder(object):
# ==============================================================================

    u"""Builds a table from a double-stage list"""

    def __init__(self, directive):
        self.directive = directive
        self.rows      = []
        self.max_cols  = 0

    def buildTableNode(self):

        colwidths    = self.directive.get_column_widths(self.max_cols)
        if isinstance(colwidths, tuple):
            # Since docutils 0.13, get_column_widths returns a (widths,
            # colwidths) tuple, where widths is a string (i.e. 'auto').
            # See https://sourceforge.net/p/docutils/patches/120/.
            colwidths = colwidths[1]
        stub_columns = self.directive.options.get('stub-columns', 0)
        header_rows  = self.directive.options.get('header-rows', 0)

        table = nodes.table()
        tgroup = nodes.tgroup(cols=len(colwidths))
        table += tgroup


        for colwidth in colwidths:
            colspec = nodes.colspec(colwidth=colwidth)
            # FIXME: It seems, that the stub method only works well in the
            # absence of rowspan (observed by the html buidler, the docutils-xml
            # build seems OK).  This is not extraordinary, because there exists
            # no table directive (except *this* flat-table) which allows to
            # define coexistent of rowspan and stubs (there was no use-case
            # before flat-table). This should be reviewed (later).
            if stub_columns:
                colspec.attributes['stub'] = 1
                stub_columns -= 1
            tgroup += colspec
        stub_columns = self.directive.options.get('stub-columns', 0)

        if header_rows:
            thead = nodes.thead()
            tgroup += thead
            for row in self.rows[:header_rows]:
                thead += self.buildTableRowNode(row)

        tbody = nodes.tbody()
        tgroup += tbody

        for row in self.rows[header_rows:]:
            tbody += self.buildTableRowNode(row)
        return table

    def buildTableRowNode(self, row_data, classes=None):
        classes = [] if classes is None else classes
        row = nodes.row()
        for cell in row_data:
            if cell is None:
                continue
            cspan, rspan, cellElements = cell

            attributes = {"classes" : classes}
            if rspan:
                attributes['morerows'] = rspan
            if cspan:
                attributes['morecols'] = cspan
            entry = nodes.entry(**attributes)
            entry.extend(cellElements)
            row += entry
        return row

    def raiseError(self, msg):
        error =  self.directive.state_machine.reporter.error(
            msg
            , nodes.literal_block(self.directive.block_text
                                  , self.directive.block_text)
            , line = self.directive.lineno )
        raise SystemMessagePropagation(error)

    def parseFlatTableNode(self, node):
        u"""parses the node from a :py:class:`FlatTable` directive's body"""

        if len(node) != 1 or not isinstance(node[0], nodes.bullet_list):
            self.raiseError(
                'Error parsing content block for the "%s" directive: '
                'exactly one bullet list expected.' % self.directive.name )

        for rowNum, rowItem in enumerate(node[0]):
            row = self.parseRowItem(rowItem, rowNum)
            self.rows.append(row)
        self.roundOffTableDefinition()

    def roundOffTableDefinition(self):
        u"""Round off the table definition.

        This method rounds off the table definition in :py:member:`rows`.

        * This method inserts the needed ``None`` values for the missing cells
        arising from spanning cells over rows and/or columns.

        * recount the :py:member:`max_cols`

        * Autospan or fill (option ``fill-cells``) missing cells on the right
          side of the table-row
        """

        y = 0
        while y < len(self.rows):
            x = 0

            while x < len(self.rows[y]):
                cell = self.rows[y][x]
                if cell is None:
                    x += 1
                    continue
                cspan, rspan = cell[:2]
                # handle colspan in current row
                for c in range(cspan):
                    try:
                        self.rows[y].insert(x+c+1, None)
                    except: # pylint: disable=W0702
                        # the user sets ambiguous rowspans
                        pass # SDK.CONSOLE()
                # handle colspan in spanned rows
                for r in range(rspan):
                    for c in range(cspan + 1):
                        try:
                            self.rows[y+r+1].insert(x+c, None)
                        except: # pylint: disable=W0702
                            # the user sets ambiguous rowspans
                            pass # SDK.CONSOLE()
                x += 1
            y += 1

        # Insert the missing cells on the right side. For this, first
        # re-calculate the max columns.

        for row in self.rows:
            if self.max_cols < len(row):
                self.max_cols = len(row)

        # fill with empty cells or cellspan?

        fill_cells = False
        if 'fill-cells' in self.directive.options:
            fill_cells = True

        for row in self.rows:
            x =  self.max_cols - len(row)
            if x and not fill_cells:
                if row[-1] is None:
                    row.append( ( x - 1, 0, []) )
                else:
                    cspan, rspan, content = row[-1]
                    row[-1] = (cspan + x, rspan, content)
            elif x and fill_cells:
                for i in range(x):
                    row.append( (0, 0, nodes.comment()) )

    def pprint(self):
        # for debugging
        retVal = "[   "
        for row in self.rows:
            retVal += "[ "
            for col in row:
                if col is None:
                    retVal += ('%r' % col)
                    retVal += "\n    , "
                else:
                    content = col[2][0].astext()
                    if len (content) > 30:
                        content = content[:30] + "..."
                    retVal += ('(cspan=%s, rspan=%s, %r)'
                               % (col[0], col[1], content))
                    retVal += "]\n    , "
            retVal = retVal[:-2]
            retVal += "]\n  , "
        retVal = retVal[:-2]
        return retVal + "]"

    def parseRowItem(self, rowItem, rowNum):
        row = []
        childNo = 0
        error   = False
        cell    = None
        target  = None

        for child in rowItem:
            if (isinstance(child , nodes.comment)
                or isinstance(child, nodes.system_message)):
                pass
            elif isinstance(child , nodes.target):
                target = child
            elif isinstance(child, nodes.bullet_list):
                childNo += 1
                cell = child
            else:
                error = True
                break

        if childNo != 1 or error:
            self.raiseError(
                'Error parsing content block for the "%s" directive: '
                'two-level bullet list expected, but row %s does not '
                'contain a second-level bullet list.'
                % (self.directive.name, rowNum + 1))

        for cellItem in cell:
            cspan, rspan, cellElements = self.parseCellItem(cellItem)
            if target is not None:
                cellElements.insert(0, target)
            row.append( (cspan, rspan, cellElements) )
        return row

    def parseCellItem(self, cellItem):
        # search and remove cspan, rspan colspec from the first element in
        # this listItem (field).
        cspan = rspan = 0
        if not len(cellItem):
            return cspan, rspan, []
        for elem in cellItem[0]:
            if isinstance(elem, colSpan):
                cspan = elem.get("span")
                elem.parent.remove(elem)
                continue
            if isinstance(elem, rowSpan):
                rspan = elem.get("span")
                elem.parent.remove(elem)
                continue
        return cspan, rspan, cellItem[:]
Commit	Line	Data
0249a764 MH	1	#!/usr/bin/env python3
	2	# -- coding: utf-8; mode: python --
	3	# pylint: disable=C0330, R0903, R0912
	4
	5	u"""
	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
	45	import sys
	46
	47	from docutils import nodes
	48	from docutils.parsers.rst import directives, roles
	49	from docutils.parsers.rst.directives.tables import Table
	50	from docutils.utils import SystemMessagePropagation
	51
	52	# ==============================================================================
	53	# common globals
	54	# ==============================================================================
	55
0249a764 MH	56	__version__ = '1.0'
	57
	58	PY3 = sys.version_info[0] == 3
	59	PY2 = sys.version_info[0] == 2
	60
	61	if PY3:
	62	# pylint: disable=C0103, W0622
	63	unicode = str
	64	basestring = str
	65
	66	# ==============================================================================
	67	def 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
b62b9d81 MH	74	return dict(
	75	version = __version__,
	76	parallel_read_safe = True,
	77	parallel_write_safe = True
	78	)
	79
0249a764 MH	80	# ==============================================================================
	81	def 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	# ==============================================================================
	92	def 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	# ==============================================================================
	104	class rowSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321
	105	class colSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321
	106	# ==============================================================================
	107
	108	# ==============================================================================
	109	class 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	# ==============================================================================
145	class 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)
217e2bfa DS	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]
0249a764 MH	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[:]