Skip to content
Newer
Older
100644 125 lines (96 sloc) 3.17 KB
9328fc7 @disolovyov Added README
disolovyov authored Jun 30, 2011
1 # XmlStream
2
3 XmlStream is a Node.js XML stream parser and editor, based on
183c62d @disolovyov Added install info
disolovyov authored Sep 24, 2011
4 [node-expat](https://github.com/astro/node-expat) (libexpat SAX-like parser
9328fc7 @disolovyov Added README
disolovyov authored Jun 30, 2011
5 binding).
6
183c62d @disolovyov Added install info
disolovyov authored Sep 23, 2011
7 $ npm install xml-stream
8
9328fc7 @disolovyov Added README
disolovyov authored Jun 30, 2011
9 ## Rationale
10
11 When working with large XML files, it is probably a bad idea to use an XML to
12 JavaScript object converter, or simply buffer the whole document in memory.
13 Then again, a typical SAX parser might be too low-level for some tasks (and
14 often a real pain).
15
16 This is why we've rolled our own stream parser that tries to address these
17 shortcomings. It processes an XML stream chunk by chunk and fires events only
18 for nodes of interest, matching them with CSS-like selectors.
19
20 ## Events
21
22 Supported events:
23
24 * `data` on outgoing data chunk,
25 * `end` when parsing has ended,
26 * `startElement[: selector]` on opening tag for selector match,
27 * `updateElement[: selector]` on finished node for selector match
28 with its contents buffered,
29 * `endElement[: selector]` on closing tag for selector match,
30 * `text[: selector]` on tag text for selector match.
31
32 When adding listeners for `startElement`, `updateElement`, and `text` the
33 callback can modify the provided node, before it is sent to the consumer.
34
35 Selector syntax is CSS-like and currently supports:
36
37 * `ancestor descendant`
38 * `parent > child`
39
40 Take a look at the examples for more information.
d403a7d @disolovyov Added some information on the element node object structure
disolovyov authored Sep 22, 2011
41
42 ## Element Node
43
3d9ee47 @disolovyov Version bump to 0.3.2; fixed typo in README
disolovyov authored Sep 23, 2011
44 Each of the four node events has a callback with one argument. When parsing,
d403a7d @disolovyov Added some information on the element node object structure
disolovyov authored Sep 22, 2011
45 this argument is set to the current matched node. Having a chunk of XML like
46 this:
47
48 ```xml
49 <item id="123" type="common">
50 <title>Item Title</title>
51 <description>Description of this item.</description>
52 (text)
53 </item>
54 ```
55
56 The structure of the **item** element node would be:
57
58 ```javascript
59 {
60 title: 'Item Title',
4cb1498 @disolovyov Aggresively removing whitespace
disolovyov authored Sep 23, 2011
61 description: 'Description of this item.',
d403a7d @disolovyov Added some information on the element node object structure
disolovyov authored Sep 22, 2011
62 '$': {
63 'id': '123',
64 'type': 'common'
65 },
4cb1498 @disolovyov Aggresively removing whitespace
disolovyov authored Sep 23, 2011
66 '$name': 'item',
67 '$text': '(text)'
d403a7d @disolovyov Added some information on the element node object structure
disolovyov authored Sep 22, 2011
68 }
69 ```
70
71 Naturally, element text and child elements wouldn't be known until discovered
72 in the stream, so the structure may differ across events. The complete
4cb1498 @disolovyov Aggresively removing whitespace
disolovyov authored Sep 23, 2011
73 structure as displayed should be available on **updateElement**. The **$name**
74 is not available on **endElement**.
38fa6da @disolovyov Added some info on collect and preserve
disolovyov authored Oct 24, 2011
75
76 # Collecting Children
77
78 It is sometimes required to select elements that have many children with
79 one and the same name. Like this XML:
80
81 ```xml
82 <item id="1">
83 <subitem>one</subitem>
84 <subitem>two</subitem>
85 </item>
86 <item id="2">
87 <subitem>three</subitem>
88 <subitem>four</subitem>
89 <subitem>five</subitem>
90 </item>
91 ```
92
93 By default, parsed element node contains children as properties. In the case
94 of several children with same names, the last one would overwrite others.
95 To collect all of *subitem* elements in an array use **collect**:
96
97 ```javascript
98 xml.collect('subitem');
99 xml.on('endElement: item', function(item) {
100 console.log(item);
101 })
102 ```
103
104 # Preserving Elements and Text
105
106 By default, element text is returned as one concatenated string. In this XML:
107
108 ```xml
109 <item>
110 one <a>1</b>
111 two <a>2</b>
112 </item>
113 ```
114
115 The value of **$text** for *item* would be: `one 1 two 2` without any
116 indication of the order of element *a*, element *b*, and text parts.
117 To preserve this order:
118
119 ```javascript
120 xml.preserve('item');
121 xml.on('endElement: item', function(item) {
122 console.log(item);
123 })
124 ```
Something went wrong with that request. Please try again.