view release on metacpan or  search on metacpan

lib/JSON/Streaming/Writer.pm  view on Meta::CPAN

        else {
            $_[0]->_print("\n");
            $_[0]->_make_indent();
        }
    }
}

sub _make_end_block {
    return unless $_[0]->pretty_output;

    if ($_[0]->_made_value) {
        $_[0]->_print("\n");
        $_[0]->_make_indent();
    }
}

sub _make_indent {
    $_[0]->_print("    " x $_[0]->{indent_level});
}

sub _indent {
    $_[0]->{indent_level}++;
}

sub _outdent {
    $_[0]->{indent_level}--;
}

my %esc = (
    "\n" => '\n',
    "\r" => '\r',
    "\t" => '\t',
    "\f" => '\f',
    "\b" => '\b',
    "\"" => '\"',
    "\\" => '\\\\',
    "\'" => '\\\'',
);
sub _json_string {
    my ($class, $value) = @_;

    $value =~ s/([\x22\x5c\n\r\t\f\b])/$esc{$1}/eg;
    $value =~ s/\//\\\//g;
    $value =~ s/([\x00-\x08\x0b\x0e-\x1f])/'\\u00' . unpack('H2', $1)/eg;

    return '"'.$value.'"';
}

sub DESTROY {
    my ($self) = @_;

    if ($self->_state != ROOT_STATE && ! $self->{intentionally_ending_early}) {
        warn "JSON::Streaming::Writer object was destroyed with incomplete output";
    }
}

1;

=head1 NAME

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

=head1 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();

=head1 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.

=head1 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 C<start_> and C<end_>
methods wrap a multi-step construct and must be used symmetrically, while
methods with names starting with C<add_> stand alone and generate output
in a single step.

The raw API methods are described below

=head2 start_object, end_object

These methods delimit a JSON object. C<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.

=head2 start_array, end_array

These methods delimit a JSON array. C<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.

=head2 start_property($name), end_property

These methods delimit a property or member of a JSON object.
C<start_property> may be called only when in the context of an
object. The C<$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
C<start_property> and C<end_property> calls.

=head2 add_string($value)

Produces a JSON string with the given value.

=head2 add_number($value)

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

=head2 add_boolean($value)

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

=head2 add_null

Produces a JSON C<null>.

=head1 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.

=head2 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 C<undef> representing
a JSON C<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.

=head2 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 C<add_value>. This can only be used
inside the context of an object, and is really just a wrapper around a C<start_property>,
C<add_value>, C<end_property> sequence for convenience.

=head1 OPTIONS

=head2 Pretty Output

This library can optionally pretty-print the JSON string it produces. To enable this,
call the C<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.

=head1 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.

=head1 LICENSE

Copyright 2009 Martin Atkins <mart@degeneration.co.uk>.

This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.