NAME

JSON::Streaming::Writer - Generate JSON output in a streaming manner

SYNOPSIS

    my $jsonw = JSON::Streaming::Writer->for_stream($fh)
    $jsonw->start_object();
    $jsonw->add_simple_property("someName" => "someValue");
    $jsonw->add_simple_property("someNumber" => 5);
    $jsonw->start_property("someObject");
    $jsonw->start_object();
    $jsonw->add_simple_property("someOtherName" => "someOtherValue");
    $jsonw->add_simple_property("someOtherNumber" => 6);
    $jsonw->end_object();
    $jsonw->end_property();
    $jsonw->start_property("someArray");
    $jsonw->start_array();
    $jsonw->add_simple_item("anotherStringValue");
    $jsonw->add_simple_item(10);
    $jsonw->start_object();
    # No items; this object is empty
    $jsonw->end_object();
    $jsonw->end_array();

DESCRIPTION

Most JSON libraries work in terms of in-memory data structures. In Perl, JSON serializers often expect to be provided with a HASH or ARRAY ref containing all of the data you want to serialize.

This library allows you to generate syntactically-correct JSON without first assembling your complete data structure in memory. This allows large structures to be returned without requiring those structures to be memory-resident, and also allows parts of the output to be made available to a streaming-capable JSON parser while the rest of the output is being generated, which may improve performance of JSON-based network protocols.

RAW API

The raw API allows the caller precise control over the generated data structure by providing explicit methods for each fundamental JSON construct.

As a general rule, methods with names starting with start_ and end_ methods wrap a multi-step construct and must be used symmetrically, while methods with names starting with add_ stand alone and generate output in a single step.

The raw API methods are described below

start_object, end_object

These methods delimit a JSON object. start_object can be called as the first method call on a writer object to produce a top-level object, or it can be called in any state where a value is expected to produce a nested object.

JSON objects contain properties, so only property-related methods may be used while in the context of an object.

start_array, end_array

These methods delimit a JSON array. start_array can be called as the first method call on a writer object to produce a top-level array, or it can be called in any state where a value is expected to produce a nested array.

JSON arrays contain properties, so only value-producing methods may be used while in the context of an array.

start_property($name), end_property

These methods delimit a property or member of a JSON object. start_property may be called only when in the context of an object. The $name parameter, a string, gives the name that the generated property will have.

Only value-producing methods may be used while in the context of a property.

Since a property can contain only one value, only a single value-producing method may be called between a pair of start_property and end_property calls.

add_string($value)

Produces a JSON string with the given value.

add_number($value)

Produces a JSON number whose value is Perl's numeric interpretation of the given value.

add_boolean($value)

Produces a JSON boolean whose value is Perl's boolean interpretation of the given value.

add_null

Produces a JSON null.

DWIM API

The DWIM API allows you to provide normal Perl data structures and have the library figure out a sensible JSON representation for them. You can mix use of the raw and DWIM APIs to allow you to exercise fine control where required but use a simpler API for normal cases.

add_value($value)

Produces a JSON value representing the given Perl value. This library can handle Perl strings, integers (i.e. scalars that have most recently been used as numbers), references to the values 0 and 1 representing booleans and undef representing a JSON null. It can also accept ARRAY and HASH refs that contain such values and produce JSON array and object values recursively, much like a non-streaming JSON producer library would do.

This method is a wrapper around the corresponding raw API calls, so the error messages it generates will often refer to the underlying raw API.

add_property($name, $value)

Produces a property inside a JSON object whose value is derived from the provided value using the same mappings as used by add_value. This can only be used inside the context of an object, and is really just a wrapper around a start_property, add_value, end_property sequence for convenience.

OPTIONS

Pretty Output

This library can optionally pretty-print the JSON string it produces. To enable this, call the pretty_output method with a true value as its first argument.

You can enable and disable pretty-printing during output, though if you do the results are likely to be sub-optimal as the additional whitespace may not be generated where you'd expect. In particular, where the whitespace is generated may change in future versions.

INTERNALS

Internally this library maintains a simple state stack that allows it to remember where it is without needing to remember the data it has already generated.

The state stack means that it will use more memory for deeper data structures.

cpanm JSON::Streaming::Writer

perl -MCPAN -e shell
install JSON::Streaming::Writer