Generated: August 27, 2003, 22:48:27Copyright ©2003, 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 21.00 (August 27, 2003, PP edition)

The XML-in-LAML common parts, which are shared between all XML-in-LAML languages. The library is used together with XHTML 1.0 transitional, XHTML 1.0 strict, XHTML 1.0 frameset, SVG 1.0, LENO (XML-in-LAML), and other similar mirrors.

This library is also designed to co-exists with non-validating HTML mirrors (mainly the sake of LENO, for instance). However, it cannot be used together with other validating AST-based HTML mirrors, such as Html4.01 transitional validating. 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 one of the XHTML mirrors mentioned above.

This library loads the the LAML final state automation library for the sake of full document validation at document generation time.

At the tool end, The XML-in-LAML Mirror Generation tool is able to create a set of Scheme mirror functions for a given XML DTD. The generated mirror functions together with the shared XML-in-LAML common library (this file) make up the effective mirror of an XML language.

Table of Contents:
1. XML front matter stuff.8. XML language bookkeeping.15. Rendering functions and procedures.
2. XML-in-LAML processing parameters.9. The language map.16. Element related functions.
3. Other Constants.10. XML navigation information.17. XML in LAML parametrization and abstraction functions.
4. AST constructors and basic selector selectors.11. Mirror generation functions.18. AST traversal and AST transformation functions.
5. High-level AST selector functions.12. Contents validation.19. Other useful functions.
6. AST predicates.13. Attribute checking.
7. Character entities.14. XML warning procedures.

