[mirror_ubuntu-bionic-kernel.git] / Documentation / sphinx / kernel_include.py

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

u"""
    kernel-include
    ~~~~~~~~~~~~~~

    Implementation of the ``kernel-include`` reST-directive.

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

    The ``kernel-include`` reST-directive is a replacement for the ``include``
    directive. The ``kernel-include`` directive expand environment variables in
    the path name and allows to include files from arbitrary locations.

    .. hint::

      Including files from arbitrary locations (e.g. from ``/etc``) is a
      security risk for builders. This is why the ``include`` directive from
      docutils *prohibit* pathnames pointing to locations *above* the filesystem
      tree where the reST document with the include directive is placed.

    Substrings of the form $name or ${name} are replaced by the value of
    environment variable name. Malformed variable names and references to
    non-existing variables are left unchanged.
"""

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

import os.path

from docutils import io, nodes, statemachine
from docutils.utils.error_reporting import SafeString, ErrorString
from docutils.parsers.rst import directives
from docutils.parsers.rst.directives.body import CodeBlock, NumberLines
from docutils.parsers.rst.directives.misc import Include

__version__  = '1.0'

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

    app.add_directive("kernel-include", KernelInclude)
    return dict(
        version = __version__,
        parallel_read_safe = True,
        parallel_write_safe = True
    )

# ==============================================================================
class KernelInclude(Include):
# ==============================================================================

    u"""KernelInclude (``kernel-include``) directive"""

    def run(self):
        path = os.path.realpath(
            os.path.expandvars(self.arguments[0]))

        # to get a bit security back, prohibit /etc:
        if path.startswith(os.sep + "etc"):
            raise self.severe(
                'Problems with "%s" directive, prohibited path: %s'
                % (self.name, path))

        self.arguments[0] = path

        #return super(KernelInclude, self).run() # won't work, see HINTs in _run()
        return self._run()

    def _run(self):
        """Include a file as part of the content of this reST file."""

        # HINT: I had to copy&paste the whole Include.run method. I'am not happy
        # with this, but due to security reasons, the Include.run method does
        # not allow absolute or relative pathnames pointing to locations *above*
        # the filesystem tree where the reST document is placed.

        if not self.state.document.settings.file_insertion_enabled:
            raise self.warning('"%s" directive disabled.' % self.name)
        source = self.state_machine.input_lines.source(
            self.lineno - self.state_machine.input_offset - 1)
        source_dir = os.path.dirname(os.path.abspath(source))
        path = directives.path(self.arguments[0])
        if path.startswith('<') and path.endswith('>'):
            path = os.path.join(self.standard_include_path, path[1:-1])
        path = os.path.normpath(os.path.join(source_dir, path))

        # HINT: this is the only line I had to change / commented out:
        #path = utils.relative_path(None, path)

        path = nodes.reprunicode(path)
        encoding = self.options.get(
            'encoding', self.state.document.settings.input_encoding)
        e_handler=self.state.document.settings.input_encoding_error_handler
        tab_width = self.options.get(
            'tab-width', self.state.document.settings.tab_width)
        try:
            self.state.document.settings.record_dependencies.add(path)
            include_file = io.FileInput(source_path=path,
                                        encoding=encoding,
                                        error_handler=e_handler)
        except UnicodeEncodeError as error:
            raise self.severe('Problems with "%s" directive path:\n'
                              'Cannot encode input file path "%s" '
                              '(wrong locale?).' %
                              (self.name, SafeString(path)))
        except IOError as error:
            raise self.severe('Problems with "%s" directive path:\n%s.' %
                      (self.name, ErrorString(error)))
        startline = self.options.get('start-line', None)
        endline = self.options.get('end-line', None)
        try:
            if startline or (endline is not None):
                lines = include_file.readlines()
                rawtext = ''.join(lines[startline:endline])
            else:
                rawtext = include_file.read()
        except UnicodeError as error:
            raise self.severe('Problem with "%s" directive:\n%s' %
                              (self.name, ErrorString(error)))
        # start-after/end-before: no restrictions on newlines in match-text,
        # and no restrictions on matching inside lines vs. line boundaries
        after_text = self.options.get('start-after', None)
        if after_text:
            # skip content in rawtext before *and incl.* a matching text
            after_index = rawtext.find(after_text)
            if after_index < 0:
                raise self.severe('Problem with "start-after" option of "%s" '
                                  'directive:\nText not found.' % self.name)
            rawtext = rawtext[after_index + len(after_text):]
        before_text = self.options.get('end-before', None)
        if before_text:
            # skip content in rawtext after *and incl.* a matching text
            before_index = rawtext.find(before_text)
            if before_index < 0:
                raise self.severe('Problem with "end-before" option of "%s" '
                                  'directive:\nText not found.' % self.name)
            rawtext = rawtext[:before_index]

        include_lines = statemachine.string2lines(rawtext, tab_width,
                                                  convert_whitespace=True)
        if 'literal' in self.options:
            # Convert tabs to spaces, if `tab_width` is positive.
            if tab_width >= 0:
                text = rawtext.expandtabs(tab_width)
            else:
                text = rawtext
            literal_block = nodes.literal_block(rawtext, source=path,
                                    classes=self.options.get('class', []))
            literal_block.line = 1
            self.add_name(literal_block)
            if 'number-lines' in self.options:
                try:
                    startline = int(self.options['number-lines'] or 1)
                except ValueError:
                    raise self.error(':number-lines: with non-integer '
                                     'start value')
                endline = startline + len(include_lines)
                if text.endswith('\n'):
                    text = text[:-1]
                tokens = NumberLines([([], text)], startline, endline)
                for classes, value in tokens:
                    if classes:
                        literal_block += nodes.inline(value, value,
                                                      classes=classes)
                    else:
                        literal_block += nodes.Text(value, value)
            else:
                literal_block += nodes.Text(text, text)
            return [literal_block]
        if 'code' in self.options:
            self.options['source'] = path
            codeblock = CodeBlock(self.name,
                                  [self.options.pop('code')], # arguments
                                  self.options,
                                  include_lines, # content
                                  self.lineno,
                                  self.content_offset,
                                  self.block_text,
                                  self.state,
                                  self.state_machine)
            return codeblock.run()
        self.state_machine.insert_input(include_lines, path)
        return []
