Generated: Monday, November 14, 2011, 09:16:12 Copyright © 2011 , Kurt Nørmark The local LAML software home page

Reference Manual of the XML-in-LAML Mirror Generation Tool

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

LAML Source file: tools/xml-in-laml/xml-in-laml.scm

This is the LAML tool that generates the language specific part of an XML mirror in Scheme. From version 20 of LAML, this tool is able to generate a fully validating mirror i Scheme of an XML language from a parsed XML DTD.

For validation purposes, this tool generates deterministic final state automata from the parsed content models, as delivered by the LAML XML DTD parser. These automata are embedded in the validation predicates which accompany the mirror functions in Scheme of the XML elements.

The generated mirrors rely heavily on the common part, which is shared for all XML-in-LAML languages. The common part is found in lib/xml-in-laml/xml-in-laml.scm, and a XML-in-LAML common library manual is available.

Let us denote the language by the symbol L. As input this tool takes a parsed DTD, L.dtd, in the Lisp representation made by the LAML DTD parser. As output the LAML mirror generation tool makes a file L-mirror.scm in the mirror-target-dir.

The tool is typically driven by a LAML script (such as the script for generation of XHTML 1.0 transitional).

An easy way to use the mirror generation tool is via the procedure generate-xml-mirror in the fundamental LAML setup library, called laml.scm.

The main procedure in LAML mirror generation tool is generate-mirror (see below). As such, the tool can be identified with the generate-mirror procedure.

Please consult "XML mirrors in Scheme: XML in LAML" (section 3) for a tutorial introduction to the use of the tool.

From LAML version 26, attributes list corresponding to the same element name, are merged to a single attribute list. (This was prompted by the processing of XHTML 1.1).

Table of Contents:
1. Tool parameters - configuration constants. 2. Default language properties. 3. The main tool procedure.

Alphabetic index:
action-elements action-elements The list of action elements (a list of symbols).
auto-lib-loading auto-lib-loading Is lib/xml-in-laml/xml-in-laml.scm loaded by the language specific mirror library?
default-document-type-declaration default-document-type-declaration The default value of document-type-declaration.
default-pass-default-dtd-attributes? default-pass-default-dtd-attributes? Controls whether to explicitly pass the default dtd attributes in every instance of it.
default-xml-accept-extended-contents? default-xml-accept-extended-contents? Controls if numbers and characters are accepted as 'extended' element contents items.
default-xml-accept-only-string-valued-attributes? default-xml-accept-only-string-valued-attributes? Controls if only string valued attributes are accepted.
default-xml-char-transformation-table default-xml-char-transformation-table The default value of xml-char-transformation-table.
default-xml-duplicated-attribute-handling default-xml-duplicated-attribute-handling Controls the handling of duplicated attributes in XML attribute lists.
default-xml-non-transliteration-elements default-xml-non-transliteration-elements The list of elements names (strings) for which the transliteration does not apply.
default-xml-preformatted-text-elements default-xml-preformatted-text-elements The list of elements names (strings) for which all white space content characters must be rendered.
default-xml-represent-white-space default-xml-represent-white-space Controls the presence of white space markers in the ast.
default-xml-transliterate-character-data? default-xml-transliterate-character-data? A boolean value which controls the default value of CDATA transliteration via the HTML/XML charater transformation table.
define-named-mirror-functions? define-named-mirror-functions? A boolean variable that controls the generation of name mirror functions.
generate-mirror (generate-mirror parsed-dtd-path mirror-destination-path language-name [file-inclusion-path]) The main tool procedure which makes the mirror of XML in LAML.
make-xml-mirror-function (make-xml-mirror-function element attribute language-name) Construct and return a mirror function.
make-xml-validation-procedure (make-xml-validation-procedure element attribute language-name) Make and return a validation procedure.
mirror-name mirror-name The name of the generated mirror - a string without initial path and without extension.
mirror-name-prefix mirror-name-prefix A string prepended to all names of function names.
mirror-target-dir mirror-target-dir The full path of the directory in which to put the mirror.
parsed-dtd-path parsed-dtd-path The full path to the parsed DTD file (a lsp file).
pass-action-procedure? pass-action-procedure? A boolean variable that controls how to pass action procedures to generate-xml-mirror-function.
reserved-scheme-names reserved-scheme-names Scheme names - a list of symbols.


1 Tool parameters - configuration constants.
Please notice that most of these constants must be passed as parameters to the procedure generate-mirror.

mirror-name
Form mirror-name
Description The name of the generated mirror - a string without initial path and without extension. Must be defined in the LAML script which parameterizes this tool.

parsed-dtd-path
Form parsed-dtd-path
Description The full path to the parsed DTD file (a lsp file). Must be defined in the LAML script which parameterizes this tool

mirror-target-dir
Form mirror-target-dir
Description The full path of the directory in which to put the mirror. Must be defined in the LAML script which parameterizes this tool

auto-lib-loading
Form auto-lib-loading
Description Is lib/xml-in-laml/xml-in-laml.scm loaded by the language specific mirror library?

action-elements
Form action-elements
Description The list of action elements (a list of symbols). The named mirror functions of action elements do not return an AST. The mirror function accessed throught the language map do, however, always return ASTs. Rather, they apply a procedure on the ast. If the element name is N, the action procedure name becomes N!

pass-action-procedure?
Form pass-action-procedure?
Description A boolean variable that controls how to pass action procedures to generate-xml-mirror-function. If #f, only pass a boolean value. If #t, pass the action procedure itself. #f is recommeded. The reason is that it allows us to load the mirror library and to define the action procedures in arbitrary order. If #t, the action procedures must be defined before the mirror library is loaded. If the value of this variable is #f, we pass #t to generate-xml-mirror-function if there is an action procedure of the element. It is then up to generate-xml-mirror-function to get the action procedure from the action procedure map (as made by make-xml-action-procedure-structure).

