| 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 |