Xport Interface: parser::add_entity

Adds an entity reference to be used by the parser for possible conversion operations.

xhtml_document_type parser::add_entity(
  char chr,
  short num,
  const std::string& named_ref,
  xhtml_entity_appearance appearance
);

Parameters

chr

The character representation of the entity. Many entities can not be specified as a valid character, so the character's hex representation may be used, such as '\\xA2' for the cent character.

num

The numeric value for the character entity reference.

named_ref

The name reference for the character entity. For example, &lt; is the named reference for '<'.

appearance

An enumerator of xhtml_entity_appearance which specifies how the character entity will be displayed in the output document. Valid enuerators are unaltered, character_entity, numeric_entity, and named_entity.

Returns

Returns an xhtml_document_type enumerator, which specifies the type of document. Values (enumerators) of xhtml_document_type are dt_strict, dt_transitional, dt_frameset, and dt_unknown.

Remarks

This operation is used to add entities to watch for in the parsed input stream or file, and to specify how they will be displayed on the resulting document. A list of the most common character entity references are included by default in the parser. This list is displayed below, with their default appearance. The appearance of these and any entities can be modified with the operation parser::entity_appearance(). For the parser to convert entities from one type to another, the convert_entity option must be set, using the operation parser::option().

The list below displays the common character entity references which are automatically included in parser by default.

Complexity

Logarithmic

Example

#include "xhtml_doc.h"
#include <iostream>
#include <sstream>

int main(int argc, char* argv[])
{
  using namespace Xport;

  document doc(root_doc);
  markup::iterator it = doc.body()->insert(element(p));

  *it << "The following character is a trademark: ™";

  // write the document to an output stream
  std::ostringstream ostr;
  formatter fmtr1(ostr);
  fmtr1 << doc;

  // parse the stream
  std::istringstream input(ostr.str());
  parser prsr(input);

  doc.clear();
  formatter fmtr2(std::cout);

  // parse the input
  doc.parse(prsr);
  std::cout << "Parsed output from an unmodified parser.\n\n";
  fmtr2 << doc;
  std::cout << "\n\n\n";

  // add the entity
  prsr.add_entity('\x99', 8482, "trade", named_entity);
  prsr.option(convert_entities, true);

  doc.clear();
  doc.parse(prsr);

  std::cout << "Parsed output after adding tm entity to parser, specifying named entity.\n\n";
  fmtr2 << doc;
  std::cout << "\n\n\n";

  return 0;
}