third_party/markdown/blockparser.py

   1 # markdown is released under the BSD license
   2 # Copyright 2007, 2008 The Python Markdown Project (v. 1.7 and later)
   3 # Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
   4 # Copyright 2004 Manfred Stienstra (the original version)
   5 #
   6 # All rights reserved.
   7 #
   8 # Redistribution and use in source and binary forms, with or without
   9 # modification, are permitted provided that the following conditions are met:
  10 #
  11 # *   Redistributions of source code must retain the above copyright
  12 #     notice, this list of conditions and the following disclaimer.
  13 # *   Redistributions in binary form must reproduce the above copyright
  14 #     notice, this list of conditions and the following disclaimer in the
  15 #     documentation and/or other materials provided with the distribution.
  16 # *   Neither the name of the <organization> nor the
  17 #     names of its contributors may be used to endorse or promote products
  18 #     derived from this software without specific prior written permission.
  19 #
  20 # THIS SOFTWARE IS PROVIDED BY THE PYTHON MARKDOWN PROJECT ''AS IS'' AND ANY
  21 # EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  22 # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  23 # DISCLAIMED. IN NO EVENT SHALL ANY CONTRIBUTORS TO THE PYTHON MARKDOWN PROJECT
  24 # BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  25 # CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  26 # SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  27 # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  28 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  29 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  30 # POSSIBILITY OF SUCH DAMAGE.
  31
  32
  33 from __future__ import unicode_literals
  34 from __future__ import absolute_import
  35 from . import util
  36 from . import odict
  37
  38 class State(list):
  39     """ Track the current and nested state of the parser.
  40
  41     This utility class is used to track the state of the BlockParser and
  42     support multiple levels if nesting. It's just a simple API wrapped around
  43     a list. Each time a state is set, that state is appended to the end of the
  44     list. Each time a state is reset, that state is removed from the end of
  45     the list.
  46
  47     Therefore, each time a state is set for a nested block, that state must be
  48     reset when we back out of that level of nesting or the state could be
  49     corrupted.
  50
  51     While all the methods of a list object are available, only the three
  52     defined below need be used.
  53
  54     """
  55
  56     def set(self, state):
  57         """ Set a new state. """
  58         self.append(state)
  59
  60     def reset(self):
  61         """ Step back one step in nested state. """
  62         self.pop()
  63
  64     def isstate(self, state):
  65         """ Test that top (current) level is of given state. """
  66         if len(self):
  67             return self[-1] == state
  68         else:
  69             return False
  70
  71 class BlockParser:
  72     """ Parse Markdown blocks into an ElementTree object.
  73
  74     A wrapper class that stitches the various BlockProcessors together,
  75     looping through them and creating an ElementTree object.
  76     """
  77
  78     def __init__(self, markdown):
  79         self.blockprocessors = odict.OrderedDict()
  80         self.state = State()
  81         self.markdown = markdown
  82
  83     def parseDocument(self, lines):
  84         """ Parse a markdown document into an ElementTree.
  85
  86         Given a list of lines, an ElementTree object (not just a parent Element)
  87         is created and the root element is passed to the parser as the parent.
  88         The ElementTree object is returned.
  89
  90         This should only be called on an entire document, not pieces.
  91
  92         """
  93         # Create a ElementTree from the lines
  94         self.root = util.etree.Element(self.markdown.doc_tag)
  95         self.parseChunk(self.root, '\n'.join(lines))
  96         return util.etree.ElementTree(self.root)
  97
  98     def parseChunk(self, parent, text):
  99         """ Parse a chunk of markdown text and attach to given etree node.
 100
 101         While the ``text`` argument is generally assumed to contain multiple
 102         blocks which will be split on blank lines, it could contain only one
 103         block. Generally, this method would be called by extensions when
 104         block parsing is required.
 105
 106         The ``parent`` etree Element passed in is altered in place.
 107         Nothing is returned.
 108
 109         """
 110         self.parseBlocks(parent, text.split('\n\n'))
 111
 112     def parseBlocks(self, parent, blocks):
 113         """ Process blocks of markdown text and attach to given etree node.
 114
 115         Given a list of ``blocks``, each blockprocessor is stepped through
 116         until there are no blocks left. While an extension could potentially
 117         call this method directly, it's generally expected to be used internally.
 118
 119         This is a public method as an extension may need to add/alter additional
 120         BlockProcessors which call this method to recursively parse a nested
 121         block.
 122
 123         """
 124         while blocks:
 125             for processor in self.blockprocessors.values():
 126                 if processor.test(parent, blocks[0]):
 127                     if processor.run(parent, blocks) is not False:
 128                         # run returns True or None
 129                         break
 130
 131