object

# xml

> Bi-directional XML parser.

author:
  `John Fletcher; adapted to Logtalk by Paulo Moura.`
version:
  `3.5`
date:
  `2014/11/3`
copyright:
  `Copyright (C) 2001-2005 Binding Time Limited, Copyright (C) 2005-2013 John Fletcher`
license:
  `This program is offered free of charge, as unsupported source code. You may use it, copy it, distribute it, modify it or sell it without restriction, but entirely at your own risk.`

compilation flags:
  `static, context_switching_calls`

(no dependencies on other files)

## Public interface

### parse/2

> Parses Chars to/from a data structure of the form xml(<atts>, <content>).

compilation flags:
  `static`
template:
  `parse(Chars,Document)`
mode – number of proofs:
  `parse(+nonvar,?nonvar) – zero_or_one`
  `parse(?nonvar,+nonvar) – zero_or_one`

### parse/3

> Parses Chars to/from a data structure of the form xml(<atts>, <content>).

compilation flags:
  `static`
template:
  `parse(Controls,Chars,Document)`
mode – number of proofs:
  `parse(+nonvar,+nonvar,?nonvar) – zero_or_one`
  `parse(+nonvar,?nonvar,+nonvar) – zero_or_one`

### subterm/2

> Unifies Subterm with a sub-term of XMLTerm. Note that XMLTerm is a sub-term of itself.

compilation flags:
  `static`
template:
  `subterm(XMLTerm,Subterm)`
mode – number of proofs:
  `subterm(+nonvar,?nonvar) – zero_or_one`

### pp/1

> Pretty prints a XML document on the current output stream.

compilation flags:
  `static`
template:
  `pp(XMLDocument)`
mode – number of proofs:
  `pp(+nonvar) – zero_or_one`

## Protected interface

(none)

## Private predicates

### xml_to_document/3

> Translates the list of character codes XML into the Prolog term Document. Controls is a list of terms controlling the treatment of layout characters and character entities.

compilation flags:
  `static`
template:
  `xml_to_document(Controls,XML,Document)`
mode – number of proofs:
  `xml_to_document(+nonvar,+nonvar,?nonvar) – zero_or_one`

### empty_map/1

> True if Map is a null map.

compilation flags:
  `static`
template:
  `empty_map(Map)`
mode – number of proofs:
  `empty_map(?nonvar) – zero_or_one`

### map_member/3

> True if Map is a ordered map structure which records the pair Key-Data. Key must be ground.

compilation flags:
  `static`
template:
  `map_member(Key,Map,Data)`
mode – number of proofs:
  `map_member(+nonvar,+nonvar,?nonvar) – zero_or_one`

### map_store/4

> True if Map0 is an ordered map structure, Key must be ground, and Map1 is identical to Map0 except that the pair Key-Data is recorded by Map1.

compilation flags:
  `static`
template:
  `map_store(Map0,Key,Data,Map1)`
mode – number of proofs:
  `map_store(+nonvar,+nonvar,+nonvar,?nonvar) – zero_or_one`

### pp_string/1

> Prints String onto the current output stream. If String contains only 7-bit chars it is printed in shorthand quoted format, otherwise it is written as a list.

compilation flags:
  `static`
template:
  `pp_string(String)`
mode – number of proofs:
  `pp_string(+nonvar) – zero_or_one`

### fault/5

> Identifies SubTerm as a sub-term of Term which cannot be serialized after Indentation. Message is an atom naming the type of error; Path is a string encoding a list of SubTerm's ancestor elements in the form <tag>{(id)}* where <tag> is the element tag and <id> is the value of any attribute _named_ id.

compilation flags:
  `static`
template:
  `fault(Term,Indentation,SubTerm,Path,Message)`
mode – number of proofs:
  `fault(+nonvar,+nonvar,?nonvar,?nonvar,?nonvar) – zero_or_one`

### exception/4

> Hook to raise an exception to be raised in respect of a fault in the XML Term: Document.

compilation flags:
  `static`
template:
  `exception(Message,Document,Culprit,Path)`
mode – number of proofs:
  `exception(+atom,+nonvar,+nonvar,+nonvar) – one`

### document_generation//2

> DCG generating Document as a list of character codes. Format is true|false defining whether layouts, to provide indentation, should be added between the element content of the resultant "string". Note that formatting is disabled for elements that are interspersed with pcdata/1 terms, such as XHTML's 'inline' elements. Also, Format is over-ridden, for an individual element, by an explicit 'xml:space'="preserve" attribute.

compilation flags:
  `static`
template:
  `document_generation(Format,Document)`

### pcdata_7bit//1

> Represents the ascii character set in its simplest format, using the character entities &amp; &quot; &lt; and &gt; which are common to both XML and HTML. The numeric entity &#39; is used in place of &apos;, because browsers don't recognize it in HTML.

compilation flags:
  `static`
template:
  `pcdata_7bit(Char)`

### character_data_format/3

> Holds when Format0 and Format1 are the statuses of XML formatting before and after Chars - which may be null.

compilation flags:
  `static`
template:
  `character_data_format(Chars,Format0,Format1)`
mode – number of proofs:
  `character_data_format(+nonvar,+nonvar,?nonvar) – zero_or_one`

### cdata_generation//1

> Holds when Format0 and Format1 are the statuses of XML formatting before and after Chars - which may be null.

compilation flags:
  `static`
template:
  `cdata_generation(Chars)`

## Operators

### (none)

## Remarks

On-line documentation
  http://www.binding-time.co.uk/xmlpl.html

Compliance
  This XML parser supports a subset of XML suitable for XML Data and Worldwide Web applications. It is neither as strict nor as comprehensive as the XML 1.0 Specification mandates.

Compliance-strictness
  It is not as strict, because, while the specification must eliminate ambiguities, not all errors need to be regarded as faults, and some reasonable examples of real XML usage would have to be rejected if they were.

Compliance-comprehensive
  It is not as comprehensive, because, where the XML specification makes provision for more or less complete DTDs to be provided as part of a document, xml.pl actions the local definition of ENTITIES only. Other DTD extensions are treated as commentary.

Bi-directional conversions
  The conversions are not completely symmetrical, in that weaker XML is accepted than can be generated. Specifically, in-bound (Chars -> Document) parsing does not require strictly well-formed XML. If Chars does not represent well-formed XML, Document is instantiated to the term malformed(<attributes>, <content>).