define-named-mirror-functions?
Form define-named-mirror-functions?
Description A boolean variable that controls the generation of name mirror functions. If true (#t) named mirror functions will be defined. If false (#f), the mirror functions are only available via the language map.

mirror-name-prefix
Form mirror-name-prefix
Description A string prepended to all names of function names. Defaults to the empty string (no mirror name prefix used). If you wish to have a '-' og ':' in between the prefix and the proper name, you should add it as the last character of the string bound to this variable. You can use the mirror name prefix to ensure that two or more mirrors of XML functions can coexist without name clashes. Notice that the use of language maps is an alternative way to handle name clashes.

reserved-scheme-names
Form reserved-scheme-names
Description Scheme names - a list of symbols. Think of these as reserved names in Scheme, which we do not want to redefine as mirror functions.


2 Default language properties.
The default language properties are string-valued variables, which are intended to be set for each new mirror. The value of these variable are inserted into the generated mirror. This explains why all values must be strings. This may seem a little strange, but take a look in the beginning of one of the generated mirror files to see the effect.

Notice that lib/xml-in-laml/xml-in-laml.scm contains a number of configuration options too, together with a number of functions that access/mutate the properties given below. You should only set those that provide inappropriate defaults. It means that you typically only have to set of few of the variables in this section when you make a new mirror.


default-xml-transliterate-character-data?
Form default-xml-transliterate-character-data?
Description A boolean value which controls the default value of CDATA transliteration via the HTML/XML charater transformation table. The default value is true. The boolean value must be embedded in a string. This value can be changed after the mirror is generated.

default-xml-non-transliteration-elements
Form default-xml-non-transliteration-elements
Description The list of elements names (strings) for which the transliteration does not apply. The list value must be embedded in a string. The value of this variable is locked at mirror generation time.

default-xml-preformatted-text-elements
Form default-xml-preformatted-text-elements
Description The list of elements names (strings) for which all white space content characters must be rendered. Typically the HTML pre element. The list value must be embedded in a string. The value of this variable is locked at mirror generation time.

default-xml-char-transformation-table
Form default-xml-char-transformation-table
Description The default value of xml-char-transformation-table. The default value is is "html-char-transformation-table". The value must be a string.

default-pass-default-dtd-attributes?
Form default-pass-default-dtd-attributes?
Description Controls whether to explicitly pass the default dtd attributes in every instance of it. Normally #f, which is the default value. If #t, it will most likely collide with the attribute validation (only one instance of each attribute name is allowed). The boolean value must be embedded a string. The value of this variable is locked at mirror generation time.

default-xml-accept-only-string-valued-attributes?
Form default-xml-accept-only-string-valued-attributes?
Description Controls if only string valued attributes are accepted. The default value is true. The boolean value must be embedded in a string.

default-xml-accept-extended-contents?
Form default-xml-accept-extended-contents?
Description Controls if numbers and characters are accepted as 'extended' element contents items. Such items will be transformed to strings before further processing. The default value is false. The boolean value must be embedded in a string.

default-document-type-declaration
Form default-document-type-declaration
Description The default value of document-type-declaration. The value must be a string. The default default is the empty string with the meaning 'no attribute type declaration'. Thus, if you do not give the default-document-type-declaration there will be no document type declartion in your documents. The value of this variable is locked at mirror generation time.

default-xml-represent-white-space
Form default-xml-represent-white-space
Description Controls the presence of white space markers in the ast. The default value is true. The boolean value must be represented as a string.

default-xml-duplicated-attribute-handling
Form default-xml-duplicated-attribute-handling
Description Controls the handling of duplicated attributes in XML attribute lists. Possible values are keep-all, keep-first, and keep-last. keep-all: the attribute list is not affected at all; All attributes are passed. keep-first: only the first attribute name/value pair is passed for further processing. keep-last: only the last attribute name/value pair is passed for further processing. The default value is the symbol keep-all. The symbol value must be represented as a string.


3 The main tool procedure.
The main tool procedure is generate-mirror. After setting the parameters call this procedure which will make the XML mirror.

generate-mirror
Form (generate-mirror parsed-dtd-path mirror-destination-path language-name [file-inclusion-path])
Description The main tool procedure which makes the mirror of XML in LAML. The procedure writes a text file in mirror-destination-path.
Parameters parsed-dtd-path the full path to the parsed dtd (a lsp file).
mirror-destination-path full path to the file on which to write the mirror.
language-name the name of language which we mirror in LAML (a symbol).
file-inclusion-path An absolute path to a text file, which will be included at the rear end of the generated mirror library. The setup of link checking is typically provided via such file inclusion.
See also About link checking in LAML Note

make-xml-mirror-function
Form (make-xml-mirror-function element attribute language-name)
Description Construct and return a mirror function.
Parameters element The parsed element structure, as produced by the LAML DTD parser.
attribute The parsed attribute structure, as produced by the LAML DTD parser.
language-name The name of the XML language, to which this mirror function belongs.

make-xml-validation-procedure
Form (make-xml-validation-procedure element attribute language-name)
Description Make and return a validation procedure.
Parameters element The parsed element structure, as produced by the LAML DTD parser.
attribute The parsed attribute structure, as produced by the LAML DTD parser.
language-name The name of the XML language, to which this mirror function belongs.

Generated: Monday, November 14, 2011, 09:16:12
Generated by LAML SchemeDoc using LAML Version 38.0 (November 14, 2011, full)