{"id":20989848,"url":"https://github.com/robtillaart/xmlwriter","last_synced_at":"2025-07-19T22:04:07.707Z","repository":{"id":45233154,"uuid":"258798555","full_name":"RobTillaart/XMLWriter","owner":"RobTillaart","description":"Arduino Library to create simple XML (messages, files, print, ...)","archived":false,"fork":false,"pushed_at":"2025-05-11T08:55:17.000Z","size":71,"stargazers_count":8,"open_issues_count":3,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-11T09:33:05.700Z","etag":null,"topics":["arduino","writer","xml"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RobTillaart.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"RobTillaart","custom":"https://www.paypal.me/robtillaart"}},"created_at":"2020-04-25T14:40:56.000Z","updated_at":"2024-02-16T22:27:38.000Z","dependencies_parsed_at":"2023-11-23T15:28:30.419Z","dependency_job_id":"20ccd604-fa52-4e1f-abb7-3c741ffa4ee0","html_url":"https://github.com/RobTillaart/XMLWriter","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/RobTillaart/XMLWriter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobTillaart%2FXMLWriter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobTillaart%2FXMLWriter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobTillaart%2FXMLWriter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobTillaart%2FXMLWriter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RobTillaart","download_url":"https://codeload.github.com/RobTillaart/XMLWriter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobTillaart%2FXMLWriter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266026177,"owners_count":23866030,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","writer","xml"],"created_at":"2024-11-19T06:26:24.711Z","updated_at":"2025-07-19T22:04:07.665Z","avatar_url":"https://github.com/RobTillaart.png","language":"C++","funding_links":["https://github.com/sponsors/RobTillaart","https://www.paypal.me/robtillaart"],"categories":[],"sub_categories":[],"readme":"\n[![Arduino CI](https://github.com/RobTillaart/XMLWriter/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)\n[![Arduino-lint](https://github.com/RobTillaart/XMLWriter/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/XMLWriter/actions/workflows/arduino-lint.yml)\n[![JSON check](https://github.com/RobTillaart/XMLWriter/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/XMLWriter/actions/workflows/jsoncheck.yml)\n[![GitHub issues](https://img.shields.io/github/issues/RobTillaart/XMLWriter.svg)](https://github.com/RobTillaart/XMLWriter/issues)\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/XMLWriter/blob/master/LICENSE)\n[![GitHub release](https://img.shields.io/github/release/RobTillaart/XMLWriter.svg?maxAge=3600)](https://github.com/RobTillaart/XMLWriter/releases)\n[![PlatformIO Registry](https://badges.registry.platformio.org/packages/robtillaart/library/XMLWriter.svg)](https://registry.platformio.org/libraries/robtillaart/XMLWriter)\n\n\n# XMLWriter\n\nArduino Library to create simple XML (messages, files, print, ...).\n\n\n## Description\n\nThe XMLWriter class supports generating XML files and send these over a stream\nlike Ethernet SD.File or Serial.\n\nWhen instantiating an XMLWriter one can define the internal buffer size.\nA bigger buffer will make the output faster, especially for Ethernet and SD.File.\nThe buffer size should be at least 2 bytes and max 250.\nHow much faster depends on the properties of the stream and the platform used.\nE.g. the baud rate and internal buffer of Serial, packet behaviour of Ethernet,\nor paging of SD cards.\nIf performance is low one should do test runs with different sizes for the buffer \nand choose one that is appropriate.\n\nIndicative sizes based upon the examples.\nRun your tests to find your application optimum.\n\n|  STREAM    |    SIZE    |\n|:-----------|:-----------|\n|  Ethernet  |   20-30    |\n|  Serial    |     5      |\n|  SD File   |   10-16    |\n\n**IMPORTANT:** When using buffering you should always call **XML.flush()** \nat the end of the XML generation. This will flush the last bytes in the internal buffer into the output stream.\n\nAs always, feedback or improvements are welcome. \nPlease open an issue.\n\n\n### Related\n\n- https://github.com/RobTillaart/printHelpers  Formatting incl scientific notation (large floats)\n- https://github.com/RobTillaart/PrintString  Make a string representation\n- https://github.com/RobTillaart/MultiPlex  send stream to multiple destinations (e.g. File and Screen)\n\n\n## Interface\n\n```cpp\n#include \"XMLWriter.h\"\n```\n\n### Constructor\n\n- **XMLWriter(Print\\* stream = \u0026Serial, uint8_t bufferSize = 10)** Constructor defines \nthe stream and the buffer size to optimize performance vs memory usage.\nNote the default bufferSize of 10 can be optimized. \nSee table in description above.\n- **~XMLWriter()** destructor\n\n\n### Functions for manual layout control\n\n- **void setIndentSize(uint8_t size = 2)** preferred a multiple of 2; no limit.\nFor compact XML with no indents set size to zero.\n- **uint8_t getIndentSize()** returns set indent size.\n- **void incrIndent()** increments indent by defined spaces (default 2).\n- **void decrIndent()** decrements indent by defined spaces (default 2).\n- **void indent()** manually indent output.\n- **void raw(char\\* str)** inject any string into XML, use with care!\n\n\n### General settings\n\n- **void setConfig(uint8_t config)** used to show/strip comment, indent, newLine. \nTo minimize the output, use **setConfig(0);**, see table below.\n- **void newLine(uint8_t n = 1)** add a number of newlines to the output, default = 1.\n\n#### Configuration flags\n\n|  setConfig flags           |  Value  |  Notes  |\n|:---------------------------|:-------:|:--------|\n|  XMLWRITER_NONE            |   0x00  |  minimizes the output size, smaller and faster.\n|  XMLWRITER_COMMENT         |   0x01  |  enable comments\n|  XMLWRITER_INDENT          |   0x02  |  enable indents\n|  XMLWRITER_NEWLINE         |   0x04  |  enable newlines\n|  XMLWRITER_CONFIG_DEFAULT  |   0x07  |  enable all, default after reset()\n\n```cpp\nsetConfig(XMLWRITER_NONE);       //  minimize the output in bytes.\nsetConfig(XMLWRITER_NEWLINE);    //  \"break up\" an XML stream in logic lines.\nsetConfig(XMLWRITER_NEWLINE | XMLWRITER_INDENT); //  show XML structure. (pretty print)\nsetConfig(XMLWRITER_NEWLINE | XMLWRITER_INDENT | XMLWRITER_COMMENT);  // show XML structure + comments.\nsetConfig(XMLWRITER_CONFIG_DEFAULT);  //  show XML structure + comments.\n```\n\n### Functions\n\n- **void header()** injects standard XML header string, must be first line.\n- **void reset()** resets internal state, to be called before new XML is written.\n- **void comment(char\\* text, bool multiLine = false)** \\\u003c!-- text --\\\u003e  \nif multiline == true it does not indent to allow bigger text blocks\nmultiline is default false.\n- **bool needFlush()** checks if internal buffer has unwritten data.\n- **void flush()** flushes the internal buffer. Call flush() at the end of writing \nto the XML file to empty the remainder in the internal buffer. **!!**\n\nThe comment() can be used to quickly embed compile time constants into the XML file.\n```cpp\n  XML.comment(__DATE__);\n  XML.comment(__TIME__);\n  XML.comment(__FILE__);\n  XML.comment(__FUNCTION__);\n```\n\nOther data types can easily be converted by means of - https://github.com/RobTillaart/PrintString\n\n\n### Functions to create simple tags with named fields\n\n- **void tagOpen(char\\* tag, bool newLine = true)** writes \\\u003ctag\\\u003e\n- **void tagOpen(char\\* tag, char\\* name, bool newLine = true)** writes \\\u003ctag name=\"name\"\\\u003e\n- **void tagClose(bool ind = true)** writes \\\u003c/tag\\\u003e\n\n\n### Functions to create tags with multiple fields\n\n- **void tagStart(char\\* tag)** writes \\\u003ctag \n- **void tagField(char\\* field, char\\* string)** writes field=\"string\"\n- **void tagField(char\\* field, T value, uint8_t base = DEC)** writes the standard integer math types,  \nfield=\"value\".\n- **void tagField(char\\* field, float value, uint8_t decimals = 2)**\n- **void tagField(char\\* field, double value, uint8_t decimals = 2)**\n- **void tagEnd(bool newline = true, bool addSlash = true);**  writes /\\\u003e\n\n\n### Functions to create a node\n\n- **void writeNode(char\\* tag, bool value);** writes \\\u003ctag\\\u003evalue\\\u003c/tag\\\u003e\n- **void writeNode(char\\* tag, T value, uint8_t base = DEC);** writes standard integer math types.\n- **void writeNode(char\\* tag, float value, uint8_t decimals = 2)**\n- **void writeNode(char\\* tag, double value, uint8_t decimals = 2)**\n\n\n### Escape helper \n\n- **void escape(char\\* str)** expands the XML chars: \\\"\\'\\\u003c\\\u003e\\\u0026\nNote one need to set the **XMLWRITER_ESCAPE_SUPPORT** flag.\n\n\n### Metrics and debug\n\nTo optimize buffer size in combination with timing.\n\n- **uint8_t bufferIndex()** returns the size of the internal buffer.\n- **uint32_t bytesWritten()** idem, since reset().\n- **void version()** injects the **XMLWRITER_VERSION** as comment in output stream.\n- **void debug()** injects comment with internal info.\n\n\n## Print interface\n\nXMLWriter 0.2.4 implements the Print interface, so at any moment one can use \n**print()** or **println()** to inject specific information.  \nNote that one might need to call **flush()** to flush the internal buffer first.\n\nNote that **tagField()** and **writeNode()** do not support 64 bit integer\ntypes and large values of float and double. \nMy **printHelpers library** helps to convert these data types to strings which can be printed.\nSee example.\n\nThe Print interface can also be used to print objects that \nimplement the **Printable** interface. See example.\n\nWith the support of the Print interface, **raw()** is becoming obsolete as it only\ncan inject strings.\n\n\n## Future\n\n#### Must\n\n- update documentation\n\n#### Should\n\n#### Could\n\n- what can be configured?\n- **uint8_t getConfig()** returns mask\n- **void comment(int)** in all its variations,\n- move code to .cpp\n\n#### Wont\n\n\n## Support\n\nIf you appreciate my libraries, you can support the development and maintenance.\nImprove the quality of the libraries by providing issues and Pull Requests, or\ndonate through PayPal or GitHub sponsors.\n\nThank you,\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobtillaart%2Fxmlwriter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobtillaart%2Fxmlwriter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobtillaart%2Fxmlwriter/lists"}