.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 "CSV 3pm"
.TH CSV 3pm "2022-05-27" "perl v5.34.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"
XML::CSV \- Perl extension converting CSV files to XML
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use XML::CSV;
\&  $csv_obj = XML::CSV\->new();
\&  $csv_obj = XML::CSV\->new(\e%attr);
\&  
\&  $status = $csv_obj\->parse_doc(file_name);
\&  $status = $csv_obj\->parse_doc(file_name, \e%attr);
\&  
\&  $csv_obj\->declare_xml(\e%attr);
\&  $csv_obj\->declare_doctype(\e%attr);
\&
\&  $csv_obj\->print_xml(file_name, \e%attr);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1XML::CSV\s0 is a new module in is going to be upgraded very often as my time permits.
For the time being it uses \s-1CSV_XS\s0 module object default values to parse the
(*.csv) document and then creates a perl data structure with xml tags names and data.  
At this point it does not allow for a write as you parse interface but is
the first upgrade for the next release.  I will also allow more access to the data structures
and more documentation.  I will also put in more support for \s-1XML,\s0 since currently
it only allows a simple \s-1XML\s0 structure.  Currently you can modify the tag structure
to allow for attributes.  No \s-1DTD\s0 support is currently available, but will be
implemented in a soon coming release.  As the module will provide both: object and event interfaces, it will
be used upon individual needs, system resources, and required performance.  Ofcourse the \s-1DOM\s0
implementation takes up more resources and in some instances timing, it's the easiest to use.
.SH "ATTRIBUTES \fBnew()\fP"
.IX Header "ATTRIBUTES new()"
error_out \- Turn on the error handling which will die on all errors and assign the error message to
\&\f(CW$XML::CSV::csvxml_error\fR.
.PP
column_headings \- Specifies the column heading to use.  Passed as an array reference.  Can be used 
as a supplement to using the first column in the file as the \s-1XML\s0 tag names.  Since \s-1XML::CSV\s0 does 
not require you to parse the \s-1CSV\s0 file, you can provide your own data structure to parse.
.PP
column_data \- Specifies the \s-1CSV\s0 data in a two dimensional array.  Passed as an array reference.
.PP
csv_xs \- Specifies the \s-1CSV_XS\s0 object to use.  This is used to create custom \s-1CSV_XS\s0 object and override
the default one created by \s-1XML::CSV.\s0
.SH "ATTRIBUTES \fBparse_doc()\fP"
.IX Header "ATTRIBUTES parse_doc()"
headings \- Specifies the number of rows to use as tag names.  Defaults to 0.
Ex.  {headings => 1} (This will use the first row of data as xml tags)
.PP
sub_char \- Specifies the character with which the illegal tag characters will be
replaced with.  Defaults to undef meaning no substitution is done.  To eliminate
characters use "\*(L" (empty string) or to replace with another see below.
Ex.  {sub_char => \*(R"_\*(L"} or {sub_char => \*(R""}
.SH "ATTRIBUTES \fBdeclare_xml()\fP"
.IX Header "ATTRIBUTES declare_xml()"
version \- Specifies the xml version.  
Ex.  {version => '1.0'}
.PP
encoding \- Specifies the type of encoding.  \s-1XML\s0 standard defaults encoding to '\s-1UTF\-8\s0' if notspecifically
           set.
Ex.  {encoding => '\s-1ISO\-8859_1\s0'}
.PP
standalone \- Specifies the the document as standalone (yes|no).  If the document is does not rely on an
             external \s-1DTD, DTD\s0 is internal, or the external \s-1DTD\s0 does not effect the contents of the document,
             the standalone attribute should be set to 'yes', otherwise 'no' should be used.  For more info
             see \s-1XML\s0 declaration documentation.
Ex.  {standalone => 'yes'}
.SH "ATTRIBUTES \fBdeclare_doctype()\fP"
.IX Header "ATTRIBUTES declare_doctype()"
source \- Specifies the source of the \s-1DTD\s0 (SYSTEM|PUBLIC)
Ex. {source => '\s-1SYSTEM\s0'}
.PP
location1 \- \s-1URI\s0 to the \s-1DTD\s0 file.  Public \s-1ID\s0 may be used if source is \s-1PUBLIC.\s0
Ex. {location1 => 'http://www.xmlproj.com/dtd/index_dtd.dtd'} or {location1 => '\-//Netscape Communications//DTD \s-1RSS 0.90//EN\s0'}
.PP
location2 \- Optional second \s-1URI.\s0  Usually used if the location1 public \s-1ID\s0 is not found by the
            validating parser.
Ex. {location2 => 'http://www.xmlproj.com/file.dtd'}
.PP
subset \- Any other information that proceedes the \s-1DTD\s0 declaration.  Usually includes internal \s-1DTD\s0 if any.
Ex. {subset => '\s-1ELEMENT\s0 first_name (#PCDATA)>\en<!ELEMENT last_name (#PCDATA)>'}
You can even enterpolate the string with \f(CW$obj\fR\->{column_headings} to dynamically build the \s-1DTD.\s0
Ex. {subset => \*(L"\s-1ELEMENT\s0 \f(CW$obj\fR\->{columnt_headings}[0] (#PCDATA)>\*(R"}
.SH "ATTRIBUTES \fBprint_xml()\fP"
.IX Header "ATTRIBUTES print_xml()"
file_tag \- Specifies the file parent tag.  Defaults to \*(L"records\*(R".
Ex. {file_tag => \*(L"file_data\*(R"} (Do not use < and > when specifying)
.PP
parent_tag \- Specifies the record parent tag.  Defaults to \*(L"record\*(R".
Ex. {parent_tag => \*(L"record_data\*(R"} (Do not use < and > when specifying)
.PP
format \- Specifies the character to use to indent nodes.  Defaults to \*(L"\et\*(R" (tab).
Ex. {format => \*(L" \*(R"} or {format => \*(L"\et\et\*(R"}
.SH "PUBLIC VARIABLES"
.IX Header "PUBLIC VARIABLES"
\&\f(CW$csv_obj\fR\->{column_headings}
\&\f(CW$csv_obj\fR\->{column_data}
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Example #1:
.PP
This is a simple implementation which uses defaults
.PP
use \s-1XML::CSV\s0;
\&\f(CW$csv_obj\fR = \s-1XML::CSV\-\s0>\fBnew()\fR;
\&\f(CW$csv_obj\fR\->parse_doc(\*(L"in_file.csv\*(R", {headings => 1});
.PP
\&\f(CW$csv_obj\fR\->print_xml(\*(L"out.xml\*(R");
.PP
Example #2:
.PP
This example uses a passed headings array reference which is used along with the parsed data.
.PP
use \s-1XML::CSV\s0;
\&\f(CW$csv_obj\fR = \s-1XML::CSV\-\s0>\fBnew()\fR;
.PP
\&\f(CW$csv_obj\fR\->{column_headings} = \e@arr_of_headings;
.PP
\&\f(CW$csv_obj\fR\->parse_doc(\*(L"in_file.csv\*(R");
\&\f(CW$csv_obj\fR\->print_xml(\*(L"out.xml\*(R", {format => \*(L" \*(R", file_tag = \*(L"xml_file\*(R", parent_tag => \*(L"record\*(R"});
.PP
Example #3:
.PP
First it passes a reference to a array with column headings and then a reference to two dimensional array
of data where the first index represents the row number and the second column number.  We also pass a custom
Text::CSV_XS object to overwrite the default object.  This is useful for creating your own \s-1CSV_XS\s0 object's args
before using the \fBparse_doc()\fR method.  See 'perldoc Text::CSV_XS' for different \fBnew()\fR attributes.
.PP
use \s-1XML::CSV\s0;
.PP
\&\f(CW$default_obj_xs\fR = Text::CSV_XS\->new({quote_char => '"'});
\&\f(CW$csv_obj\fR = \s-1XML::CSV\-\s0>new({csv_xs => \f(CW$default_obj_xs\fR});
\&\f(CW$csv_obj\fR\->{column_headings} = \e@arr_of_headings;
.PP
\&\f(CW$csv_obj\fR\->{column_data} = \e@arr_of_data;
.PP
\&\f(CW$csv_obj\fR\->print_xml(\*(L"out.xml\*(R");
.SH "AUTHOR"
.IX Header "AUTHOR"
Ilya Sterin, isterin@mail.com
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Text::CSV_XS