Changes between Version 6 and Version 7 of MicroXmlCowan


Ignore:
Timestamp:
08/16/17 14:37:46 (6 weeks ago)
Author:
cowan
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • MicroXmlCowan

    v6 v7  
    11== Events == 
    22 
    3 A MicroXML event is either an end-of-file object or a list representing a parsing event, in one of the following formats.  ''Stack'' is a list of element names currently being processed; the first element of the list is the current element. 
     3A MicroXML event is either an end-of-file object or a list representing a parsing event, in one of the following formats.  ''Stack'' is a list of SXML element names currently being processed; the car of the list is the name of the current element. 
    44 
    55`($start `''stack attr-list''`)` 
     
    2525== SXML == 
    2626 
    27 MicroXML uses a simplified version of SXML as the internal representation of documents.  Each SXML element is a list whose first member is a symbol representing the element name, whose second member is a JSO mapping the attribute names (as symbols) to their values (as strings), and whose remaining members (if any) are either SXML elements or strings.  The prototype of a JSO representing an attribute list is ignored.  There is no representation of comments or processing instructions in this version of SXML, and no notion of document objects (a document is just an element that has no parent).  The parent of an element that has one is stored as an attribute named `$parent` whose value is a SRFI 111 box containing the parent element.  This pseudo-attribute is ignored by all other attribute processing.  The box is used to prevent SXML elements from being circular tree structure. 
     27MicroXML uses a simplified version of SXML as the internal representation of documents.  Each SXML element is a list whose first member is a symbol representing the element name, whose second member is a JSO mapping the attribute names (as symbols) to their values (as strings), and whose remaining members (if any) are either SXML elements or strings.  The prototype of a JSO representing an attribute list is ignored.  There is no representation of comments or processing instructions in this version of SXML, and no notion of document objects (a document is just an element that has no parent). 
    2828 
    2929== Parsing, building, and printing procedures == 
    3030 
    31 ''Options'' is a list of symbols that control how MicroXML is written.  All implementations recognize `apos` to wrap attribute values in apostrophes, `end-tags` to write end-tags for empty elements, and `ascii` to escape all characters outside the ASCII range.  Other symbols are also allowed. 
    32  
    33 `(uxml->sxml `''port'' [ ''handler'' ]`)` 
     31''Options'' is a list of symbols that control how MicroXML is written.  All implementations recognize `apos` to wrap attribute values in apostrophes, `end-tags` to write end-tags for empty elements, and `ascii` to escape all characters outside the ASCII range.  The symbol `pretty` causes pretty-printing in implementations that support it.  Other symbols are also allowed; their effects are implementation-defined. 
     32 
     33`(uxml->sxml `''port handler''`)` 
    3434 
    3535Reads all the characters from the textual input port ''port'' as a MicroXML document and returns the SXML equivalent.  The procedure ''handler'' is invoked when a `$error` or `$pi` event is produced.  The default handler signals an error that satisfies `uxml-error?`.  If the handler is `#f`, errors and processing instructions are ignored; this relaxed parsing mode allows some XML documents that are not well-formed MicroXML to be parsed. 
     
    4141`(make-uxml-generator `''port''`)` 
    4242 
    43 Returns a generator of event objects representing a MicroXML document read from the textual input port ''port''.  Processing continues no matter how many errors there are until all characters have been read. 
     43Returns a [http://srfi.schemers.org/srfi-158/srfi-158.html SRFI 158] generator of event objects that represent a MicroXML document read from the textual input port ''port''.  Processing continues no matter how many errors there are until all characters have been read. 
    4444 
    4545`(make-sxml-generator `''element''`)` 
     
    5353`(event-generator->sxml `''gen''`)` 
    5454 
    55 Invokes the generator ''gen'' to obtain event objects, constructs the corresponding SXML element, and returns it.  If the resulting object would not be well-formed SXML, an error is signaled that satisfies `uxml-error?`. 
     55Invokes the generator ''gen'' to obtain event objects, constructs the corresponding SXML element, and returns it.  If the resulting object would not be structurally sound SXML, an error is signaled that satisfies `uxml-error?`. 
    5656 
    5757`(write-uxml `''port options''`)` 
    5858 
    59 Returns a procedure that accepts an event object.  When invoked repeatedly, it writes the corresponding MicroXML representation to the textual output port ''port'' using the symbols in ''options''.    If the resulting document would not be well-formed MicroXML, an error is signaled that satisfies `uxml-error?`. 
     59Returns a procedure that accepts an event object.  When invoked repeatedly, the procedure writes the corresponding MicroXML representation to the textual output port ''port'' using the symbols in ''options'', and returns an undefined value.    If the resulting document would not be well-formed MicroXML, an error is signaled that satisfies `uxml-error?`. 
    6060 
    6161`(build-sxml)` 
    6262 
    63 Returns a builder procedure that accepts an event object or an end of file object.  When invoked repeatedly, it builds the corresponding SXML representation.  If the object is an end of file object, the procedure returns the SXML element; if not, it returns an unspecified value.  If the resulting document would not be well-formed MicroXML, an error is signaled that satisfies `uxml-error?`. 
     63Returns a [http://srfi.schemers.org/srfi-158/srfi-158.html SRFI 158] accumulator that accepts an event object or an end of file object.  When invoked repeatedly, it builds the corresponding SXML representation.  If the object is an end of file object, the procedure returns the SXML element; if not, it returns an unspecified value.  If the resulting document would not be well-formed MicroXML, an error is signaled that satisfies `uxml-error?`. 
    6464 
    6565== Predicates == 
     
    6767`(sxml-element? `''obj''`)` 
    6868 
    69 Returns `#t` if ''obj'' is an SXML element and `#f` otherwise.  The procedure checks that ''obj'' is a list whose first element is a symbol and whose second element is a JSO; further elements of the list are not examined. 
     69Returns `#t` if ''obj'' is an SXML element and `#f` otherwise.  The procedure checks that ''obj'' is a list whose first element is a symbol and whose second element's car is the symbol `@`; further elements of the list are not examined. 
    7070 
    7171`(sxml-empty? `''element''`)` 
     
    9999`(sxml-language? `''element language''`)` 
    100100 
    101 Returns `#t` if the language of ''element'', as specified by the value of a `lang` or `xml:lang` attribute (the latter is not well-formed MicroXML but is supported for backward compatibility) matches ''language''. If ''element'' has no such attribute, the language of the nearest ancestor of ''element'' that has such an attribute is used. If there is no such attribute at all, then `sxml-language?` returns `#f`. 
     101Returns `#t` if the language of ''element'', as specified by the value of a `lang` or `xml:lang` attribute (the latter is not well-formed MicroXML but is supported for backward compatibility) matches ''language''; returns `#f` otherwise. If ''element'' has no such attribute, the language of the nearest ancestor of ''element'' that has such an attribute is used. If there is no such attribute at all, then `sxml-language?` returns `#f`. 
    102102 
    103103The attribute value matches ''language'' if, in a case-insensitive comparison, ''language'' exactly equals the attribute value, or if ''language'' exactly equals a prefix of the attribute value such that the first character following the prefix is "-".  
     
    105105== Element procedures == 
    106106 
     107`(sxml-copy `''element''`)` 
     108 
     109Returns a copy of ''element'' that shares nothing with it except possibly strings. 
     110 
    107111`(sxml-name `''element''`)` 
    108112 
    109113Returns the name of ''element'' as a symbol. 
    110114 
    111 `(sxml-set-name `''element name''`)` 
    112  
    113115`(sxml-set-name! `''element name''`)` 
    114116 
    115 Changes the name of ''element'' to the symbol ''name'', purely or with mutation. 
     117Replaces the name of ''element'' with the symbol ''name'' by mutation. 
    116118 
    117119`(sxml-attr-list `''element''`)` 
     
    119121Returns the attribute list of ''element'' as a JSO. 
    120122 
    121 `(sxml-set-attr-list `''element jso''`)` 
    122  
    123123`(sxml-set-attr-list! `''element jso''`)` 
    124124 
    125 Changes the attribute list of ''element'' to ''jso'', purely or with mutation. 
     125Replaces the attribute list of ''element'' with the JSO ''jso'' by mutation. 
    126126 
    127127`(sxml-content`''element''`)` 
     
    129129Returns the name of ''element'' as a list. 
    130130 
    131 `(sxml-set-content `''element list''`)` 
    132  
    133131`(sxml-set-content! `''element list''`)` 
    134132 
    135 Changes the content of ''element'' to the ''list'', purely or with mutation. 
     133Replaces the content of ''element'' with ''list'' by mutation. 
    136134 
    137135`(sxml-value `''element''`)` 
     
    139137Returns the results of concatenating all string content children in ''element'' and all its descendants in depth-first left-to-right preorder. 
    140138 
    141 `(sxml-defaults `''element attribute-defaults element-defaults inherited-attributes''`)` 
    142  
    143139`(sxml-defaults! `''element attribute-defaults element-defaults inherited-attributes''`)` 
    144140 
    145 Returns ''element'' with default values expanded in itself and all its descendants (purely or with mutation) as follows: 
     141Returns ''element'' with default values expanded in itself and all its descendants by mutation.  The following transformations are made: 
    146142 
    147143 * ''attribute-defaults'' is a list of 3-element sublists.  Each sublist contains an element name (a symbol), an attribute name (a symbol), and a default value (a string).  All elements with those names are checked for the presence of the corresponding attribute.  If it is missing, the attribute is added with the specified default value. 
     
    151147 * ''inherited-attributes'' is a list of symbols.  All elements are checked for an attribute whose name is one of the list.  If absent, then the most recent ancestor of the element that has this attribute is found (note that no parent map is required), and the attribute is added to the element being processed with the same value as in the ancestor. 
    152148 
    153 `(sxml-element position `''element parent-map''`)` 
     149`(sxml-element-position `''element parent-map''`)` 
    154150 
    155151Returns the position of ''element'' among the element children of the parent of ''element'' as an exact integer, with 1 meaning the first element child.  If there is no parent, return 0. 
     
    174170 * If any content children are elements, they are recursively normalized. 
    175171 
    176 `(sxml-trace `''element traceproc''`)` 
    177  
    178 Displays information on `(current-error-port)` about ''element''.  The precise nature of the information displayed is undefined, except that it should end with a newline.  ''Element'' is returned. 
     172`(sxml-write `''element''`)` 
     173 
     174Displays information on `(current-error-port)` about ''element''.  The precise nature of the information displayed is undefined, except that it should end with a newline; there is no guarantee that it can be re-read.  ''Element'' is returned. 
    179175 
    180176`(sxml-root `''element''`)` 
     
    182178Returns the root element of ''element''. 
    183179 
    184 `(sxml-parent `''element''`)` 
    185  
    186 Uses the `$parent` pseudo-attribute to determine the parent of ''element'' and returns it, or `#f` if there is none. 
     180== Mapping procedures == 
     181 
     182`(sxml-make-parent-mapping `''document''`)` 
     183 
     184Creates a parent mapping based on the SXML element ''document''.  A parent mapping is an opaque object that maps an element to its parent.  Returns the parent mapping. 
     185 
     186`(sxml-parent `''element parent-mapping''`)` 
     187 
     188Uses ''parent-mapping'' to determine the parent of ''element'' and returns it, or `#f` if there is none. 
    187189 
    188190`(sxml-detach-parent! `''element parent-mapping''`)` 
     
    226228`(sxml-number->boolean `''number''`)` 
    227229 
    228 If ''number'' returns `#t` when `zero?` is applied to it, returns `#f`; otherwise returns `#t`; 
     230If ''number'' returns `#t` when `zero?` is applied to it, returns `#f`; otherwise returns `#t`. 
    229231 
    230232`(sxml-boolean->number `''boolean''`)` 
     
    234236== Axis procedures == 
    235237 
    236 The following procedures are generator operations:  they accept a generator (of SXML elements) and return a generator (also of SXML elements).  After the `sxml-` prefix, they begin with `g`, using the convention of [http://srfi.schemers.org/srfi-121/srfi-121.html SRFI 121] for generator operations. 
    237  
    238 `(sxml-gparent `''gen''`)` 
     238The following procedures are generator operations:  they accept a generator (of SXML elements) and return a generator (also of SXML elements).  After the `sxml-` prefix, they begin with `g`, using the convention of [http://srfi.schemers.org/srfi-158/srfi-121.html SRFI 158] for generator operations. 
     239 
     240`(sxml-gparent `''parent-mapping gen''`)` 
    239241 
    240242Returns a generator of SXML elements which invokes SXML elements from ''gen'' and returns their parent elements on successive invocations. 
    241243 
    242 `(sxml-gancestor `''gen''`)` 
     244`(sxml-gancestor `''parent-mapping gen''`)` 
    243245 
    244246Returns a generator of SXML elements which invokes SXML elements from ''gen'' and returns their ancestor elements from parent to root on successive invocations. 
    245247 
    246 `(sxml-gancestor-or-self `''gen''`)` 
     248`(sxml-gancestor-or-self `''parent-mapping gen''`)` 
    247249 
    248250Returns a generator of SXML elements which invokes SXML elements from ''gen'' and returns their element itself and then its ancestor elements from parent to root on successive invocations. 
    249251 
    250 `(sxml-gchild `''gen''`)` 
     252`(sxml-gchild `''parent-mapping gen''`)` 
    251253 
    252254Returns a generator of SXML elements which invokes SXML elements from ''gen'' and returns their descendant elements in depth-first order from left to right on successive invocations. 
    253255 
    254 `(sxml-gdescendant `''gen''`)` 
     256`(sxml-gdescendant `''parent-mapping gen''`)` 
    255257 
    256258Returns a generator of SXML elements which invokes SXML elements from ''gen'' and returns their child elements from left to right on successive invocations. 
    257259 
    258 `(sxml-gdescendant-or-self `''gen''`)` 
     260`(sxml-gdescendant-or-self `''parent-mapping gen''`)` 
    259261 
    260262Returns a generator of SXML elements which invokes SXML elements from ''gen'' and returns their element itself and then its child elements from left to right on successive invocations. 
    261263 
    262 `(sxml-gfollowing `''gen''`)` 
     264`(sxml-gfollowing `''parent-mapping gen''`)` 
    263265 
    264266Returns a generator of SXML elements which invokes SXML elements from ''gen'' and returns all of their following elements in document order on successive invocations. 
    265267 
    266 `(sxml-gfollowing-or-self `''gen''`)` 
     268`(sxml-gfollowing-or-self `''parent-mapping gen''`)` 
    267269 
    268270Returns a generator of SXML elements which invokes SXML elements from ''gen'' and returns the elements themselves and then all of their following elements in document order on successive invocations. 
    269271 
    270 `(sxml-gpreceding `''gen''`)` 
     272`(sxml-gpreceding `''parent-mapping gen''`)` 
    271273 
    272274Returns a generator of SXML elements which invokes SXML elements from ''gen'' and returns all of their preceding elements in reverse document order on successive invocations. 
    273275 
    274 `(sxml-gpreceding-or-self `''gen''`)` 
     276`(sxml-gpreceding-or-self `''parent-mapping gen''`)` 
    275277 
    276278Returns a generator of SXML elements which invokes SXML elements from ''gen'' and returns the elements themselves and then all of their preceding elements in reverse document order on successive invocations. 
     
    278280== Paths == 
    279281 
    280 TBD 
     282`(sxml-path `''element parent-map item'' ...`)` 
    281283 
    282284== Error handling == 
     
    290292`(uxml-error-event `''xml-error''`)` 
    291293 
    292 Returns an `$error` or `$pi` event (i.e. a list) encapsulated in an error object. 
     294Returns an `$error` or `$pi` event (i.e. a list) encapsulated in ''xml-error''.