mirror of
https://github.com/RobTillaart/Arduino.git
synced 2024-10-03 18:09:02 -04:00
143 lines
4.7 KiB
Markdown
143 lines
4.7 KiB
Markdown
|
|
[](https://github.com/marketplace/actions/arduino_ci)
|
|
[](https://github.com/RobTillaart/XMLWriter/blob/master/LICENSE)
|
|
[](https://github.com/RobTillaart/XMLWriter/releases)
|
|
|
|
|
|
# XMLWriter
|
|
|
|
Arduino Library to create simple XML (messages, files, print, ...)
|
|
|
|
## Description
|
|
|
|
The XMLWriter class supports generating XML files and send these over a stream
|
|
like Ethernet SD.File or Serial.
|
|
|
|
When instantiating an XMLWriter one can define the internal buffer size.
|
|
A bigger buffer will make the output faster, especially for Ethernet and SD.File.
|
|
The buffer size should be at least 2 bytes and max 250.
|
|
How much faster depends on the properties of the stream and the platform used.
|
|
E.g. the baudrate and internal buffer of Serial, packet behaviour of Ethernet,
|
|
or paging of SD cards.
|
|
If performance is low one should do testruns with different sizes for the buffer
|
|
and choose one that is appropriate.
|
|
|
|
Indicative sizes based upon the examples.
|
|
Run your tests to find your application optimum.
|
|
|
|
| STREAM | SIZE |
|
|
|:------------|:----------|
|
|
| Ethernet | 20-30 |
|
|
| Serial | 5 |
|
|
| SD File | 10-16 |
|
|
|
|
**IMPORTANT:** When using buffering you should always call **XML.flush()**
|
|
at the end of the XML generation. This will flush the last bytes in the internal buffer into the output stream.
|
|
|
|
|
|
## Interface
|
|
|
|
### Constructor
|
|
|
|
- **XMLWriter(stream, bufsize);** Constructor defines the stream and the buffersize
|
|
to optimize performance vs memory usage.
|
|
|
|
|
|
### Functions for manual layout control
|
|
|
|
- **setIndentSize(size = 2)** preferred a multiple of 2; no limit
|
|
- **getIndentSize()** returns set indent
|
|
- **incrIndent()** increments indent by 2 spaces
|
|
- **decrIndent()** decrements indent by 2 spaces
|
|
- **indent()** manually indent output
|
|
- **raw(str)** inject any string
|
|
|
|
|
|
### General settings
|
|
|
|
- **setConfig(cfg)** used to show/strip comment, indent, newLine.
|
|
use **setConfig(0);** to minimize the output
|
|
- **newLine(n)** add a number of newlines to the output, default = 1
|
|
|
|
|
|
### Functions
|
|
|
|
- **header()** injects standard XML header string, must be first line
|
|
- **reset()** resets internal state, to be called before new XML is written
|
|
- **comment(text, multiline)** \<!-- text --\>
|
|
if multiline == true it does not indent to allow bigger text blocks
|
|
multiline is default false.
|
|
- **flush()** call flush() at the end of writing to empty the internal buffer. **!!**
|
|
|
|
|
|
### Functions to create simple tags with named fields
|
|
|
|
- **tagOpen(tag, newLine)** \<tag\>
|
|
- **tagOpen(tag, name, newLine)** \<tag name="name"\>
|
|
- **tagClose()** \</tag\>
|
|
|
|
|
|
### Functions to make up tags with multiple fields
|
|
|
|
- **tagStart(tag)** \<tag
|
|
- **tagField(field, string);** field="string"
|
|
- **tagField(field, T value, base = DEC);** standard math types, field="value"
|
|
- **tagEnd(newline = true, addSlash = true);** /\>
|
|
|
|
### Functions to make a node
|
|
|
|
- **writeNode(tag, value);** \<tag\>value\</tag\>
|
|
- **writeNode(tag, T value, base = DEC);** standard math types
|
|
|
|
### Helper
|
|
|
|
- **escape(str)** expands the xml chars: \"\'\<\>\&
|
|
|
|
|
|
### Metrics and debug
|
|
|
|
To optimize buffersize in combination with timing.
|
|
|
|
- **bufferIndex()** returns the size of the internal buffer
|
|
- **bytesWritten()** idem, since reset().
|
|
- **version()** injects the XMLWRITER_VERSION as comment in outputstream.
|
|
- **debug()** injects comment with internal info.
|
|
|
|
|
|
## Print interface
|
|
|
|
XMLWriter 0.2.4 implements the Print interface, so at any moment one can use
|
|
**print()** or **println()** to inject specific information.
|
|
|
|
Note that **tagField()** and **writeNode()** do not support 64 bit integer
|
|
types and large values of double.
|
|
My **printHelpers library** helps to convert these to strings which can be printed.
|
|
See example.
|
|
|
|
The Print interface can also be used to print objects that
|
|
implement the **Printable** interface. See example.
|
|
|
|
With the support of the Print interface, **raw()** is becoming obsolete as it only
|
|
can inject strings.
|
|
|
|
|
|
## Configuration flags
|
|
|
|
| Flag | Value | Meaning |
|
|
|:----|:----|:----|
|
|
|XMLWRITER_NONE | 0x00 | minimize output, smaller & faster |
|
|
|XMLWRITER_COMMENT | 0x01 | allow comments |
|
|
|XMLWRITER_INDENT | 0x02 | allow indentation |
|
|
|XMLWRITER_NEWLINE | 0x04 | allow newlines |
|
|
|
|
- **setConfig(XMLWRITER_NONE);** to minimize the output in bytes.
|
|
- **setConfig(XMLWRITER_NEWLINE);** to break an XML stream in lines.
|
|
- **setConfig(XMLWRITER_NEWLINE | XMLWRITER_INDENT);** to see XML structure.
|
|
- **setConfig(XMLWRITER_NEWLINE | XMLWRITER_INDENT | XMLWRITER_COMMENT);** to see XML structure + comments.
|
|
|
|
|
|
## Operation
|
|
|
|
See examples
|
|
|