Alphabetic index:
__The symbolic name of explicit white space suppress.
ast-attribute(ast-attribute ast name [default-attribute-value])Return the value of the attribute name in ast.
ast-attributes(ast-attributes ast)Return the list of attributes of the ast.
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 the ast.
ast-of-type?(ast-of-type? type name)A higher-order function that returns an AST predicate, which checks if the type of the AST is name.
ast-subtree(ast-subtree ast el-name [n])Return a specific subtree of ast, namely the n'th subtree with element-name el-name.
ast-subtrees(ast-subtrees ast)Return the list of substrees of ast.
ast-text(ast-text ast)Return a string of the aggregated CDATA contents 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
attribute-getter(attribute-getter attribute-name [default-value])A higher-order function which returns an attribute getter function on ASTs.
can-have-element-constituent?(can-have-element-constituent? ast el-name)Can ast have a direct or indirect constituent (sub-ast) with element name el-name.
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
char-ref(char-ref x)Return a character reference value for x.
char-ref-value(char-ref-value char-ref-structure)Return the number or symbol of char-ref-structure.
char-ref?(char-ref? x)Is x a character reference.
contents-data?(contents-data? x)Is the parameter x either an ast or a contents string.
display-xml-warning(display-xml-warning . messages)A variant of display-warning which prefixes the warning text with a 'XML Warning' prefix.
element-names-of-language(element-names-of-language language)Return the element names of language, as defined by its language map.
explicit-spaceexplicit-spaceThe explicit white space value, as used internally in ast.
explicit-space-suppressexplicit-space-suppressThe explicit white space suppress value.
find-asts(find-asts ast el-name [ast-transformer])Find and return a list of transformed sub ASTs of ast (first parameter) each with a root element of name el-name.
find-first-ast(find-first-ast ast el-name [ast-transformer])Find and return a sub-AST of ast (first parameter) with a root element of name el-name.
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.
indentation-deltaindentation-deltaAn integer which gives the level of indentation for pretty printed output.
laml-source-prepare(laml-source-prepare laml-lst)Prepare laml-list to be used as input to a mirror function.
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), and an XML language name.
possible-attributes-rooted-by-element(possible-attributes-rooted-by-element element-name language)Return a list of attribute names that can appear as direct or indirect constituents of an AST rooted by element-name.
possible-elements-rooted-by-element(possible-elements-rooted-by-element element-name language)Return a list of element names that can appear as direct or indirect constituents of an AST rooted by element-name.
preferred-maximum-widthpreferred-maximum-widthAn integer that expresses the prefered maximum column width for pretty printed ouput.
pretty-render-to-output-port(pretty-render-to-output-port xml-clause output-port [prolog epilog])Pretty print the XML clause (an AST) to output-port.
pretty-xml-render(pretty-xml-render xml-clause [prolog epilog])Pretty print xml-clause (an LAML AST) and return the rendered string.
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.
register-xml-in-laml-navigator(register-xml-in-laml-navigator language navigator-structure)Register navigator-structure and an XML-in-LAML navigator for language.
render-to-output-port(render-to-output xml-clause output-port [prolog epilog])Render the XML clause (an AST) to output-port.
required-implied-attributes(required-implied-attributes required-attribute-names implied-attribute-names [tag-name])A higher-order function which returns an attribute checker.
set-xml-accept-only-string-valued-attributes-in(set-xml-accept-only-string-valued-attributes-in language new-value)Controls the handling of LAML attribute values in language.
set-xml-char-transformation-table-in(set-xml-char-transformation-table-in language new-value)Set the HTML/XML character transformation table used for language.
set-xml-transliterate-character-data-in(set-xml-transliterate-character-data-in language new-value)Ask for transliteration of all CDATA characters via an HTML/XML character transformation table.
standard-prolog(standard-prolog [language])The standard-prolog function as redefined for XML.
terminal-ast-node?(terminal-ast-node? x)Is x an ast nodes without subtrees?
transform-ast-list(transform-ast-list input-list . transform-specs)Apply the transformation-specs on input-list and return a list of transformed input elements.
traverse-and-collect-all-from-ast(traverse-and-collect-all-from-ast ast-tree node-interesting? ast-transformer)Traverse all nodes of the AST ast-tree, and return transformed subtrees that satisfy the node-interesting? predicate.
traverse-and-collect-first-from-ast(traverse-and-collect-first-from-ast ast-tree node-interesting? ast-transformer)Traverse the AST ast-tree, and return a transformation of the first subtree which satisfies the predicate node-interesting.
unique-ast-attribute(unique-ast-attribute ast name [default-attribute-value])Return the value of the attribute name in ast, or in one of the subtrees of ast.
validate-as-pcdata!(validate-as-pcdata! contents tag-name)Validate that contents is pure PCDATA.
validate-contents-by-dfa!(validate-contents-by-dfa! contents dfa tag-name)Apply the deterministic final state automaton dfa on contents.
validate-mixed-contents-by-simple-means!(validate-mixed-contents-by-simple-means! contents symbol-choice-list tag-name)Validate that contents corresponds to mixed contents.
white-space-related?(white-space-related? x)Is the parameter x white space related?
white-space-suppress?(white-space-suppress? x)Is the parameter x a white suppress space mark.
xml-accept-only-string-valued-attributes-in?(xml-accept-only-string-valued-attributes-in? language)A boolean variable that controls how rigid LAML handles attribute values in language (first parameter).
xml-char-transformation-table-in(xml-char-transformation-table-in language)Return the HTML/XML character transformation table used for language.
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 element attributes.
xml-check-error(xml-check-error . messages)The procedure that reports XML 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-document-type-declaration-in(xml-document-type-declaration-in language)Return the document type declaration of language.
xml-error-truncation-lengthxml-error-truncation-lengthHow many characters of the validation error messages to be presented.
xml-in-laml-abstraction(xml-in-laml-abstraction f [parameter-validator! f-name])Generate a function with XML-in-LAML parameter passing rules which sends its input to an XML or HTML mirror function, or to another XML-in-LAML abstraction.
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-in-laml-parametrization(xml-in-laml-parametrization f parameter-mediator [parameter-validator! f-name])Generate a function with XML-in-LAML parameter passing rules which sends its input to an ordinary function, f, with positional parameters via a parameter mediator.
xml-modify-element(xml-modify-element element . attributes-and-contents)Bind some attributes content elements of element (the first parameter) and return a new, 'modified element function'.
xml-modify-element-prepend(xml-modify-element-prepend element . attributes-and-contents)A function similar to xml-modify-element, but instead of appending attributes-and-contents to the actual parameters of the modified function, it prepends attributes-and-contents.
xml-navigator-of(xml-navigator-of language)Return the XML navigator structure of language.
xml-non-transliteration-elements-in(xml-non-transliteration-elements-in language)Return the list of element names, for which we do not carry out the character transliteration in language.
xml-pass-default-dtd-attributes-in?(xml-pass-default-dtd-attributes-in? language)Controls whether the default attribute values, as specified in the DTD, are passed explicitly as attribute values in every instance of the element.
xml-preformatted-text-elements-in(xml-preformatted-text-elements-in language)Return the list of element names, for which we consistenly render all white space content characters as given in the input.
xml-render(xml-render xml-clause [prolog epilog])Render the xml-clause (an LAML AST) and return the rendered string.
xml-represent-white-space-in?(xml-represent-white-space-in? language)This value controls the representation of white space in the internal AST representation of a document.
xml-sort-superficially-tag-parameters(xml-sort-superficially-tag-parameters parameters tag-name [language])Like xml-sort-tag-parameters, but collect the content contribution in a relatively raw surface form.
xml-sort-tag-parameters(xml-sort-tag-parameters parameters tag-name [language])Separates parameters according to the mirror rules of LAML.
xml-transliterate-character-data-in?(xml-transliterate-character-data-in? language)Return if CDATA (Character data) is transformed through an HTML/XML character transformation table.
xml-validate-contents?xml-validate-contents?A boolean variable that controls the XML validation.

 

