json.h File Reference

Detailed Description

FastLED's Elegant JSON Library: fl::Json

The fl::Json library provides a lightweight, type-safe, and highly ergonomic interface for both parsing and generating JSON data within the FastLED ecosystem.

Key Features & Design Principles:

• Fluid Chaining: Effortlessly navigate nested JSON structures using json["key"]["nested_key"] or json["array_key"][index].
• Default Values (operator|): The cornerstone of robust parsing. Safely extract values with a fallback, preventing crashes from missing keys or type mismatches: int value = json["path"]["to"]["key"] | 123;
• Type Safety: Methods return fl::optional<T> for explicit handling of potential absence or type errors, ensuring predictable behavior.
• Unified API: A consistent and intuitive interface for both reading and writing JSON data.
• Explicit Creation: Clearly define JSON objects and arrays using fl::Json::object() and fl::Json::array().

Parsing JSON Data - The Clean Way:

Parse a JSON string and extract values with graceful defaults.

#include "fl/json.h"
#include "fl/warn.h" // For FL_WARN
 
const char* jsonStr = R"({
  "config": {
    "brightness": 128,
    "enabled": true,
    "name": "my_device"
  },
  "status": "active"
})";
 
fl::Json jsonDoc = fl::Json::parse(jsonStr);
 
// Accessing an integer with a default value
int brightness = jsonDoc["config"]["brightness"] | 255; // Result: 128
FL_WARN("Brightness: " << brightness);
 
// Accessing a boolean with a default value
bool enabled = jsonDoc["config"]["enabled"] | false;    // Result: true
FL_WARN("Enabled: " << enabled);
 
// Accessing a string with a default value
fl::string deviceName = jsonDoc["config"]["name"] | fl::string("unknown"); // Result: "my_device"
FL_WARN("Device Name: " << deviceName);
 
// Accessing a non-existent key with a default value
int nonExistent = jsonDoc["config"]["non_existent_key"] | 0; // Result: 0
FL_WARN("Non-existent: " << nonExistent);

Generating JSON Data - Build with Ease:

Construct complex JSON objects and arrays programmatically.

#include "fl/json.h"
#include "fl/string.h"
#include "fl/vector.h"
#include "fl/warn.h"
 
// Create a root JSON object
fl::Json newJson = fl::Json::object();
 
// Set primitive values
newJson.set("version", 1.0);
newJson.set("isActive", true);
newJson.set("message", "Hello, FastLED!");
 
// Create and set a nested object
fl::Json settings = fl::Json::object();
settings.set("mode", "dynamic");
settings.set("speed", 50);
newJson.set("settings", settings);
 
// Create and set a nested array
fl::Json colors = fl::Json::array();
colors.push_back(fl::Json("red"));
colors.push_back(fl::Json("green"));
colors.push_back(fl::Json("blue"));
newJson.set("colors", colors);
 
// Convert the entire JSON object to a string
fl::string jsonString = newJson.to_string();
FL_WARN("Generated JSON:\n" << jsonString);
// Expected output (formatting may vary):
// {"version":1.0,"isActive":true,"message":"Hello, FastLED!","settings":{"mode":"dynamic","speed":50},"colors":["red","green","blue"]}

Important Considerations:

• Error Handling: While operator| is powerful, for critical parsing steps (e.g., validating the root object), always use has_value() and is_object()/is_array() checks.
• Memory Management: fl::Json leverages fl::shared_ptr internally, simplifying memory management. You typically won't need manual new/delete.
• fl:: Namespace: Adhere to FastLED's convention; always use the fl:: prefix for library components (e.g., fl::Json, fl::string, fl::vector). Avoid std:: equivalents.

HIGH LEVEL: For platforms with a lot of memory, this parsing library (ArduinoJson) will automatically be included. Othweise you'll just get Json -> str encoding (and no parsing). You can check if you haee the full library by detecting if FASTLED_ENABLE_JSON is defined.

It's important to note that ArduinoJson only is used for parsing. We use a custom serializer for output to string. But this is usually easy to do. For help serializing out, look at fl/sstream.h for converting a collection of values to a string.

It's entirely possible that our json string output serializer is NOT 100% correct with respect to complex string encoding (for example an HTML document). If you see bugs, then file an issue at https://github.com/fastled/FastLED/issues

for string parsing, we should be full featured when FASTLED_ENABLE_JSON is defined (automiatic for SKETCH_HAS_LOTS_OF_MEMORY). If there is some string that doesn't correctly parse, use b64 encoding. For example, you might get better luck b64 encoding 1024 elements of small ints then manually deserializing to a fl::vector<u8>. Infact, it's pretty much assured.

That being said...

This api is designed specifically to be fast for input <--> output of arrays of numbers in {u8, i16, float}. If you have a different encodings scheme, for example an array of tuples, then this library will be MUCH MUCH slower than Arduino Json. If you stick to the scheme we have optimized for (flat arrays of numbers and few dictionaries) then this api will be blazing fast. Otherwise? Expect pain: slowdowns and lots of memory consumption.

Why?

ArduinoJson only has a nice interface if you agree to bring in std::-everything. Ever bring in std::sstream? The amount of code that will be pulled for <sstream> will blow your mind. To keep things strict and tiny we have to take ArduinoJson and strip all the optional components out then seal the remaining api in cement and bolt on a nice fluid interface ontop. That's what fl/json.h is.

And the good news is - it works great!! And if it doesn't? File a bug and we'll have it fixed in the next release.

Definition in file json.h.

#include "fl/string.h"
#include "fl/vector.h"
#include "fl/hash_map.h"
#include "fl/variant.h"
#include "fl/optional.h"
#include "fl/unique_ptr.h"
#include "fl/shared_ptr.h"
#include "fl/functional.h"
#include "fl/str.h"
#include "fl/promise.h"
#include "fl/warn.h"
#include "fl/sketch_macros.h"

Include dependency graph for json.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	fl::DefaultValueVisitor< T >
struct	fl::FloatConversionVisitor< FloatType >
struct	fl::FloatConversionVisitor< double >
struct	fl::IntConversionVisitor< IntType >
struct	fl::IntConversionVisitor< int64_t >
class	fl::Json
struct	fl::JsonValue
class	fl::JsonValue::array_iterator< T >
class	fl::JsonValue::const_iterator
struct	fl::JsonValue::const_iterator::KeyValue
struct	fl::JsonValue::IsArrayVisitor
class	fl::JsonValue::iterator
struct	fl::JsonValue::iterator::KeyValue
struct	fl::ParseResult< T >
struct	fl::StringConversionVisitor

Namespaces
namespace	fl
	IMPORTANT!

Macros
#define	FASTLED_ENABLE_JSON   SKETCH_HAS_LOTS_OF_MEMORY

Typedefs
using	fl::JsonArray = fl::vector<fl::shared_ptr<JsonValue>>
using	fl::JsonObject = fl::HashMap<fl::string, fl::shared_ptr<JsonValue>>

Functions
JsonObject &	fl::get_empty_json_object ()
FL_DISABLE_WARNING_POP JsonValue &	fl::get_null_value ()