/
LocationContainer.pm
261 lines (185 loc) · 8.28 KB
/
LocationContainer.pm
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
package Biome::Role::Location::LocationContainer;
use Biome::Role;
use MooseX::Role::Parameterized;
# we make no assumptions about the implementation of the
# class, just that the class has a short name (Segment, Location,
# Feature, etc).
parameter class => (
isa => 'Str',
);
parameter short_name => (
isa => 'Str',
required => 1
);
# Don't assume the plural ends with 's', but default to it
parameter plural => (
isa => 'Str',
lazy => 1,
default => sub { shift->short_name.'s' }
);
parameter layered => (
isa => 'Bool',
default => 0
);
role {
my $p = shift;
my ($class, $singular, $plural) = ($p->class, $p->short_name, $p->plural);
$class ||= 'Biome::Role::Location::Simple'; # any location consumer
if ($p->layered) {
$singular = "sub$singular";
$plural = "sub$plural";
}
has $singular => (
is => 'ro',
isa => "ArrayRef[$class]", # needs a subtype or role type
traits => ['Array'],
default => sub {[]},
handles => {
"get_$singular" => 'get',
"has_$singular" => 'count',
"all_$plural" => 'elements',
"remove_$plural" => 'clear'
}
);
# implementing class must provide this, is implementation-specific
requires "add_$singular";
};
no Biome::Role;
1;
__END__
=head1 NAME
Biome::Role::Location::LocationContainer - Parameterizable role for a Location
container.
=head1 SYNOPSIS
package Foo;
use Biome;
with 'Biome::Role::Location::LocationContainer' =>
{ class => 'Biome::SeqFeature::Generic',
abbrev => 'Feature'};
# Foo now can contain an array of Biome::SeqFeature::Generic. Adding
# a new
=head1 DESCRIPTION
Simple parameterizable role for anything that has one or more Locations
(Biome::Role::Location::Simple consumers). This requires the implementation
provide several things:
=over3
=item *
=item *
A method to add new Locations; as this is implementation-specific,
this is required for anything consuming this class. For instance, a consumer
=back
=head1 SUBROUTINES/METHODS
<TODO>
A separate section listing the public components of the module's interface.
These normally consist of either subroutines that may be exported, or methods
that may be called on objects belonging to the classes that the module provides.
Name the section accordingly.
In an object-oriented module, this section should begin with a sentence of the
form "An object of this class represents...", to give the reader a high-level
context to help them understand the methods that are subsequently described.
=head1 DIAGNOSTICS
<TODO>
A list of every error and warning message that the module can generate
(even the ones that will "never happen"), with a full explanation of each
problem, one or more likely causes, and any suggested remedies.
=head1 CONFIGURATION AND ENVIRONMENT
<TODO>
A full explanation of any configuration system(s) used by the module,
including the names and locations of any configuration files, and the
meaning of any environment variables or properties that can be set. These
descriptions must also include details of any configuration language used.
=head1 DEPENDENCIES
<TODO>
A list of all the other modules that this module relies upon, including any
restrictions on versions, and an indication of whether these required modules are
part of the standard Perl distribution, part of the module's distribution,
or must be installed separately.
=head1 INCOMPATIBILITIES
<TODO>
A list of any modules that this module cannot be used in conjunction with.
This may be due to name conflicts in the interface, or competition for
system or program resources, or due to internal limitations of Perl
(for example, many modules that use source code filters are mutually
incompatible).
=head1 BUGS AND LIMITATIONS
There are no known bugs in this module.
User feedback is an integral part of the evolution of this and other Biome and
BioPerl modules. Send your comments and suggestions preferably to one of the
BioPerl mailing lists. Your participation is much appreciated.
bioperl-l@bioperl.org - General discussion
http://bioperl.org/wiki/Mailing_lists - About the mailing lists
Patches are always welcome.
=head2 Support
Please direct usage questions or support issues to the mailing list:
L<bioperl-l@bioperl.org>
rather than to the module maintainer directly. Many experienced and reponsive
experts will be able look at the problem and quickly address it. Please include
a thorough description of the problem with code and data examples if at all
possible.
=head2 Reporting Bugs
Preferrably, Biome bug reports should be reported to the GitHub Issues bug
tracking system:
http://github.com/cjfields/biome/issues
Bugs can also be reported using the BioPerl bug tracking system, submitted via
the web:
http://bugzilla.open-bio.org/
=head1 EXAMPLES
<TODO>
Many people learn better by example than by explanation, and most learn better
by a combination of the two. Providing a /demo directory stocked with
well-commented examples is an excellent idea, but your users might not have
access to the original distribution, and the demos are unlikely to have been
installed for them. Adding a few illustrative examples in the documentation
itself can greatly increase the "learnability" of your code.
=head1 FREQUENTLY ASKED QUESTIONS
<TODO>
Incorporating a list of correct answers to common questions may seem like extra
work (especially when it comes to maintaining that list), but in many cases it
actually saves time. Frequently asked questions are frequently emailed
questions, and you already have too much email to deal with. If you find
yourself repeatedly answering the same question by email, in a newsgroup, on a
web site, or in person, answer that question in your documentation as well. Not
only is this likely to reduce the number of queries on that topic you
subsequently receive, it also means that anyone who does ask you directly can
simply be directed to read the fine manual.
=head1 COMMON USAGE MISTAKES
<TODO>
This section is really "Frequently Unasked Questions". With just about any kind
of software, people inevitably misunderstand the same concepts and misuse the
same components. By drawing attention to these common errors, explaining the
misconceptions involved, and pointing out the correct alternatives, you can once
again pre-empt a large amount of unproductive correspondence. Perl itself
provides documentation of this kind, in the form of the perltrap manpage.
=head1 SEE ALSO
<TODO>
Often there will be other modules and applications that are possible
alternatives to using your software. Or other documentation that would be of use
to the users of your software. Or a journal article or book that explains the
ideas on which the software is based. Listing those in a "See Also" section
allows people to understand your software better and to find the best solution
for their problem themselves, without asking you directly.
By now you have no doubt detected the ulterior motive for providing more
extensive user manuals and written advice. User documentation is all about not
having to actually talk to users.
=head1 (DISCLAIMER OF) WARRANTY
<TODO>
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
=head1 ACKNOWLEDGEMENTS
<TODO>
Acknowledging any help you received in developing and improving your software is
plain good manners. But expressing your appreciation isn't only courteous; it's
also enlightened self-interest. Inevitably people will send you bug reports for
your software. But what you'd much prefer them to send you are bug reports
accompanied by working bug fixes. Publicly thanking those who have already done
that in the past is a great way to remind people that patches are always
welcome.
=head1 AUTHOR
Chris Fields C<< <cjfields at bioperl dot org> >>
=head1 LICENCE AND COPYRIGHT
Copyright (c) 2011 Chris Fields (cjfields at bioperl dot org). All rights reserved.
followed by whatever licence you wish to release it under.
For Perl code that is often just:
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See L<perlartistic>.