balxml_formatter Component

Provide a simple interface for writing formatted XML. More...

Namespaces
namespace	balxml

Detailed Description

Outline

Purpose
Classes
Description
- Usage

Purpose:: Provide a simple interface for writing formatted XML.

Classes:

balxml::Formatter

provides formatted XML

See also:

Description:: The balxml::Formatter class provides methods to write a formatted XML to an underlining output stream. These methods generate header, tags, data, attributes, comments in a human-readable, indented format.

: XML documents use a self-describing and simple syntax that consists of nested XML elements. Each element is bounded by a pair of opening and closing tags. Within the pair of tags, there can be more nested elements, or just plain text or numeric data in text format. The opening tag of an element can also contain attributes in the form of name="value" pairs. This component provides methods to generate these XML ingredients and takes care of proper indentation and line wrapping. Visit http://www.w3schools.com/xml/xml_syntax.asp for a complete tutorial.

Usage:

Here is a basic example showing ten steps of how to create an XML document using this component's major manipulators:

  // 1. Create a formatter:
  balxml::Formatter formatter(bsl::cout);

  // 2. Add a header:
  formatter.addHeader("UTF-8");

  // 3. Open the root element,
  //    Add attributes if there are any:
  formatter.openElement("Fruits");

  // 4. Open an element,
  //    Add attributes if there are any:
  formatter.openElement("Oranges");
  formatter.addAttribute("farm", "Francis' Orchard"); // ' is escaped
  formatter.addAttribute("size", 3.5);

  // 5. If there are nested elements, recursively do steps 4 - 8:
  // 6. Else, there are no more nested elements, add data:
  formatter.openElement("pickDate");               // step 4
  formatter.addData(bdlt::Date(2004, 8, 31));       // step 6
  formatter.closeElement("pickDate");              // step 7
  formatter.addElementAndData("Quantity", 12);     // step 8
            // element "Quantity" has no attributes, can use
            // shortcut 'addElementAndData' to complete steps
            // 4, 6 and 7 in one shot.

  // 7. Close the element:
  formatter.closeElement("Oranges");

  // 8. If there are more elements, repeat steps 4 - 8
  formatter.openElement("Apples");                 // step 4
  formatter.addAttribute("farm", "Fuji & Sons");   // '&' is escaped
  formatter.addAttribute("size", 3);
  formatter.closeElement("Apples");                // step 7

  // 9. Close the root element:
  formatter.closeElement("Fruits");

Indentation is correctly taken care of and the user need only concern her/himself with the correct ordering of the XML elements s/he's trying to write. The output of the above example is:

  +--bsl::cout--------------------------------------------------------------+
  |<?xml version="1.0" encoding="UTF-8" ?>                                  |
  |<Fruits>                                                                 |
  |    <Oranges farm="Francis&apos; Orchard" size="3.5">                    |
  |        <pickDate>2004-08-31</pickDate>                                  |
  |        <Quantity>12</Quantity>                                          |
  |    </Oranges>                                                           |
  |    <Apples farm="Fuji &amp; Sons" size="3"/>                            |
  |</Fruits>                                                                |
  +-------------------------------------------------------------------------+

Following is a more complete usage example that uses most of the manipulators provided by balxml::Formatter:

  balxml::Formatter formatter(bsl::cout, 0, 4, 40);

  formatter.addHeader("UTF-8");

  formatter.openElement("Fruits");
  formatter.openElement("Oranges");
  formatter.addAttribute("farm", "Francis' Orchard");
      // notice that the apostrophe in the string will be escaped
  formatter.addAttribute("size", 3.5);

  formatter.addElementAndData("Quantity", 12);

  formatter.openElement("pickDate");
  formatter.addData(bdlt::Date(2004, 8, 31));
  formatter.closeElement("pickDate");

  formatter.openElement("Feature");
  formatter.addAttribute("shape", "round");
  formatter.closeElement("Feature");

  formatter.addComment("No wrapping for long comments");

  formatter.closeElement("Oranges");

  formatter.addBlankLine();

  formatter.openElement("Apples");
  formatter.addAttribute("farm", "Fuji & Sons");
  formatter.addAttribute("size", 3);

  formatter.openElement("pickDates",
                        balxml::Formatter::BAEXML_NEWLINE_INDENT);
  formatter.addListData(bdlt::Date(2005, 1, 17));
  formatter.addListData(bdlt::Date(2005, 2, 21));
  formatter.addListData(bdlt::Date(2005, 3, 25));
  formatter.addListData(bdlt::Date(2005, 5, 30));
  formatter.addListData(bdlt::Date(2005, 7, 4));
  formatter.addListData(bdlt::Date(2005, 9, 5));
  formatter.addListData(bdlt::Date(2005, 11, 24));
  formatter.addListData(bdlt::Date(2005, 12, 25));

  formatter.closeElement("pickDates");

  formatter.openElement("Feature");
  formatter.addAttribute("color", "red");
  formatter.addAttribute("taste", "juicy");
  formatter.closeElement("Feature");

  formatter.closeElement("Apples");

  formatter.closeElement("Fruits");

  formatter.reset();
  // reset the formatter for a new document in the same stream

  formatter.addHeader();
  formatter.openElement("Grains");

  bsl::ostream& os = formatter.rawOutputStream();
  os << "<free>anything that can mess up the XML doc</free>";
  // Now coming back to the formatter, but can't do the following:
  // formatter.addAttribute("country", "USA");
  formatter.addData("Corn, Wheat, Oat");
  formatter.closeElement("Grains");

Following are the two resulting documents, as separated by the call to reset(),

  +--bsl::cout-----------------------------+
  |<?xml version="1.0" encoding="UTF-8" ?> |
  |<Fruits>                                |
  |    <Oranges                            |
  |         farm="Francis&apos; Orchard"   |
  |         size="3.5">                    |
  |        <Quantity>12</Quantity>         |
  |        <pickDate>2004-08-31</pickDate> |
  |        <Feature shape="round"/>        |
  |        <!-- No wrapping for long comments --> |
  |    </Oranges>                          |
  |                                        |
  |    <Apples farm="Fuji &amp; Sons"      |
  |         size="3">                      |
  |        <pickDates>                     |
  |            2005-01-17 2005-02-21       |
  |            2005-03-25 2005-05-30       |
  |            2005-07-04 2005-09-05       |
  |            2005-11-24 2005-12-25       |
  |        </pickDates>                    |
  |        <Feature color="red"            |
  |             taste="juicy"/>            |
  |    </Apples>                           |
  |</Fruits>                               |
  +----------------------------------------+
  +--bsl::cout-----------------------------+
  |<?xml version="1.0" encoding="UTF-8" ?> |
  |<Grains><free>anything that can mess up the XML doc</free>
  |              Corn, Wheat, Oat</Grains> |
  +----------------------------------------+

Component balxml_formatter [Package balxml]

Namespaces

Detailed Description

Component balxml_formatter
[Package balxml]