blib/lib/BoutrosLab/TSVStream/IO/Writer.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::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