1.   XML FRONT MATTER STUFF.
This section contains the XML declaration and other XML front matter stuff


standard-prolog


Form
(standard-prolog [language])

Description
The standard-prolog function as redefined for XML. It returns the xml-declaration, the document type declaration, and a copyright comment. The standard prolog is the document part before the document root element. A default version of the standard-prolog is found in laml.scm. The present function relies on another function, xml-document-type-declaration-in, which returns an appropriate document type declaration

See also
applied functionxml-declaration    
applied functionxml-document-type-declaration-in    
applied functioncopyright-clause


xml-declaration


Form
(xml-declaration)

Description
Return the xml declaration


 

2.   XML-IN-LAML PROCESSING PARAMETERS.
The variables and functions in this part controls a number of general properties of XML-in-LAML processing. Some of these are generic for all XML-in-LAML languages; Others are specific to a single language. A number of the properties are related to 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 element attributes. If true, check the element attributes against the attributes as defined in the DTD file. This variable is generic and common for all XML-in-LAML languages. 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. This variable is generic and common for all XML-in-LAML languages. 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. Quite naturally, this variable is generic and common for XML-in-LAML loaded at the same time.


xml-transliterate-character-data-in?


Form
(xml-transliterate-character-data-in? language)

Description
Return if CDATA (Character data) is transformed through an HTML/XML character transformation table. The value is boolean, and normally true.

See also
mutatorset-xml-transliterate-character-data-in    
transformation tablelaml.scm


set-xml-transliterate-character-data-in


Form
(set-xml-transliterate-character-data-in language new-value)

Description
Ask for transliteration of all CDATA characters via an HTML/XML character transformation table. new-value must be boolean.

Parameters
languageThe name of the XML-in-LAML language - see the first few linew of relevant mirror library manuals - a symbol.
new-valueA boolean value.

See also
selectorxml-transliterate-character-data-in?    
table getterxml-char-transformation-table-in    
table setterset-xml-char-transformation-table-in    
exceptionsxml-non-transliteration-elements-in    
transformation tablelaml.scm

Note
Consider macro implementation.


xml-char-transformation-table-in


Form
(xml-char-transformation-table-in language)

Description
Return the HTML/XML character transformation table used for language.

Returns
A character transformation table.

See also
transformation tablelaml.scm
table setterset-xml-char-transformation-table-in    
exceptionsxml-non-transliteration-elements-in    


set-xml-char-transformation-table-in


Form
(set-xml-char-transformation-table-in language new-value)

Description
Set the HTML/XML character transformation table used for language. The value must be a character transformation table.

Parameters
languageThe name of the XML-in-LAML language - see the first few linew of relevant mirror library manuals - a symbol.
new-valueA character transformation table.

See also
table getterxml-char-transformation-table-in    
exceptionsxml-non-transliteration-elements-in    
transformation tablelaml.scm

Note
Consider macro implementation.


xml-non-transliteration-elements-in


Form
(xml-non-transliteration-elements-in language)

Description
Return the list of element names, for which we do not carry out the character transliteration in language. In XHTML, the list typically include the elements style and script. The value is a list of strings. The value of this function is locked and bound at mirror generation time.

See also
transliterationxml-transliterate-character-data-in?    


xml-preformatted-text-elements-in


Form
(xml-preformatted-text-elements-in language)

Description
Return the list of element names, for which we consistenly render all white space content characters as given in the input. In XHTML, the list typically include the pre element. The value is a list of strings. The value of this function is locked and bound at mirror generation time.


xml-error-truncation-length


Form
xml-error-truncation-length

Description
How many characters of the validation error messages to be presented. If you want longer error messages, just increase the value of this variable. The default value is currently 130.


xml-pass-default-dtd-attributes-in?


Form
(xml-pass-default-dtd-attributes-in? language)

Description
Controls whether the default attribute values, as specified in the DTD, are passed explicitly as attribute values in every instance of the element. The value is boolean, and normally false. A true value in most cases give problems relative to the XML attribute validation. The value of this function is locked and bound at mirror generation time.

See also
validation controlxml-check-attributes?    


xml-accept-only-string-valued-attributes-in?


Form
(xml-accept-only-string-valued-attributes-in? language)