Commit	Line	Data
03776378 MH	1	#!/usr/bin/env python3
	2	# -- coding: utf-8; mode: python --
	3	# pylint: disable=R0903, C0330, R0914, R0912, E0401
	4
	5	u"""
	6	kernel-include
	7	~~~~~~~~~~~~~~
	8
	9	Implementation of the ``kernel-include`` 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 ``kernel-include`` reST-directive is a replacement for the ``include``
	15	directive. The ``kernel-include`` directive expand environment variables in
	16	the path name and allows to include files from arbitrary locations.
	17
	18	.. hint::
	19
	20	Including files from arbitrary locations (e.g. from ``/etc``) is a
	21	security risk for builders. This is why the ``include`` directive from
	22	docutils prohibit pathnames pointing to locations above the filesystem
	23	tree where the reST document with the include directive is placed.
	24
	25	Substrings of the form $name or ${name} are replaced by the value of
	26	environment variable name. Malformed variable names and references to
	27	non-existing variables are left unchanged.
	28	"""
	29
	30	# ==============================================================================
	31	# imports
	32	# ==============================================================================
	33
	34	import os.path
	35
	36	from docutils import io, nodes, statemachine
	37	from docutils.utils.error_reporting import SafeString, ErrorString
	38	from docutils.parsers.rst import directives
	39	from docutils.parsers.rst.directives.body import CodeBlock, NumberLines
	40	from docutils.parsers.rst.directives.misc import Include
	41
b62b9d81 MH	42	__version__ = '1.0'
b62b9d81 MH	43
03776378 MH	44	# ==============================================================================
	45	def setup(app):
	46	# ==============================================================================
	47
	48	app.add_directive("kernel-include", KernelInclude)
b62b9d81 MH	49	return dict(
	50	version = __version__,
	51	parallel_read_safe = True,
	52	parallel_write_safe = True
	53	)
