JSON-Streaming-Reader

 view release on metacpan or  search on metacpan

META.yml  view on Meta::CPAN

--- #YAML:1.0
name:               JSON-Streaming-Reader
version:            0.06
abstract:           Read JSON strings in a streaming manner
author:
    - Martin Atkins <mart@degeneration.co.uk>
license:            unknown
distribution_type:  module
configure_requires:
    ExtUtils::MakeMaker:  0
build_requires:
    ExtUtils::MakeMaker:  0
requires:
    B:           0

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

=head1 NAME

JSON::Streaming::Reader - Read JSON strings in a streaming manner

=cut

package JSON::Streaming::Reader;

use strict;
use warnings;
use Carp;
use IO::Scalar;
use JSON::Streaming::Reader::EventWrapper;

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

that comes after the corresponding C<end_> token for the current container. The corresponding
C<end_> token is never returned.

The return value of this method call will be a Perl data structure
representing the data that was skipped. This uses the same mappings as other
popular Perl JSON libraries: objects become hashrefs, arrays become arrayrefs,
strings and integers become scalars, boolean values become references to either
1 or 0, and null becomes undef.

This is useful if there is a part of the tree that you would rather handle
via an in-memory data structure like you'd get from a non-streaming JSON parser.
It allows you to mix-and-match streaming parsing and one-shot parsing
within a single data stream.

Note that errors encountered during skip are actually raised via C<die> rather than
via the return value as with C<get_token>.

If you call this when in property state it will return the value of the property
and parsing will continue after the corresponding C<end_property>. In object or
array state it will return the object or array and continue after the corresponding
C<end_object> or C<end_array>.

=head1 EVENT-BASED API

This module has an experimental event-based API which can be used to
do streaming JSON processing in event-driven applications or those
which do non-blocking I/O.

In event-based mode it is the caller's responsibility to obtain data and
when data is available provide it to the reader for processing. When
enough data is available to unambigously represent a complete, atomic token
a callback function is called in a similar fashion to the callback-based API
described above.

The event-based API implementation is currently somewhat hacky and
inefficient. Caution is advised when making use of it in production

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

In most cases this method will be called in response to some event,
such as a notification that a socket stream has been closed.

=head1 TOKEN TYPES

There are two major classes of token types. Bracketing tokens enclose other tokens
and come in pairs, named with C<start_> and C<end_> prefixes. Leaf tokens stand alone
and have C<add_> prefixes.

For convenience the token type names match the method names used in the "raw" API
of L<JSON::Streaming::Writer>, so it is straightforward to implement a streaming JSON
normalizer by feeding the output from this module into the corresponding methods on that module.
However, this module does have an additional special token type 'error' which is used
to indicate tokenizing errors and does not have a corresponding method on the writer.

=head2 start_object, end_object

These token types delimit a JSON object. In a valid JSON stream an object will contain
only properties as direct children, which will result in start_property and end_property tokens.

=head2 start_array, end_array