The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-JSON-Nibble-1.01
River stage zero No dependents
++
/ Text::JSON::Nibble

NAME

Text::JSON::Nibble - Nibble complete JSON objects from buffers

VERSION

Version 1.01

WARNING

This module should be used with caution, it will not handle 'badly formed' json well, its entire purpose was because I was experiencing segfaults with Cpanel::XS's decode_prefix when dealing with a streaming socket buffer.

DESCRIPTION

This module is a 'character' crawling JSON extractor for plain TEXT, usable in both a 'streaming' or 'block' method, for when you need something that is not XS.

It is particularly handy for when you want to deal with JSON without decoding it.

SYNOPSIS

        use Text::JSON::Nibble;

        my $json = '{"lol":{"a":[1,2,3],"b":"lol"}}';
        my $item = Text::JSON::Nibble->new();

        my @results = @{ $item->digest($json) };

EXAMPLES

Example1 (Basic usage)

        use Text::JSON::Nibble;

        my $json = '{"lol":{"a":[1,2,3],"b":"lol"}}{"lol":{"a":[1,2,3],"b":"lol"}}';
        my $item = Text::JSON::Nibble->new();

        foreach my $jsonBlock ( @{ $item->digest($json) } ) {
                print "Found: $jsonBlock\n";
        }

        # Will display the following:
        # Found: {"lol":{"a":[1,2,3],"b":"lol"}}
        # Found: {"lol":{"a":[1,2,3],"b":"lol"}}

Example2 (Basic usage - mangled JSON)

        use Text::JSON::Nibble;

        my $json = '\cxa4GL<A{"lol":{"a":[1,2,3],"b":"lol"}}He Random Stuf${"lol":{"a":[1,2,3],"b":"lol"}}\cxa4GL<A';
        my $item = Text::JSON::Nibble->new();

        foreach my $jsonBlock ( @{ $item->digest($json) } ) {
                print "Found: $jsonBlock\n";
        }

        # Will display the following:
        # Found: {"lol":{"a":[1,2,3],"b":"lol"}}
        # Found: {"lol":{"a":[1,2,3],"b":"lol"}}

Example3 (Streaming usage for POE and others)

        use Text::JSON::Nibble;
        
        my @jsonStream = qw( {"test":1} {"moreTest":2} {"part ial":3} );
        my $item = Text::JSON::Nibble->new();
        
        $item->process( shift @jsonStream );

        while( $item->stack ) {
                my $jsonBlock = $item->pull;
                print "Found $jsonBlock\n";

                while ( my $newJSON = shift @jsonStream ) {
                        $item->process($newJSON);
                }
        }

Generic callers

new

Generate a new JSON Nibble object

Block functions

digest

Digest the text that is fed in and attempt to return a complete an array of JSON object from it, returns either a blank array or an array of text-encoded-json.

Note you can call and use this at any time, even if you are using streaming functionality.

Streaming functions

process

Load data into the buffer for json extraction, can be called at any point.

This function will return the buffer length remaining after extraction has been attempted.

This function takes 1 optional argument, text to be added to the buffer.

stack

Return the amount of succesfully extracted JSON blocks ready to be pulled.

If no JSON blocks are ready, returns 0.

This function takes no arguments.

pull

Pull an item from the stack, shortening the stack by 1.

This function will return "" if the stack is empty.

This function takes no arguments.

reset

Effectively flushs the objects buffers, giving you a clean object, this can be handy when you want to start processing from another stream.

This function returns nothing.

This function takes no arguments.

AUTHOR

Paul G Webster, <daemon at cpan.org>

BUGS

Please report any bugs or feature requests to bug-text-json-nibble at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Text-JSON-Nibble. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Text::JSON::Nibble

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2017 Paul G Webster.

This program is released under the following license: BSD