Events system

The events interface allows different parts of the library to communicate and to efficiently convert between data representations. It consists of two concepts event_consumer and event_producer.

Event consumers

The event_consumer concepts is modeled after the SAX-interface for XML. The most simple consumer which ignores all events would look as follows:

struct discard_consumer
{
    void integer(std::int64_t value) { }
    void string(std::string_view value) { }
    void list_begin() {}
    void list_begin(std::size_t size) {}
    void list_end() {}
    void list_end(std::size_t size) {}
    void list_item() {}
    void dict_begin() {}
    void dict_begin(std::size_t size) {}
    void dict_end() {}
    void dict_end(std::size_t size) {}
    void dict_key() {}
    void dict_value() {}
};

Every bencode data structure can be described by successive calls to this interface. Following bencode data structure (formatted as JSON) would generate these calls.

{
  "foo": ["a", "b"],
  "bar": {"one": 1, "two": 2}
}

dict_begin(2)
    string("foo")
    dict_key()
    list_begin(2)
        begin_string("a")
        list_item()
        string("b")
        list_item()
    list_end()
    dict_value()
    string("bar")
    dict_key()
    dict_begin(2)
        string("one")
        dict_key()
        integer(1)
        dict_value()
        string("two")
        dict_key()
        integer(2)
        dict_value()
    dict_end()
    dict_value()
dict_end()

Note that list_item(), dict_key() and dict_value() are called after describing the value.

Event producers

The event_producer concept is defined as any object that can generate calls to a class satisfying the event_consumer concept through the connect() method.

Connecting consumer and producers

event_producers are connected to event_consumers with the connect function. Connecting a producer and consumer will generate calls from the producer to the consumers interface.

connect(EC& consumer, U&& producer)

Available consumers

bencode::events::debug_to will print events to an output stream or output iterator. It is defined in <bencode/events/debug_to.hpp>.

bencode::events::encode_to will convert events into bencode. This consumer is used by the encode and encode_to convenience functions. It is defined in <bencode/events/encode_to.hpp>.

bencode::events::format_json_to will convert events into json; It is defined in <bencode/events/format_json_to.hpp>.