Generated: September 4, 2002, 15:49:30Copyright ©2002, Kurt NørmarkThe local LAML software home page

Reference Manual of the XML-in-LAML library

Kurt Nørmark ©    normark@cs.auc.dk    Department of Computer Science    Aalborg University    Denmark    

Master index
Source file: lib/xml-in-laml/xml-in-laml.scm
LAML Version 18.00 (August 31, 2002) full

The XML-in-LAML common parts, which are shared between all XML-in-LAML languages. This library is designed to co-exists with non-validating HTML mirrors (for the sake of LENO, for instance). It cannot be used together with validating ast-based HTML mirrors, such as html4.01-transitional-validating. If you need to, you should use an all xml-in-laml solution. By that we mean a solution, where also the HTML stuff is based on XML-in-LAML. In practical terms, it means that you should use the XML-in-LAML XHTML mirror in lib/xml-in-laml/mirrors/

Table of Contents:
1. This section contains the XML declaration 5. XML language registration and language related bookkeeping.9. Attribute checking.
2. Configuration part.6. The language map.10. Rendering functions and procedures.
3. Other Constants.7. Mirror generation functions.11. Other useful functions.
4. AST functions.8. Contents validation.

Alphabetic index:
__The symbolic name of explicit white space suppress
ast-attributes(ast-attributes ast)Return the list of attributes of ast, on property list format.
ast-element-name(ast-element-name ast)Return the root element name of ast.
ast-kind(ast-kind ast)Return the kind of the ast.
ast-language(ast-language ast)Return the language of teh ast (a symbol).
ast-subtrees(ast-subtrees ast)Return the list of substrees of ast.
ast-to-parse-tree(ast-to-parse-tree ast)Convert an abtract syntax tree to a parse tree.
ast?(ast? x)Is the parameter x an AST
causes-xml-in-laml-name-clash?(causes-xml-in-laml-name-clash? name)Is name involed in a name clash among the registered xml-in-laml languages?
cdata?(cdata? x)Is the parameter x CDATA
check-ast-constituents?check-ast-constituents?A boolean variable that controls whether or not we check the internal soundness of ASTs.
contents-data?(contents-data? x)Is the parameter x either an ast or a contents string.
element-names-of-language(element-names-of-language language)Return the element names of language, as defined by its language map.
forced-white-space?(forced-white-space? x)Is the parameter x a white space mark.
generate-xml-mirror-function(generate-xml-mirror-function validation-procedure tag-name default-dtd-attributes single-double-kind language overlap-check? action-procedure)Return an XML mirror surface function, in which textual content parameters and attribute value pairs can be given in a very liberal fashion.
get-mirror-function(get-mirror-function language-map element-name)Return the mirror function based on element-name from language map.
language-in-use?(language-in-use? language)Is language in use - is it registered as an xml-in-laml language?
language-map-of(language-map-of language)Return the language map of language.
languages-in-use(languages-in-use)Return the list of language in used, as registered by register-xml-in-laml-language.
make-ast(make-ast element-name contents attributes kind language)Make an AST given element-name, contents, a property list of attributes, a kind (single/double) an an XML language name.
one-or-more(one-or-more . element-constituent-list)Return a predicate which checks whether the contents matches one or more instances from element-constituent-list.
pass-default-dtd-attributes?pass-default-dtd-attributes?Pass the default attributes from the DTD explicitly side by side (but after) the explicitly given attributes of an element.
pcdata-checker(pcdata-checker contents)A predicate which checks whether the contents is PCDATA.
put-mirror-function(put-mirror-function language-map element-name mirror-function)Update the language map by the association of element-name and mirror function.
register-xml-in-laml-language(register-xml-in-laml-language language language-map)Register that language (the first parameter) is an XML language in use in the current LAML session.
render-to-output-port(render-to-output xml-clause output-port [prolog epilog])Render the XML clause (an AST) to output-port.
sequence-with-optionals(sequence-with-optionals . rhs-elements)Return a predicate which checks whether the contents match the sequential rhs-elements.
white-space-related?(white-space-related? x)Is the parameter x white space related?
xml-check-attributes!(xml-check-attributes! attributes dtd-attribute-definition number-of-req-attributes tag-name)Check the attributes (first par) in the calling form against the attribute definitions taken from the DTD file (second par).
xml-check-attributes?xml-check-attributes?A boolean variable which controls the checking of tag attributes.
xml-check-errorxml-check-errorThe definition of the procedure that reports validation errors.
xml-check-language-overlap?xml-check-language-overlap?A boolean variable that controls the check of XML language overlap.
xml-declaration(xml-declaration)Return the xml declaration
xml-error-truncation-lengthxml-error-truncation-lengthHow many characters of the validation error messages to be presented.
xml-in-laml-name-clashesxml-in-laml-name-clashesThe list of names (symbols) which causes name clashes relative to the current set of languages in use.
xml-modify-element(xml-modify-element element . attributes-and-contents)Define partial attributes and element contents of element and return a new element function with the attributes and contents partially fixed.
xml-non-transliteration-elementsxml-non-transliteration-elementsA list of elements for which content data - CDATA - is never transformed.
xml-render(render xml-clause [prolog epilog])Render the xml-clause (an AST) and return the rendered string
xml-sort-tag-parameters(xml-sort-tag-parameters parameters tag-name)The central function which 'sorts out' the parameters of the mirror functions.
xml-transliterate-character-data?xml-transliterate-character-data?A boolean variable that controls whether CDATA (Character data) are transformed through the HTML/XML character transformation table.
xml-validate-contents?xml-validate-contents?A boolean variable that controls the XML validation.
zero-or-more(zero-or-more . element-constituent-list)Return a predicate which checks whether the contents matches zero or more instances from element-constituent-list

 