Description
A boolean variable that controls how rigid LAML handles attribute values in language (first parameter). As the name indicates, the value controls if only string valued attributes are allowed in the language. If no language information is present (i.e., if the language parameter is #f) always return #t.

See also
setterset-xml-accept-only-string-valued-attributes-in    


set-xml-accept-only-string-valued-attributes-in


Form
(set-xml-accept-only-string-valued-attributes-in language new-value)

Description
Controls the handling of LAML attribute values in language. If new-value is true, LAML only accept string valued XML attribute. If new-value is false, LAML string converts whatever follows an attribute symbol. The value must be a boolean value. True is recommended.

Parameters
languageThe name of the XML-in-LAML language - see the first few linew of relevant mirror library manuals - a symbol.
new-valueA boolean value.

See also
getterxml-accept-only-string-valued-attributes-in?    

Note
Consider macro implementation.


xml-document-type-declaration-in


Form
(xml-document-type-declaration-in language)

Description
Return the document type declaration of language. The empty string signals that no document type declaration is available. The value of this function is locked and bound at mirror generation time.


xml-represent-white-space-in?


Form
(xml-represent-white-space-in? language)

Description
This value controls the representation of white space in the internal AST representation of a document. If true, white space markers are inserted. If false, a clean AST without any white space marking is produced. In some languages, white space handling is essential. This is the case in XHTML. In XML languages that are not related to presentation at all, white space handling is not relevant. The value of this function is locked and bound at mirror generation time.


 

3.   OTHER CONSTANTS.


explicit-space


Form
explicit-space

Description
The explicit white space value, as used internally in ast. The default value is boolean #t.


explicit-space-suppress


Form
explicit-space-suppress

Description
The explicit white space suppress value. The default value is boolean #f.


_


Form
_

Description
The symbolic name of explicit white space suppress.


preferred-maximum-width


Form
preferred-maximum-width

Description
An integer that expresses the prefered maximum column width for pretty printed ouput.


indentation-delta


Form
indentation-delta

Description
An integer which gives the level of indentation for pretty printed output.


 

4.   AST CONSTRUCTORS AND BASIC SELECTOR SELECTORS.
In this section we document the functions that work on abstract syntax trees (ASTs). More specifically, we describe the AST constructur function and the most basic functions that select a constituent of an AST. Abstract syntax trees make up the internal representation of XML documents in LAML. All XML mirror functions return abstract syntax trees, and as such they can be thought as convenient, high level AST constructors.


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), and an XML language name. The parameter contents may be a list of subtrees. It may also be 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 normally strings.

Parameters
element-nameA symbol or a string.
contentsA list of contents in term of CDATA (strings), white space markers, or other ASTs.
attributesThe attributes represented as a property list
kindThe symbol double or single
languageA symbol or string that represent the XML-in-LAL language name.


ast-element-name


Form
(ast-element-name ast)

Description
Return the root element name of ast. The type of the returned value is a string.

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. This is also known as the contents of the ast. It is a list of CDATA (strings), ASTs, and white space markers.

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

See also
similar functionast-subtree    


ast-attributes


Form
(ast-attributes ast)

Description
Return the list of attributes of the ast.

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

Returns
The list of attributes, as a property list.

See also
Relevant functionget-prop
Relevant functiondefaulted-get-prop
high-level selectorast-attribute    
high-order selectorattribute-getter    

Note
The functions get-prop and defaulted-get-prop are useful for accessing the individual attribute values in the returned property list.


ast-kind


Form
(ast-kind ast)

Description
Return the kind of the ast. The type of the returned value is a symbol, either single or double. ASTs of type single are also known as empty elements. 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 the ast. The type of the returned value is a symbol.

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


 

5.   HIGH-LEVEL AST SELECTOR FUNCTIONS.
In this section we describe a set of more elaborate functions that access the constituents of an AST. In many contexts, the functions in this section are more convenient than the basic selector functions from the previous section.


ast-subtree


Form
(ast-subtree ast el-name [n])

Description
Return a specific subtree of ast, namely the n'th subtree with element-name el-name. If no such subtree exists, return #f. The first subtree of a given name counts as number 1 (not 0).

Preconditions
n > 0

Parameters
astThe ast in which to locate a subtree
el-nameThe ast element name of a subtree of ast (string or symbol)
nThe constituent number regarding el-name subtrees (an integer). Defaults to 1.

Returns
A subtree of AST (if located) or #f

See also
basic selectorast-subtrees    
generalized accessorstraverse-and-collect-all-from-ast    traverse-and-collect-first-from-ast    


ast-attribute


Form
(ast-attribute ast name [default-attribute-value])

Description
Return the value of the attribute name in ast. Only attributes of the root of the root node of ast are considered. This function is a convenient shorcut of (defauted-get-prop name (ast-attributes ast) default-value). The optional parameter serves as the attribute value in case no name attribute is found in the attribute list of ast.

Parameters
astAn AST.
nameThe name of an attribute (a symbol).
default-attribute-valueThe default value, used if no attribute of name is found. A string.

