diff options
| -rw-r--r--[-rwxr-xr-x] | docs/writing_extensions.txt | 117 |
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 |