.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2018 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.html.HtmlParser:

==========================================================================================================================================
|phoenix_title|  **wx.html.HtmlParser**
==========================================================================================================================================

Classes derived from this handle the **generic**  parsing of HTML documents: it scans the document and divide it into blocks of tags (where one block consists of beginning and ending tag and of text between these two tags).          

It is independent from :ref:`wx.html.HtmlWindow`  and can be used as stand-alone parser. 

It uses system of tag handlers to parse the HTML document. Tag handlers are not statically shared by all instances but are created for each :ref:`wx.html.HtmlParser`  instance. The reason is that the handler may contain document-specific temporary data used during parsing (e.g. complicated structures like tables). 

Typically the user calls only the :meth:`wx.html.HtmlParser.Parse`   method. 







         



.. seealso:: :ref:`Cells and Containers <cells and containers>`, :ref:`Tag Handlers <tag handlers>`, :ref:`wx.html.HtmlTag`    







|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>HtmlParser</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.html.HtmlParser_inheritance.png" alt="Inheritance diagram of HtmlParser" usemap="#dummy" class="inheritance"/></center>
   </div>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.html.HtmlParser.html" title="wx.html.HtmlParser" alt="" coords="5,5,152,35"/> </map> 
   </p>

|


|sub_classes| Known Subclasses
==============================