See also
basic selectorast-attributes    
related functionunique-ast-attribute    


attribute-getter


Form
(attribute-getter attribute-name [default-value])

Description
A higher-order function which returns an attribute getter function on ASTs. The returned function takes an AST as parameter.

Parameters
attribute-namethe attribute name - a symbol.
default-valuethe default value returned if there is no attribute named attribute-name in the attribute-list.

See also
lower-order functionast-attribute    


ast-text


Form
(ast-text ast)

Description
Return a string of the aggregated CDATA contents of ast. White space markers are taken into account, but ast subtrees of ast are ignored.


 

6.   AST PREDICATES.
The functions in this section are predicates that work on ASTs.


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-suppress?


Form
(white-space-suppress? x)

Description
Is the parameter x a white suppress space mark.


white-space-related?


Form
(white-space-related? x)

Description
Is the parameter x white space related?


terminal-ast-node?


Form
(terminal-ast-node? x)

Description
Is x an ast nodes without subtrees?


ast-of-type?


Form
(ast-of-type? type name)

Description
A higher-order function that returns an AST predicate, which checks if the type of the AST is name. The type is either element-name, kind, or language (a symbol). The resulting predicate may be applied on both ASTs and non-ASTs. If type is the symbol element-name, the generated predicate checks if a given AST has that element name at top level. If type is the symbol kind, the generated predicate checks if a given AST is either double or single. If type is the symbol language, the generated predicate checks if a given AST belongs to the language.


 

7.   CHARACTER ENTITIES.
The function char-ref returns a character-reference. In XML, character references are used to denote characters which are not directly accessible from normal input devices.


char-ref


Form
(char-ref x)

Description
Return a character reference value for x. The parameter may be a positive, decimal integer or a symbolic name (string or symbol), such as amp, gt, or lt. Character references are represented internally as an appropriate list structure, similar to an AST list structure. In xml-render, these structures are converted to XML's character notation. With this we avoid a conflict with character transformation using the HTML transformation tables.


char-ref?


Form
(char-ref? x)

Description
Is x a character reference.


char-ref-value


Form
(char-ref-value char-ref-structure)

Description
Return the number or symbol of char-ref-structure.


 

8.   XML LANGUAGE 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?


 

9.   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 of LAML the language map is an association that maps element names (symbols) to function objects. In the longer run, it should be a 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


 

10.   XML NAVIGATION INFORMATION.
XML navigation information provides for "smart searching" of XML ASTs. The smartness is based on the following knowledge: (1) The possible direct and indirect sub-elements of a given element. (2) The possible attributes of an element and its direct and indirect sub-elements. This information is pre-computed in the XML-in-LAML mirror generation tool. The functions in this section provides access to this pre-computed information. Notice that the functions in this section Return static information, as derived from the DTD.


register-xml-in-laml-navigator


Form
(register-xml-in-laml-navigator language navigator-structure)

Description
Register navigator-structure and an XML-in-LAML navigator for language. This function is called "automatically" when the mirror functions are loaded.


xml-navigator-of


Form
(xml-navigator-of language)

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


possible-elements-rooted-by-element


Form
(possible-elements-rooted-by-element element-name language)

Description
Return a list of element names that can appear as direct or indirect constituents of an AST rooted by element-name. Reflexively, element-name will always be returned as part of the result.

Preconditions
language is a registered XML language in the enclosing LAML session, and element-name is an existing name of an element in language.

Returns
The list of possible elements names (a list of symbols). The list is sorted alphabetically.


possible-attributes-rooted-by-element


Form
(possible-attributes-rooted-by-element element-name language)

Description
Return a list of attribute names that can appear as direct or indirect constituents of an AST rooted by element-name. Reflexively, the attributes of element-names are always parts of the result.

Preconditions
language is a registered XML language in the enclosing LAML session, and element-name is an existing name of an element in language.

Returns
The list of possible attribute names (a list of symbols). The list is sorted alphabetically.


can-have-element-constituent?


Form
(can-have-element-constituent? ast el-name)

Description
Can ast have a direct or indirect constituent (sub-ast) with element name el-name. The result is always true if (ast-element-name ast) equals to el-name.

Parameters
astAn AST
el-nameis the name of an element in the language of ast (a string or a symbol).


 

11.   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 [language])

Description
Separates parameters according to the mirror rules of LAML. In other words, this is the function which implements the central LAML mirror function rules. Returns a cons cell of contents and attributes. Attributes are returned in property list format. Contents are returned as a list contents elements (strings, ASTs, booleans).

See also
similar functionxml-sort-superficially-tag-parameters    


xml-sort-superficially-tag-parameters


Form
(xml-sort-superficially-tag-parameters parameters tag-name [language])

