2 # -*- coding: utf-8; mode: python -*-
3 # pylint: disable=R0903, C0330, R0914, R0912, E0401
9 Implementation of the ``kernel-include`` reST-directive.
11 :copyright: Copyright (C) 2016 Markus Heiser
12 :license: GPL Version 2, June 1991 see linux/COPYING for details.
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.
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.
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.
30 # ==============================================================================
32 # ==============================================================================
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
42 # ==============================================================================
44 # ==============================================================================
46 app
.add_directive("kernel-include", KernelInclude
)
48 # ==============================================================================
49 class KernelInclude(Include
):
50 # ==============================================================================
52 u
"""KernelInclude (``kernel-include``) directive"""
55 path
= os
.path
.realpath(
56 os
.path
.expandvars(self
.arguments
[0]))
58 # to get a bit security back, prohibit /etc:
59 if path
.startswith(os
.sep
+ "etc"):
61 'Problems with "%s" directive, prohibited path: %s'
64 self
.arguments
[0] = path
66 #return super(KernelInclude, self).run() # won't work, see HINTs in _run()
70 """Include a file as part of the content of this reST file."""
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.
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
))
87 # HINT: this is the only line I had to change / commented out:
88 #path = utils.relative_path(None, path)
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
)
97 self
.state
.document
.settings
.record_dependencies
.add(path
)
98 include_file
= io
.FileInput(source_path
=path
,
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" '
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)
112 if startline
or (endline
is not None):
113 lines
= include_file
.readlines()
114 rawtext
= ''.join(lines
[startline
:endline
])
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)
124 # skip content in rawtext before *and incl.* a matching text
125 after_index
= rawtext
.find(after_text
)
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)
132 # skip content in rawtext after *and incl.* a matching text
133 before_index
= rawtext
.find(before_text
)
135 raise self
.severe('Problem with "end-before" option of "%s" '
136 'directive:\nText not found.' % self
.name
)
137 rawtext
= rawtext
[:before_index
]
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.
144 text
= rawtext
.expandtabs(tab_width
)
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
:
153 startline
= int(self
.options
['number-lines'] or 1)
155 raise self
.error(':number-lines: with non-integer '
157 endline
= startline
+ len(include_lines
)
158 if text
.endswith('\n'):
160 tokens
= NumberLines([([], text
)], startline
, endline
)
161 for classes
, value
in tokens
:
163 literal_block
+= nodes
.inline(value
, value
,
166 literal_block
+= nodes
.Text(value
, value
)
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
175 include_lines
, # content
181 return codeblock
.run()
182 self
.state_machine
.insert_input(include_lines
, path
)