Merge pull request #8 from tobozo/1.2.7

1.2.7

Author: tobozo

License

@@ -1,5 +1,5 @@
-
 ESP32-yaml
+-------------------------------------------------------------------------------
 Project Page: https://github.com/tobozo/esp32-yaml
 Copyright 2022 tobozo http://github.com/tobozo
 
@@ -25,8 +25,13 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 OTHER DEALINGS IN THE SOFTWARE.
 
 
+-------------------------------------------------------------------------------
+ESP32-yaml is bundled with libyaml and cJSON
+-------------------------------------------------------------------------------
+
 
 libyaml
+-------------------------------------------------------------------------------
 Copyright (c) 2017-2020 Ingy döt Net
 Copyright (c) 2006-2016 Kirill Simonov
 
@@ -47,3 +52,28 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+
+
+cJSON
+-------------------------------------------------------------------------------
+Copyright (c) 2009-2017 Dave Gamble and cJSON contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

ReadMe.md

@@ -2,51 +2,58 @@
 
 This arduino library is based on [libyaml](https://github.com/yaml/libyaml).
 
-It provides several ways to serialize/deserialize YAML<=>JSON using cJSON or ArduinoJson objects.
+It provides several ways to convert YAML<=>JSON using libyaml, cJSON or ArduinoJson objects.
 
 Supported platforms (some untested):
 
-- esp32
-- esp8266
-- samd
-- rp2040
+- ESP32
+- RP2040
+- ESP8266
+- SAMD
+
 
 
 ### Usage
 
-#### cJSON
+```cpp
+#include <ArduinoYaml.h>
+
+```
+
+or
+
+```cpp
+#include <YAMLDuino.h>
+
+```
+
+
+
+
+#### pure libyaml
+
+YAML is a superset of JSON, so native conversion from JSON is possible without any additional JSON library.
 
 ```cpp
-#include <cJSON.h> // note: cJSON is built-in with esp32
 #include <ArduinoYaml.h>
 
-  // cJSON object to YAML string
-  size_t serializeYml( cJSON* src_obj, String &dest_string );
-  // cJSON object to YAML stream
-  size_t serializeYml( cJSON* src_obj, Stream &dest_stream );
-  // JSON stream to cJSON object to YAML stream, disabled on some architectures
+  // JSON stream to YAML stream
   size_t serializeYml( Stream &json_src_stream, Stream &yml_dest_stream );
 
-  // YAML string to cJSON object
-  int deserializeYml( cJSON* dest_obj, const char* src_yaml_str );
-  // YAML stream to cJSON object
-  int deserializeYml( cJSON* dest_obj, Stream &src_stream );
 ```
 
+
 #### ArduinoJson
 
 
 ```cpp
-
-#include <ArduinoJson.h>
+#include <ArduinoJson.h> // include this first or functions will be disabled
 #include <ArduinoYaml.h>
 
   // ArduinoJSON object to YAML string
   size_t serializeYml( JsonVariant src_obj, String &dest_string );
   // ArduinoJSON object to YAML stream
   size_t serializeYml( JsonVariant src_obj, Stream &dest_stream );
-  // JSON stream to JsonObject to YAML stream, disabled on some architectures
-  size_t serializeYml( Stream &json_src_stream, Stream &yml_dest_stream );
   // Deserialize YAML string to ArduinoJSON object
   DeserializationError deserializeYml( JsonObject &dest_obj, const char* src_yaml_str );
   // Deserialize YAML stream to ArduinoJSON object
@@ -60,15 +67,40 @@ Supported platforms (some untested):
 
 
 
+#### cJSON
+
+⚠️ cJSON has a memory leak with floats, the leak happens only once though, and may be
+avoided by quoting the float, which won't affect yaml output.
+
+
+```cpp
+// #include <cJSON.h> // no need to include, cJSON is built-in with esp32 and also bundled with ArduinoYaml
+#include <ArduinoYaml.h>
+
+  // cJSON object to YAML string
+  size_t serializeYml( cJSON* src_obj, String &dest_string );
+  // cJSON object to YAML stream
+  size_t serializeYml( cJSON* src_obj, Stream &dest_stream );
+  // YAML string to cJSON object
+  int deserializeYml( cJSON* dest_obj, const char* src_yaml_str );
+  // YAML stream to cJSON object
+  int deserializeYml( cJSON* dest_obj, Stream &src_stream );
+
+```
+
+
+
+
+
 ### Credits and special thanks to:
 
-  - [libyaml](https://github.com/yaml/libyaml)
-  - [yaml2json](https://github.com/vikman90/yaml2json)
-  - [@bblanchon](https://github.com/bblanchon)
+  - [@yaml](https://github.com/yaml)
   - [@DaveGamble](https://github.com/DaveGamble)
-  - [@espressif](https://github.com/espressif)
+  - [@bblanchon](https://github.com/bblanchon)
+  - [@vikman90](https://github.com/vikman90/yaml2json)
 
 ### Additional resources:
 
   - ArduinoJson : https://github.com/bblanchon/ArduinoJson
   - cJSON : https://github.com/DaveGamble/cJSON
+  - libyaml : https://github.com/yaml/libyaml