1.   THIS SECTION CONTAINS THE XML DECLARATION


xml-declaration


Form
(xml-declaration)

Description
Return the xml declaration


 

2.   CONFIGURATION PART.
The variables and functions in this part controls the checking, validation, and error reporting of the XML mirror functions.


xml-check-attributes?


Form
xml-check-attributes?

Description
A boolean variable which controls the checking of tag attributes. If true, check the tag (element) attributes against the attributes as defined in the DTD file. The default value is true.


xml-validate-contents?


Form
xml-validate-contents?

Description
A boolean variable that controls the XML validation. If true, do validate the generated XML document against the DTD. The default value is true.


xml-check-language-overlap?


Form
xml-check-language-overlap?

Description
A boolean variable that controls the check of XML language overlap. If true, check that that no elements are used via ambiguous simple names.


xml-transliterate-character-data?


Form
xml-transliterate-character-data?

Description
A boolean variable that controls whether CDATA (Character data) are transformed through the HTML/XML character transformation table. The default value is true.

See also
Character transformation tabletable


xml-non-transliteration-elements


Form
xml-non-transliteration-elements

Description
A list of elements for which content data - CDATA - is never transformed. As an example, it will often cause problems if scripts are being modified by means of transliterations using the HTML character transformation table. A list of strings. Defaults to the empty list You can redefine it after the document style has been loaded. XML language specific.


xml-error-truncation-length


Form
xml-error-truncation-length

Description
How many characters of the validation error messages to be presented.


pass-default-dtd-attributes?


Form
pass-default-dtd-attributes?

Description
Pass the default attributes from the DTD explicitly side by side (but after) the explicitly given attributes of an element. Pr. default, not not pass them.


 

3.   OTHER CONSTANTS.


_


Form
_

Description
The symbolic name of explicit white space suppress


 

4.   AST FUNCTIONS.
In this section we document the functions that work on abstract syntax trees. All the XML mirror functions return abstract syntax trees, which need to be transformed to text before they can be presented. The function xml-render performs this transformation.


check-ast-constituents?


Form
check-ast-constituents?

Description
A boolean variable that controls whether or not we check the internal soundness of ASTs. If the basic mirror is used directly, it makes good sense to set this variable to #t. Else we recommend a #f value.


make-ast


Form
(make-ast element-name contents attributes kind language)

