view release on metacpan or  search on metacpan

lib/JSON/SL.pm  view on Meta::CPAN

    use Data::Dumper;
    
    my $txt = <<'EOT';
    {
        "some" : {
            "partial" : 42.42
        },
        "other" : {
            "partial" : "a string"
        },
        "complex" : {
            "partial": {
                "a key" : "a value"
            }
        },
        "more" : {
            "more" : "stuff"
    EOT
    
    my $json = JSON::SL->new();
    my $jpath = "/^/partial";
    $json->set_jsonpointer( [$jpath] );
    my @results = $json->feed($txt);
    
    foreach my $result (@results) {
        printf("== Got result (path %s) ==\n", $result->{Path});
        printf("Query was %s\n", $result->{JSONPointer});
        my $value = $result->{Value};
        if (!ref $value) {
            printf("Got scalar value %s\n", $value);
        } else {
            printf("Got reference:\n");
            print Dumper($value);
        }
        print "\n";
    }
    
Produces:

    == Got result (path /some/partial) ==
    Query was /^/partial
    Got scalar value 42.42
    
    == Got result (path /other/partial) ==
    Query was /^/partial
    Got scalar value a string
    
    == Got result (path /complex/partial) ==
    Query was /^/partial
    Got reference:
    $VAR1 = {
              'a key' => 'a value'
            };

    
=head2 DESCRIPTION

JSON::SL was designed from the ground up to be easily accessible and
searchable for partially received streamining content.

It uses an embedded C library (C<jsonsl>) to do the streaming and most
of the dirty work.

JSON::SL allows you to use the
L<JSONPointer|http://tools.ietf.org/html/draft-pbryan-zyp-json-pointer-02>
URI/path syntax to tell it about certain objects and elements which are of
interest to you. JSON::SL will then incrementally parse the input stream,
returning those selected objects to you as soon as they arrive.

In addition, the objects are returned with extra context information, which is
itself another JSONPointer path specifying the path from the root of the JSON
stream until the current object.

Since I hate SAX's callback interface, and since almost all the boilerplate
for a SAX interface needs to be done for just about every usage case, I have
decided to move over the core work of state stacking and such to the C library
itself. This means minimal boilerplate and ultra fast performance on your part.

=head2 GENERIC METHODS

=head3 new()

=head3 new($max_levels)

Creates a new C<JSON::SL> object

If C<$max_levels> is provided, then it is taken as the maximum recursion depth
the parser will be able to descend. This can only be set during construction time
as it affects the amount of memory allocated for the internal structures.

The amount of memory allocated for each structure is around 64 bytes on 64-bit
(i.e. C<sizeof (char*) == 8>) systems
and around 48 bytes on 32 bit (i.e. C<sizeof (char*) == 4>) systems.

The default is 512, or a total of 32KB allocated

=head3 set_jsonpointer(["/arrayref/of", "/json/paths/^"])

Set the I<JSONPointer> query paths for this object. Note this can only be
done once per the object's lifetime, and only before you have started calling
the L</feed> method.

The JSONPointer notation is quite simple, and follows URI scheme conventions.
Each C</> represents a level of descent into an object, and each path component
represents a hash key or array index (whether something is indeed a key or an
index is derived from the context of the JSON stream itself, in case you were
wondering).

http://tools.ietf.org/html/draft-pbryan-zyp-json-pointer-02 Contains the draft
for the JSONPointer specification.

As an extension to the specification, C<JSON::SL> allows you to use the C<^>
(caret) character as a wildcard. Placing the lone C<^> in any path component
means to match any value in the current level, effectively providing glob-style
semantics.

=head3 feed($input_text)

=head3 incr_parse($input_text)

This is the meat and potatoes of C<JSON::SL>. Call it with C<$input> being a