3. Parsing inputs

The parsing functions attempts to parse the input string with the grammar provided. The result will be an XML document (or a map) that is either the parsed result or a document that specifies that an error occurred.

The grammar provided must be in XML format. This can be obtained with the grammar loading functions or, in the case of XML format grammars, through any convenient means.

The parsing functions return an XML document (or a map). If the parse is successful, this will be a representation of the result of parsing the input with the grammar.

If the parse is unsuccessful, a top-level ixml:state attribute (or property) with the value “fail” indicates that the parse did not succeed. The rest of the document will contain information that is designed to help you identify the error.

If the grammar could not be used, what will be returned will be a cs:error document (where the cs prefix is bound to https://ninenl.org/ns/coffeesacks/error). This document will have a code attribute that attempts to identify the error. The contents of the error document will further describe the error.

(If a JSON result was requested, the error document will have a cs:error property with the value of the code.)

The possible codes are notgrammar, if the input grammar was not a recognized XML representation of an Invisible XML grammar, or notxml, if the input grammar was not XML.

3.1 cs:parse-string

Parses an input string against a grammar.

cs:parse-string($grammar, $input)item()
$grammarnodeThe ixml grammar
$inputxs:stringThe input
cs:parse-string($grammar, $input, $options)item()
$grammarnodeThe ixml grammar
$inputxs:stringThe input
$optionsmap(xs:string, xs:string)Parsing options

The following options are recognized:

cache

If unspecified or specified with the value “true” or “yes”, the grammar will be cached. If any other value is specified, the grammar will not be cached.

Caching at this level saves the mapping between the XML representation of the grammar and the underlying Invisible XML parser object.

format

Identifies the format of the result:

xml

Returns an XML node.

json or json-data

Returns a “data” map. This method will fail if the result contains mixed content.

json-tree or json-text

Returns a “text” map. This map structure can represent any tree.

It is an error to specify any other value.

3.2 cs:parse-uri

Loads the document at the specified URI and attempts to parse it with the grammar provided.

cs:parse-uri($grammar, $href)item()
$grammarnodeThe ixml grammar
$hrefxs:stringThe document location
cs:parse-uri($grammar, $href, $options)item()
$grammarnodeThe ixml grammar
$hrefxs:stringThe document location
$optionsmap(xs:string, xs:string)Parsing options

The following options are recognized:

cache

If unspecified or specified with the value “true” or “yes”, the grammar will be cached. If any other value is specified, the grammar will not be cached.

Caching at this level saves the mapping between the XML representation of the grammar and the underlying Invisible XML parser object.

encoding

Specifies the encoding to use for the input document.

format

Identifies the format of the result:

xml

Returns an XML node.

json or json-data

Returns a “data” map. This method will fail if the result contains mixed content.

json-text or json-text

Returns a “text” map. This map structure can represent any tree.

It is an error to specify any other value.