Description
Make an AST given element-name, contents, a property list of attributes, a kind (single/double) an an XML language name. elment-name must be a string or symbol. The parameter contents may be a list of subtrees. It may also be or an element which satisfies either ast?, cdata? or forced-white-space?. In these cases, we embed the single element into a list. attributes is the list of attributes on property list format (such as '(a1 "v1" a2 "v2")). attribute names are always symbols, and attribute values are always strings. Kind is either the symbol double or single. Language is a symbol or string that represent the XML language name.


ast-element-name


Form
(ast-element-name ast)

Description
Return the root element name of ast.

Preconditions
ast is an abstract syntax tree that satisfies the ast? predicate


ast-subtrees


Form
(ast-subtrees ast)

Description
Return the list of substrees of ast.

Preconditions
ast is an abstract syntax tree that satisfies the ast? predicate


ast-attributes


Form
(ast-attributes ast)

Description
Return the list of attributes of ast, on property list format.

Preconditions
ast is an abstract syntax tree that satisfies the ast? predicate


ast-kind


Form
(ast-kind ast)

Description
Return the kind of the ast. It is either the symbol single or double. Tells whether the ast is to be rendered as a single or double tag.

Preconditions
ast is an abstract syntax tree that satisfies the ast? predicate


ast-language


Form
(ast-language ast)

Description
Return the language of teh ast (a symbol).

Preconditions
ast is an abstract syntax tree that satisfies the ast? predicate


ast?


Form
(ast? x)

Description
Is the parameter x an AST


cdata?


Form
(cdata? x)

Description
Is the parameter x CDATA


contents-data?


Form
(contents-data? x)

Description
Is the parameter x either an ast or a contents string.


forced-white-space?


Form
(forced-white-space? x)

Description
Is the parameter x a white space mark.


white-space-related?


Form
(white-space-related? x)

Description
Is the parameter x white space related?


 

5.   XML LANGUAGE REGISTRATION AND LANGUAGE RELATED BOOKKEEPING.


xml-in-laml-name-clashes


Form
xml-in-laml-name-clashes

Description
The list of names (symbols) which causes name clashes relative to the current set of languages in use. Assigned by register-xml-in-laml-language. Thus, this variable is always up-to-date in between registrations of languages. Be careful not to redefine this variable by double loading this file.


register-xml-in-laml-language


Form
(register-xml-in-laml-language language language-map)

Description
Register that language (the first parameter) is an XML language in use in the current LAML session. The first parameter, language, is a symbol. The second parameter, language-map, is the language map of the language. As a precondition is a assumed that we do not register the same language more than once.


language-map-of


Form
(language-map-of language)

Description
Return the language map of language. If language is not registered via register-xml-in-laml-language, return #f. The parameter language is a symbol.


language-in-use?


Form
(language-in-use? language)

Description
Is language in use - is it registered as an xml-in-laml language?


languages-in-use


Form
(languages-in-use)

Description
Return the list of language in used, as registered by register-xml-in-laml-language.


element-names-of-language


Form
(element-names-of-language language)

Description
Return the element names of language, as defined by its language map.


causes-xml-in-laml-name-clash?


Form
(causes-xml-in-laml-name-clash? name)

Description
Is name involed in a name clash among the registered xml-in-laml languages?


 

6.   THE LANGUAGE MAP.
The language map is a mapping that allows us to access the element mirror functions independent of any name clash. In this version the language map is an association list from element names (symbols) to function objects. In the longer run, it should be more efficient search structure.


get-mirror-function


Form
(get-mirror-function language-map element-name)

Description
Return the mirror function based on element-name from language map. Return #f if no mirror function exists in the map. The parameter element-name is either a symbol or a string.


put-mirror-function


Form
(put-mirror-function language-map element-name mirror-function)

Description
Update the language map by the association of element-name and mirror function. Returns the updated map. The parameter element-name is either a symbol or a string. Causes an error if there already is an entry for element-name


 

7.   MIRROR GENERATION FUNCTIONS.
The functions in this sections are the important and 'heavy' mirror generation functions.


xml-sort-tag-parameters


Form
(xml-sort-tag-parameters parameters tag-name)

Description
The central function which 'sorts out' the parameters of the mirror functions. Returns a cons cell of contents and attributes. Attributes are returned in property list format.


generate-xml-mirror-function


Form
(generate-xml-mirror-function validation-procedure tag-name default-dtd-attributes single-double-kind language overlap-check? action-procedure)

Description
Return an XML mirror surface function, in which textual content parameters and attribute value pairs can be given in a very liberal fashion.

Parameters
validation-procedurethe procedure that validates all aspects of the application of the element mirror function.
tag-namea string which represents the name of the tag (used for error message purposes).
default-dtd-attributesan alist of attribute key value pairs, as specified in the DTD.
single-double-kindeither the symbol single, double or possible-single.
languagethe language in use (a symbol).
overlap-check?controls whether to check for name clashes in between the registered XML-in-LAML languages.
action-procedureserves both as a boolean and a procedure. If non-false, the parameter servers as action procedure, which will receive the AST for action purposes.


 

8.   CONTENTS VALIDATION.
The definitions in this section is used by the validation procedures, which are specific for each supported XML language


one-or-more


Form
(one-or-more . element-constituent-list)

Description
Return a predicate which checks whether the contents matches one or more instances from element-constituent-list. Element constituent-list is a list of strings, namely element tag names or "#PCDATA". A true results means OK - no error Avoid a O(n^2) algorithm here in the final implementation


zero-or-more


Form
(zero-or-more . element-constituent-list)

Description
Return a predicate which checks whether the contents matches zero or more instances from element-constituent-list


sequence-with-optionals


Form
(sequence-with-optionals . rhs-elements)

Description
Return a predicate which checks whether the contents match the sequential rhs-elements. rhs-elements is a list of strings or symbols, where symbols represent optionals. Example (sequence-with-optionals "xxx" "yyy" 'zzz) corresponds to xxx, yyy, zzz? We assume that rhs-elements, in the starting point, always contains at least one element.


pcdata-checker


Form
(pcdata-checker contents)

Description
A predicate which checks whether the contents is PCDATA.


 

9.   ATTRIBUTE CHECKING.
The definitions in this section is used by the validation procedures, which are specific for each supported XML language. Current status of attribute checking: TokenizedTypes are not checked (ID, IDREFS, ...). In reality there is probably not much to check (besides some lexical checks which we can easily deal with, and some contraints which are much harder). NotationTypes are not dealt with - mostly because I have never encountered them, so the motivation to program check for this special enumeration type is not high. The #FIXED default keyword is present in the parsed DTD information, but we do not carry out any check against it (which is: If the attribute is given it must have the fixed default value). The attribute value normalization called for in section 3.3.3 of the XML specificaiton is not done either.


xml-check-attributes!


Form
(xml-check-attributes! attributes dtd-attribute-definition number-of-req-attributes tag-name)

Description
Check the attributes (first par) in the calling form against the attribute definitions taken from the DTD file (second par). The first parameter, attribute, is the attributes of the calling form, on property list form: (a1 v1 ... an vn). ai is a symbol and vi is a string. The second parameter dtd-attribute-definition is the attributes as defined in the dtd for the element in question. The third parameter number-of-req-attributes is the number of required attributes in dtd-attr-definitions. It happens to be the case that all the required attributes are located in the front of dtd-attribute-definition. The fourth parameter, tag-name, is the name of the enclosing tag. dtd-attribute-definition is a list of triples (attr-name attr-type require-status). attr-name is a string, attr-type is a string or a list of strings (possibilities), and require-status is a string such as "#IMPLIED" or "#REQUIRED"


xml-check-error


Form
xml-check-error

Description
The definition of the procedure that reports validation errors. The default value is display-xml-warning, which issues non-fatal warning messages. Alternative value: laml-error (fatal error messaging).


 

10.   RENDERING FUNCTIONS AND PROCEDURES.
The functions and procedures in this section transform the internal document representation (abstract syntax trees) to a textual form (text strings).


render-to-output-port


Form
(render-to-output xml-clause output-port [prolog epilog])

Description
Render the XML clause (an AST) to output-port. output-port is assumed to be open. output-port will not be closed by this procedure.

Parameters
xml-clausean AST
output-portan open output port
prologThe symbol prolog, in which case (standard-prolog) is inserted, or a prolog string to be inserted
epilogThe symbol epilog in which case (standard-epilog) is inserted, or a epilog string to be inserted


xml-render


Form
(render xml-clause [prolog epilog])

Description
Render the xml-clause (an AST) and return the rendered string

Parameters
xml-clausean AST
prologThe symbol prolog, in which case (standard-prolog) is inserted, or a prolog string to be inserted
epilogThe symbol epilog in which case (standard-epilog) is inserted, or a epilog string to be inserted


 

11.   OTHER USEFUL FUNCTIONS.
In this section there are non-mirror functions which are useful in in the context of XML and LAML.


xml-modify-element


Form
(xml-modify-element element . attributes-and-contents)

Description
Define partial attributes and element contents of element and return a new element function with the attributes and contents partially fixed. attributes-and-contents is of the same form as the parameters to a LAML surface mirror functions. In fact, attributes-and-contents are just appended to the actual parameters to the modified.

Returns
an attribute-modified mirror function

Example
(define a-main (modify-element a 'target "main"))


ast-to-parse-tree


Form
(ast-to-parse-tree ast)

Description
Convert an abtract syntax tree to a parse tree. Abstract syntax trees are produced by the validating mirror functions. Parse trees are used as an internal format in the HTML and the XML pretty printing procedures. You can use the function pretty-print-html-parse-tree on the parse tree returned by ast-to-parse-tree.

Preconditions
The LAML tool html-support (for parsing and pretty printing) must be loaded for this function to work.

Note
To load html-support: (laml-tool-load "xml-html-support/html-support.scm")


Generated: September 4, 2002, 15:49:30
This documentation has been extracted automatically from the Scheme source file by means of the Schemedoc tool