Skip to content

Commit 8decbfb

Browse files
sophiebremersophiebremer
committed
Update README.md
1 parent f06a659 commit 8decbfb

File tree

1 file changed

+59
-63
lines changed

1 file changed

+59
-63
lines changed

‎README.md

Lines changed: 59 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -12,27 +12,42 @@ This package provides simple ways to parse any XML-like text.
1212

1313

1414

15-
Table Of Content
15+
Table of Content
1616
----------------
1717

18+
- [XMLTree](#xmltree)
19+
- [XMLTree Example](#xmltree-example)
20+
- [XMLScanner](#xmlscanner)
21+
- [XMLScanner Example](#xmlscanner-example)
22+
- [Types of XML Nodes](#types-of-xml-nodes)
23+
- [XMLPrinter Example](#xmlprinter-example)
1824

1925

20-
- [Examples](#examples)
21-
- [XMLTree Example](#xmltree-example)
22-
- [XMLScanner Example](#xmlscanner-example)
23-
- [XMLPrinter Example](#xmlprinter-example)
24-
- [Use Cases](#use-cases)
25-
- [Types Of XML Nodes](#types-of-xml-nodes)
26-
- [Walk On The XML Tree](#walk-on-the-xml-tree)
27-
- [Read Raw XML](#read-raw-xml)
2826

27+
XMLTree
28+
-------
2929

3030

31-
Examples
32-
--------
31+
The XML tree, often also called the DOM (Document Object Model), is the natural
32+
representation of XML. The `XMLTree` class can have multiple root nodes in the
33+
`XMLTree.roots` property.
3334

35+
Usually the last root is the one that contains most data. Or you check each root
36+
if it is a tag by using the `isXMLTag` helper function. Afterwards you can check
37+
the `XMLTag.innerXML` property for child nodes.
3438

35-
### XMLTree Example
39+
You can also use the `XMLTag.query` function to extract XML nodes with the help
40+
of selectors as known from CSS. It depends on the selector and use case whether
41+
this is faster than a custom walk through the tree nodes.
42+
43+
The `XMLTree` uses the `XMLScanner`, which is available via the
44+
`XMLTree.scanner` property. There you can adjust the `XMLScanner.cdataTags`
45+
property or the `XMLScanner.scanSize` property for special use cases.
46+
47+
48+
49+
XMLTree Example
50+
---------------
3651

3752
``` TypeScript
3853
const tree = XMLTree.parse(
@@ -90,7 +105,24 @@ console.log( JSON.stringify( tree.roots, null, ' ' ) );
90105
```
91106
92107
93-
### XMLScanner Example
108+
109+
XMLScanner
110+
----------
111+
112+
If XML should be read exactly like it is written, the `XMLScanner` is the class
113+
to use. It keeps every linebreak and every variant of a closing tag. The only
114+
things not preserved by the scanner are the surrounding quote characters for
115+
attribute values.
116+
117+
If you expect text between XML tags or an XML tag itself to be larger than 1 MB,
118+
then you should increase the value of the `XMLScanner.scanSize` property
119+
accordingly. If you like to save memory during a scan, you can also decrease the
120+
scan size.
121+
122+
123+
124+
XMLScanner Example
125+
------------------
94126
95127
``` TypeScript
96128
const scanner = new XMLScanner(
@@ -123,31 +155,9 @@ while ( node = scanner.scan() ) {
123155
```
124156
125157
126-
### XMLPrinter Example
127-
128-
``` TypeScript
129-
const printer = new XMLPrinter( [
130-
{ tag: "!DOCTYPE", attributes: { html: "" } },
131-
{ tag: "html", attributes: { lang: "en" } }
132-
]);
133-
134-
console.log( printer.toString() );
135-
```
136-
``` HTML
137-
<!DOCTYPE html=""><html></html>
138-
```
139-
140-
141-
142-
Use Cases
143-
---------
144-
145158
146-
In the following you find a list of typical use cases for this library. They
147-
give you an idea how to use the library and how to work around edge cases.
148-
149-
150-
### Types Of XML Nodes
159+
Types of XML Nodes
160+
------------------
151161
152162
XML has 7 different types of nodes.
153163
@@ -177,33 +187,19 @@ XML has 7 different types of nodes.
177187
starting with a `?` character. A typical instruction tag is `?xml`.
178188
179189
180-
### Walk On The XML Tree
181190
182-
The XML tree, often also called the DOM (Document Object Model), is the natural
183-
representation of XML. The `XMLTree` class can have multiple root nodes in the
184-
`XMLTree.roots` property.
185191
186-
Usually the last root is the one that contains most data. Or you check each root
187-
if it is a tag by using the `isXMLTag` helper function. Afterwards you can check
188-
the `XMLTag.innerXML` property for child nodes.
192+
XMLPrinter Example
193+
------------------
189194
190-
You can also use the `XMLTag.query` function to extract XML nodes with the help
191-
of selectors as known from CSS. It depends on the selector and use case whether
192-
this is faster than a custom walk through the tree nodes.
193-
194-
The `XMLTree` uses the `XMLScanner`, which is available via the
195-
`XMLTree.scanner` property. There you can adjust the `XMLScanner.cdataTags`
196-
property or the `XMLScanner.scanSize` property for special use cases.
197-
198-
199-
### Read Raw XML
200-
201-
If XML should be read exactly like it is written, then `XMLScanner` is the class
202-
to go with. It keeps every linebreak and every variant of a closing tag. The
203-
only things not preserved by the scanner are the surrounding quote characters
204-
for attribute values.
195+
``` TypeScript
196+
const printer = new XMLPrinter( [
197+
{ tag: "!DOCTYPE", attributes: { html: "" } },
198+
{ tag: "html", attributes: { lang: "en" } }
199+
]);
205200

206-
If you expect text between XML tags or an XML tag itself to be larger than 1 MB,
207-
then you should increase the value of the `XMLScanner.scanSize` property
208-
accordingly. If you like to save memory during a scan, you can also decrease the
209-
scan size.
201+
console.log( printer.toString() );
202+
```
203+
``` HTML
204+
<!DOCTYPE html=""><html></html>
205+
```

0 commit comments

Comments
 (0)