2. Loading grammars

Before it can be used, a grammar must be loaded. You can load Invisible XML grammars in either the text or XML syntax. You can also load grammars in the CoffeeGrinder compiled format.

The grammar loading functions return an XML document. If the function succeeds, this will be a compiled representation of the grammar. It is not very useful except as the grammar input to one of the parsing functions. (If you’re interested in a useful XML representation of an Invisible XML grammar, parse the grammar with the Invisible XML grammar.)

If the grammar could not be loaded, 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.

The only code returned by the grammar functions is badgrammar, indicating that the attempt to parse the grammar failed.

2.1 cs:grammar-string

This function takes a string in the Invisible XML grammar format and parses it into a grammar. You can load the XML grammar formats directly as XML. You can load grammars from URIs with cs:grammar-uri.

cs:grammar-string($grammar)→node()

$grammar

xs:string

The Invisible XML grammar in text format

cs:grammar-string($grammar, $options)→node()

$grammar	xs:string	The Invisible XML grammar in text format
$options	map(xs:string, xs:string)	Grammar options

The following options are recognized:

type

Identifies the type of grammar to parse. The only value accepted is ixml, the text format.

It is an error to specify any other value.

2.2 cs:grammar-uri

This function loads a grammar from a URI.

cs:grammar-uri($href)→node()

$href

xs:string

The grammar location

cs:grammar-uri($href, $options)→node()

$href	xs:string	The grammar location
$options	map(xs:string, xs:string)	Grammar 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 the grammar saves the mapping between the URI and the parsed XML node.

type

Identifies the type of grammar to parse:

ixml: For Invisible XML in text format.
xml or vxml: For Invisible XML in XML format.
cxml or compiled: For a grammar in the compiled CoffeeGrinder format.

It is an error to specify any other value.

This is not usually necessary. The grammar compiler will “sniff” the first 4,095 bytes of the file to identify the grammar which is usually sufficient.

encoding

Specifies the encoding to use for Invisible XML grammars in the text format.