source: project/wiki/eggref/5/sxml-modifications @ 39101

Last change on this file since 39101 was 39101, checked in by svnwiki, 5 months ago

Anonymous wiki edit for IP [78.85.4.246]: revert to 0.2 version

File size: 8.6 KB
Line 
1[[tags:eggs]]
2
3This is version 0.2 of the '''sxml-modifications''' extension library for Chicken Scheme.
4
5[[toc:]]
6
7== Sxml-modifications
8
9The {{modif}} parts of the [[http://cvs.sourceforge.net/viewcvs.py/ssax/sxml-tools/|sxml-tools]] from the [[http://ssax.sf.net|SSAX project]] at Sourceforge.
10
11== Requirements
12
13* [[srfi-1]]
14* [[sxpath]]
15
16== Documentation
17
18This egg provides procedures for making modifications to SXML
19documents, functional-style.
20
21Some documentation is available in
22[[http://modis.ispras.ru/Lizorkin/sxml-tutorial.html#hevea:modif|Dmitry
23Lizorkin's tutorial]] and the [[http://ssax.sf.net|SSAX homepage]].
24Note that the SSAX documentation uses the more awkward and arbitrary
25{{sxml:}} or {{modif:}} prefixes.
26
27The initial documentation on this wiki page came straight from the
28comments in the extremely well-documented source code. It's
29recommended you read the code if you want to learn more.
30
31Modifications are done to all nodes that match an xpath expression.
32These can be either textual "standard" XPath or [[sxpath]]
33expressions.
34
35<procedure>(modify [update-specifier ...])</procedure>
36
37Returns a procedure which accepts a document and returns a modified
38copy of this document.  How it will be modified depends on the
39{{update-specifier}}s passed to it.  Each update-specifier is a list
40of two or three elements:
41
42  update-specifier ::= (xpath-location-path  action  [action-parameter ...])
43
44{{xpath-location-path}} addresses the node(s) to be transformed, in
45the form of an XPath location path. If the location path is absolute,
46it addresses the node(s) with respect to the root of the document
47being transformed. If the location path is relative, it addresses the
48node(s) with respect to the node selected by the previous
49update-specifier. The location path in the first update-specifier
50always addresses the node(s) with respect to the root of the
51document. We'll further refer to the node with respect of which the
52location path is evaluated as to the base-node for this location path.
53
54{{action}} specifies the modification to be made over each of the
55node(s) addressed by the location path. Possible actions are described
56below.
57
58{{action-parameter}}s are additional parameters supplied for the
59action. The number of parameters and their semantics depend on the
60definite action.
61
62Each {{action}} is either a symbol that describes what to do, or a
63handler lambda which performs the action itself.  The allowed symbols
64are as follows:
65
66; {{delete}} : deletes the node. Expects no action-parameters
67; {{delete-undeep}} : deletes the node, but keeps all its content (which thus moves to one level upwards in the document tree). Expects no action-parameters.
68; {{insert-into}} : inserts the new node(s) as the last children of the given node. The new node(s) are specified in SXML as action-parameters.
69; {{insert-following}}, {{insert-preceding}} : inserts the new node(s) after (before) the given node. Action-parameters are the same as for {{insert-into}}.
70; {{replace}} : replaces the given node with the new node(s). Action-parameters are the same as for {{insert-into}}.
71; {{rename}} : renames the given node. The node to be renamed must be a pair (i.e. not a text node). A single action-parameter is expected, which is to be a Scheme symbol to specify the new name of the given node.
72; {{move-into}} : moves the given node to a new location. The single action-parameter is the location path, which addresses the new location with respect to the given node as the base node. The given node becomes the last child of the node selected by the parameter location path.
73; {{move-following}}, {{move-preceding}} : the given node is moved to the location respectively after (before) the node selected by the parameter location path.
74
75If a handler is passed, it should look like {{(lambda (node context base-node) ...)}}.
76The {{node}} is the current target of the {{xpath-location-path}} in the current
77update specifier.  {{context}} is a list that consists of the symbol {{*CONTEXT*}}, followed by
78the current node and all its ancestors that were looked at during the XPath matching process
79(as per [[sxpath]]'s {{context-sxpath}} module).  {{base-node}} is the node that was used
80as the starting point for the current {{xpath-location-path}} (useful if it's a relative
81path; you can "see" the previous update specifier's node this way).
82
83The handler can return either an SXML node, which will then replace
84the source document's node, or a nodeset (list of nodes), in which
85case it will splice this set into the place occupied by the source
86node.  If an empty nodeset -- ie, {{'()}} -- is returned, this has the
87effect of deleting the source node.
88
89Example:
90
91<enscript highlight="scheme">
92(import (prefix sxml-modifications sxmlm:))
93
94(define doc
95  '(*TOP*
96    (*PI* xml "version='1.0'")
97    (purchaseOrder (@ (orderDate "07.23.2001"))
98      (recipient
99        (name "Dennis Scannell")
100        (street "175 Perry Lea Side Road"))
101      (order
102        (cd (@ (title "Little Lion") (artist "Brooks Williams")))))))
103
104(define delete-recipient (sxmlm:modify '("purchaseOrder/recipient" delete)))
105(delete-recipient doc)
106=>
107(*TOP*
108 (*PI* xml "version='1.0'")
109 (purchaseOrder (@ (orderDate "07.23.2001"))
110   ;; (recipient ...) is gone
111   (order
112     (cd (@ (title "Little Lion") (artist "Brooks Williams"))))))
113
114;; insert-into accepts any number of action-parameters, being the node(s) to insert at the end
115((sxmlm:modify '("purchaseOrder/recipient" insert-into (postalCode "05676") (city "Footown"))) doc)
116=>
117(*TOP*
118 (*PI* xml "version='1.0'")
119 (purchaseOrder (@ (orderDate "07.23.2001"))
120   (recipient
121     (name "Dennis Scannell")
122     (street "175 Perry Lea Side Road")
123     (postalCode "05676") ; New
124     (city "Footown"))    ; New
125   (order
126     (cd (@ (title "Little Lion") (artist "Brooks Williams"))))))
127</enscript>
128
129<procedure>(modify! [update-specifier ...])</procedure>
130
131Destructively updating version of {{modify}}.  Like the
132linear-updating variants of SRFI-1, you should use the return value of
133this procedure rather than assuming the original document was mutated
134in-place.
135
136<procedure>(insert-following node-specifier)</procedure>
137<procedure>(insert-preceding node-specifier)</procedure>
138<procedure>(insert-into node-specifier)</procedure>
139<procedure>(rename new-name)</procedure>
140<procedure>delete</procedure>
141<procedure>delete-undeep</procedure>
142
143These procedures all correspond to the action symbols accepted by
144{{modify}}.  There are no procedures corresponding to
145{{move-into}}, {{move-preceding}}, {{move-following}} or {{replace}}.
146
147The {{delete}} and {{delete-undeep}} procedures can only be
148put directly into the action-parameters list as-is, which means this
149adds zero expressiveness over the corresponding symbols.
150
151The {{insert-following}}, {{insert-preceding}} and {{insert-into}}
152procedures all accept a {{node-specifier}} procedure of two arguments
153which must return a node or node-set which shall be inserted.  The
154first argument of the procedure is the context, the second is the base
155node.
156
157The {{rename}} procedure accepts a symbol which indicates the new
158element name to use for the matched nodes.
159
160Here's the example from {{modify}} using these procedures instead
161of action symbols:
162
163<enscript highlight="scheme">
164(prefix sxml-modifications sxmlm:)
165
166(define doc
167  '(*TOP*
168    (*PI* xml "version='1.0'")
169    (purchaseOrder (@ (orderDate "07.23.2001"))
170      (recipient
171        (name "Dennis Scannell")
172        (street "175 Perry Lea Side Road"))
173      (order
174        (cd (@ (title "Little Lion") (artist "Brooks Williams")))))))
175
176(define delete-recipient (sxmlm:modify `("purchaseOrder/recipient" ,sxmlm:delete)))
177(delete-recipient doc)
178=>
179(*TOP*
180 (*PI* xml "version='1.0'")
181 (purchaseOrder (@ (orderDate "07.23.2001"))
182   ;; (recipient ...) is gone
183   (order
184     (cd (@ (title "Little Lion") (artist "Brooks Williams"))))))
185
186;; insert-into accepts any number of action-parameters, being the node(s) to insert at the end
187((sxmlm:modify `("purchaseOrder/recipient"
188                ,(sxmlm:insert-into
189                  (lambda (context base-node)
190                    (list '(postalCode "05676") '(city "Footown"))))))
191 doc)
192=>
193(*TOP*
194 (*PI* xml "version='1.0'")
195 (purchaseOrder (@ (orderDate "07.23.2001"))
196   (recipient
197     (name "Dennis Scannell")
198     (street "175 Perry Lea Side Road")
199     (postalCode "05676") ; New
200     (city "Footown"))    ; New
201   (order
202     (cd (@ (title "Little Lion") (artist "Brooks Williams"))))))
203</enscript>
204
205== About this egg
206
207=== Author
208
209[[http://okmij.org/ftp/|Oleg Kiselyov]], [[http://metapaper.net/|Kirill Lisovsky]], [[http://modis.ispras.ru/Lizorkin/index.html|Dmitry Lizorkin]].
210
211=== Version history
212
213; 0.2 : Ported to Chicken 5
214; 0.1 : First Chicken 4 release
215
216=== License
217
218The sxml-tools are in the public domain.
Note: See TracBrowser for help on using the repository browser.