Description
Like xml-sort-tag-parameters, but collect the content contribution in a relatively raw surface form. Handle attributes in the same way as xml-sort-tag-parameters. As a contrast to xml-sort-tag-parameters, white space related values are passed unchanged by this funnction. Use this kind of 'sorting' to obtain XML-in-LAML parameter passing in abstractions, which transfer data to XML-in-LAML mirror functions (which in turn use xml-sort-tag-parameters).

See also
similar functionxml-sort-tag-parameters    


laml-source-prepare


Form
(laml-source-prepare laml-lst)

Description
Prepare laml-list to be used as input to a mirror function. This function is useful when the result of transform-ast-list is passed as input to a XML mirror function. Elimiate forced-white-space markers, and introduce explict-space-suppres when necessary.

See also
in relation totransform-ast-list    


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 serves as action procedure, which will receive the AST for action purposes.


 

12.   CONTENTS VALIDATION.
The definitions in this section carry out the content validation.


validate-contents-by-dfa!


Form
(validate-contents-by-dfa! contents dfa tag-name)

Description
Apply the deterministic final state automaton dfa on contents. If contents is not accepted call xml-check-error for an appropriate reporting of the validation error.

Parameters
contentsA list of content items, such as strings, ASTs and white space markers.
dfaA deterministic final state automation which controls the acceptance.
tag-nameThe name of the element - used for error message purposes.


validate-as-pcdata!


Form
(validate-as-pcdata! contents tag-name)

Description
Validate that contents is pure PCDATA.

Parameters
contentsA list of content items, such as strings, ASTs and white space markers.
tag-nameThe name of the element - used for error message purposes.


validate-mixed-contents-by-simple-means!


Form
(validate-mixed-contents-by-simple-means! contents symbol-choice-list tag-name)

Description
Validate that contents corresponds to mixed contents. Mixed contents includes PCDATA a number of other choices in a 'zero-or-more' structure. It means that it is PCDATA or one of a number of possible ASTs.

Parameters
contentsA list of content items, such as strings, ASTs and white space markers.
tag-nameThe name of the element - used for error message purposes.
symbol-choice-listA list of symbols for the possible choices - a list of symbols.


 

13.   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. Attribute duplication is checked for, as well as presence of angle characters in attribute values.


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"


 

14.   XML WARNING PROCEDURES.


display-xml-warning


Form
(display-xml-warning . messages)

Description
A variant of display-warning which prefixes the warning text with a 'XML Warning' prefix.


xml-check-error


Form
(xml-check-error . messages)

Description
The procedure that reports XML validation errors. The default is display-xml-warning, which issues non-fatal warning messages. As an alternative you can use laml-error which provides for fatal error messaging. Both of these accept an arbitrary number of parameters, which are string converted prior to string appending them.

See also
default valuedisplay-xml-warning    
alternative valuelaml-error


 

15.   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

See also
standard-prologlaml.scm
standard-epiloglaml.scm


pretty-render-to-output-port


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

Description
Pretty print the XML clause (an AST) to output-port. output-port is assumed to be open. output-port will not be closed by this procedure. The constants preferred-maximum-width and indentation-delta affect the pretty printing.

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

See also
standard-prologlaml.scm
standard-epiloglaml.scm


xml-render


Form
(xml-render xml-clause [prolog epilog])

Description
Render the xml-clause (an LAML AST) and return the rendered string. In this context, rendering means linearization of the AST to its textual form.

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


pretty-xml-render


Form
(pretty-xml-render xml-clause [prolog epilog])

Description
Pretty print xml-clause (an LAML AST) and return the rendered string. In this context, rendering means linearization of the AST to its textual, pretty printed form. The constants preferred-maximum-width and indentation-delta affect the pretty printing.

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


 

16.   ELEMENT RELATED FUNCTIONS.
This section contains (mostly) higher-order functions that are related to the mirrors of the XML elements.


xml-modify-element


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

Description
Bind some attributes content elements of element (the first parameter) and return a new, 'modified element function'. With this, some attributes and some content elements are pre-bound to certain values in the modified element. The parameter attributes-and-contents is of the same form as the parameters to a LAML surface mirror functions. In fact, attributes-and-contents is appended to the actual parameters, which are passed to the modified element function.

Returns
an attribute-modified mirror function

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

See also
similar functionxml-modify-element-prepend    


xml-modify-element-prepend


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

Description
A function similar to xml-modify-element, but instead of appending attributes-and-contents to the actual parameters of the modified function, it prepends attributes-and-contents.

See also
similar functionxml-modify-element    


 

