File Coverage

blib/lib/Text/TabFile.pm
Criterion Covered Total %
statement 11 17 64.7
branch 0 8 0.0
condition n/a
subroutine 4 6 66.6
pod 2 2 100.0
total 17 33 51.5


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