blib/lib/BoutrosLab/TSVStream/IO/Reader.pm untested

filter: Statementstmt n/a Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a SCAR -
1 package BoutrosLab::TSVStream::IO::Reader;
2  
3 =head1 NAME
4  
5 BoutrosLab::TSVStream::IO::Reader
6  
7 =cut
8  
9 =head1 SYNOPSIS
10  
11 This namespace hierarchy contains classes that can convert an input
12 stream (file or handle) into a series of objects of some type.
13  
14 =head1 DESCRIPTION
15  
16 Usually, a reader object is created indirectly, using a
17 reader method of the target class (which it acquires by
18 consuming the BoutrosLab::TSVStream::IO::Role::Fixed, or
19 BoutrosLab::TSVStream::IO::Role::Dyn role).
20  
21 Since most of the attributes and methods of readers are the
22 same, this document describes them - there are differences
23 between Fixed and Dyn readers which are distinguished below.
24  
25 It is recommended that when there are multiple formats possible for
26 a target class, they be implemented as a group of classes, where
27 each class in the group implements its attributes able to coerce
28 their value from any of the formats. If that is done, then a file
29 in any of the formats (or even using a mixture of the formats)
30 can be used as the text stream and a reader will automatically
31 convert it to the format of the target class that the reader is
32 associated with. Additionally, objects of any of the group of
33 classes can be provided to a writer from any of the group and it
34 will use the coercion to automatically convert to the desired format.
35 So, you choose a reader that matches the format you wish to use for
36 your programming code, and a writer for the format you wish for the
37 output. The classes BoutrosLab::TSVStream::Format::AnnovarInput::Human and
38 BoutrosLab::TSVStream::Format::AnnovarInput::NoChr provide an example of this.
39  
40 =head1 Methods
41  
42 =head2 new
43  
44 my $reader = Some::Class->reader(
45 # class => $class, # (required) class
46 handle => $fd, # (optional if file provided)
47 file => $file, # (optional if handle provided)
48 header => $str, # (optional) auto check none
49 comment => 1, # (optional) Bool: default 0
50 dyn_fields => $ref, # (optional, Dyn only)
51 extra_class_params => [...], # (optional) extra params for
52 # creating new class objects
53 );
54  
55 The B<new> method will usually be called indirectly from within
56 the B<reader> method of some other class. Such a B<reader> method
57 will provide its own class as the B<class> argument to the B<new>
58 method, so the user calling the B<reader> method does not need to
59 provide it. The B<reader> method will pass any arguments that the
60 caller provides to it on to the B<new> method. This document will
61 refer to that other class as the related class.
62  
63 At least one of the B<handle> and B<file> arguments must be provided.
64 If only the B<file> is provided, it will be opened for reading and
65 the B<handle> attribute will be initialized to that. If B<handle> is
66 provided, it must be an open handle to a readable stream. If errors
67 are encountered during processing, the B<file> (if provided) and line
68 number are used in the diagnostic - which means that even if you
69 are providing a B<handle>, it can be useful to provide the B<file>
70 argument as well to make the diagnostics clearer (unless your users
71 never make mistakes, of course).
72  
73 If B<header> is provided, it can be C<'check'>, C<'none'>,
74 or C<'auto'>. This controls what is done to the handle initially.
75  
76 =over
77  
78 If C<'check'> is specified, the first line of the stream is read.
79 The fields in that line are checked to ensure that they match the
80 names of the fixed
81 fields of the related class, both in name and order. However, it
82 is permitted for the field names to mismatch by having different
83 capitalization - the comparison is not case sensitive. (Dyn only:
84 if the B<dyn_fields> attribute was provided, the dynamic fields
85 will also be validated (possibly
86 causing the stream to be rejected); otherwise, if B<dyn_fields>
87 was not provided, the attribute be set to contain the field names
88 that follow the validated fixed field names.)
89  
90 If C<'none'> is specified, the stream is not checked for a header
91 line, the first line is treated as a data line. You would use this
92 option either if the file does not have a header line, or if you are
93 scanning from the middle of a file handle that is no longer at the
94 start of the file. In this case, if the B<dyn_fields> attribute was
95 not provided, then a default set of header names will be provided
96 (C<'extra1'>, C<'extra2'>, ...) matching the number of extra fields
97 that are in the first (data) line.
98  
99 By default, or if C<'auto'> was explicitly specified, the first
100 line is examined. If it matches all of the fixed field names
101 (and the dyn_fields names if they were provided) then the line
102 is processed as if C<'check'> were specified. However, if it
103 doesn't match, then the first line is treated as a data line
104 just as if C<'none'> had been specified.
105  
106 =back
107  
108 The B<comment> attribute can be set to a true value to enable
109 comment line stripping. Then, input lines which have a
110 comment symbol (C<#>) as the first non-blank character will not
111 generate an input record. After each input record is generated,
112 the reader object method B<read_comments> that will return any
113 comment lines that preceeded that record. After the end of the
114 stream has been reached (a undef was returned from the read method)
115 the B<read_comments> method will return any trailing comments that
116 followed the last data record.
117  
118 You can also set the attribute B<comment_pattern> to provide a
119 regular expression pattern to be used to decide whether an input
120 line is comment or data.
121  
122 There is a similar trio of attributes, B<pre_header>, B<pre_header_pattern>,
123 and B<pre_headers> that allow an additional type of comment to be
124 detected before the initial header (if there is one). If pre_header
125 is set, then any line that matches the pre_header_pattern or the
126 comment_pattern before the actual header line will be ignored and saved.
127 All such lines will be returned by the pre_headers attribute. If
128 pre_header is not set, but comment is set, then comment lines will still
129 be detected before the actual header line and be available with the
130 pre_headers attribute.
131  
132 At present, there
133 is no support for trailing comments after data fields. It can be
134 awkward to determine when a comment symbol is actually desired as
135 the content of an actual field value. That gets especially tricky
136 to determine with dynamic fields. Rather than use tricky coding,
137 and perhaps requiring escape characters in field values, it was
138 decided to only provide the minimal support. If such comments are
139 permitted in the future, it will be enabled by setting the B<comment>
140 to B<2>, while full-line comments (without field comments) would
141 continue as at present with a setting of B<1>.
142  
143 For Dyn readers, the B<dyn_fields> parameter can be passed to
144 specify the field names for the dynamic fields. If so, they will
145 be validated (if header validation is enabled - either C<'check'>
146 or C<'auto'> for the B<header> attribute).
147  
148 The B<extra_class_params> attribute accepts a ref to a list of
149 strings. These will be passed to the I<new> method of the target
150 class when a set of values has been read. This may be useful for
151 some target classes. The only current use for this is for I<Dyn>
152 I<reader> objects - they can be given:
153  
154 extra_class_params => [ install_methods => 1 ],
155  
156 to have dynamic fields be given accessor methods in the created
157 object. (If you wish to do this, the definition of the target class
158 must not invoke the make_immutable method in the class definition.
159 Not using make_immutable, and the time to install these extra
160 attribute accessors on every object is somewhat time-consuming -
161 if you are writing code that knows about the names of the dynamic
162 fields, then perhaps they should instead be written as fixed fields.)
163  
164 =head2 pre_headers
165  
166 This attribute will return an array ref to the list of any pre_header
167 or comment lines that preceeded the header line in the input stream.
168  
169 =head2 read
170  
171 The B<read> method takes no arguments. It reads the next line
172 (if any) from the handle, validates the fields, and retuns an
173 object of C<$class> with the field contents used to initialize
174 the attributes. At end of file, it returns C<undef>.
175  
176 =head2 read_comments
177  
178 This attribute will return an array ref to the list of any comment
179 lines that preceeded the most recent record in the input stream
180 (but ony those that followed the previous record or the header or
181 the start of the stream). After a read returns C<undef> to indicate
182 the end of the stream, this attribute will return any trailing
183 comments that followed the final record.
184  
185 =head2 _croak
186  
187 $reader->_croak("error message");
188  
189 The C<_croak> method is needed internally, but may also be useful
190 in some cases by the code that uses the reader. It croaks with
191 the supplied message, appending the filename and line number.
192  
193 =head1 SEE ALSO
194  
195 =over
196  
197 =item BoutrosLab::TSVStream::IO::Reader::Fixed
198  
199 =item BoutrosLab::TSVStream::IO::Reader::Dyn
200  
201 These are the two classes of reader - which read streams containing
202 either only the fields of the consumed class (Fixed), or the fields
203 of the consumed class followed by an additional dynamic set of fields
204 (Dyn).
205  
206 =item BoutrosLab::TSVStream::Format
207  
208 Describes the hierarchy of provided modules that define a
209 set of attributes that are useful to move to/from a text
210 stream.
211  
212 =item BoutrosLab::TSVStream::Format::None::Dyn
213  
214 A class that has no fixed fields, just dynamic fields. It is useful
215 for processing one-off files where there is no value in going to the
216 work of creating an entire class for that file format.
217  
218 =item BoutrosLab::TSVStream::IO
219  
220 Describes the format of a text stream that a reader can read from.
221  
222 =back
223  
224 =head1 AUTHOR
225  
226 John Macdonald - Boutros Lab
227  
228 =head1 ACKNOWLEDGEMENTS
229  
230 Paul Boutros, Phd, PI - Boutros Lab
231  
232 The Ontario Institute for Cancer Research
233  
234 =cut
235  
236 1;
237