diff options
Diffstat (limited to 'docs/extensions/api.md')
| -rw-r--r-- | docs/extensions/api.md | 164 |
1 files changed, 62 insertions, 102 deletions
diff --git a/docs/extensions/api.md b/docs/extensions/api.md index a110cef..c236a93 100644 --- a/docs/extensions/api.md +++ b/docs/extensions/api.md @@ -495,25 +495,24 @@ configuration options for your extension and attach the various processors and patterns to the Markdown instance. 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 [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. +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 a [Registry][]. Your `Extension` class will need to manipulate +those registries appropriately. You may `register` instances of your processors +and patterns with an appropriate priority, `deregister` built-in instances, or +replace a built-in instance with your own. ### `extendMarkdown` {: #extendmarkdown } The `extendMarkdown` method of a `markdown.extensions.Extension` class -accepts two arguments: +accepts one argument: * **`md`**: A pointer to the instance of the Markdown class. You should use this to - access the [OrderedDict][]s of processors and patterns. They are found - under the following attributes: + access the [Registries][Registry] of processors and patterns. They are + found under the following attributes: * `md.preprocessors` * `md.inlinePatterns` @@ -529,14 +528,9 @@ accepts two arguments: * `md.output_format` * `md.serializer` * `md.registerExtension()` - * `md.html_replacement_text` * `md.tab_length` - * `md.enable_attributes` - * `md.smart_emphasis` - -* **`md_globals`**: - - Contains all the various global variables within the markdown module. + * `md.block_level_elements` + * `md.isBlockLevel()` !!! Warning With access to the above items, theoretically you have the option to @@ -554,109 +548,75 @@ A simple example: from markdown.extensions import Extension class MyExtension(Extension): - def extendMarkdown(self, md, md_globals): - # Insert instance of 'mypattern' before 'references' pattern - md.inlinePatterns.add('mypattern', MyPattern(md), '<references') + def extendMarkdown(self, md): + # Register instance of 'mypattern' with a priority of 175 + md.inlinePatterns.register(MyPattern(md), 'mypattern', 175) ``` -### OrderedDict {: #ordereddict } - -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. - -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. - -Generally speaking, within Markdown extensions you will be using the special -helper method `add()` to add additional items to an existing OrderedDict. +### Registry -The `add()` method accepts three arguments: +The `markdown.util.Registry` class is a priority sorted registry which Markdown +uses internally to determine the processing order of its various processors and +patterns. -* **`key`**: A string. The key is used for later reference to the item. +A `Registry` instance provides two public methods to alter the data of the +registry: `register` and `deregister`. Use `register` to add items and +`deregister` to remove items. See each method for specifics. -* **`value`**: The object instance stored in this item. +When registering an item, a "name" and a "priority" must be provided. All +items are automatically sorted by "priority" from highest to lowest. The +"name" is used to remove (`deregister`) and get items. -* **`location`**: The items location in relation to other items. +A `Registry` instance is like a list (which maintains order) when reading +data. You may iterate over the items, get an item and get a count (length) +of all items. You may also check that the registry contains an item. - Note that the location can consist of a few different values: +When getting an item you may use either the index of the item or the +string-based "name". For example: - * 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: - -```pycon ->>> from markdown.odict import OrderedDict ->>> od = 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)] -``` + registry = Registry() + registry.register(SomeItem(), 'itemname', 20) + # Get the item by index + item = registry[0] + # Get the item by name + item = registry['itemname'] -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 let's -insert another item into the OrderedDict. +When checking that the registry contains an item, you may use either the +string-based "name", or a reference to the actual item. For example: -```pycon ->>> od.add('two', 2, '>one') # Insert after 'one' ->>> od.values() -[1, 2, 3, 4] -``` + someitem = SomeItem() + registry.register(someitem, 'itemname', 20) + # Contains the name + assert 'itemname' in registry + # Contains the item instance + assert someitem in registry -Now let's insert another item. +`markdown.util.Registry` has the following methods: -```pycon ->>> od.add('two-point-five', 2.5, '<three') # Insert before 'three' ->>> od.keys() -["one", "two", "two-point-five", "three", "four"] -``` +#### `Registry.register(self, item, name, priority)` {: #registry.register } -Note that we also could have set the location of "two-point-five" 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 an extension adding -"two-point-five" 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. +: Add an item to the registry with the given name and priority. -Once an OrderedDict is created, the items are available via key: + Parameters: -```python -MyNode = od['somekey'] -``` + * `item`: The item being registered. + * `name`: A string used to reference the item. + * `priority`: An integer or float used to sort against all items. -Therefore, to delete an existing item: + If an item is registered with a "name" which already exists, the existing + item is replaced with the new item. Tread carefully as the old item is lost + with no way to recover it. The new item will be sorted according to its + priority and will **not** retain the position of the old item. -```python -del od['somekey'] -``` +#### `Registry.deregister(self, name, strict=True)` {: #registry.deregister } -To change the value of an existing item (leaving location unchanged): +: Remove an item from the registry. -```python -od['somekey'] = MyNewObject() -``` + Set `strict=False` to fail silently. -To change the location of an existing item: +#### `Registry.get_index_for_name(self, name)` {: #registry.get_index_for_name } -```python -t.link('somekey', '<otherkey') -``` +: Return the index of the given `name`. ### registerExtension {: #registerextension } @@ -682,7 +642,7 @@ To register an extension, call `md.registerExtension` from within your `extendMarkdown` method: ```python -def extendMarkdown(self, md, md_globals): +def extendMarkdown(self, md): md.registerExtension(self) # insert processors and patterns here ``` @@ -850,7 +810,7 @@ module and call the `makeExtension` function to initiate your extension. [workingwithetree]: #working_with_et [Integrating your code into Markdown]: #integrating_into_markdown [extendMarkdown]: #extendmarkdown -[OrderedDict]: #ordereddict +[Registry]: #registry [registerExtension]: #registerextension [Config Settings]: #configsettings [makeExtension]: #makeextension |