Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 178 lines (96 sloc) 5.584 kb
dac41be @jberger Initial commit released as version 0.01 to CPAN
authored
1 =head1 NAME
2
3 Tie::Array::CSV - A tied array which combines the power of Tie::File and Text::CSV
4
5 =head1 SYNOPSIS
6
7 use strict; use warnings;
8 use Tie::Array::CSV;
9 tie my @file, 'Tie::Array::CSV', 'filename';
10
11 print $file[0][2];
12 $file[3][5] = "Camel";
13
14 =head1 DESCRIPTION
15
4c386b5 @jberger Minor POD improvement, still prior to 0.01 release
authored
16 This module allows an array to be tied to a CSV file for reading and writing. The array is a standard Perl 2D array (i.e. an array of array references) which gives access to the row and column of the user's choosing. This is done using the well established modules:
17
18 =over
19
20 =item *
21 L<Tie::File>
22
23 =over
24
25 =item *
26
b802807 @jberger More POD improvements
authored
27 arbitrary line access
4c386b5 @jberger Minor POD improvement, still prior to 0.01 release
authored
28
29 =item *
30
b802807 @jberger More POD improvements
authored
31 low memory use even for large files
4c386b5 @jberger Minor POD improvement, still prior to 0.01 release
authored
32
33 =back
34
35 =item *
36
37 L<Text::CSV>
38
39 =over
40
41 =item *
42
43 row parsing
44
45 =item *
46
47 row updating
48
49 =item *
50
51 uses the speedy L<Text::CSV_XS> if installed
52
53 =back
54
55 =back
dac41be @jberger Initial commit released as version 0.01 to CPAN
authored
56
57 This module was inspired by L<Tie::CSV_File> which (sadly) hasn't been maintained. It also doesn't attempt to do any of the parsing (as that module did), but rather passes all of the heavy lifting to other modules.
58
4b09440 @jberger POD fix, ::HoldRow slipped into main doc
authored
59 Note that while the L<Tie::File> prevents the need to read in the entire file, while in use, a parsed row IS held in memory.
22af31d @jberger More improvements to POD
authored
60
23f73f4 @jberger Describe the class method 'new' constructor
authored
61 =head1 CONSTRUCTORS
62
22af31d @jberger More improvements to POD
authored
63 Since version 0.04 both constructors allow the options that version 0.03 only offered for the C<new> constructor. The constructors must be passed a file name, either as the first argument, or as the value to the option key C<file>. Options may be passed as key-value pairs or as a hash reference. This yields the many ways of calling the constructors shown below, one for every taste.
64
65 N.B. Should a lone argument filename and a C<file> option key both be passed to the constructor, the lone argument wins.
66
23f73f4 @jberger Describe the class method 'new' constructor
authored
67 =head2 C<tie> Constructor
dac41be @jberger Initial commit released as version 0.01 to CPAN
authored
68
22af31d @jberger More improvements to POD
authored
69 As with any tied array, the construction uses the C<tie> function. Basic usage is as follows:
b802807 @jberger More POD improvements
authored
70
71 tie my @file, 'Tie::Array::CSV', 'filename';
72
22af31d @jberger More improvements to POD
authored
73 which would tie the lexically scoped array C<@file> to the file C<filename> using this module. Following the first two arguements to C<tie>, one may optionally pass a key-value pairs or a hashref containing additional configuration or even file specification.
23f73f4 @jberger Describe the class method 'new' constructor
authored
74
75 tie my @file, 'Tie::Array::CSV', 'filename', { opt_key => val, ... };
22af31d @jberger More improvements to POD
authored
76 tie my @file, 'Tie::Array::CSV', 'filename', opt_key => val, ... ;
77 tie my @file, 'Tie::Array::CSV', { file => 'filename', opt_key => val, ... };
78 tie my @file, 'Tie::Array::CSV', file => 'filename', opt_key => val, ... ;
23f73f4 @jberger Describe the class method 'new' constructor
authored
79
80 Of course, the magical Perl C<tie> can be scary for some, for those people there is the ...
81
82 =head2 C<new> Constructor
83
0e04180 @jberger Added note on when 'new' was added
authored
84 [ Added in version 0.03 ]
85
23f73f4 @jberger Describe the class method 'new' constructor
authored
86 my $array = Tie::Array::CSV->new( 'filename' );
87 my $array = Tie::Array::CSV->new( 'filename', { opt_key => val, ... });
88 my $array = Tie::Array::CSV->new( 'filename', opt_key => val, ... );
89 my $array = Tie::Array::CSV->new( file => 'filename', opt_key => val, ... );
90 my $array = Tie::Array::CSV->new( { file => 'filename', opt_key => val, ... } );
91
92 It only returns a reference to the C<tie>d array due to a limitations in how C<tie> magic works.
93
94 =head2 Options
95
dac41be @jberger Initial commit released as version 0.01 to CPAN
authored
96 =over
97
98 =item *
99
22af31d @jberger More improvements to POD
authored
100 C<file> - alternative method for specifing the file to C<tie>. This is overridden by a lone filename or handle passed as the first argument to the constructor.
101
102 =item *
103
104 C<tie_file> - hashref of options which are passed to the L<Tie::File> constructor
105
106 =item *
107
108 C<text_csv> - hashref of options which are passed to the L<Text::CSV> constructor
dac41be @jberger Initial commit released as version 0.01 to CPAN
authored
109
110 =item *
111
22af31d @jberger More improvements to POD
authored
112 C<sep_char> - for ease of use, a C<sep_char> option may be specified, which is passed to the L<Text::CSV> constructor. This option overrides a corresponding entry in the C<text_csv> pass-through hash.
113
dac41be @jberger Initial commit released as version 0.01 to CPAN
authored
114 =back
115
22af31d @jberger More improvements to POD
authored
116 Equivalent examples:
b802807 @jberger More POD improvements
authored
117
118 tie my @file, 'Tie::Array::CSV', 'filename', {
119 tie_file => {},
120 text_csv => { sep_char => ';' },
121 };
122
4b09440 @jberger POD fix, ::HoldRow slipped into main doc
authored
123 tie my @file, 'Tie::Array::CSV', 'filename', sep_char => ';';
124
125 Note that as of version 0.05 the functionality from the former C<hold_row> option has been moved to the subclass module L<Tie::Array::CSV::HoldRow>. If deferring row operations is of interest to you, please see that module.
22af31d @jberger More improvements to POD
authored
126
4c386b5 @jberger Minor POD improvement, still prior to 0.01 release
authored
127 =head1 ERRORS
128
5752a2c @jberger POD improvement
authored
129 For simplicity this module C<croak>s on all almost all errors, which are trappable using a C<$SIG{__DIE__}> handler. Modifing a severed row object issues a warning.
4c386b5 @jberger Minor POD improvement, still prior to 0.01 release
authored
130
dac41be @jberger Initial commit released as version 0.01 to CPAN
authored
131 =head1 CAVEATS
132
5cbd6ad @jberger Updated POD to include note on fields with linebreaks.
authored
133 =over
134
135 =item *
136
dac41be @jberger Initial commit released as version 0.01 to CPAN
authored
137 Much of the functionality of normal arrays is mimicked using L<Tie::Array>. The interaction of this with L<Tie::File> should be mentioned in that certain actions may be very inefficient. For example, C<(un)shift>-ing the first row of data will probably involve L<Tie::Array> asking L<Tie::File> to move each row up one line, one-by-one. As a note, the intra-row C<(un)shift> does not suffer this problem.
138
5cbd6ad @jberger Updated POD to include note on fields with linebreaks.
authored
139 =item *
140
4b09440 @jberger POD fix, ::HoldRow slipped into main doc
authored
141 At one time, some effort was been made to allow for fields which contain linebreaks. Quickly it became clear that linebreaks would change line numbers used for row access by L<Tie::File>. Attempts to compensate for this, unfortunately, moved the module far from its stated goals, and therefore far less powerful for its intended purposes. The decision has been made (for now) not to support such files.
5cbd6ad @jberger Updated POD to include note on fields with linebreaks.
authored
142
143 =back
144
4c386b5 @jberger Minor POD improvement, still prior to 0.01 release
authored
145 =head1 SEE ALSO
146
147 =over
148
149 =item *
150
151 L<Tie::CSV_File> - inspiration for this module, but problematic
152
153 =item *
154
155 L<Tie::Array::DBD> - tie database connection to array
156
157 =item *
158
159 L<Tie::DBI> - similar but hash based
160
161 =back
162
dac41be @jberger Initial commit released as version 0.01 to CPAN
authored
163 =head1 SOURCE REPOSITORY
164
165 L<http://github.com/jberger/Tie-Array-CSV>
166
167 =head1 AUTHOR
168
169 Joel Berger, E<lt>joel.a.berger@gmail.comE<gt>
170
171 =head1 COPYRIGHT AND LICENSE
172
4b09440 @jberger POD fix, ::HoldRow slipped into main doc
authored
173 Copyright (C) 2012 by Joel Berger
dac41be @jberger Initial commit released as version 0.01 to CPAN
authored
174
175 This library is free software; you can redistribute it and/or modify
176 it under the same terms as Perl itself.
177
Something went wrong with that request. Please try again.