NAME

       Statistics::R::IO::QapEncoding - Functions for parsing Rserve packets

VERSION

       version 1.0002

SYNOPSIS

           use Statistics::R::IO::QapEncoding qw( decode );

           # Assume $data comes from an Rserve response body
           my ($rexp, $state) = @{ decode($data) }
               or die "couldn't parse";

           # If we're reading a QAP response, there should be no data left
           # unparsed
           die 'Unread data remaining' unless $state->eof;

           # the result of the unserialization is a REXP
           say $rexp;

           # REXPs can be converted to the closest native Perl data type
           print $rexp->to_pl;

DESCRIPTION

       This module implements the actual reading of serialized R objects encoded with Rserve's
       QAP protocol and their conversion to a Statistics::R::REXP. You are not expected to use it
       directly, as it's normally wrapped by "evalRserve" in Statistics::R::IO and "eval" in
       Statistics::R::IO::Rserve.

SUBROUTINES

       decode $data
           Constructs a Statistics::R::REXP object from its serialization in $data. Returns a
           pair of the object and the Statistics::R::IO::ParserState at the end of serialization.

       decode_sexp, decode_int
           Parsers for Rserve's "DT_SEXP" and "DT_INT" data types, respectively.

       dt_sexp_data
           Parses the body of an RServe "DT_SEXP" object by parsing its header ("XT_" type and
           length) and content (done by sequencing "unpack_sexp_info" and "sexp_data".

       unpack_sexp_info
           Parser for the header (consisting of the "XT_*" type, flags, and object length) of a
           serialized SEXP. Returns a hash with keys "object_type", "has_attributes", and
           "length", each corresponding to the field in R serialization described in QAP1
           protocol description <http://www.rforge.net/Rserve/dev.html>.

       sexp_data $obj_info
           Parser for a QAP-serialized R object, using the object type stored in $obj_info hash's
           "object_type" key to use the correct parser for the particular type.

       intsxp, langsxp, lglsxp, listsxp, rawsxp, dblsxp, cplxsxp, strsxp, symsxp, vecsxp, expsxp,
       closxp, s4sxp
           Parsers for the corresponding R SEXP-types.

       nosxp
           Parser for the Rserve's "XT_UNKNOWN" type, encoding an R SEXP-type that does not have
           a corresponding representation in QAP.

       maybe_attributes $object_info
           Convenience parser for SEXP attributes, which are serialized as a tagged pairlist
           "XT_LIST_TAG" followed by a SEXP for the object value. Attributes are stored only if
           $object_info indicates their presence. Returns a pair of $object_info and a hash
           reference to the attributes, as returned by "tagged_pairlist_to_attribute_hash".

       tagged_pairlist
           Parses a pairlist (optionally tagged) and returns an array where each element is a
           hash containing keys "value" (the REXP of the pairlist element) and, optionally,
           "tag".

       tagged_pairlist_to_rexp_hash
           Converts a pairlist to a REXP hash whose keys are the pairlist's element tags and
           values the pairlist elements themselves.

       tagged_pairlist_to_attribute_hash
           Converts object attributes, which are serialized as a pairlist with attribute name in
           the element's tag, to a hash that can be used as the "attributes" argument to
           Statistics::R::REXP constructors.

           Some attributes are serialized using a compact encoding (for instance, when a table's
           row names are just integers 1:nrows), and this function will decode them to a complete
           REXP.

BUGS AND LIMITATIONS

       There are no known bugs in this module. Please see Statistics::R::IO for bug reporting.

SUPPORT

       See Statistics::R::IO for support and contact information.

AUTHOR

       Davor Cubranic <cubranic@stat.ubc.ca>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2017 by University of British Columbia.

       This is free software, licensed under:

         The GNU General Public License, Version 3, June 2007