[linux-2.6-block.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

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

    app.add_directive("kernel-include", KernelInclude)

# ==============================================================================
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
	42	# ==============================================================================
	43	def setup(app):
	44	# ==============================================================================
	45
	46	app.add_directive("kernel-include", KernelInclude)
	47
	48	# ==============================================================================
	49	class KernelInclude(Include):
	50	# ==============================================================================
	51
	52	u"""KernelInclude (``kernel-include``) directive"""
	53
	54	def run(self):
	55	path = os.path.realpath(
	56	os.path.expandvars(self.arguments[0]))
	57
	58	# to get a bit security back, prohibit /etc:
	59	if path.startswith(os.sep + "etc"):
	60	raise self.severe(
	61	'Problems with "%s" directive, prohibited path: %s'
	62	% (self.name, path))
	63
	64	self.arguments[0] = path
65
66	#return super(KernelInclude, self).run() # won't work, see HINTs in _run()
67	return self._run()
68
69	def _run(self):
70	"""Include a file as part of the content of this reST file."""
71
72	# HINT: I had to copy&paste the whole Include.run method. I'am not happy
73	# with this, but due to security reasons, the Include.run method does
74	# not allow absolute or relative pathnames pointing to locations above
75	# the filesystem tree where the reST document is placed.
76
77	if not self.state.document.settings.file_insertion_enabled:
78	raise self.warning('"%s" directive disabled.' % self.name)
79	source = self.state_machine.input_lines.source(
80	self.lineno - self.state_machine.input_offset - 1)
81	source_dir = os.path.dirname(os.path.abspath(source))
82	path = directives.path(self.arguments[0])
83	if path.startswith('<') and path.endswith('>'):
84	path = os.path.join(self.standard_include_path, path[1:-1])
85	path = os.path.normpath(os.path.join(source_dir, path))
86
87	# HINT: this is the only line I had to change / commented out:
88	#path = utils.relative_path(None, path)
89
90	path = nodes.reprunicode(path)
91	encoding = self.options.get(
92	'encoding', self.state.document.settings.input_encoding)
93	e_handler=self.state.document.settings.input_encoding_error_handler
94	tab_width = self.options.get(
95	'tab-width', self.state.document.settings.tab_width)
96	try:
97	self.state.document.settings.record_dependencies.add(path)
98	include_file = io.FileInput(source_path=path,
99	encoding=encoding,
100	error_handler=e_handler)
101	except UnicodeEncodeError as error:
102	raise self.severe('Problems with "%s" directive path:\n'
103	'Cannot encode input file path "%s" '
104	'(wrong locale?).' %
105	(self.name, SafeString(path)))
106	except IOError as error:
107	raise self.severe('Problems with "%s" directive path:\n%s.' %
108	(self.name, ErrorString(error)))
109	startline = self.options.get('start-line', None)
110	endline = self.options.get('end-line', None)
111	try:
112	if startline or (endline is not None):
113	lines = include_file.readlines()
114	rawtext = ''.join(lines[startline:endline])
115	else:
116	rawtext = include_file.read()
117	except UnicodeError as error:
118	raise self.severe('Problem with "%s" directive:\n%s' %
119	(self.name, ErrorString(error)))
120	# start-after/end-before: no restrictions on newlines in match-text,
121	# and no restrictions on matching inside lines vs. line boundaries
122	after_text = self.options.get('start-after', None)
123	if after_text:
124	# skip content in rawtext before and incl. a matching text
125	after_index = rawtext.find(after_text)
126	if after_index < 0:
127	raise self.severe('Problem with "start-after" option of "%s" '
128	'directive:\nText not found.' % self.name)
129	rawtext = rawtext[after_index + len(after_text):]
130	before_text = self.options.get('end-before', None)
131	if before_text:
132	# skip content in rawtext after and incl. a matching text
133	before_index = rawtext.find(before_text)
134	if before_index < 0:
135	raise self.severe('Problem with "end-before" option of "%s" '
136	'directive:\nText not found.' % self.name)
137	rawtext = rawtext[:before_index]
138
139	include_lines = statemachine.string2lines(rawtext, tab_width,
140	convert_whitespace=True)
141	if 'literal' in self.options:
142	# Convert tabs to spaces, if `tab_width` is positive.
143	if tab_width >= 0:
144	text = rawtext.expandtabs(tab_width)
145	else:
146	text = rawtext
147	literal_block = nodes.literal_block(rawtext, source=path,
148	classes=self.options.get('class', []))
149	literal_block.line = 1
150	self.add_name(literal_block)
151	if 'number-lines' in self.options:
152	try:
153	startline = int(self.options['number-lines'] or 1)
154	except ValueError:
155	raise self.error(':number-lines: with non-integer '
156	'start value')
157	endline = startline + len(include_lines)
158	if text.endswith('\n'):
159	text = text[:-1]
160	tokens = NumberLines([([], text)], startline, endline)
161	for classes, value in tokens:
162	if classes:
163	literal_block += nodes.inline(value, value,
164	classes=classes)
165	else:
166	literal_block += nodes.Text(value, value)
167	else:
168	literal_block += nodes.Text(text, text)
169	return [literal_block]
170	if 'code' in self.options:
171	self.options['source'] = path
172	codeblock = CodeBlock(self.name,
173	[self.options.pop('code')], # arguments
174	self.options,
175	include_lines, # content
176	self.lineno,
177	self.content_offset,
178	self.block_text,
179	self.state,
180	self.state_machine)
181	return codeblock.run()
182	self.state_machine.insert_input(include_lines, path)
183	return []