:ref:`wx.html.HtmlWinParser`

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.html.HtmlParser.__init__`                                             Constructor.
:meth:`~wx.html.HtmlParser.AddTag`                                               This may (and may not) be overwritten in derived class.
:meth:`~wx.html.HtmlParser.AddTagHandler`                                        Adds handler to the internal list ( hash table) of handlers.
:meth:`~wx.html.HtmlParser.DoParsing`                                            Parses the whole m_Source.
:meth:`~wx.html.HtmlParser.DoneParser`                                           This must be called after :meth:`~HtmlParser.DoParsing` .
:meth:`~wx.html.HtmlParser.GetFS`                                                Returns pointer to the file system.
:meth:`~wx.html.HtmlParser.GetProduct`                                           Returns product of parsing.
:meth:`~wx.html.HtmlParser.GetSource`                                            Returns pointer to the source being parsed.
:meth:`~wx.html.HtmlParser.InitParser`                                           Setups the parser for parsing the `source`  string.
:meth:`~wx.html.HtmlParser.OpenURL`                                              Opens given URL and returns  :ref:`wx.FSFile`  object that can be used to read data from it.
:meth:`~wx.html.HtmlParser.Parse`                                                Proceeds parsing of the document.
:meth:`~wx.html.HtmlParser.PopTagHandler`                                        Restores parser's state before last call to :meth:`~HtmlParser.PushTagHandler` .
:meth:`~wx.html.HtmlParser.PushTagHandler`                                       Forces the handler to handle additional tags (not returned by :meth:`wx.html.HtmlTagHandler.GetSupportedTags` ).
:meth:`~wx.html.HtmlParser.SetFS`                                                Sets the virtual file system that will be used to request additional files.
:meth:`~wx.html.HtmlParser.StopParsing`                                          Call this function to interrupt parsing from a tag handler.
================================================================================ ================================================================================


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.html.HtmlParser.FS`                                                   See :meth:`~wx.html.HtmlParser.GetFS` and :meth:`~wx.html.HtmlParser.SetFS`
:attr:`~wx.html.HtmlParser.Product`                                              See :meth:`~wx.html.HtmlParser.GetProduct`
:attr:`~wx.html.HtmlParser.Source`                                               See :meth:`~wx.html.HtmlParser.GetSource`
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.html.HtmlParser(object)

   **Possible constructors**::

       HtmlParser()
       
   
   Classes derived from this handle the generic parsing of HTML
   documents: it scans the document and divide it into blocks of tags
   (where one block consists of beginning and ending tag and of text
   between these two tags).



   .. method:: __init__(self)

      Constructor.                   





   .. method:: AddTag(self, tag)

      This may (and may not) be overwritten in derived class.                  

      This method is called each time new tag is about to be added. `tag`  contains information about the tag. (See :ref:`wx.html.HtmlTag`  for details.) 

      Default (:ref:`wx.html.HtmlParser`) behaviour is this: first it finds a handler capable of handling this tag and then it calls handler's HandleTag() method.                  


      :param `tag`: 
      :type `tag`: wx.html.HtmlTag







   .. method:: AddTagHandler(self, handler)

      Adds handler to the internal list ( hash table) of handlers.                  

      This method should not be called directly by user but rather by derived class' constructor. 

      This adds the handler to this **instance**  of :ref:`wx.html.HtmlParser`, not to all objects of this class! (Static front-end to AddTagHandler is provided by :ref:`wx.html.HtmlWinParser`). 

      All handlers are deleted on object deletion.                  


      :param `handler`: 
      :type `handler`: wx.html.HtmlTagHandler







   .. method:: DoParsing(self)

      Parses the whole m_Source.                   





   .. method:: DoneParser(self)

      This must be called after :meth:`DoParsing` .                   





   .. method:: GetFS(self)

      Returns pointer to the file system.                  

      Because each tag handler has reference to it is parent parser it can easily request the file by calling: ::

          f = self.Parser.GetFS().OpenFile("image.jpg")

                 

      :rtype: :ref:`FileSystem`








   .. method:: GetProduct(self)

      Returns product of parsing.                  

      Returned value is result of parsing of the document. 

      The type of this result depends on internal representation in derived parser (but it must be derived from Object!). See :ref:`wx.html.HtmlWinParser`  for details.                  

      :rtype: :ref:`Object`








   .. method:: GetSource(self)

      Returns pointer to the source being parsed.                  

      :rtype: `string`








   .. method:: InitParser(self, source)

      Setups the parser for parsing the `source`  string.                  

      (Should be overridden in derived class)                  


      :param `source`: 
      :type `source`: string







   .. method:: OpenURL(self, type, url)

      Opens given URL and returns  :ref:`wx.FSFile`  object that can be used to read data from it.                   

      This method may return ``None`` in one of two cases: either the URL doesn't point to any valid resource or the URL is blocked by overridden implementation of `OpenURL`  in derived class. 




      :param `type`: Indicates type of the resource. Is one of:

       - ``wx.html.HTML_URL_PAGE``: Opening a HTML page. 
       - ``wx.html.HTML_URL_IMAGE``: Opening an image. 
       - ``wx.html.HTML_URL_OTHER``: Opening a resource that doesn't fall into any other category.  

 

      :type `type`: wx.html.HtmlURLType
      :param `url`: URL being opened.  
      :type `url`: string








      :rtype: :ref:`FSFile`



                  



      .. note:: 

         Always use this method in tag handlers instead of :meth:`GetFS` .OpenFile() because it can block the URL and is thus more secure. Default behaviour is to call :meth:`wx.html.HtmlWindow.OnOpeningURL`   of the associated :ref:`wx.html.HtmlWindow`  object (which may decide to block the URL or redirect it to another one),if there's any, and always open the URL if the parser is not used with :ref:`wx.html.HtmlWindow`. Returned :ref:`wx.FSFile`  object is not guaranteed to point to url, it might have been redirected!   








   .. method:: Parse(self, source)

      Proceeds parsing of the document.                  

      This is end-user method. You can simply call it when you need to obtain parsed output (which is parser-specific). 

      The method does these things:

      - calls InitParser(source) 
      - calls :meth:`DoParsing`  
      - calls :meth:`GetProduct`  
      - calls :meth:`DoneParser`  
      - returns value returned by :meth:`GetProduct`  




      You shouldn't use :meth:`InitParser` , :meth:`DoParsing` , :meth:`GetProduct`   or :meth:`DoneParser`   directly.                  


      :param `source`: 
      :type `source`: string




      :rtype: :ref:`Object`








   .. method:: PopTagHandler(self)

      Restores parser's state before last call to :meth:`PushTagHandler` .                   





   .. method:: PushTagHandler(self, handler, tags)

      Forces the handler to handle additional tags (not returned by :meth:`wx.html.HtmlTagHandler.GetSupportedTags` ).                  

      The handler should already be added to this parser. 




      :param `handler`: the handler   
      :type `handler`: wx.html.HtmlTagHandler
      :param `tags`: List of tags (in same format as GetSupportedTags()'s return value). The parser will redirect these tags to handler (until call to :meth:`PopTagHandler` ).  
      :type `tags`: string








      Imagine you want to parse following pseudo-html structure: 

      .. code-block:: xml

          <myitems>
              <param name="one" value="1">
              <param name="two" value="2">
          </myitems>

          <execute>
              <param program="text.exe">
          </execute>



      It is obvious that you cannot use only one tag handler for <param> tag. Instead you must use context-sensitive handlers for <param> inside <myitems> and <param> inside <execute>. This is the preferred solution: 

      ::

                  # some code in HandleTag for "MYITEMS"...

                  self.Parser.PushTagHandler(self, "PARAM")
                  self.ParseInner(tag)
                  self.Parser.PopTagHandler()

                  # back to working on "MYITEMS"...

                  





   .. method:: SetFS(self, fs)

      Sets the virtual file system that will be used to request additional files.                  

      (For example  ``IMG``   tag handler requests  :ref:`wx.FSFile`  with the image data.)                  


      :param `fs`: 
      :type `fs`: wx.FileSystem







   .. method:: StopParsing(self)

      Call this function to interrupt parsing from a tag handler.                  

      No more tags will be parsed afterward. This function may only be called from :meth:`Parse`   or any function called by it (i.e. from tag handlers).                   





   .. attribute:: FS

      See :meth:`~wx.html.HtmlParser.GetFS` and :meth:`~wx.html.HtmlParser.SetFS`


   .. attribute:: Product

      See :meth:`~wx.html.HtmlParser.GetProduct`


   .. attribute:: Source

      See :meth:`~wx.html.HtmlParser.GetSource`