blib/lib/BoutrosLab/TSVStream/Format.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::Format;
2  
3 =head1 NAME
4  
5 BoutrosLab::TSVStream::Format
6  
7 =cut
8  
9 =head1 SYNOPSIS
10  
11 This namespace hierarchy contains classes that define a useful
12 object that also embeds the ability to create a reader or
13 writer.
14  
15 =head1 DESCRIPTION
16  
17 Classes in this namespace provide a set of useful attributes, etc. as
18 any normal class. But they also consume one of the roles:
19  
20 BoutrosLab::TSVStream::IO::Role::Fixed
21 BoutrosLab::TSVStream::IO::Role::Dyn
22  
23 which allows them to create a reader (or writer) object that can read
24 from (or write to) a stream or file, converting the text of the stream
25 to (or from) an object of this class.
26  
27 A class that consumes ...::IO::Role::Fixed deals with streams which
28 contain only the fixed defined fields for this class (as specified
29 by the class attribute _class).
30  
31 A class that consumes ...::IO::Role::Dyn deals with streams which
32 contain the fixed defined fields for this class (as specified
33 by the class attribute _class), but on each line the fixed attributes
34 are followed by a number of dynamic fields.
35  
36 The stream format is a series of lines. Each line consists of a
37 number of fields, separated by a tab character. The first line is
38 (usually) a text line that has the field names as the contents of
39 each field. (The field names are validated on reading to verify
40 match the definition of the object.) The remaining lines of the
41 stream consist of fields that contain data. The first fields
42 contain data for each of the attributes defined by the object (in
43 the order defined by the object). This data is validated using
44 the type specification for those attributes. For Dyn objects,
45 remaining fields contain text data for additional contents.
46 The number and content of these dynamic fields are determined at
47 run-time - there must be a consistant number of fields throughout
48 an entire stream, but the validity of the content cannot be
49 determined automatically (because each stream can have a different
50 set of dynamic fields, so there is no way for the code to know in
51 advance how to validate them).
52  
53 =head1 SEE ALSO
54  
55 =over
56  
57 =item BoutrosLab::TSVStream::Format::AnnovarInput::Human::Fixed
58  
59 =item BoutrosLab::TSVStream::Format::AnnovarInput::Human::Dyn
60  
61 =item BoutrosLab::TSVStream::Format::AnnovarInput::HumanNoChr::Fixed
62  
63 =item BoutrosLab::TSVStream::Format::AnnovarInput::HumanNoChr::Dyn
64  
65 These modules provide an example of how to write a module
66 able to read/write TSV stream text. You can use them as
67 templates either for adding a new module under this
68 hierarchy, or for writing your own TSV capable objects that
69 are not added to this namespace.
70  
71 They provide objects that use AnnovarInput file format for the text
72 form, and restrict the chrosome values to ones appropriate
73 to humans.
74  
75 =item BoutrosLab::TSVStream::Format::None::Dyn
76  
77 A class with no fixed fields, but only dynamic fields.
78 This is useful for dealing with dynamic TSV streams where
79 you don't know the stream contents, or for fixed field
80 formats where you don't want to have to create an object
81 to define the fields - and you are able to simply treat
82 the field contents as unconstrained text.
83  
84 There is no point in defining the corresponding
85 ...::None::Fixed module since that would only deal with
86 objects having no attributes, converting them to/from
87 streams containing only empty lines.
88  
89 =back
90  
91 =head1 AUTHOR
92  
93 John Macdonald - Boutros Lab
94  
95 =head1 ACKNOWLEDGEMENTS
96  
97 Paul Boutros, Phd, PI - Boutros Lab
98  
99 The Ontario Institute for Cancer Research
100  
101 =cut
102  
103 1;
104