blib/lib/BoutrosLab/TSVStream/IO.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;
2  
3 =head1 NAME
4  
5 BoutrosLab::TSVStream::IO
6  
7 =head1 SYNOPSIS
8  
9 This namespace hierarchy contains roles that allow an object
10 the ability to create a reader (or writer) object that can load
11 (or store) instances of the consuming object class from (or to)
12 a file or stream.
13  
14 package MyObject;
15  
16 use Moose;
17 use MooseX::ClassAttribute;
18  
19 # the definition of _fields must precede the 'with' statement
20 class_has '_fields' => (
21 is => 'ro',
22 isa => 'ArrayRef',
23 default => sub { [qw(my_field1 my_field2)] }
24 );
25  
26 # one of:
27 with 'BoutrosLab::TSVStream::IO::Role::Fixed';
28  
29 # or:
30 with 'BoutrosLab::TSVStream::IO::Role::Dyn';
31  
32 has my_field1 => ( isa => 'Int', ... );
33 has my_field2 => ( isa => 'Str', ... );
34  
35 package UserCode;
36  
37 use MyObject;
38  
39 my $reader = MyObject->reader( file => 'lib/myfobjectfile' );
40 my $writer = MyObject->writer( file => 'lib/myfobjectfile.over10' );
41 while (my $obj = $reader->read) {
42 # $obj is a MyObject
43 $writer->write($obj) if $obj->my_field1 > 10;
44 }
45  
46  
47 =head1 DESCRIPTION
48  
49 Consuming classes can acquire the ability to generate reader and
50 writer objects by consuming one of the Roles:
51  
52 =over
53  
54 =item BoutrosLab::TSVStream::IO::Role::Fixed
55  
56 =item BoutrosLab::TSVStream::IO::Role::Dyn
57  
58 =back
59  
60 Consuming classes must provide a set of useful attributes, etc. as
61 any normal class. But they also consume one of the roles:
62  
63 A class that consumes ...::IO::Role::Fixed deals with streams which
64 contain only the fixed defined fields for this class (as specified
65 by the class attribute _class).
66  
67 A class that consumes ...::IO::Role::Dyn deals with streams which
68 contain the fixed defined fields for this class (as specified
69 by the class attribute _class), but on each line the fixed attributes
70 are followed by a number of dynamic fields.
71  
72 The stream format is a series of lines.
73  
74 =over
75  
76 =item .
77  
78 Each line consists of a number of fields, separated by a tab
79 character.
80  
81 =item .
82  
83 If comments are enabled, then lines with the first non-space
84 character being a comment symbol (#) will be discarded on input
85 and not returned by a reader.
86  
87 =item .
88  
89 All non-comment lines must contain the same number of fields.
90  
91 =item .
92  
93 The first line is (usually) a header line that has the field names
94 as the text contents of each field. (The field names are validated
95 on reading to verify match the definition of the object. The header
96 line is not returned by the reader as an object.) A writer will
97 write out a header line unless it was configured not to.
98  
99 =item .
100  
101 The remaining lines of the stream consist of fields that contain
102 data.
103  
104 =item .
105  
106 The first fields contain data for each of the attributes defined
107 by the object (in the order defined by the object). Each field is
108 validated using the type specification for those attributes.
109  
110 =item .
111  
112 For IO::Role::Fixed consuming objects, that must be all of the
113 fields in the stream.
114  
115 =item .
116  
117 For IO::Role::Dyn objects, remaining fields contain text data for
118 additional contents. The number and content of these dynamic fields
119 are determined at run-time - there must be a consistant number of
120 fields throughout an entire stream, but the validity of the content
121 cannot be determined automatically (because each stream can have a
122 different set of dynamic fields, so there is no way for the code to
123 know in advance how to validate them). When reading, if the reader
124 definition did not provide field names for the dynamic fields and if
125 header processing is enabled, then the field names for the dynamic
126 fields will be determined from the input.
127  
128 =back
129  
130 =head1 Requirements for Comsuning class
131  
132 The consuming class must satify a number of requirements.
133  
134 =over
135  
136 =item .
137  
138 class_attribute B<_fields>: must provide a ref to an array of strings
139 that specify the fixed field names.
140  
141 =item .
142  
143 attribute I<FIELD>: each field listed in the _fields class attribute
144 must be defined as an attribute of the consuming object.
145  
146 =back
147  
148 =head1 Methods Provided to the Consuming class (by either Fixed or Dyn)
149  
150 =head2 B<reader>
151  
152 The reader method returns an object that reads a stream
153 and produces objects of the consuming class. See
154 BoutrosLab::TSVStream::IO::Reader for details.
155  
156 =head2 B<writer>
157  
158 The writer method returns an object that writes a stream,
159 from objects of the consuming class (or equivalent values).
160 See BoutrosLab::TSVStream::IO::Writer for details.
161  
162 =head1 Attributes Provided to the Consuming class (only by Dyn)
163  
164 =head2 B<dyn_fields>
165  
166 the names of the dynamic fields. If they are not provided by
167 the calling code, or by a header (in an input stream), they
168 are set to 'extra1', 'extra2', ...
169  
170 =head2 B<dyn_values>
171  
172 the values of the dynamic fields (in the same order as dyn_field,
173 and as in a stream).
174  
175 =head2 B<extra_class_params>
176  
177 List of string values to be passed to the B<new> method for the
178 target object. This can be of value to specific target objects.
179  
180 The only such attribute defined by this package is
181 B<install_methods>, which is a Boolean attribute that can be provided
182 to a B<Dyn> B<reader> to cause all new objects created by that
183 reader to be provided with accessor methods for the dynamic fields.
184 Generally, this is not needed:
185  
186 =over
187  
188 =item . the whole point of dynamic
189 fields is that the code doesn't know what the fields will be called
190  
191 =item . it is potentially dangerous since if a dynamic field has
192 the same name as a fixed field or as another dynamic field there
193 would be an attempt to create multiple methods with the same name -
194 this is treated as an error when the dynamic fields are determined
195  
196 =item . it is time-costly both for the cost of installing the
197 methods for each created object dynamically, and also because the
198 target class may not use the Moose make_immuable to pre-compile
199 the object-oriented internal code, since that would prevent adding
200 these attributes
201  
202 =back
203  
204 =head1 SEE ALSO
205  
206 =over
207  
208 =item BoutrosLab::TSVStream::IO::Reader
209  
210 =item BoutrosLab::TSVStream::IO::Writer
211  
212 These are the classes of reader and writer objects that are returned
213 by this role. See them for the creation parameters you can provide
214 to the reader and writer methods described here as well as for the
215 methods that reader and writer objects provide.
216  
217 =item BoutrosLab::TSVStream::Format
218  
219 Describes the hierarchy of provided modules that define a
220 set of attributes that are useful to move to/from a text
221 stream.
222  
223 =back
224  
225 =head1 AUTHOR
226  
227 John Macdonald - Boutros Lab
228  
229 =head1 ACKNOWLEDGEMENTS
230  
231 Paul Boutros, Phd, PI - Boutros Lab
232  
233 The Ontario Institute for Cancer Research
234  
235 =cut
236  
237 1;
238