.TH XML 2.SH NAMExml \- XML navigation.SH SYNOPSIS.EXinclude "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);fopen: fn(iob: ref Bufio->Iobuf, 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 Xmlprovides an interface for navigating XML files (`documents'). Once loaded, the modulemust 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 ffor parsing as an XML document,or.BR fopen(\fIiob\fP,\ \fIname\fP,\ \fIwarning\fP,\ \fIpreelem\fP) ,which does the same for an already open.B Iobuf(the string.I namewill be used in diagnostics).Both functions return a tuple.RI ( p ,\  err ).If there is an error opening the document,.I pis nil, and.I errcontains a description of the error; otherwise.I pcan be used to examine the contents of the document.If.I warningis not nil, non-fatal errors encountered when parsingwill be sent on this channel - a separate process willbe needed to received them. Each error is representedby a tuple.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..PPOnce an XML document has been opened, the following.B Parsermethods may be used to examine the items contained within:.TP 10.IB p .next()An XML document is represented by a tree-structure..B Nextreturns the next item in the document at the current level of the treewithin the current parent element. If there are no more suchitems, it returns.BR nil ..TP.IB p .down().B Downdescends into the element that has just been returned by.BR next ,which should be a.B Tagitem. Subsequent items returned by.B nextwill be those within that tag..TP.IB p .up().B Upmoves up one level in the XML tree..TP.IB p .mark().B Markreturns a mark that can be used to return later to the currentposition in the document. The underlying file mustbe 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 Atmarkreturns non-zero if the currentposition 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 Str2markturns a string as created by.B Mark.strback into a mark as returned by.BR Parser.mark ..SS ItemsVarious species of items live in XML documents; they are encapsulatedin the.B Itemadt. 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 TagA generic XML tag..B Namenames the tag, and.B attrsholds its attributes, if any..TP.B Text.B Textrepresents inline text in the XML document.With the exception of text inside the tag named by.I preelemin.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 Chcontains the resulting text;.B ws1and.B ws2are non-zero if there was originally white space at the startor end of the text respectively..TP.B Process.B Processrepresents an XML document processing directive..B Targetis the processing instruction's target, and.B dataholds the rest of the text inside the directive.XML stylesheet directives are recognised directly and havetheir own item type..TP.B Doctype.B Doctypeshould only occur at the start of an xml document,and represents the type of the XML document..TP.B Stylesheet.B Stylesheetrepresents an XML stylesheet processing request. Thedata of the processing request is parsed as per the RFCinto attribute-value pairs..TP.B ErrorIf an unrecoverable error occurs processing the document,an.B Erroritem is returned holding the location.RB ( loc ),and description.RB ( msg )of the error.This will be the last item returned by the parser..PPThe attribute-value pairs in.B Tagand.B Stylesheetitems are held in an.B Atttributesadt, 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 ..PPThe location returned when an error is reported is heldinside a.B Locatoradt, 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)..PPA.B Mark.I mmay be converted to a string with.IB m .str()\fR;\fPthis enables marks to be written out to external storage, to indexa large XML document, for example.Note that if the XML document changes, any stored marks willno 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 BUGSXML's definition makes it tricky to handle leading and trailing white spaceefficiently;.B ws1and.B ws2in.B Item.Textis the current compromise.