20060303-partial

1 files changed, 266 insertions, 0 deletions

diff --git a/man/2/xml b/man/2/xml
new file mode 100644
index 00000000..8387971a
--- /dev/null
+++ b/man/2/xml
@@ -0,0 +1,266 @@
+.TH XML 2
+.SH NAME
+xml \- XML navigation
+.SH SYNOPSIS
+.EX
+include "xml.m";
+
+xml := load Xml Xml->PATH;
+Parser, Item, Location, Attributes, Mark: import xml;
+
+init:   fn(): string;
+open: fn(f: string, warning: chan of (Locator, string),
+                preelem: string): (ref Parser, string);
+
+Parser: adt {
+    fileoffset: int;
+
+    next:       fn(p: self ref Parser): ref Item;
+    down:       fn(p: self ref Parser);
+    up:         fn(p: self ref Parser);
+    mark:       fn(p: self ref Parser): ref Mark;
+    atmark:     fn(p: self ref Parser, m: ref Mark): int;
+    goto:       fn(p: self ref Parser, m: ref Mark);
+    str2mark:   fn(p: self ref Parser, s: string): ref Mark;
+};
+
+Item: adt {
+    fileoffset: int;
+    pick {
+    Tag =>
+        name:   string;
+        attrs:  Attributes;
+    Text =>
+        ch:     string;
+        ws1:	int;
+		ws2:    int;
+    Process =>
+        target: string;
+        data:   string;
+    Doctype =>
+        name:   string;
+        public: int;
+        params: list of string;
+    Stylesheet =>
+        attrs:  Attributes;
+    Error =>
+        loc:    Locator;
+        msg:    string;
+    }
+};
+
+Locator: adt {
+    line:       int;
+    systemid:   string;
+    publicid:   string;
+};
+
+Attribute: adt {
+    name:       string;
+    value:      string;
+};
+
+Attributes: adt {
+    all:        fn(a: self Attributes): list of Attribute;
+    get:        fn(a: self Attributes, name: string): string;
+};
+
+Mark: adt {
+    offset:     int;
+    str:        fn(m: self ref Mark): string;   
+};
+.EE
+.SH DESCRIPTION
+.B Xml
+provides an interface for navigating XML files (`documents'). Once loaded, the module
+must first be initialised by calling
+.BR init .
+A new parser instance is created by calling
+.BR open(\fIf\fP,\ \fIwarning\fP,\ \fIpreelem\fP) ,
+which opens the file
+.I f
+for parsing as an XML document.
+It returns a tuple, say
+.RI ( p ,\  err ).
+If there is an error opening the document,
+.I p
+is nil, and
+.I err
+contains a description of the error; otherwise
+.I p
+can be used to examine the contents of the document.
+If
+.I warning
+is not nil, non-fatal errors encountered when parsing
+will be sent on this channel - a separate process will
+be needed to received them. Each error is represented
+by a tuple, say
+.RI ( loc ,\  msg ),
+containing the location
+.IR loc ,
+and the description,
+.IR msg ,
+of the error encountered. One XML tag,
+.IR preelem ,
+may be marked for special treatment by the XML parser:
+within this tag all white space will be passed through as-is.
+.PP
+Once an XML document has been opened, the following
+.B Parser
+methods may be used to examine the items contained within:
+.TP 10
+.IB p .next()
+An XML document is represented by a tree-structure.
+.B Next
+returns the next item in the document at the current level of the tree
+within the current parent element. If there are no more such
+items, it returns
+.BR nil .
+.TP
+.IB p .down()
+.B Down
+descends into the element that has just been returned by
+.BR next ,
+which should be a
+.B Tag
+item. Subsequent items returned by
+.B next
+will be those within that tag.
+.TP
+.IB p .up()
+.B Up
+moves up one level in the XML tree.
+.TP
+.IB p .mark()
+.B Mark
+returns a mark that can be used to return later to the current
+position in the document. The underlying file must
+be seekable for this to work.
+.TP
+.IB p .goto(\fIm\fP)
+Goes back to a previously marked position,
+.IR m ,
+in the document.
+.TP
+.IB p .atmark(\fIm\fP)
+.B Atmark
+returns non-zero if the current
+position in the document is the same as that marked by
+.IR m .
+The current tree level is ignored in the comparison.
+.TP
+.IB p .str2mark(\fIs\fP)
+.B Str2mark
+turns a string as created by
+.B Mark.str
+back into a mark as returned by
+.BR Parser.mark .
+.SS Items
+Various species of items live in XML documents; they are encapsulated
+in the
+.B Item
+adt. This contains one member in common to all its subtypes:
+.BR fileoffset ,
+the position in the XML document of the start of the item.
+The various kinds of item are as follows:
+.TP
+.B Tag
+A generic XML tag.
+.B Name
+names the tag, and
+.B attrs
+holds its attributes, if any.
+.TP
+.B Text
+.B Text
+represents inline text in the XML document.
+With the exception of text inside the tag named by
+.I preelem
+in
+.BR open ,
+any runs of white space are compressed to a single space,
+and white space at the start or end of the text is elided.
+.B Ch
+contains the resulting text;
+.B ws1
+and
+.B ws2
+are non-zero if there was originally white space at the start
+or end of the text respectively.
+.TP
+.B Process
+.B Process
+represents an XML document processing directive.
+.B Target
+is the processing instruction's target, and
+.B data
+holds the rest of the text inside the directive.
+XML stylesheet directives are recognised directly and have
+their own item type.
+.TP
+.B Doctype
+.B Doctype
+should only occur at the start of an xml document,
+and represents the type of the XML document.
+.TP
+.B Stylesheet
+.B Stylesheet
+represents an XML stylesheet processing request. The
+data of the processing request is parsed as per the RFC
+into attribute-value pairs.
+.TP
+.B Error
+If an unrecoverable error occurs processing the document,
+an
+.B Error
+item is returned holding the location
+.RB ( loc ),
+and description
+.RB ( msg )
+of the error.
+This will be the last item returned by the parser.
+.PP
+The attribute-value pairs in
+.B Tag
+and
+.B Stylesheet
+items are held in an
+.B Atttributes
+adt, say
+.IR a .
+.IB A .all()
+yields a list holding all the attributes;
+.IB a .get( name )
+yields the value of the attribute
+.IR name .
+.PP
+The location returned when an error is reported is held
+inside a
+.B Locator
+adt, which holds the line number on which the error occurred,
+the ``system id'' of the document (in this implementation, its file name),
+and the "public id" of the document (not currently used).
+.PP
+A
+.B Mark
+.I m
+may be converted to a string with
+.IB m .str()\fR;\fP
+this enables marks to be written out to external storage, to index
+a large XML document, for example.
+Note that if the XML document changes, any stored marks will
+no longer be valid.
+.SH SOURCE
+.B /appl/lib/xml.b
+.SH SEE ALSO
+``Extensible Markup Language (XML) 1.0 (Second Edition)'',
+.B http://www.w3.org/TR/REC-xml
+.SH BUGS
+XML's definition makes it tricky to handle leading and trailing white space
+efficiently;
+.B ws1
+and
+.B ws2
+in
+.B Item.Text
+is the current compromise.