2 # Authors: David Goodger <goodger@python.org>; Ueli Schlaepfer
3 # Copyright: This module has been placed in the public domain.
6 This package contains Docutils Reader modules.
9 __docformat__
= 'reStructuredText'
13 from docutils
import utils
, parsers
, Component
14 from docutils
.transforms
import universal
15 if sys
.version_info
< (2,5):
16 from docutils
._compat
import __import__
19 class Reader(Component
):
22 Abstract base class for docutils Readers.
24 Each reader module or package must export a subclass also called 'Reader'.
26 The two steps of a Reader's responsibility are `scan()` and
27 `parse()`. Call `read()` to process a document.
30 component_type
= 'reader'
31 config_section
= 'readers'
33 def get_transforms(self
):
34 return Component
.get_transforms(self
) + [
35 universal
.Decorations
,
36 universal
.ExposeInternals
,
37 universal
.StripComments
,]
39 def __init__(self
, parser
=None, parser_name
=None):
41 Initialize the Reader instance.
43 Several instance attributes are defined with dummy initial values.
44 Subclasses may use these attributes as they wish.
48 """A `parsers.Parser` instance shared by all doctrees. May be left
49 unspecified if the document source determines the parser."""
51 if parser
is None and parser_name
:
52 self
.set_parser(parser_name
)
55 """`docutils.io` IO object, source of input data."""
58 """Raw text input; either a single string or, for more complex cases,
59 a collection of strings."""
61 def set_parser(self
, parser_name
):
62 """Set `self.parser` by name."""
63 parser_class
= parsers
.get_parser_class(parser_name
)
64 self
.parser
= parser_class()
66 def read(self
, source
, parser
, settings
):
70 self
.settings
= settings
71 self
.input = self
.source
.read()
76 """Parse `self.input` into a document tree."""
77 self
.document
= document
= self
.new_document()
78 self
.parser
.parse(self
.input, document
)
79 document
.current_source
= document
.current_line
= None
81 def new_document(self
):
82 """Create and return a new empty document tree (root node)."""
83 document
= utils
.new_document(self
.source
.source_path
, self
.settings
)
87 class ReReader(Reader
):
90 A reader which rereads an existing document tree (e.g. a
93 Often used in conjunction with `writers.UnfilteredWriter`.
96 def get_transforms(self
):
97 # Do not add any transforms. They have already been applied
98 # by the reader which originally created the document.
99 return Component
.get_transforms(self
)
104 def get_reader_class(reader_name
):
105 """Return the Reader class from the `reader_name` module."""
106 reader_name
= reader_name
.lower()
107 if reader_name
in _reader_aliases
:
108 reader_name
= _reader_aliases
[reader_name
]
109 module
= __import__(reader_name
, globals(), locals(), level
=1)