03776378 MH	54
	55	# ==============================================================================
	56	class KernelInclude(Include):
	57	# ==============================================================================
	58
	59	u"""KernelInclude (``kernel-include``) directive"""
	60
	61	def run(self):
	62	path = os.path.realpath(
	63	os.path.expandvars(self.arguments[0]))
	64
	65	# to get a bit security back, prohibit /etc:
	66	if path.startswith(os.sep + "etc"):
	67	raise self.severe(
	68	'Problems with "%s" directive, prohibited path: %s'
	69	% (self.name, path))
	70
	71	self.arguments[0] = path
	72
	73	#return super(KernelInclude, self).run() # won't work, see HINTs in _run()
	74	return self._run()
	75
	76	def _run(self):
	77	"""Include a file as part of the content of this reST file."""
	78
	79	# HINT: I had to copy&paste the whole Include.run method. I'am not happy
	80	# with this, but due to security reasons, the Include.run method does
	81	# not allow absolute or relative pathnames pointing to locations above
	82	# the filesystem tree where the reST document is placed.
	83
	84	if not self.state.document.settings.file_insertion_enabled:
	85	raise self.warning('"%s" directive disabled.' % self.name)
	86	source = self.state_machine.input_lines.source(
	87	self.lineno - self.state_machine.input_offset - 1)
	88	source_dir = os.path.dirname(os.path.abspath(source))
	89	path = directives.path(self.arguments[0])
	90	if path.startswith('<') and path.endswith('>'):
	91	path = os.path.join(self.standard_include_path, path[1:-1])
	92	path = os.path.normpath(os.path.join(source_dir, path))
	93
	94	# HINT: this is the only line I had to change / commented out:
	95	#path = utils.relative_path(None, path)
	96
	97	path = nodes.reprunicode(path)
	98	encoding = self.options.get(
	99	'encoding', self.state.document.settings.input_encoding)
	100	e_handler=self.state.document.settings.input_encoding_error_handler
	101	tab_width = self.options.get(
	102	'tab-width', self.state.document.settings.tab_width)
	103	try:
	104	self.state.document.settings.record_dependencies.add(path)
	105	include_file = io.FileInput(source_path=path,
	106	encoding=encoding,
	107	error_handler=e_handler)
	108	except UnicodeEncodeError as error:
	109	raise self.severe('Problems with "%s" directive path:\n'
	110	'Cannot encode input file path "%s" '
	111	'(wrong locale?).' %
	112	(self.name, SafeString(path)))
	113	except IOError as error:
	114	raise self.severe('Problems with "%s" directive path:\n%s.' %
	115	(self.name, ErrorString(error)))
	116	startline = self.options.get('start-line', None)
	117	endline = self.options.get('end-line', None)
118	try:
119	if startline or (endline is not None):
120	lines = include_file.readlines()
121	rawtext = ''.join(lines[startline:endline])
122	else:
123	rawtext = include_file.read()
124	except UnicodeError as error:
125	raise self.severe('Problem with "%s" directive:\n%s' %
126	(self.name, ErrorString(error)))
127	# start-after/end-before: no restrictions on newlines in match-text,
128	# and no restrictions on matching inside lines vs. line boundaries
129	after_text = self.options.get('start-after', None)
130	if after_text:
131	# skip content in rawtext before and incl. a matching text
132	after_index = rawtext.find(after_text)
133	if after_index < 0:
134	raise self.severe('Problem with "start-after" option of "%s" '
135	'directive:\nText not found.' % self.name)
136	rawtext = rawtext[after_index + len(after_text):]
137	before_text = self.options.get('end-before', None)
138	if before_text:
139	# skip content in rawtext after and incl. a matching text
140	before_index = rawtext.find(before_text)
141	if before_index < 0:
142	raise self.severe('Problem with "end-before" option of "%s" '
143	'directive:\nText not found.' % self.name)
144	rawtext = rawtext[:before_index]
145
146	include_lines = statemachine.string2lines(rawtext, tab_width,
147	convert_whitespace=True)
148	if 'literal' in self.options:
149	# Convert tabs to spaces, if `tab_width` is positive.
150	if tab_width >= 0:
151	text = rawtext.expandtabs(tab_width)
152	else:
153	text = rawtext
154	literal_block = nodes.literal_block(rawtext, source=path,
155	classes=self.options.get('class', []))
156	literal_block.line = 1
157	self.add_name(literal_block)
158	if 'number-lines' in self.options:
159	try:
160	startline = int(self.options['number-lines'] or 1)
161	except ValueError:
162	raise self.error(':number-lines: with non-integer '
163	'start value')
164	endline = startline + len(include_lines)
165	if text.endswith('\n'):
166	text = text[:-1]
167	tokens = NumberLines([([], text)], startline, endline)
168	for classes, value in tokens:
169	if classes:
170	literal_block += nodes.inline(value, value,
171	classes=classes)
172	else:
173	literal_block += nodes.Text(value, value)
174	else:
175	literal_block += nodes.Text(text, text)
176	return [literal_block]
177	if 'code' in self.options:
178	self.options['source'] = path
179	codeblock = CodeBlock(self.name,
180	[self.options.pop('code')], # arguments
181	self.options,
182	include_lines, # content
183	self.lineno,
184	self.content_offset,
185	self.block_text,
186	self.state,
187	self.state_machine)
188	return codeblock.run()
189	self.state_machine.insert_input(include_lines, path)
190	return []