object

# `xml`

Bi-directional XML parser.

Author: John Fletcher; adapted to Logtalk by Paulo Moura.
Version: 3:8:2
Date: 2022-09-06
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`
Uses:
list
term
Remarks:

> - On-line documentation: https://binding-time.co.uk/index.php/Parsing_XML_with_Prolog

> - 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: Conversions are not fully symmetrical as weaker XML is accepted than can be generated. Notably, in-bound (Codes -> Document) parsing does not require strictly well-formed XML. If Codes does not represent well-formed XML, Document is instantiated to the term `malformed(<attributes>,<content>)`.

Inherited public predicates:
(none)

## Public predicates

### `parse/2`

Parses a list of character codes to/from a data structure of the form `xml(<atts>,<content>)`.

Compilation flags:
`static`
Template:
`parse(Codes,Document)`
Mode and number of proofs:
`parse(+list(character_code),?nonvar)` - `zero_or_one`
`parse(?list(character_code),+nonvar)` - `zero_or_one`

### `parse/3`

Parses a list of character codes to/from a data structure of the form `xml(<atts>,<content>)` using the given list of options.

Compilation flags:
`static`
Template:
`parse(Options,Codes,Document)`
Mode and number of proofs:
`parse(++list(compound),+list(character_code),?nonvar)` - `zero_or_one`
`parse(++list(compound),?list(character_code),+nonvar)` - `zero_or_one`
Remarks:

> - `extended_characters(Boolean)` option: Use the extended character entities for XHTML (default `true`).

> - `format(Boolean)` option: For parsing, strip layouts when no character data appears between elements (default `true`). For generating, indent the element content (default `true`).

> - `remove_attribute_prefixes(Boolean)` option: Remove namespace prefixes from attributes when it’s the same as the prefix of the parent element (default `false`).

> - `allow_ampersand(Boolean)` option: Allow unescaped ampersand characters (&) to occur in PCDATA (default `false`).

### `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 and 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 and number of proofs:
`pp(+nonvar)` - `zero_or_one`

## Protected predicates

(no local declarations; see entity ancestors if any)

## Private predicates

### `xml_to_document/3`

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

Compilation flags:
`static`
Template:
`xml_to_document(Options,XML,Document)`
Mode and 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 and 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 and 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 and 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 and 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 and 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 and 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)`
Mode and number of proofs:
`document_generation(+nonvar,+nonvar)` - `zero_or_one`

### `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(Code)`
Mode and number of proofs:
`pcdata_7bit(?nonvar)` - `zero_or_one`

### `character_data_format/3`

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

Compilation flags:
`static`
Template:
`character_data_format(Codes,Format0,Format1)`
Mode and 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 `Codes` - which may be null.

Compilation flags:
`static`
Template:
`cdata_generation(Codes)`
Mode and number of proofs:
`cdata_generation(+list)` - `zero_or_one`

## Operators

(none)