17.   XML IN LAML PARAMETRIZATION AND ABSTRACTION FUNCTIONS.
The functions in this category are higher-order functions which generate functions that obey XML-in-LAML parameter passing rules. In other words, the function that are generated use the same parameter conventions as the mirror functions of the HTML and XML elements.


xml-in-laml-parametrization


Form
(xml-in-laml-parametrization f parameter-mediator [parameter-validator! f-name])

Description
Generate a function with XML-in-LAML parameter passing rules which sends its input to an ordinary function, f, with positional parameters via a parameter mediator. The first parameter, f, is typically a web-related function with positional parameter correspondence (such as an existing, old-style 'conveninece function'). The parameter parameter-mediator is a function that generates a parameter list for f from content-list and the attributes property list, which is produced by the function xml-sort-tag-parameters. Thus, the parameter-mediator function translates the 'new parameter profile' to the 'old one', which is associated with f. The optional procedure parameter-validator! validates the contents-list and the attribute-list by reporting problems via xml-check-error. The optional f-name parameter is a string corresponding to the name of f (used for error message purposes only).

Parameters
fAn 'old style' fuction web function with positional parameters. Is applied on the result of parameter-mediator.
parameter-mediatora function of two parameters (contents-list and attribute property list) which transforms the new style parameters to the old style. f is applied on the output of parameter-mediator!
parameter-validator!a procedure of two parameters (contents-list and attribute property list) which validates the input of the generated function.
f-nameThe name of the generated function. Solely used for error message purposes.

See also
applied functionxml-sort-tag-parameters    
similar functionxml-in-laml-abstraction    
useful par. validatorrequired-implied-attributes    

Note
See the LAML tutorial - authoring with higher-order functions - for additional discussion and examples.


xml-in-laml-abstraction


Form
(xml-in-laml-abstraction f [parameter-validator! f-name])

Description
Generate a function with XML-in-LAML parameter passing rules which sends its input to an XML or HTML mirror function, or to another XML-in-LAML abstraction. The first parameter, f, is supposed to call one or more XML or HTML mirror function, or another XML-in-LAML abstraction. The function f takes two parameters: A content list and an attribute property list. The optional procedure parameter-validator! validates the contents-list and the attribute-list by reporting problems via xml-check-error. The optional f-name parameter is a string corresponding to the name of f (used for error message purposes only).

Parameters
fA transformer function of two parameters - contents and the attribute property list
parameter-validator!A checking procedure of two parameters - contents and the attribute property list. Must report errors explicitly by xml-check-error.
f-nameThe name of abstraction - used for error message purposes

See also
applied functionxml-sort-superficially-tag-parameters    
similar functionxml-in-laml-parametrization    
useful par. validatorrequired-implied-attributes    

Note
See the LAML tutorial - authoring with higher-order functions - for additional discussion and examples.


required-implied-attributes


Form
(required-implied-attributes required-attribute-names implied-attribute-names [tag-name])

Description
A higher-order function which returns an attribute checker. Report problems via xml-check-error. Check that all required-attribute-names are present and that the actual attributes are covered by required-attribute-names and implied-attribute-names together. The generated functions can be used as parameter valdiator procedures in xml-in-laml-abstraction and xml-in-laml-parametrization

Parameters
required-attribute-namesA list of attribute names (symbols) which are required.
implied-attribute-namesA list of additional attribute names (symbols) which are allowed, or the list (*) - a singleton list with the symbol * - in the meaning of any attribute.

See also
relevant context of usexml-in-laml-abstraction    xml-in-laml-parametrization    
error functionxml-check-error    


 

18.   AST TRAVERSAL AND AST TRANSFORMATION FUNCTIONS.
The AST traversal functions extract information from AST by means of traversal and searching. The "find" functions use guided search, aided by the XML navigation information which is derived from the XML DTD. The "traverse-and-collect" functions are slightly more general (with a node-interesting? predicate), but they do not (and cannot) make use of the XML navigation information. Thus, these function do an exhaustive search.


find-asts


Form
(find-asts ast el-name [ast-transformer])

Description
Find and return a list of transformed sub ASTs of ast (first parameter) each with a root element of name el-name. The search is guided by the XML navigation information, hereby pruning the tree traversal. Apart from the pruning, the AST is traversed in pre-order. The transformation of the resulting sub-ASTS is done by the optional ast-transformer. If a sub-ast is returned as a part of the result then the sub-ast is not searched internally for recursive matches.

Parameters
astAn AST.
el-nameA name of an element in the language of ast (a string or symbol).
ast-transformerAn optional AST transformation function, which defaults to the identity function id-1.

Returns
A list of ASTs, each with element name el-name.

See also
similar functiontraverse-and-collect-all-from-ast    traverse-and-collect-first-from-ast    find-first-ast    
related functionstraverse-and-collect-first-from-ast    find-first-ast    


