aboutsummaryrefslogtreecommitdiffstats
path: root/docs/writing_extensions.txt
diff options
context:
space:
mode:
authorWaylan Limberg <waylan@gmail.com>2008-10-29 11:26:42 -0400
committerWaylan Limberg <waylan@gmail.com>2008-10-29 11:26:42 -0400
commit870ddad1e12b3549da76be64b3a4cfa322e1eec7 (patch)
tree456de31b80bba59419e289e4ddb46992d8bf1ec6 /docs/writing_extensions.txt
parentd5cbf69c1cad6b88d36b27cd5ff8c803b9ec67ed (diff)
downloadmarkdown-870ddad1e12b3549da76be64b3a4cfa322e1eec7.tar.gz
markdown-870ddad1e12b3549da76be64b3a4cfa322e1eec7.tar.bz2
markdown-870ddad1e12b3549da76be64b3a4cfa322e1eec7.zip
Added documentation for OrderedDict.
Diffstat (limited to 'docs/writing_extensions.txt')
-rw-r--r--[-rwxr-xr-x]docs/writing_extensions.txt117
1 files changed, 84 insertions, 33 deletions
diff --git a/docs/writing_extensions.txt b/docs/writing_extensions.txt
index 35bc3e2..bbddb1b 100755..100644
--- a/docs/writing_extensions.txt
+++ b/docs/writing_extensions.txt
@@ -26,7 +26,7 @@ features documented here.
* [Working with the ElementTree][]
* [Integrating your code into Markdown][]
* [extendMarkdown][]
- * [Treaps][]
+ * [OrderedDict][]
* [registerExtension][]
* [Config Settings][]
* [makeExtension][]
@@ -266,10 +266,10 @@ It is important to note that the order of the various processors and patterns
matters. For example, if we replace ``http://...`` links with <a> elements, and
*then* try to deal with inline html, we will end up with a mess. Therefore,
the various types of processors and patterns are stored within an instance of
-the Markdown class in [Treaps][]. Your ``Extension`` class will need to
-manipulate those Treaps appropriately. You may insert instances of your
-processors and patterns into the appropriate location in a Treap, remove a
-built-in instance, or replace a built-in instance with your own.
+the Markdown class in [OrderedDict][]s. Your ``Extension`` class will need to
+manipulate those OrderedDicts appropriately. You may insert instances of your
+processors and patterns into the appropriate location in an OrderedDict, remove
+a built-in instance, or replace a built-in instance with your own.
<h4 id="extendmarkdown">`extendMarkdown`</h4>
@@ -279,8 +279,8 @@ arguments:
* ``md``:
A pointer to the instance of the Markdown class. You should use this to
- access the Treaps of processors and patterns. They are found under the
- following attributes:
+ access the [OrderedDict][]s of processors and patterns. They are found
+ under the following attributes:
* ``md.preprocessors``
* ``md.inlinePatterns``
@@ -307,43 +307,94 @@ Consider yourself warned.
[monkey_patching]: http://en.wikipedia.org/wiki/Monkey_patch
-<h4 id="treaps">Treaps</h4>
+A simple example:
-A treap is a binary search tree that orders nodes by accepting a priority
-attribute with a node, a well as a key to store the node. The priority
-determines the node's location in the heap. Each new node entry causes the
-heap to re-balance. The name "treap" is a composition of "tree" and "heap".
+ class MyExtension(makrdown.Extension):
+ def extendMarkdown(self, md, md_globals):
+ # Insert instance of 'mypattern' before 'references' pattern
+ md.inlinePatterns.add('mypattern', MyPattern(md), '<references')
-An example:
+<h4 id="ordereddict">OrderedDict</h4>
- tr = markdown.Treap()
- tr.add("key1", Object1, "_begin")
- tr.add("key2", Object2, ">key1")
- tr.add("key3", Object3, "<key2")
- tr.add("key4", Object4, "_end")
+An OrderedDict is a dictionary like object that retains the order of it's
+items. The items are ordered in the order in which they were appended to
+the OrderedDict. However, an item can also be inserted into the OrderedDict
+in a specific location in relation to the existing items.
-Note that the priority can consist of a few different values. The special
-strings ``"_begin"`` and ``"_end"`` insert that node at the beginning or end
-of the sorted heap. A less-than sign (``<``) followed by an existing key (i.e.:
-``"<key2"``) inserts that node before that existing key. A greater-than sign
-(``>``) followed by an existing key (i.e.: ``">key1"``) inserts that node after
-that existing key.
+Think of OrderedDict as a combination of a list and a dictionary as it has
+methods common to both. For example, you can get and set items using the
+``od[key] = value`` syntax and the methods ``keys()``, ``values()``, and
+``items()`` work as expected with the keys, values and items returned in the
+proper order. At the same time, you can use ``insert()``, ``append()``, and
+``index()`` as you would with a list.
-Once a treap is created, the nodes are available via key:
+Generally speaking, within Markdown extensions you will be using the special
+helper method ``add()`` to add additional items to an existing OrderedDict.
- MyNode = tr['somekey']
+The ``add()`` method accepts three arguments:
-Therefore, to delete an existing node:
+* **``key``**: A string. The key is used for later reference to the item.
+* **``value``**: The object instance stored in this item.
+* **``location``**: Optional. The items location in relation to other items.
+ Note that the location can consist of a few different values:
- del tr['somekey']
+ * The special strings ``"_begin"`` and ``"_end"`` insert that item at the
+ beginning or end of the OrderedDict respectively.
+
+ * A less-than sign (``<``) followed by an existing key (i.e.:
+ ``"<somekey"``) inserts that item before the existing key.
+
+ * A greater-than sign (``>``) followed by an existing key (i.e.:
+ ``">somekey"``) inserts that item after the existing key.
+
+Consider the following example:
+
+ >>> import markdown
+ >>> od = markdown.OrderedDict()
+ >>> od['one'] = 1 # The same as: od.add('one', 1, '_begin')
+ >>> od['three'] = 3 # The same as: od.add('three', 3, '>one')
+ >>> od['four'] = 4 # The same as: od.add('four', 4, '_end')
+ >>> od.items()
+ [("one", 1), ("three", 3), ("four", 4)]
+
+Note that when building an OrderedDict in order, the extra features of the
+``add`` method offer no real value and are not necessary. However, when
+manipulating an existing OrderedDict, ``add`` can be very helpful. So lets
+insert another item into the OrderedDict.
+
+ >>> od.add('two', 2, '>one') # Insert after 'one'
+ >>> od.values()
+ [1, 2, 3, 4]
+
+Now lets insert another item.
+
+ >>> od.add('twohalf', 2.5, '<three') # Insert before 'three'
+ >>> od.keys()
+ ["one", "two", "twohalf", "three", "four"]
+
+Note that we also could have set the location of "twohalf" to be 'after two'
+(i.e.: ``'>two'``). However, it's unlikely that you will have control over the
+order in which extensions will be loaded, and this could affect the final
+sorted order of an OrderedDict. For example, suppose a extension adding
+'twohalf' in the above examples was loaded before a separate extension which
+adds 'two'. You may need to take this into consideration when adding your
+extension components to the various markdown OrderedDicts.
+
+Once an OrderedDict is created, the items are available via key:
+
+ MyNode = od['somekey']
+
+Therefore, to delete an existing item:
+
+ del od['somekey']
-To change the value of an existing node (leaving priority the same):
+To change the value of an existing item (leaving location unchanged):
- tr['somekey'] = MyNewObject
+ od['somekey'] = MyNewObject()
-To change the priority of an existing object:
+To change the location of an existing item:
- tr.link('somekey', '<otherkey')
+ t.link('somekey', '<otherkey')
<h4 id="registerextension">registerExtension</h4>
@@ -438,7 +489,7 @@ than one residing in a module.
[Working with the ElementTree]: #working_with_et
[Integrating your code into Markdown]: #integrating_into_markdown
[extendMarkdown]: #extendmarkdown
-[Treaps]: #treaps
+[OrderedDict]: #ordereddict
[registerExtension]: #registerextension
[Config Settings]: #configsettings
[makeExtension]: #makeextension