Generated: Monday, August 18, 2008, 20:11:41 Copyright © 2008 , Kurt NÝrmark The local LAML software home page

LAML Compatibility Functions

Kurt NÝrmark Department of Computer Science, Aalborg University

The LAML software relies on a number of functions, which are non-standard both in R4RS and R5RS. You can think of these as functions that extend R4RS/R5RS a little bit to fill the gap between the LAML code base and the Scheme standard.

We support a set of compatibility files for different platforms, operating systems, and Scheme systems in the directory lib/compatibility/ of the LAML distribution. The relevant compatibility file is loaded automatically by laml.scm, based on the configuration file that you elaborated as part of LAML installation process.

It is important to understand that some of the compatibility functions, described in this manual, are alread implemented by some Scheme systems. If that is the case, it is not necessary to implement them in the LAML compatility file.

Help to implementors: See also advice on how to port LAML to another Scheme System.

Table of Contents:
1. Mandatory compatibility functions 2. LAML context functions 3. Optional compatibility functions

Alphabetic index:
bound? (bound? name) Return if the name is bound in the current interaction environment.
copy-file (copy-file source destination) Copy the source file to destination file.
current-time (current-time) Returns the number of seconds elapsed since January 1, 1970.
delete-file (delete-file file-path) Deletes a file.
directory-exists? (directory-exists? dir-path) Returns whether the directory dir-path exists.
directory-list (directory-list dir-path) Return a list of files and directories in dir-path.
error (error error-message-string) Stop program executation and print information about the error, as described by the string error-message-string.
eval-cur-env (eval-cur-env e) Evaluates the expression e in the current interaction environment.
fake-start-up-parameters (fake-startup-parameters source-file startup-dir . program-parameters) Fake the contextual startup parameters to a specific source file name, a specific startup directory and specific (optional) program parameters.
file-exists? (file-exists? file-path) Returns whether a file named file-path exists.
getenv (getenv name) Read and return the value of an environment variable in the operating system.
laml-canonical-command-line (laml-canonical-command-line) Return the contextual command line information passed to LAML upon activation.
mail (mail receiver title contents) Send email to receiver with title and contents.
make-directory-in-directory (make-directory-in-directory in-directory-path new-dir) Make a new directory new-dir in an existing directory path..
sort-list (sort-list list leq-fn) Returns a sorted copy of list.
url-target-exists? (url-target-exists? url-string) Return if the absolute URL, as represented by url-string, exists.


1 Mandatory compatibility functions
Here follows documentation of the important compatibility functions that must be implemented by in order to use LAML.

file-exists?
Form (file-exists? file-path)
Description Returns whether a file named file-path exists.
Parameters file-path the full and absolute path to the file (a text string).
Returns A boolean value

directory-exists?
Form (directory-exists? dir-path)
Description Returns whether the directory dir-path exists.
Parameters dir-path the full and absolute directory path to the directory. As a convention in LAML, a directory path is always terminated by a forward slash character: '/'. dir-path is a text string.
Returns A boolean value

delete-file
Form (delete-file file-path)
Description Deletes a file.
Parameters file-path the full and absolute path to the file (a text string).

copy-file
Form (copy-file source destination)
Description Copy the source file to destination file.
Precondition The source file exists, and the target file does not exist.
Parameters source The full file path to the source file
target The full file path to the destination file
Postcondition Both the source file and target file exists, and they are identical.

make-directory-in-directory
Form (make-directory-in-directory in-directory-path new-dir)
Description Make a new directory new-dir in an existing directory path..
Precondition There is no directory new-dir in in-directory-path
Parameters in-directory-path a full and absolute directory path (ending in a forward slash). A string
new-dir a simple directory name (without any slash character). A string.
Postcondition Directory new-dir in in-directory-path exists.

directory-list
Form (directory-list dir-path)
Description Return a list of files and directories in dir-path.
Parameters dir-path a full and absolute directory path, which ends in a forward slash.
Returns The list of file and directory names (without initial path). The resulting list does not include the directories named '.' and '..'.