find-first-ast


Form
(find-first-ast ast el-name [ast-transformer])

Description
Find and return a sub-AST of ast (first parameter) with a root element of name el-name. The search is guided by the XML navigation information, hereby pruning the tree traversal. Apart from the pruning, the AST is traversed in pre-order. When an appropriate sub-AST is found, the search is terminated. The transformation of the resulting sub-ASTS is done by the optional ast-transformer.

Parameters
astAn AST.
el-nameA name of an element in the language of ast (a string or symbol).
ast-transformerAn optional AST transformation function, which defaults to the identity function id-1.

Returns
A list of ASTs, each with element name el-name.

See also
similar functiontraverse-and-collect-first-from-ast    
related functionstraverse-and-collect-all-from-ast    find-asts    


unique-ast-attribute


Form
(unique-ast-attribute ast name [default-attribute-value])

Description
Return the value of the attribute name in ast, or in one of the subtrees of ast. If, from a static consideration, the attribute is not unique in ast, a fatal error occurs. The default attribute value is only applied if the attribute could occur, but if it does NOT in the actual AST. This function is useful for extraction of deep attributes given the fact that they only can occur once in the document, according to both the actual document structure and the statically extracted XML navigation information. The navigation towards a deep, unique attribute is efficient.

Preconditions
Statically, only one occurence of attr-name can appear in ast.

Parameters
astThe AST in which to look for the attribute
nameThe name of the attribute (symbol or string)
default-attribute-valueThe default value, used if no attribute of name is found, but only if it is allowed to occur. A string.

See also
related functionast-attribute    


traverse-and-collect-all-from-ast


Form
(traverse-and-collect-all-from-ast ast-tree node-interesting? ast-transformer)

Description
Traverse all nodes of the AST ast-tree, and return transformed subtrees that satisfy the node-interesting? predicate. No traversal takes place inside subtrees that sastify the node-interesting? predicate. The transformation of the interesting subtree is done with ast-transformer (the third parameter). Non-AST constituents of the AST (CDATA and white space markers) are not visited during the traversal. The traversal is done in pre-order.

Parameters
ast-treeThe AST to be traversed.
node-interesting?The AST predicate that identifies the ASTs of interest.
ast-transformerThe function which is applied on the ASTs identified by node-interesting?

Returns
The mapping of the function ast-transformer on the list of interesting subtrees.

See also
useful as parameterast-of-type?    
sibling functiontraverse-and-collect-first-from-ast    
similar functionfind-asts    

Note
The higher-order function ast-of-type? generates useful node-interesting? functions.


traverse-and-collect-first-from-ast


Form
(traverse-and-collect-first-from-ast ast-tree node-interesting? ast-transformer)

Description
Traverse the AST ast-tree, and return a transformation of the first subtree which satisfies the predicate node-interesting. The transformation of the interesting subtree is done with ast-transformer (the third parameter). Non-AST constituents of the AST (CDATA and white space markers) are not visited during the traversal. The traversal is done in pre-order. Return #f in case no match is found. In fact, return the transformed AST, applying ast-transformer on the returned tree.

Parameters
ast-treeThe AST to be traversed.
node-interesting?The AST predicate that identifies the ASTs of interest.
ast-transformerThe function which is applied on the ASTs identified by node-interesting?

Returns
(ast-transformer TR), where TR is the first encounted tree matched by node-interesting? or #f if no tree is matched.

See also
useful as parameterast-of-type?    
more restricted accessorast-subtree    
sibling functiontraverse-and-collect-all-from-ast    
similar functionfind-first-ast    

Note
The higher-order function ast-of-type? generates useful node-interesting? functions.


transform-ast-list


Form
(transform-ast-list input-list . transform-specs)

Description
Apply the transformation-specs on input-list and return a list of transformed input elements. This function can, for instance, be applied on the subtree list of an AST. A single transformation spec is a list of two element: A predicate and a transformation function. A transformation function is applied if the corresponding predicate holds on the input element. If no predicate holds on an input element, the input element is returned without being transformed. No recursive transformations is done by this function.

Parameters
input-listEach element in input-list can be an AST, a string, a character reference, or a white space related marker
transform-specA list of transformation specifications, each of which is a list of length 2: (input-predicate transformation-function)

Returns
A list of the same length of input-list. Some elements in the returned list are transformed as requested by transform-spec.

See also
usefully applied on results ofast-subtrees    traverse-and-collect-all-from-ast    
similar-functionstraverse-and-collect-all-from-ast    traverse-and-collect-first-from-ast    


 

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


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: August 27, 2003, 22:48:28
This documentation has been extracted automatically from the Scheme source file by means of the Schemedoc tool