Documentation

Concepts

XML can be considered a fancy way of formulating sexps. This library is for interpreting xml-data as lisp code. The xml-data is interpreted as follows:

tagnames - function or macro names
content (of a tag) - argument
attributes - keywords
namespaces - packages

By default all attributes and contents of tags are read as strings - However you may specify a reader function. Evaluation takes place by calling eval - you may want to change this too.

API

General

Code is situated in Package :nrw.xmcl and :nrw.xml.tags. There are several function and macros which are specific to me (Norman Werner (nrw)). For users who are not me the file fake-nrw.lisp is supplied. Some other Packages may be declared inside of this file. If this is a problem for you - send me a message.

Functions

process-xml-data

(process-xml-data #p"/home/norman/bsp.xhtml")

(process-xml-data (data &key  (table *namespace-table*) (default *default-package*)
                                    (upcase-tagnames t) (upcase-attributes t)
                                    (attribute-reader 'identity) 
                                    (body-reader 'identity)
                                    (evaluator 'eval)))

opens data parses xml-content and process data according to evaluator.

data	The stream, pathname or string containg the xml.
table	An alist specifing a xml-namespace to cl-package mapping. The function or macro belongin to a tagname is looked for in a packaged specified by this mapping. See also namespace-table.
default	A package used for looking up functions, if no other cl-package was found by consulting table.
upase-tagnames	As xml is case-sensitive and cl is not. You may want to control whether tagnames are upcased before converting them to function or macro names.
attribute-reader	A package used for looking up functions, if no other cl-package was found by consulting table.
body-reader	A function used to read attributes. You may want to change this eg. to #'read or a function which split multiple arguemnts into a list.
evaluator	After all tagnames, attributes and body-elemts are converted the resulting lisp is interpreted as a lisp-programm. This argument specifies how this is to be done.

parse

(parse s)

Parse parses a stream containing xml and returns an xmls compatible list or NIL (if the stream does not contain valid xml).

By default parse uses xmls. You may override this by redefining parse.

s	An input-stream which yields the xml data to parse.

read-to-xmls-sexp

(read-to-xmls-sexp input-stream)

Reads a string or stream (or a pathname designating a file) into an xmls compatible sexp. It mainly is a wrapper for parse.

s	Should be a stream, a pathname or a literal string containg valid xml.

Conditions

The following conditions may be thrown:

xml-error : Is signaled when youre data does not seem to be valid xml
missing-package: Is signaled when a package, which was specified, does not exist.

Variables

default-package

If no package is found - this package is used for interning tagnames to cl-symbols.

namespace-table

If no other mapping from xml-namespaces to cl-packages was specified this alist is used.

Installation and Caveats

Installation

Read the supplied file README for installation instructions. In short: You may use asdf or asdf-install (asdf-install:install :nrw-xmcl)

Prerequsites

You will need the library xmls.

Portability

I am not aware of any implementation dependencies. However - if you find some: Please let me know.

The code was developed on sbcl on linux(debian) so it is to work at least on this platform.

Caveats

Case

XML is case-sensitive as is Common Lisp. However often the lisp-reader upcases symbol-names. This leads to case-insensitive behaviour. By using the upcase-tagnames Argument for process-xml-data you may choose to upcase tagnames as well.

Undefined functions

If you call (by processing your xml-data) a function which doesn't exist you will experience errors.

You may want to have a look at the source code. There is an example on how to setup default functions for certain tagnames (in this example all tagnames of xhtml).

Types of function Arguments

By default all arguments and keyword arguments are supplied as specified in the XML-data - as objects of type string.

You may want to change this to allow eg. For inclusion of numbers or lists of strings. To do so, change the attribute-reader and body-reader arguments of process-xml-data

Disclaimer

While writing documentation I was drunk. So this documentation is bound to contain errors and is at best higly inaccurate. Imagine a huge DISCLAIMER. Double it. Add two.

nrw-xmcl

Contents