aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorWaylan Limberg <waylan@gmail.com>2008-10-19 19:22:59 -0400
committerWaylan Limberg <waylan@gmail.com>2008-10-19 19:22:59 -0400
commit760154f833b6fbea152aa7abd7d50f9588c6cae1 (patch)
tree5fd20dfadd7b68e440d294c4cc34c0b3d0388dee
parentd38e33e8d87c3190df0a1b2c7f72a4ac7df35f3b (diff)
downloadmarkdown-760154f833b6fbea152aa7abd7d50f9588c6cae1.tar.gz
markdown-760154f833b6fbea152aa7abd7d50f9588c6cae1.tar.bz2
markdown-760154f833b6fbea152aa7abd7d50f9588c6cae1.zip
Updated docs/writing_extensions.txt to include documentation about MarkdownParser.
-rwxr-xr-xdocs/writing_extensions.txt44
1 files changed, 43 insertions, 1 deletions
diff --git a/docs/writing_extensions.txt b/docs/writing_extensions.txt
index ed4427a..9232b4d 100755
--- a/docs/writing_extensions.txt
+++ b/docs/writing_extensions.txt
@@ -9,7 +9,7 @@ custom functionality and/or syntax into the parser. There are preprocessors
which allow you to alter the source before it is passed to the parser,
inline patterns which allow you to add, remove or override the syntax of
any inline elements, and postprocessors which allow munging of the
-output of the parser before it is returned.
+output of the parser before it is returned. If you really want to dive in, there is also the option to subclass the core MarkdownParser.
As the parser builds an [ElementTree][] object which is later rendered
as Unicode text, there are also some helpers provided to make manipulation of
@@ -25,6 +25,7 @@ features documented here.
* [Postprocessors][]
* [ElementTree Postprocessors][]
* [TextProstprocessors][]
+* [MarkdownParser][]
* [Working with the ElementTree][]
* [Integrating your code into Markdown][]
* [extendMarkdown][]
@@ -185,6 +186,46 @@ contents to a document:
def run(self, text):
return MYMARKERRE.sub(MyToc, text)
+<h3 id="markdownparser">MarkdownParser</h3>
+
+Sometimes, pre/postprocessors and Inline Patterns aren't going to do what you
+need. In such a situation, you can override the core ``MarkdownParser``. The
+easiest way is to simply subclass the existing ``MarkdownParser`` class and
+assign an instance of your subclass to ``Markdown``.
+
+ class MyCustomParser(markdown.MarkdownParser):
+ def my_method(self, ...):
+ #do stuff
+
+ md = markdown.Markdown()
+ md.parser = MyCustomParser()
+
+Of course, it is possible to write your own class from scratch which keeps the
+same public API. At the very least, you must provide the three public methods,
+the arguments and/or keywords they take, and return the appropriate object.
+Those methods are:
+
+* ``parseDocument``
+ * Keywords:
+ * ``lines``: A list of lines.
+ * Return an ElementTree object
+
+* ``parseChunk``
+ * Keywords:
+ * ``parent_elem``: An ElementTree Element.
+ * ``lines``: A list of lines.
+ * ``inList``: Boolean, optional.
+ * ``looseList``: Boolean, optional.
+ * Return None. However, it should attach the parsed ``lines`` as children
+ of the ``parent_elem``.
+
+* ``detechTabbed``
+ * Keywords:
+ * ``lines``: A list of lines.
+ * Return a 2 item tuple which should contain:
+ * A list of lines that were tabbed (now in a detabbed state) and
+ * a list of all remaining lines.
+
<h3 id="working_with_et">Working with the ElementTree</h3>
As mentioned, the Markdown parser converts a source document to an
@@ -384,6 +425,7 @@ than one residing in a module.
[Postprocessors]: #postprocessors
[ElementTree Postprocessors]: #etpostprocessors
[TextProstprocessors]: #textpostprocessors
+[MarkdownParser]: #markdownparser
[Working with the ElementTree]: #working_with_et
[Integrating your code into Markdown]: #integrating_into_markdown
[extendMarkdown]: #extendmarkdown