get_sgml_parser/2

Availability::- use_module(library(sgml)).(can be autoloaded)

get_sgml_parser(+Parser, -Option)

Retrieve infomation on the current status of the parser. Notably useful if the parser is used in the call-back mode. Currently defined options:

file(-File)

Current file-name. Note that this may be different from the provided file if an external entity is being loaded.

line(-Line)

Line-offset from where the parser started its processing in the file-object.

charpos(-CharPos)

Offset from where the parser started its processing in the file-object. See section 6.

charpos(-Start, -End)

Character offsets of the start and end of the source processed causing the current call-back. Used in PceEmacs to for colouring text in SGML and XML modes.

source(-Stream)

Prolog stream being processed. May be used in the on_begin, etc. callbacks from sgml_parse/2.

dialect(-Dialect)

Return the current dialect used by the parser (sgml, html, html5, xhtml, xhtml5, xml or xmlns).

event_class(-Class)

The event class can be requested in call-back events. It denotes the cause of the event, providing useful information for syntax highlighting. Defined values are:

explicit: The code generating this event is explicitely present in the document.
omitted: The current event is caused by the insertion of an omitted tag. This may be a normal event in SGML mode or an error in XML mode.
shorttag: The current event (begin or end) is caused by an element written down using the shorttag notation (<tag/value/>.
shortref: The current event is caused by the expansion of a shortref. This allows for highlighting shortref strings in the source-text.

doctype(-Element)

Return the defined document-type (= toplevel element). See also set_sgml_parser/2.

dtd(-DTD)

Return the currently used DTD. See dtd_property/2 for obtaining information on the DTD such as element and attribute properties.

context(-StackOfElements)

Returns the stack of currently open elements as a list. The head of this list is the current element. This can be used to determine the context of, for example, CDATA events in call-back mode. The elements are passed as atoms. Currently no access to the attributes is provided.

allowed(-Elements)

Determines which elements may be inserted at the current location. This information is returned as a list of element-names. If character data is allowed in the current location, #pcdata is part of Elements. If no element is open, the doctype is returned.

This option is intended to support syntax-sensitive editors. Such an editor should load the DTD, find an appropriate starting point and then feed all data between the starting point and the caret into the parser. Next it can use this option to determine the elements allowed at this point. Below is a code fragment illustrating this use given a parser with loaded DTD, an input stream and a start-location.

        ...,
        seek(In, Start, bof, _),
        set_sgml_parser(Parser, charpos(Start)),
        set_sgml_parser(Parser, doctype(_)),
        Len is Caret - Start,
        sgml_parse(Parser,
                   [ source(In),
                     content_length(Len),
                     parse(input)       % do not complete document
                   ]),
        get_sgml_parser(Parser, allowed(Allowed)),
        ...