| 1 | package BoutrosLab::TSVStream::IO::Writer; | ||
| 2 | |||
| 3 | =head1 NAME | ||
| 4 | |||
| 5 | BoutrosLab::TSVStream::IO::Writer | ||
| 6 | |||
| 7 | =cut | ||
| 8 | |||
| 9 | =head1 SYNOPSIS | ||
| 10 | |||
| 11 | This namespace hierarchy contains classes that can convert a series | ||
| 12 | of objects compatible with some type into an output stream (file | ||
| 13 | or handle). | ||
| 14 | |||
| 15 | =head1 DESCRIPTION | ||
| 16 | |||
| 17 | Usually, a writer object is created indirectly, using a | ||
| 18 | B<writer> method of the target class (which it acquires by | ||
| 19 | consuming the I<BoutrosLab::TSVStream::IO::Role::Fixed>, or | ||
| 20 | I<BoutrosLab::TSVStream::IO::Role::Dyn> role). | ||
| 21 | |||
| 22 | Since most of the attributes and methods of writers are the | ||
| 23 | same, this document describes them - there are differences | ||
| 24 | between Fixed and Dyn writers which are distinguished below. | ||
| 25 | |||
| 26 | It is recommended that when there are multiple formats possible for | ||
| 27 | a target class, they be implemented as a group of classes, where | ||
| 28 | each class in the group implements its attributes able to coerce | ||
| 29 | their value from any of the formats. If that is done, then a file | ||
| 30 | in any of the formats (or even using a mixture of the formats) | ||
| 31 | can be used as the text stream and a reader will automatically | ||
| 32 | convert it to the format of the target class that the reader is | ||
| 33 | associated with. Additionally, objects of any of the group of | ||
| 34 | classes can be provided to a writer from any of the group and it will | ||
| 35 | use the coercion to automatically convert to the desired format. | ||
| 36 | So, you choose a reader that matches the format you wish to use | ||
| 37 | for your programming code, and a writer for the format you wish for | ||
| 38 | the output. The classes I<BoutrosLab::TSVStream::Format::AnnovarInput::Human> | ||
| 39 | and I<BoutrosLab::TSVStream::Format::AnnovarInput::NoChr> provide an example | ||
| 40 | of this. | ||
| 41 | |||
| 42 | =head1 Methods | ||
| 43 | |||
| 44 | =head2 new | ||
| 45 | |||
| 46 | my $writer = Some::Class->writer( | ||
| 47 | # class => $class, # (required) class | ||
| 48 | handle => $fd, # (optional if file provided) | ||
| 49 | file => $file, # (optional if handle provided) | ||
| 50 | append => 1, # (optional) append to file | ||
| 51 | header => $str, # (optional) write skip | ||
| 52 | dyn_fields => $ref, # (optional, Dyn only) | ||
| 53 | extra_class_params => [...], # (optional) extra params for | ||
| 54 | # creating new class objects | ||
| 55 | ); | ||
| 56 | |||
| 57 | The B<new> method will usually be called indirectly from within | ||
| 58 | the B<writer> method of some other class. Such a B<writer> method | ||
| 59 | will provide its own class as the B<class> argument to the B<new> | ||
| 60 | method, so the user calling the B<writer> method does not need to | ||
| 61 | provide it. The B<writer> method will pass any arguments that the | ||
| 62 | caller provides to it on to the B<new> method. This document will | ||
| 63 | refer to that other class as the related class. | ||
| 64 | |||
| 65 | At least one of the B<handle> and B<file> arguments must be provided. | ||
| 66 | If only the B<file> is provided, it will be opened for writing and | ||
| 67 | the B<handle> attribute will be initialized to that. If B<handle> is | ||
| 68 | provided, it must be an open handle to a readable stream. If errors | ||
| 69 | are encountered during processing, the B<file> (if provided) and line | ||
| 70 | number are used in the diagnostic - which means that even if you | ||
| 71 | are providing a B<handle>, it can be useful to provide the B<file> | ||
| 72 | argument as well to make the diagnostics clearer (unless your users | ||
| 73 | never make mistakes, of course). | ||
| 74 | |||
| 75 | If no B<handle> is provided, the B<file> is opened. By default, | ||
| 76 | it is opened for normal write (overwriting any previous contents). | ||
| 77 | However, if the optional B<append> attribute is provided and has | ||
| 78 | a true value, the B<file> is instead opened for append. If the | ||
| 79 | B<handle> attribute is provided, this B<append> attribute has | ||
| 80 | no effect. | ||
| 81 | |||
| 82 | If B<header> is provided, it can be C<'write'>, or C<'skip'>. | ||
| 83 | This controls what is done to the handle initially. | ||
| 84 | |||
| 85 | =over | ||
| 86 | |||
| 87 | If C<'write'> is specified, the field names are written as a header | ||
| 88 | to the stream before any data. If C<'skip'> is specified, no header | ||
| 89 | is written before any data records. The default is to C<'write'> | ||
| 90 | the headers. | ||
| 91 | |||
| 92 | If the optional B<pre_headers> attribute is provided, it must contain | ||
| 93 | an arrayref contining a list of comment lines that are to be written | ||
| 94 | before the header is written (if any). | ||
| 95 | |||
| 96 | =back | ||
| 97 | |||
| 98 | For Dyn writers, the B<dyn_fields> parameter can be passed to specify | ||
| 99 | the field names for the dynamic fields. If not, and if headers are | ||
| 100 | being written. then a default set of header names will be provided | ||
| 101 | (C<'extra1'>, C<'extra2'>, ...). | ||
| 102 | |||
| 103 | The B<extra_class_params> attribute accepts a ref to a list of | ||
| 104 | strings. These will be passed to the I<new> method of the target | ||
| 105 | class when a set of values has been read. This may be useful for | ||
| 106 | some target classes. There is currently no generic use of this for | ||
| 107 | B<writer>. | ||
| 108 | |||
| 109 | =head2 write | ||
| 110 | |||
| 111 | The B<write> method takes arguments. Usually, you will call it | ||
| 112 | with a single object of the target class, and its fields will be | ||
| 113 | written to the stream. | ||
| 114 | |||
| 115 | Alternatively, you can pass an object of a compatible class, an | ||
| 116 | array ref or a list of values. These values will be validated | ||
| 117 | converted (if possible) into the target class and then written | ||
| 118 | (croaking if conversion fails). | ||
| 119 | |||
| 120 | =head2 write_comments | ||
| 121 | |||
| 122 | The B<write_comments> method takes an array ref containing lines | ||
| 123 | to be written verbatim to the output stream. It is the caller's | ||
| 124 | respopnsibility to ensure that these lines are formatted properly | ||
| 125 | to match the commenting conventions for the targe TSVStream file | ||
| 126 | type. | ||
| 127 | |||
| 128 | =head2 _croak | ||
| 129 | |||
| 130 | $writer->_croak("error message"); | ||
| 131 | |||
| 132 | The C<_croak> method is needed internally, but may also be useful | ||
| 133 | in some cases by the code that uses the writer. It croaks with | ||
| 134 | the supplied message, appending the filename and line number. | ||
| 135 | |||
| 136 | =head1 SEE ALSO | ||
| 137 | |||
| 138 | =over | ||
| 139 | |||
| 140 | =item BoutrosLab::TSVStream::IO::Writer::Fixed | ||
| 141 | |||
| 142 | =item BoutrosLab::TSVStream::IO::Writer::Dyn | ||
| 143 | |||
| 144 | These are the two classes of writer - which read streams containing | ||
| 145 | either only the fields of the consumed class (Fixed), or the fields | ||
| 146 | of the consumed class followed by an additional dynamic set of fields | ||
| 147 | (Dyn). | ||
| 148 | |||
| 149 | =item BoutrosLab::TSVStream::Format | ||
| 150 | |||
| 151 | Describes the hierarchy of provided modules that define a | ||
| 152 | set of attributes that are useful to move to/from a text | ||
| 153 | stream. | ||
| 154 | |||
| 155 | =item BoutrosLab::TSVStream::Format::None::Dyn | ||
| 156 | |||
| 157 | A class that has no fixed fields, just dynamic fields. It is useful | ||
| 158 | for processing one-off files where there is no value in going to the | ||
| 159 | work of creating an entire class for that file format. | ||
| 160 | |||
| 161 | =item BoutrosLab::TSVStream::IO | ||
| 162 | |||
| 163 | Describes the format of a text stream that a writer can read from. | ||
| 164 | |||
| 165 | =back | ||
| 166 | |||
| 167 | =head1 AUTHOR | ||
| 168 | |||
| 169 | John Macdonald - Boutros Lab | ||
| 170 | |||
| 171 | =head1 ACKNOWLEDGEMENTS | ||
| 172 | |||
| 173 | Paul Boutros, Phd, PI - Boutros Lab | ||
| 174 | |||
| 175 | The Ontario Institute for Cancer Research | ||
| 176 | |||
| 177 | =cut | ||
| 178 | |||
| 179 | 1; | ||
| 180 |