annotate ext/json11/README.md @ 186:52322dde68ea

Fix erroneous logic for handling step and block size in prior commit

The earlier change had a logical misconception. If PluginStub is
receiving the correct step and block size back from the configure call,
the plugin on the server side must have already been successfully
initialised, as the step and block size are only returned in a
successful configure response. This means the test for a failed
initialise and redo with the correct parameters must be done on the
server side (in LoaderRequests) not the client. The client has a more
complicated job, which is to notice that a *successful* configure had
returned different framing parameters from those passed to the
initialise call, and to pretend that it had actually failed until the
host called again with the correct parameters. We definitely need tests
for this!

json11
------

json11 is a tiny JSON library for C++11, providing JSON parsing and serialization.

The core object provided by the library is json11::Json. A Json object represents any JSON
value: null, bool, number (int or double), string (std::string), array (std::vector), or
object (std::map).

Json objects act like values. They can be assigned, copied, moved, compared for equality or
order, and so on. There are also helper methods Json::dump, to serialize a Json to a string, and
Json::parse (static) to parse a std::string as a Json object.

It's easy to make a JSON object with C++11's new initializer syntax:

    Json my_json = Json::object {
        { "key1", "value1" },
        { "key2", false },
        { "key3", Json::array { 1, 2, 3 } },
    };
    std::string json_str = my_json.dump();

There are also implicit constructors that allow standard and user-defined types to be
automatically converted to JSON. For example:

    class Point {
    public:
        int x;
        int y;
        Point (int x, int y) : x(x), y(y) {}
        Json to_json() const { return Json::array { x, y }; }
    };

    std::vector<Point> points = { { 1, 2 }, { 10, 20 }, { 100, 200 } };
    std::string points_json = Json(points).dump();

JSON values can have their values queried and inspected:

    Json json = Json::array { Json::object { { "k", "v" } } };
    std::string str = json[0]["k"].string_value();

More documentation is still to come. For now, see json11.hpp.