.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "PGObject::Util::PseudoCSV 3pm" .TH PGObject::Util::PseudoCSV 3pm "2022-12-02" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" PGObject::Util::PseudoCSV \- Tuple/Array parsing and serialization for PGObject .SH "VERSION" .IX Header "VERSION" Version 2 .SH "SYNOPSIS" .IX Header "SYNOPSIS" This is a parser and constructor for PostgreSQL text representations of tuples and arrays. .PP To parse: .PP For a tuple, we'd typically: .PP .Vb 1 \& my @list = pseudocsv_parse($text_representation); .Ve .PP We can then arrange the hash as: .PP .Vb 1 \& my $hashref = pseudocsv_to_hash(\e@list, \e@col_list); .Ve .PP Which we can combine as: .PP .Vb 4 \& my $hashref = pseudocsv_to_hash( \& pseudocsv_parse($text_representation), \& \e@col_list \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" PostgreSQL can represent tuples and arrays in a text format that is almost like \&\s-1CSV.\s0 Unfortunately this format has a number of gotchas which render existing CSV-parsers useless. This module provides basic parsing functions to other programs for db interface purposes. With this module you can both parse pseudocsv representations of tuples and arrays and you can create them from a list. .PP The \s-1API\s0's here assume you send one (and only one) pseudo-csv record to the \s-1API\s0 at once. These may be nested, so a single tuple can contain arrays of tuples which can contain arrays of tuples ad infinitum but the parsing only goes one layer deep tuple-wise so that handling classes have an opportunity to re-parse with appropriate type information. Naturally this has performance implications, so depth in \s-1SQL\s0 structures passed should be reasonably limited. .PP As of 2.0, we no longer automatically call deserialization functions from the parser itself. At his point the calling classes \s-1MUST\s0 call the deserializer themselves but this is far easier since this has been moved to a separate service in PGObject 2.0. This avoids an unnecessary dependency on PGObject and ensures that the module is more geneally useful. .SH "EXPORT" .IX Header "EXPORT" .IP "pseudocsv_to_hash" 4 .IX Item "pseudocsv_to_hash" .PD 0 .IP "pseudocsv_parse" 4 .IX Item "pseudocsv_parse" .IP "to_pseudocsv" 4 .IX Item "to_pseudocsv" .PD .SH "SUBROUTINES/METHODS" .IX Header "SUBROUTINES/METHODS" .SS "pseudocsv_parse" .IX Subsection "pseudocsv_parse" This does a one-level deep parse of the pseudo-csv, with additional levels in arrays. When a tuple is encountered it is instantiated as its type but a subarray is parsed for more entities. .PP Only one pseudocsv record can be passed in at once, but embedded newlines are properly handled. .ie n .SS "pcsv2hash($literal_string, @cols);" .el .SS "pcsv2hash($literal_string, \f(CW@cols\fP);" .IX Subsection "pcsv2hash($literal_string, @cols);" Returns a hash from a tuple literal or array literal. .ie n .SS "hash2pcsv($hashref, @cols)" .el .SS "hash2pcsv($hashref, \f(CW@cols\fP)" .IX Subsection "hash2pcsv($hashref, @cols)" Takes an ordered list of columns and a hashref and returns a tuple literal .ie n .SS "pseudocsv_tohash($coldata, $colnames) \s-1DEPRECATED\s0" .el .SS "pseudocsv_tohash($coldata, \f(CW$colnames\fP) \s-1DEPRECATED\s0" .IX Subsection "pseudocsv_tohash($coldata, $colnames) DEPRECATED" Takes an arrayref of column data and an arrayref of column names and returns a hash. This is mostly a helper function designed to help with tuple types. .PP This interface is deprecated and will go away in 2.0. Use pcsv2hash instead. .ie n .SS "to_pseudocsv($datalist, $is_tuple)" .el .SS "to_pseudocsv($datalist, \f(CW$is_tuple\fP)" .IX Subsection "to_pseudocsv($datalist, $is_tuple)" Takes a list of data and an is_tuple argument and creates a pseudocsv. .PP Note: this does not check for array sanity. If you are not careful you can get arrays returned which are not valid \s-1SQL\s0 arrays. Remember that \s-1SQL\s0 arrays have every item being the same size, and all \s-1SQL\s0 arrays are are regular in size (so all 1 and 2d arrays follow the same form as mathematical matrices). .SH "AUTHOR" .IX Header "AUTHOR" Chris Travers, \f(CW\*(C`\*(C'\fR .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \f(CW\*(C`bug\-pgobject\-util\-pseudocsv at rt.cpan.org\*(C'\fR, or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc PGObject::Util::PseudoCSV .Ve .PP You can also look for information at: .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker (report bugs here) .Sp .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright 2014\-2017 Chris Travers. .PP Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: .PP * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. .PP * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. .PP \&\s-1THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \*(L"AS IS\*(R" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \&\s-1LOSS OF USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\s0