NAME
    Redis::Parser::XS - unified redis protocol parser

SYNOPSIS
        use Redis::Parser::XS;
    
        my @output;
    
        my $buf = "+OK" . 
                  "\x0d\x0a";
    
        my $len = parse_redis $buf, \@output;
    
        if (!defined $len) {
    
            warn "incorrect protocol message\n";
        
        } elsif ($len == 0) {
    
            warn "not enough data to parse, " . 
                 "read some more and try again\n";
        
            if (length ($buf) > 16384) {  # 16k and still incomplete ?
                                          # better to just bail
                ...
            }
        } else { # $len > 0
    
            warn "parsed $len bytes\n";
        
            # got status reply:
            #    @output = ( [ '+', 'OK' ] )
        
            $buf = substr $buf, $len; 
        }

DESCRIPTION
    Easy way to parse unified redis protocol.

    Protocol specification <http://redis.io/topics/protocol>

FUNCTIONS
    $len = parse_redis $buf, \@output;
        Parses redis protocol messages from $buf and pushes each message
        into @output. Returns "undef" on error or total length of parsed
        data. Return value of 0 returned as a "0 but true" string and
        indicates, that there isn't enough data to parse even one message.

        Parsed messages added to the @output in the following format:

            @output = (
        
                ['+', 'OK'                 ],  # +OK     CRLF
                                               # 
                ['-', 'ERROR'              ],  # -ERROR  CRLF
                                               #
                [':', '123'                ],  # :123    CRLF
                                               # 
                ['$', 'foo'                ],  # $3      CRLF
                                               # foo     CRLF
                                               #
                ['$', undef                ],  # $-1     CRLF
                                               # 
                ['$', ''                   ],  # $0      CRLF
                                               #         CRLF
                                               #
                ['*', []                   ],  # *0      CRLF
                                               #
                ['*', undef                ],  # *-1     CRLF
                                               #
                ['*', [ 'foo',                 # *2      CRLF 
                        ['+', 'OK'],           # $3      CRLF
                         ...         ]         # foo     CRLF
                                               # +OK     CRLF
                                               # ...
                                               #
                ['*', ['foo', undef ]      ],  # *2      CRLF 
                                               # $3      CRLF 
                                               # foo     CRLF 
                                               # $-1     CRLF
            )

EXPORT
    Exports only one function:

        parse_redis

BENCHMARK
    Here is a sample benchmark against Protocol::Redis::XS, generated by
    eg/bench.pl:

        Status reply
                                  Rate
        Protocol::Redis::XS   281098/s
        Redis::Parser::XS     367589/s
    
        Multibulk reply
                                  Rate
        Protocol::Redis::XS   127999/s
        Redis::Parser::XS     270490/s

SEE ALSO
    Protocol::Redis::XS

AUTHOR
    Alexandr Gomoliako <zzz@zzz.org.ua>

LICENSE
    Copyright 2011 Alexandr Gomoliako. All rights reserved.

    This module is free software. It may be used, redistributed and/or
    modified under the same terms as Perl itself.