current-time
Form (current-time)
Description Returns the number of seconds elapsed since January 1, 1970. A LAML compatibility function.
Returns An integer

sort-list
Form (sort-list list leq-fn)
Description Returns a sorted copy of list. The sorting is based on the function leq-fn, which returns if two elements in the list are considered less than or equal. See note below.
Parameters list A list
leq-fn A function of two parameters (list elements) (lambda (e1 e1) ...) which return if e1 is less than or equal to e2.
Returns The sorted list
Note Note to implementors of sort-list: If you cannot easily provide an implementation of sort-list, we provide the file lib/compatibility/sorting/sort.scm with Aubrey Jaffer's sorting functions. You can include this file in the compatibility file and add (define sort-list sort:sort).

bound?
Form (bound? name)
Description Return if the name is bound in the current interaction environment.
Parameters name A symbol

eval-cur-env
Form (eval-cur-env e)
Description Evaluates the expression e in the current interaction environment. Rationale: Bridges the differences between R4RS systems (in which eval is not standardized) and R5RS systems, in which eval takes two parameters.
Parameters e A Scheme expression, such as a list structure.
Returns The value of e

error
Form (error error-message-string)
Description Stop program executation and print information about the error, as described by the string error-message-string. Most Scheme systems supports this function already.
Parameters error-message-string The error message. A string


2 LAML context functions
The functions in this section define and return the activation context of the LAML processor. You must define these two functions in the compatibility files.

laml-canonical-command-line
Form (laml-canonical-command-line)
Description Return the contextual command line information passed to LAML upon activation. This function must be redefined in Scheme-system/OS/platform dependent compatibility file.
Returns Returns a list of length four or #f if no command line activation exists. The first element must be the symbol laml (a tag). Element number two must be the laml source file name (without extension and initial path). Element number three must be a slash terminated, full directory path (with forward slashes), in which the source file resides. Element number four must be a list of program parameters (strings).
See also Implicit accessor source-filename-without-extension
Implicit accessor startup-directory
Implicit accessor laml-program-parameters

fake-start-up-parameters
Form (fake-startup-parameters source-file startup-dir . program-parameters)
Description Fake the contextual startup parameters to a specific source file name, a specific startup directory and specific (optional) program parameters. The parameters source-file and startup-dir must be strings, or the boolean value #f (in case the informations are unknown). This function is used for programmatic startup of LAML. This function must be redefined in the scheme-system dependent compatibility file
Parameters source-file a file name without initial path and without extension.
startup-dir an absolute path to a directory ending in a slash /.
program-parameteres zero, one or more strings
Note Notice the correct calling form of this function is (fake-startup-parameters "source" "dir" "p1" "p2" "p3"). The following calling form is wrong: (fake-startup-parameters "source" "dir" ("p1" "p2" "p3")).


3 Optional compatibility functions
Here follows a few compatibility functions which are not used in central parts of LAML. You cannot necessarily expect these functions to exist in your LAML system.

getenv
Form (getenv name)
Description Read and return the value of an environment variable in the operating system. Mainly Used for LAML CGI programming purposes.
Parameters name A string
Returns The value of the environment variable

mail
Form (mail receiver title contents)
Description Send email to receiver with title and contents.
Parameters receiver email address. A string
title Email title. A string
contents Email body. A string

url-target-exists?
Form (url-target-exists? url-string)
Description Return if the absolute URL, as represented by url-string, exists. If you use the value all or absolute of the variable xml-link-checking in lib/xml-in-laml/xml-in-laml.scm you must implement this function. This provides for checking the existence of the absolute URLs in your documents. In other situations, you do not need to implement it.
Parameters url-strinig A URL. A string
Returns A boolean result

Generated: Monday, August 18, 2008, 20:11:42
Generated by LAML SchemeDoc using LAML Version 33.0 (February 4, 2008, full)