File Coverage

blib/lib/Text/Delimited.pm
Criterion Covered Total %
statement 79 111 71.1
branch 12 34 35.2
condition 2 8 25.0
subroutine 18 26 69.2
pod 11 19 57.8
total 122 198 61.6


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             Text::Delimited - Module for parsing delimited text files
4              
5             =head1 SYNOPSIS
6              
7             Text::Delimited provides a programattical interface to data stored in
8             delimited text files. It is dependant upon the first row of the text
9             file containing header information for each corresponding "column" in the
10             remainder of the file.
11              
12             After instancing, for each call to Read the next row's data is returned as
13             a hash reference. The individual elements are keyed by their corresonding
14             column headings.
15              
16             =head1 USAGE
17              
18             A short example of usage is detailed below. It opens a pipe delimited file
19             called 'infile.txt', reads through every row and prints out the data from
20             "COLUMN1" in that row. It then closes the file.
21              
22             my $file = new Text::Delimited;
23             $file->delimiter('|');
24             $file->open('infile.txt');
25              
26             my @header = $file->fields;
27              
28             while ( my $row = $file->read ) {
29             print $row->{COLUMN1}, "\n";
30             }
31              
32             $file->close;
33              
34             The close() method is atuomatically called when the object passes out of
35             scope. However, you should not depend on this. Use close() when
36             approrpiate.
37              
38             Other informational methods are also available. They are listed blow:
39              
40             =head1 METHODS:
41              
42             =over
43              
44             =item close()
45              
46             Closes the file or connection, and cleans up various bits.
47              
48             =item delimiter(delimiter)
49              
50             Allows you to set the delimiter if a value is given. The default
51             delimiter is a tab. Returns the delimiter.
52              
53             =item fields()
54              
55             Returns an array (or arrayref, depending on the requested context) with
56             the column header fields in the order specified by the source file.
57              
58             =item filename()
59              
60             If open() was given a filename, this function will return that value.
61              
62             =item linenumber()
63              
64             This returns the line number of the last line read. If no calls to Read
65             have been made, will be 0. After the first call to Read, this will return
66             1, etc.
67              
68             =item new([filename|filepointer],[enumerate])
69              
70             Creates a new Text::Delimited object. Takes optional parameter that is either
71             a filename or a globbed filehandle. Files specified by filename must
72             already exist.
73              
74             Can optionally take a second argument. If this argument evaluates to true,
75             Text::Delimited will append a _NUM to the end of all fields with duplicate names.
76             That is, if your header row contains 2 columns named "NAME", one will be
77             changed to NAME_1, the other to NAME_2.
78              
79             =item open([filename|filepointer], [enumerate])
80              
81             Opens the given filename or globbed filehandle and reads the header line.
82             Returns 0 if the operation failed. Returns the file object if succeeds.
83              
84             Can optionally take a second argument. If this argument evaluates to true,
85             Text::Delimited will append a _NUM to the end of all fields with duplicate names.
86             That is, if your header row contains 2 columns named "NAME", one will be
87             changed to NAME_1, the other to NAME_2.
88              
89             =item read()
90              
91             Returns a hashref with the next record of data. The hash keys are determined
92             by the header line.
93              
94             __DATA__ and __LINE__ are also returned as keys.