{"id":14985645,"url":"https://github.com/tobozo/yamlduino","last_synced_at":"2025-04-11T22:04:29.380Z","repository":{"id":61352670,"uuid":"545696703","full_name":"tobozo/YAMLDuino","owner":"tobozo","description":"YAML \u003c=\u003e JSON converter for ESP32, ESP8266, RP2040 and possibly other devices","archived":false,"fork":false,"pushed_at":"2024-06-18T14:44:14.000Z","size":709,"stargazers_count":45,"open_issues_count":3,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-20T02:47:51.644Z","etag":null,"topics":["arduino","arduinojson","cjson","esp32","esp8266","json","libyaml","rp2040","rp2040-zero","rp2040w","samd","yaml","yaml2json","yamltojson","yml"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tobozo.png","metadata":{"files":{"readme":"ReadMe.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2022-10-04T20:33:06.000Z","updated_at":"2025-01-10T22:20:43.000Z","dependencies_parsed_at":"2024-06-16T14:55:02.575Z","dependency_job_id":null,"html_url":"https://github.com/tobozo/YAMLDuino","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobozo%2FYAMLDuino","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobozo%2FYAMLDuino/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobozo%2FYAMLDuino/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobozo%2FYAMLDuino/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tobozo","download_url":"https://codeload.github.com/tobozo/YAMLDuino/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239785312,"owners_count":19696754,"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","arduinojson","cjson","esp32","esp8266","json","libyaml","rp2040","rp2040-zero","rp2040w","samd","yaml","yaml2json","yamltojson","yml"],"created_at":"2024-09-24T14:11:25.277Z","updated_at":"2025-04-11T22:04:29.366Z","avatar_url":"https://github.com/tobozo.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ArduinoYaml A.K.A YAMLDuino\n\n\n[![arduino-library-badge](https://www.ardu-badge.com/badge/YAMLDuino.svg?)](https://www.ardu-badge.com/YAMLDuino)\n[![PlatformIO Registry](https://badges.registry.platformio.org/packages/tobozo/library/YAMLDuino.svg?)](https://registry.platformio.org/packages/libraries/tobozo/YAMLDuino)\n\n![](https://raw.githubusercontent.com/tobozo/YAMLDuino/main/assets/sleazy-logo-with-title.png)\n\n\nThis arduino library is based on [libyaml](https://github.com/yaml/libyaml).\n\n\n### Supported platforms:\n\n- ESP32\n- RP2040\n- ESP8266\n- SAMD\n- TeensyDuino\n\n### Features:\n\n- YAML➔JSON and JSON➔YAML conversion\n- Accepts *valid* JSON or YAML as the input.\n- Standalone serializers/deserializers\n- ArduinoJson serializers/deserializers\n- cJSON serializers/deserializers\n- Node accessors\n- l10n style gettext()\n- i18n loader\n\n----------------------------\n\n\n## Usage\n\n```cpp\n#include \u003cArduinoYaml.h\u003e\n```\n\nor\n\n```cpp\n#include \u003cYAMLDuino.h\u003e\n```\n\n----------------------------\n\n\n## Pure libyaml implementation\n\nYAML is a superset of JSON, so native conversion from/to JSON is possible without any additional JSON library.\n\n```cpp\n// Available values for output format:\n//   OUTPUT_YAML (default)\n//   OUTPUT_JSON\n//   OUTPUT_JSON_PRETTY\n// JSON/YAML document to YAML/JSON string\nsize_t serializeYml( yaml_document_t* src_doc, String \u0026dest_string, OutputFormat_t format=OUTPUT_YAML );\n// JSON/YAML object to YAML/JSON stream\nsize_t serializeYml( yaml_document_t* src_doc, Stream \u0026dest_stream, OutputFormat_t format=OUTPUT_YAML );\n\n// YAML string to YAML document\nint deserializeYml( YAMLNode\u0026 dest_obj, const char* src_yaml_str );\n// YAML stream to YAML document\nint deserializeYml( YAMLNode\u0026 dest_obj, Stream \u0026src_stream );\n\n```\n\n\n**Convert YAML to JSON**\n```cpp\nString yaml_str = \"hello: world\\nboolean: true\\nfloat: 1.2345\";\nYAMLNode yamlnode = YAMLNode::loadString( yaml_str );\nserializeYml( yamlnode.getDocument(), Serial, OUTPUT_JSON_PRETTY ); // pretty JSON\n// serializeYml( yamlnode.getDocument(), Serial, OUTPUT_JSON ); // ugly JSON\n```\n\n\n\n**Convert JSON to YAML**\n```cpp\nString json_str = \"{\\\"hello\\\": \\\"world\\\", \\\"boolean\\\": true, \\\"float\\\":1.2345}\";\nYAMLNode yamlnode = YAMLNode::loadString( yaml_str );\nserializeYml( yamlnode.getDocument(), Serial, OUTPUT_YAML );\n```\n\n----------------------------\n\n## Bindings\n\nArduinoJson and cJSON bindings operate differently depending on the platform.\n\n\n|                 | ArduinoJson support |         cJSON support        |\n|-----------------|---------------------|------------------------------|\n|        ESP32    |    detected (*)     |  implicit (built-in esp-idf) |\n|        ESP8266  |    implicit         |  implicit (bundled)          |\n|        RP2040   |    implicit         |  implicit (bundled)          |\n|        SAMD     |    implicit         |  implicit (bundled)          |\n\n\n(*) On ESP32 platform, the detection depends on `__has_include(\u003cArduinoJson.h\u003e)` macro.\nSo all ArduinoJson functions will be disabled unless `#include \u003cArduinoJson.h\u003e` is found **before** `#include \u003cArduinoYaml.h\u003e`.\n\nOn ESP8266/RP2040/SAMD platforms it is assumed that ArduinoJson is already available as a dependency.\n\n\nIn order to save flash space and/or memory, the default bindings can be disabled independently by setting one or all of the\nfollowing macros before including ArduinoYaml:\n\n```cpp\n#define YAML_DISABLE_ARDUINOJSON // disable all ArduinoJson functions\n#define YAML_DISABLE_CJSON       // disable all cJSON functions\n```\n\nNote to self: this should probably be the other way around e.g. explicitely enabled by user.\n\nNote to readers: should ArduinoJson and/or cJSON be implicitely loaded?\n[Feedback is welcome!](https://github.com/tobozo/YAMLDuino/issues)\n\n\n----------------------------\n\n## ArduinoJson bindings\n\nSee the [motivational post](https://github.com/bblanchon/ArduinoJson/issues/1808) for this implementation.\n\nArduinoJson support is implicitely enabled on most platforms except for ESP32 where dependencies can be detected.\n\n*****ESP32 plaforms must include ArduinoJson.h before ArduinoYaml.h or bindings will be disabled!******\n\n```cpp\n#include \u003cArduinoJson.h\u003e\n#include \u003cArduinoYaml.h\u003e\n```\n\nEnabling support will expose the following functions:\n\n```cpp\n// ArduinoJSON object to YAML string\nsize_t serializeYml( JsonVariant src_obj, String \u0026dest_string );\n// ArduinoJSON object to YAML stream\nsize_t serializeYml( JsonVariant src_obj, Stream \u0026dest_stream );\n// Deserialize YAML string to ArduinoJSON object\nDeserializationError deserializeYml( JsonObject \u0026dest_obj, const char* src_yaml_str );\n// Deserialize YAML stream to ArduinoJSON object\nDeserializationError deserializeYml( JsonObject \u0026dest_obj, Stream \u0026src_stream );\n// Deserialize YAML stream to ArduinoJSON document\nDeserializationError deserializeYml( JsonDocument \u0026dest_doc, Stream \u0026src_stream );\n// Deserialize YAML string to ArduinoJSON document\nDeserializationError deserializeYml( JsonDocument \u0026dest_doc, const char *src_yaml_str) ;\n\n```\n\n----------------------------\n\n## cJSON bindings\n\ncJSON support is implicitely enabled on most platforms, and will use the bundled cJSON version unless ESP32 platform is detected.\nESP32 will use the built-in cJSON version from esp-idf instead of the YAMLDuino bundled version.\n\n\n⚠️ Both versions of cJSON have a memory leak with floats, the leak happens only once though, and\nmay be avoided by quoting the float, which won't affect yaml output.\n\n\nEnabling support will expose the following functions:\n\n```cpp\n\n// cJSON object to YAML string\nsize_t serializeYml( cJSON* src_obj, String \u0026dest_string );\n// cJSON object to YAML stream\nsize_t serializeYml( cJSON* src_obj, Stream \u0026dest_stream );\n// YAML string to cJSON object\nint deserializeYml( cJSON* dest_obj, const char* src_yaml_str );\n// YAML stream to cJSON object\nint deserializeYml( cJSON* dest_obj, Stream \u0026src_stream );\n// YAML document to cJSON object\nint deserializeYml( cJSON** dest_obj, yaml_document_t* src_document );\n\n```\n\n----------------------------\n\n## String/Stream helper\n\nAlthough `const char*` is an acceptable source type for conversion, using `Stream` is recommended as it is more memory efficient.\n\nThe `StringStream` class is provided with this library as a helper.\n\n```cpp\n\nString my_json = \"{\\\"blah\\\":true}\";\nStringStream json_input_stream(my_json);\n\nString my_output;\nStringStream output_stream(my_output);\n\n```\n\nThe `StringStream` bundled class is based on Arduino `String` and can easily be replaced by any class inheriting from `Stream`.\n\n```cpp\nclass StringStream : public Stream\n{\npublic:\n  StringStream(String \u0026s) : str(s), pos(0) {}\n  virtual ~StringStream() {};\n  virtual int available() { return str.length() - pos; }\n  virtual int read() { return pos\u003cstr.length() ? str[pos++] : -1; }\n  virtual int peek() { return pos\u003cstr.length() ? str[pos] : -1; }\n  virtual size_t write(uint8_t c) { str += (char)c; return 1; }\n  virtual void flush() {}\nprivate:\n  String \u0026str;\n  unsigned int pos;\n};\n```\n\nSee [ArduinoStreamUtils](https://github.com/bblanchon/ArduinoStreamUtils) for other types of streams (i.e. buffered).\n\n\n----------------------------\n\n\n## Output decorators\n\n\nJSON and YAML indentation levels can be customized:\n\n\n```cpp\nvoid YAML::setYAMLIndent( int spaces_per_indent=2 ); // min=2, max=16\nvoid YAML::setJSONIndent( const char* spaces_or_tabs=\"\\t\", int folding_depth=4 );\n\n```\n\n\nSet custom JSON indentation and folding depth:\n\n```cpp\n// this set two spaces per indentation level, unfolds up to 8 nesting levels\nYAML::setJSONIndent(\"  \", 8 ); // lame fact: folds on objects, not on arrays\n\n```\n\n\nSet custom YAML indentation (minimum=2, max=16):\n\n```cpp\n// annoy your friends with 3 spaces indentation, totally valid in YAML\nYAML::setYAMLIndent( 3 );\n\n```\n\n\n----------------------------\n\n## YAML gettext Module\n\nThe gettext module is a member of YAMLNode object.\n\n```cpp\nclass YAMLNode\n{\n  // (...)\npublic:\n  const char* gettext( const char* path, char delimiter=':' );\n  // YAMLNode objects also bring few interesting methods to scope:\n  const char* scalar();\n  size_t size();\n  bool isScalar();\n  bool isSequence();\n  bool isMap();\n  bool isNull();\n  // (...)\n}\n```\n\n#### Usage (persistent)\n\nLoad from string:\n```cpp\nYAMLNode yamlnode = YAMLNode::loadString( yaml_or_json_string );\n```\n\nLoad from stream:\n```cpp\nYAMLNode yamlnode = YAMLNode::loadStream( yaml_or_json_stream );\n```\n\n\nAccess a value:\n```cpp\nconst char* text = yamlnode.gettext( \"path:to:property:name\" );\n```\n\n#### Usage (non persistent)\n\nYAMLNode supports chaining:\n\n```cpp\n// load yaml and extract value from 'stuff'\nYAMLNode::loadString(\"blah:\\n  stuff:\\n    true\\n\").gettext(\"blah:stuff\");\n// load json and extract value from 'stuff'\nYAMLNode::loadString(\"{\\\"blah\\\":{\\\"stuff\\\":\\\"true\\\"}}\").gettext(\"blah:stuff\");\n```\n\n\n## I18N/L10N with gettext Module\n\nNote: i18n Support is disabled with WIO Terminal (platform needs a proper `fs::FS` filesystem implementation).\nWIO Terminal can still use the native `YAMLNode::gettext()` though.\n\n\n#### Usage\n\n* Include ArduinoJson and a `fs::FS` filesystem first\n* Create an i18n instance and assign the filesystem `i18n_t i18n( \u0026LittleFS );`.\n* Load `en-GB` locale with `i18n.setLocale(\"en-GB\")`.\n* Use `i18n.gettext()` to access localized strings.\n\n\n#### Example\n\nYAML Sample `/lang/en-GB.yml` stored in LittleFS:\n\n```yml\nen-GB:\n  hello: world\n  blah:\n    my_array:\n    - first\n    - second\n    - third\n\n```\n\nLoad the language file and access translations:\n\n\n```cpp\n\n#include \u003cLittleFS.h\u003e      // Mandatory filestem (can be SPIFFS, SD, SD_MMC, LittleFS)\n#include \u003cYAMLDuino.h\u003e     // Load the library\n\n\ni18n_t i18n( \u0026LittleFS ); // Create an i18n instance attached to filesystem\n\nvoid setup()\n{\n  Serial.begin(115200);\n  LittleFS.begin();\n\n  // i18n.setFS( \u0026SD ); // change filesystem to SD\n  i18n.setLocale(\"en-GB\"); // This will look for \"en-GB.yml\" language file in \"/lang/\" folder and set \"en-GB\" as locale\n  // i18n.setLocale(\"/lang/en-GB.yml\"); // This will load \"/lang/en-GB.yml\" language file and set \"en-GB\" as locale\n  // i18n.setLocale(\"en-GB\", \"/non-locale/file.yml\"); // This will set \"en-GB\" as locale and load arbitrary \"/non-locale/file.yml\" language file\n\n  Serial.println( i18n.gettext(\"hello\" ) ); // prints \"world\"\n  Serial.println( i18n.gettext(\"blah:my_array:2\" ) ); // prints \"third\"\n}\n\n\nvoid loop()\n{\n\n  delay(1000);\n}\n```\n\n\n----------------------------\n\n\n\n## Debug\n\n\nThe debug level can be changed at runtime:\n\n\n```cpp\nvoid YAML::setLogLevel( LogLevel_t level );\n```\n\nSet library debug level:\n\n```cpp\n//\n// Accepted values:\n//   LogLevelNone    : No logging\n//   LogLevelError   : Errors\n//   LogLevelWarning : Errors+Warnings\n//   LogLevelInfo    : Errors+Warnings+Info\n//   LogLevelDebug   : Errors+Warnings+Info+Debug\n//   LogLevelVerbose : Errors+Warnings+Info+Debug+Verbose\nYAML::setLogLevel( YAML::LogLevelDebug );\n```\n\n----------------------------\n\n\n## Support the Project\n\nThere are a few things you can do to support the project:\n\n  - Star 🌟 this [repository](https://github.com/tobozo/YAMLDuino) and/or [follow me](https://github.com/tobozo/) on GitHub\n  - Share and upvote on sites like Twitter, Reddit, and Hacker News\n  - [Report](https://github.com/tobozo/YAMLDuino/issues) any bugs, glitches, or errors that you find\n\n\nThese things motivate me to to keep sharing what I build, and they provide\nvalidation that my work is appreciated! They also help me improve the\nproject. Thanks in advance!\n\n\n----------------------------\n\n## Credits and special thanks to:\n\n  - [@yaml](https://github.com/yaml)\n  - [@DaveGamble](https://github.com/DaveGamble)\n  - [@bblanchon](https://github.com/bblanchon)\n  - [@vikman90](https://github.com/vikman90/yaml2json)\n  - [@Visse](https://github.com/Visse/libyaml-cpp)\n\n\n\n## Additional resources:\n\n  - ArduinoJson : https://github.com/bblanchon/ArduinoJson\n  - ArduinoStreamUtils : https://github.com/bblanchon/ArduinoStreamUtils\n  - cJSON : https://github.com/DaveGamble/cJSON\n  - libyaml : https://github.com/yaml/libyaml\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobozo%2Fyamlduino","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftobozo%2Fyamlduino","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobozo%2Fyamlduino/lists"}