.. _xmltable: =========================================== :mod:`rusty.xmltable` -- XMLTable directive =========================================== .. module:: xmltable :platform: Unix, Windows :synopsis: Generate RST tables by from XML documents .. moduleauthor:: Juha Mustonen .. versionadded:: 0.2.0 .. NOTE:: The module depends on `BeautifulSoup`_ -module. Install it using setuptools:: sudo easy_install BeautifulSoup .. contents:: :local: Features ======== XMLTable directive generates the table based on XML document and query, defined in the document. The :ref:`usage is simple `, but should cover most of the cases. **Iteration** The given query iterates all the items that matches with document. **Values** XML element values can be listed in a table cells. The selector is relative to iteration query, but can be also the parent and child elemnt of it. The text between elements is automatically taken, but it can be noted with ``@value`` -notation as well. **Attributes** XML element attributes can be shown as a value. The attribute is noted with ``@attribute-name`` -notation. **Header** Header columns can be defined for the table. Separate the values with comma. .. _xmltable-usage: Usage ===== Define ``xmltable`` -directive into your document. The path to document is given with ``file`` option, and it is relative to document path. The directive argument is reserved for the optional table caption. .. code-block:: rst This is an example rst-document .. xmltable:: caption :file: path/to/document.xml :header: Name, Name, Name, Name :query: /xml/query element-name element-name@attrib self @attrib * list * item And so on.. As it can be seen from the example, there are few options and content defined for the element. The description for each: **file** (required) Relative path (based on document) to XML file. Compulsory option. **header** (optional) Optional column fields for the header. If not defined, no table header is created. *Separate the column names with comma (,)*. Quotes are not needed and they are actually shown as is. If the header is not defined, the generated table won't have either. If the number of header entries does not match with the rows (columns) of the directive content area, an error is raised. **query** XML query, or more like a path, **defines the name of elements that will be iterated from the XML document. Each element will create a new row to table**. For example, if XML document contains multiple ```` elements (within ```` element), each entry is shown as a new row with the definition:: /zoo/animal Then, the :ref:`content area defines ` from which sub-elements the string value is taken from:: .. xmltable:: :file: animals.xml :query: /zoo/animal column1 column2 The query consists only from the strings and slashes. The first slash is ignored as the path always starts from the beginning of the XML document. Example:: /world/countries/country :ref:`See advanced example ` **widths** Optional parameter for defining the size of the column widths. The expected values are integers, separated with comma (the number of values must match) with number of columns. .. _xmltable-content: **content** **Each row** on the ``xmltable`` -directive content area **defines the path to the sub-element** which string value is taken into table cell. To continue with the animal-example, let's consider following document: .. literalinclude:: example/animals.xml :language: xml Following directive iterates each animal and prints some info about it into table. Notice the matching header definition: .. code-block:: rest .. xmltable:: Animal table caption :file: example/animals.xml :header: Name, Species, ID :query: /zoo/animal name species self@id Producing following table: .. xmltable:: Animal table caption :file: example/animals.xml :header: Name, Species, ID :query: /zoo/animal name species self@id If the selected element does not have string value, all the string values from the sub-elements are taken. Example: .. code-block:: rest .. xmltable:: List of countries :file: document.xml :header: Description :query: countries/country self .. xmltable:: List of countries :file: example/document.xml :header: Description :query: countries/country self .. _xmltable-example: Example ======= Sometimes the example is the best way to learn. Consider this example: **XML document** First we have a XML document: .. literalinclude:: example/document.xml :language: xml **RST document** Now the text document could have something like: .. code-block:: rst .. xmltable:: List of countries :file: document.xml :header: ID, Name, Time, Currency, All :widths: 60, 10, 10, 10 :query: /countries/country name self@id time currency self .. NOTE:: Note the special ``self`` -keyword: it references to the last element defined with the ``query``. In the case of example, the ``self`` references to ``country`` element and ``self@id`` to ``id`` attribute element. If the selected element has no string value, it retrievs the string from the subelements recursively. **Output** Once generated, the output shows the contents of the XML in table format. .. xmltable:: List of countries :file: example/document.xml :header: ID, Name, Time, Currency, All :widths: 40, 10, 10, 10, 20 :query: /countries/country name self@id time currency self Development =========== Known issues or development ideas for directive. May be fixed/implemented in the future. * File path cannot contain quotes (are spaces supported?) * Multiple entries per field * Support for remote resources Module in detail ================ .. automodule:: rusty.xmltable .. autoclass:: rusty.xmltable.XMLTableDirective .. autoclass:: rusty.xmltable.BeautifulTable .. include:: global.rst