SGML or XML files are loaded through the common predicate load_structure/3. This is a predicate with many options. For simplicity a number of commonly used shorthands are provided: load_sgml_file/2, load_xml_file/2, and load_html_file/2.
- load_structure(+Source, -ListOfContent, +Options)
- Parse Source and return the resulting structure in
ListOfContent. Source is either a term of the
stream(StreamHandle)or a file-name. Options is a list of options controlling the conversion process.
A proper XML document contains only a single toplevel element whose name matches the document type. Nevertheless, a list is returned for consistency with the representation of element content. The ListOfContent consists of the following types:
- Atoms are used to represent
CDATA. Note this is possible in SWI-Prolog, as there is no length-limit on atoms and atom garbage collection is provided.
- element(Name, ListAttributes, ListOfContent)
- Name is the name of the element. Using SGML, which is
case-insensitive, all element names are returned as lowercase atoms.
ListOfAttributes is a list of Name=Value pairs for attributes. Attributes of type
CDATAare returned literal. Multi-valued attributes (
NAMES, etc.) are returned as a list of atoms. Handling attributes of the types
NUMBERSdepends on the setting of the
number(+NumberMode)attribute through set_sgml_parser/2 or load_structure/3. By default they are returned as atoms, but automatic conversion to Prolog integers is supported. ListOfContent defines the content for the element.
- If an entity with declared content-type
SDATAis encountered, this term is returned holding the data in Text.
- If an entity with declared content-type
NDATAis encountered, this term is returned holding the data in Text.
- If a processing instruction is encountered (
<?...?>), Text holds the text of the processing instruction. Please note that the
<?xml ...?>instruction is handled internally.
The Options list controls the conversion process. Currently defined options are below. Other options are passed to sgml_parse/2.
- Reference to a DTD object. If specified, the
<!DOCTYPE ...>declaration is ignored and the document is parsed and validated against the provided DTD. If provided as a variable, the created DTD is returned. See section 3.5.
- Specify the parsing dialect. Supported are
xmlns. See the option
dialectof set_sgml_parser/2 for details.
- Define whether SHORTTAG abbreviation is accepted. The default is true
for SGML mode and false for the XML modes. Without SHORTTAG, a
is accepted with warning as part of an unquoted attribute-value, though
/>still closes the element-tag in XML mode. It may be set to false for parsing HTML documents to allow for unquoted URLs containing
- Sets the‘space-handling-mode' for the initial environment. This
mode is inherited by the other environments, which can override the
inherited value using the XML reserved attribute
xml:space. See section 3.2.
- Determines how attributes of type
NUMBERSare handled. If
token(default) they are passed as an atom. If
integerthe parser attempts to convert the value to an integer. If successful, the attribute is passed as a Prolog integer. Otherwise it is still passed as an atom. Note that SGML defines a numeric attribute to be a sequence of digits. The
sign is not allowed and
1is different from
01. For this reason the default is to handle numeric attributes as tokens. If conversion to integer is enabled, negative values are silently accepted.
- Treat attribute values as case sensitive. The default is
truefor XML and
falsefor SGML and HTML dialects.
- Treat attribute values as case insensitive but do not alter their case.
The default is
false. Setting this option sets the
case_sensitive_attributesto the same value. This option was added to support HTML quasi quotations and most likely has little value in other contexts.
- Define whether SYSTEM entities are expanded. The default is
- Determines how default and fixed values from the DTD are used. By
default, defaults are included in the output if they do not appear in
the source. If
false, only the attributes occurring in the source are emitted.
- entity(+Name, +Value)
- Defines (overwrites) an entity definition. At the moment, only
CDATAentities can be specified with this construct. Multiple entity options are allowed.
- Sets the name of the file on which errors are reported. Sets the linenumber to 1.
- Sets the starting line-number for reporting errors.
- Sets the maximum buffer size in bytes available for input data and CDATA
output. If this limit is reached a resource error is raised. Using
max_memory(0)(the default) means no resource limit will be enforced.
- Specify the representation of cdata elements. Supported are
string. The choice is not obvious. Strings are allocated on the Prolog stacks and subject to normal stack garbage collection. They are quicker to create and avoid memory fragmentation. But, multiple copies of the same string are stored multiple times, while the text is shared if atoms are used. Strings are also useful for security sensitive information as they are invisible to other threads and cannot be enumerated using, e.g., current_atom/1. Finally, using strings allows for resource usage limits using the global stack limit (see set_prolog_stack/2).
- Specify the representation of attribute values. Supported are
string. See above for the advantages and disadvantages of using strings.
true, xmlns namespaces with prefixes are returned as
ns(Prefix, URI)terms. If
false(default), the prefix is ignored and the xmlns namespace is returned as just the URI.