lib/Bio/NEXUS/Functions.pm

filter: Statementstmt 65.4% 91 / 139 Branchbran 56.9% 41 / 72 Conditioncond 38.1% 8 / 21 MC/DCmcdc 7.1% 1 / 14 Subroutinesub 68.1% 15 / 22 Podpod n/a totaltotal 58.2% 156 / 268 CC 47 SCAR 28.3
CC
47
Cov
60%
_rebuild_numbers
72.0
_is_same_array
20.0
_parse_nexus_words
17.2
CRAP 16.9
« lib/Bio/NEXUS/UnalignedBlock.pm ↑ Summary lib/Bio/NEXUS.pm »
1 #################################################################
2 # Functions.pm - internal functions for reading, parsing, arrays
3 #################################################################
4 # Original version thanks to Tom Hladish
5 #
6 # $Id: Functions.pm,v 1.16 2012/02/07 21:49:27 astoltzfus Exp $
7  
8 #################### START POD DOCUMENTATION ##################
9  
10 =head1 NAME
11  
12 Bio::NEXUS::Functions - Provides private utiliy functions for the module
13  
14 =head1 SYNOPSIS
15  
16 =head1 DESCRIPTION
17  
18 This package provides private functions that are not object-specific.
19  
20 =head1 COMMENTS
21  
22 =head1 FEEDBACK
23  
24 All feedback (bugs, feature enhancements, etc.) is greatly appreciated.
25  
26 =head1 AUTHORS
27  
28 Original version by Thomas Hladish (tjhladish at yahoo)
29  
30 =head1 VERSION
31  
32 $Revision: 1.16 $
33  
34 =head1 METHODS
35  
36 =cut
37  
38 package Bio::NEXUS::Functions;
39  
40 35 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
41 #use Data::Dumper; # XXX this is not used, might as well not import it!
42 #use Carp; # XXX this is not used, might as well not import it!
43 35 ▶use Bio::NEXUS::Util::Exceptions;
Subroutine BEGIN: called CC=1 SCAR=0.0
44 35 ▶use vars qw(@EXPORT @EXPORT_OK @ISA $VERSION);
Subroutine BEGIN: called CC=1 SCAR=0.0
45 35 ▶use Bio::NEXUS; $VERSION = $Bio::NEXUS::VERSION;
Subroutine BEGIN: called CC=1 SCAR=0.0
46 35 ▶use Exporter ();
Subroutine BEGIN: called CC=1 SCAR=0.0
47  
48 35 @ISA = qw ( Exporter );
49 35 @EXPORT = qw(
50 &_slurp
51 &_parse_nexus_words
52 &_ntsa
53 &_stna
54 &_quote_if_needed
55 &_nexus_formatted
56 &_is_comment
57 &_is_number
58 &_is_dec_number
59 &_sci_to_dec
60 &_unique
61 &_nonunique
62 &_share_elements
63 &_fast_in_array
64 &_in_array
65 &_is_same_array
66 );
67  
68 ## READING & PARSING FUNCTIONS:
69  
70 =begin comment
71  
72 Name : _slurp
73 Usage : $file_content = _slurp($filename);
74 Function: reads an entire file into memory
75 Returns : none
76 Args : file name (string)
77  
78 =end comment
79  
80 =cut
81  
82 69 ▶sub _slurp {
Subroutine _slurp: called CC=2 SCAR=7.1
83 69 my ($filename) = @_;
84 69 ▶ open my $fh, '<', "$filename"
Condition33%1/3
"$filename" || 'Bio::NEXUS::Util::Exceptions::FileError'->throw('error', "ERROR: Could not open filename <$filename> for input; $!")
l!l&&r!l&&!r
6900
MC/DC0%0/2
"$filename" || 'Bio::NEXUS::Util::Exceptions::FileError'->throw('error', "ERROR: Could not open filename <$filename> for input; $!")
"$filename" 'Bio::NEXUS::Util::Exceptions::FileError'->throw('error', "ERROR: Could not open filename <$filename> for input; $!")
Truth table33%1/3
A || B
A= "$filename"B= 'Bio::NEXUS::Util::Exceptions::FileError'->throw('error', "ERROR: Could not open filename <$filename> for input; $!")
ABresult
1X1
011
000
85 || Bio::NEXUS::Util::Exceptions::FileError->throw(
86 'error' => "ERROR: Could not open filename <$filename> for input; $!"
87 );
88 69 my $file_content = do { local ($/); <$fh> };
89 69 return $file_content;
90 }
91  
92 =begin comment
93  
94 Title : _parse_nexus_words
95 Usage : $parsed_words = _parse_nexus_words($buffer);
96 Function: parse a string of text into "words" (as defined in the NEXUS standard)
97 Returns : an array ref of "words" and punctuation marks. Single-quoted expressions are single "words". Double quotes are not supported.
98 Args : text buffer
99 Notes : this method has replaced _parse_string_tokens(), which did not conform to the NEXUS standard in all its quirky splendor (particularly with regard to punctuation)
100  
101 =end comment
102  
103 =cut
104  
105 559 ▶sub _parse_nexus_words {
Subroutine _parse_nexus_words: called CC=17 SCAR=28.5
106 559 my $buffer = shift;
107 559 ▶ if ( not defined $buffer ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $buffer) 0 559 559
108 0 Bio::NEXUS::Util::Exceptions::BadArgs->throw(
109 'error' => '_parse_nexus_words() requires a text string argument (the text to be parsed)'
110 );
111 }
112 559 my @words;
113 559 my ( $word, $in_quotes ) = ( q{}, 0 );
114  
115 559 my @chars = split( //, $buffer );
116 559 my $comment_level = 0;
117  
118 # iterate through the characters
119 559 ▶ for ( my $i = 0; $i < @chars; $i++ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i < @chars) 66989 559 67548
120 66989 my $char = $chars[$i];
121 66989 my $next = $chars[ $i + 1 ];
122  
123 66989 ▶ if ($comment_level) { # if we are in a comment already
Branch: 6 branches
BranchTrueFalseTotal
if ($comment_level) { } 1790 65199 66989
elsif ($char eq q[']) { } 428 64771 65199
elsif ($in_quotes) { } 4669 60102 64771
elsif ($char eq '[') { } 90 60012 60102
elsif ($char =~ m([\[\]\-(){}/\\,;:=*"`+<>])) { } 5821 54191 60012
elsif ($char =~ /\s/) { } 6775 47416 54191
124 1790 ▶ $comment_level++ if ( $char eq '[' );
Branch: 1 branch
BranchTrueFalseTotal
if $char eq "[" 0 1790 1790
125 1790 ▶ $comment_level-- if ( $char eq ']' );
Branch: 1 branch
BranchTrueFalseTotal
if $char eq "]" 90 1700 1790
126 1790 $word .= $char;
127 }
128  
129 # If we see a quote
130 elsif ( $char eq q{'} ) {
131  
132 # and we're already inside quotes . . .
133 428 ▶ if ($in_quotes) {
Branch: 1 branch
BranchTrueFalseTotal
if ($in_quotes) { } 214 214 428
134  
135 # check to see if this is an escaped (doubled single) quote,
136 # (unless we're already at the end of the string to be parsed).
137 214 ▶ if ( defined $next && $next eq q{'} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $next and $next eq q[']) { } 0 214 214
Condition66%2/3
defined $next and $next eq "'"
!ll&&!rl&&r
82060
MC/DC0%0/2
defined $next and $next eq "'"
defined $next $next eq "'"
Truth table66%2/3
A and B
A= defined $nextB= $next eq "'"
ABresult
0X0
100
111
138  
139 # If it is, append it to the current word;
140 0 $word .= $char;
141 }
142 else {
143  
144 # otherwise, close off the quoted string
145 214 $in_quotes--;
146  
147 # Replace spaces with underscores (according to NEXUS, they're equivalent)
148 #
149 # This may not be correct. Certainly TreeBASE doesn't like it
150 # when we use both quoted strings and underscores in them
151 214 $word =~ s/ /_/g;
152  
153 # Push it onto the word list, after
154 # dealing with funny apostrophe business
155 214 push @words, _ntsa($word);
156  
157 # And clean the slate
158 214 $word = q{};
159 }
160 }
161 else {
162  
163 # If we weren't in quotes before, we are now
164 214 $in_quotes++;
165 }
166 }
167 elsif ($in_quotes) {
168  
169 # We're in a quoted string, so anything can be part of the word
170 4669 $word .= $char;
171 }
172 elsif ( $char eq '[' ) { # hit new comment, level 0 (bug if we just finished one)
173 90 $comment_level++;
174 90 $word .= $char;
175 }
176  
177 # If we see NEXUS-style punctuation
178 elsif ( $char =~ /[\[\]\-(){}\/\\,;:=*"`+<>]/ ) {
179
180 5821 ▶ push @words, &_ntsa($word)
Branch: 1 branch
BranchTrueFalseTotal
unless $word eq "" 2617 3204 5821
181  
182 # $word will be q{} if there was a preceding space;
183 # otherwise, it will contain some string
184 unless $word eq q{};
185  
186 # then that counts as a word (we'll deal with pos/neg
187 # numbers later in _rebuild_numbers() if that gets called)
188 5821 push @words, $char;
189 5821 $word = q{};
190 }
191  
192 # If we see whitespace
193 elsif ( $char =~ /\s/ ) {
194  
195 # then we just finished a [probably] normal, space-delimited word
196 6775 ▶ push @words, &_ntsa($word)
Branch: 1 branch
BranchTrueFalseTotal
unless $word eq "" 1965 4810 6775
197  
198 unless $word eq q{};
199  
200 # although we don't want to keep pushing it
201 # if there are multiple spaces, so we empty $word
202 6775 $word = q{};
203 }
204  
205 # If $word isn't quoted, and $char is neither punctuation nor whitespace
206 else {
207 47416 $word .= $char;
208 }
209 }
210  
211 559 ▶ push @words, $word unless $word eq q{};
Branch: 1 branch
BranchTrueFalseTotal
unless $word eq "" 397 162 559
212 559 return \@words;
213 }
214  
215 0 ▶sub _rebuild_numbers {
Subroutine _rebuild_numbers: not called CC=8 SCAR=42.8
216 0 my $words = shift;
217 0 my @new_words;
218  
219 # Don't bother checking whether the last word is a '+' or '-'
220 0 ▶ for ( my $i = 0; $i < ( @$words - 1 ); $i++ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i < @$words - 1) 0 0 0
221 0 my $word = $words->[$i];
222 0 my $next = $words->[ $i + 1 ]; # There will always be a next
223  
224 # my $next_next = defined $words[$i +2] ? $words[$i+2] : q{};
225 # There might be a previous
226 0 ▶ my $last = $i == 0 ? undef: $words->[ $i - 1 ];
Branch: 1 branch
BranchTrueFalseTotal
$i == 0 ? : 0 0 0
227  
228 0 ▶ if ( $word eq '-' || $word eq '+' ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($word eq '-' or $word eq '+') { } 0 0 0
Condition0%0/3
$word eq "-" or $word eq "+"
l!l&&r!l&&!r
000
MC/DC0%0/2
$word eq "-" or $word eq "+"
$word eq "-" $word eq "+"
Truth table0%0/3
A or B
A= $word eq "-"B= $word eq "+"
ABresult
1X1
011
000
229 0 ▶ if ( my ( $num, $exp ) = $next =~ /^([\d.]+)(e)?/i ) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = $next =~ /^([\d.]+)(e)?/i) 0 0 0
230 0 ▶ if ( _is_dec_number($num) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (_is_dec_number($num)) 0 0 0
231 0 $word .= $next;
232 0 $i++;
233 0 ▶ if ($exp) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exp) 0 0 0
234  
235 }
236 }
237 }
238 }
239 else {
240 0 push @new_words, $word;
241 }
242 }
243 0 return \@new_words;
244 }
245  
246 =begin comment
247  
248 Title : _ntsa (nexus to standard apostrophe)
249 Usage : $standard_word = $block->_ntsa($nexus_word);
250 Function: change doubled single quotes to single single quotes (apostrophes)
251 Returns : a standard english word (or phrase)
252 Args : a nexus "word"
253 Notes : See NEXUS definition of "word" for an explanation
254
255 =end comment
256  
257 =cut
258  
259 4796 ▶sub _ntsa {
Subroutine _ntsa: called CC=1 SCAR=0.0
260 4796 my $nexus_word = shift;
261 4796 $nexus_word =~ s/[^']''[^']/'/g;
262 4796 return $nexus_word;
263 }
264  
265 =begin comment
266  
267 Title : _stna (standard to nexus apostrophe)
268 Usage : $nexus_word = $block->_stna($standard_word);
269 Function: change single single quotes (apostrophes) to double single quotes
270 Returns : a nexus "word"
271 Args : a standard english word (or phrase)
272 Notes : See NEXUS definition of "word" for an explanation
273
274 =end comment
275  
276 =cut
277  
278 1189 ▶sub _stna {
Subroutine _stna: called CC=1 SCAR=0.0
279 1189 my $standard_word = shift;
280 1189 $standard_word =~ s/[^']'[^']/''/g;
281 1189 return $standard_word;
282 }
283  
284 =begin comment
285  
286 Title : _quote_if_needed
287 Usage : $string = Bio::NEXUS::Block::_quote_if_needed($string);
288 Function: put single quotes around string if it contains spaces or NEXUS punctuation
289 Returns : a string, in single quotes if necessary
290 Args : a string
291
292 =end comment
293  
294 =cut
295  
296 1189 ▶sub _quote_if_needed {
Subroutine _quote_if_needed: called CC=2 SCAR=6.9
297 1189 my $nexus_word = shift;
298 1189 ▶ if ( $nexus_word =~ /[-\s(){}\[\]\/\\,;:=+*<>`'"]/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($nexus_word =~ m([-\s(){}\[\]/\\,;:=+*<>`'"])) { } 4 1185 1189
299 4 return "'$nexus_word'";
300 }
301 else {
302 1185 return $nexus_word;
303 }
304 }
305  
306 =begin comment
307  
308 Title : _nexus_formatted
309 Usage : $string = Bio::NEXUS::Block::_nexus_formatted($string);
310 Function: escape apostrophes and quote strings as needed for NEXUS output
311 Returns : a string
312 Args : a string
313
314 =end comment
315  
316 =cut
317  
318 1189 ▶sub _nexus_formatted {
Subroutine _nexus_formatted: called CC=1 SCAR=0.0
319 1189 my $nexus_word = shift;
320 1189 $nexus_word = _quote_if_needed( _stna($nexus_word) );
321 1189 return $nexus_word;
322 }
323  
324 =begin comment
325  
326 Name : _is_comment
327 Usage : $boolean = _is_comment($string);
328 Function: tests whether something looks like a comment
329 Returns : boolean
330 Args : string to test
331  
332 =end comment
333  
334 =cut
335  
336 2139 ▶sub _is_comment {
Subroutine _is_comment: called CC=2 SCAR=6.9
337 2139 my ($string) = @_;
338 2139 ▶ if ( $string =~ /^\[.*\]$/s ) { return 1 }
Branch: 1 branch
BranchTrueFalseTotal
if ($string =~ /^\[.*\]$/s) { } 358 1781 2139
339 1781 else { return 0 }
340 }
341  
342 =begin comment
343  
344 Title : _is_dec_number
345 Usage : if ( _is_dec_number($num) ) { do_something() };
346 Function: verifies that a number is a normal decimal number (e.g. 3 or 9.41)
347 Returns : 1 if $num is a number, otherwise 0
348 Args : a number
349  
350 =end comment
351  
352 =cut
353  
354 861 ▶sub _is_dec_number {
Subroutine _is_dec_number: called CC=5 SCAR=17.0
355 861 my ($number) = @_;
356  
357 861 ▶ return 0 unless defined $number && length $number;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $number and length $number 0 861 861
Condition33%1/3
defined $number and length $number
!ll&&!rl&&r
00861
MC/DC0%0/2
defined $number and length $number
defined $number length $number
Truth table33%1/3
A and B
A= defined $numberB= length $number
ABresult
0X0
100
111
358  
359 861 my $number_regex = qr/^[-+]? # positive or negative
360 (?: \d+ # e.g., 523
361 | \d*[.]\d+ # 3.14 or .45
362 | \d+[.]\d* # 212. or 212.0
363 )
364 $/x;
365  
366 861 ▶ return 0 unless defined $number && $number =~ $number_regex;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $number and $number =~ /$number_regex/x 4 857 861
Condition66%2/3
defined $number and $number =~ /$number_regex/x
!ll&&!rl&&r
04857
MC/DC50%1/2
defined $number and $number =~ /$number_regex/x
defined $number $number =~ /$number_regex/x
Truth table66%2/3
A and B
A= defined $numberB= $number =~ /$number_regex/x
ABresult
0X0
100
111
367  
368 857 return 1;
369 }
370  
371 =begin comment
372  
373 Title : _is_number
374 Usage : if ( _is_number($num) ) { do_something() };
375 Function: verifies that a number is of reasonable form (such as 0.4 or 6.1e2.1)
376 Returns : 1 if $num is a number, otherwise 0
377 Args : a number
378  
379 =end comment
380  
381 =cut
382  
383 761 ▶sub _is_number {
Subroutine _is_number: called CC=5 SCAR=17.0
384 761 my ($number) = @_;
385  
386 761 ▶ return 0 unless defined $number && length $number;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $number and length $number 0 761 761
Condition33%1/3
defined $number and length $number
!ll&&!rl&&r
00761
MC/DC0%0/2
defined $number and length $number
defined $number length $number
Truth table33%1/3
A and B
A= defined $numberB= length $number
ABresult
0X0
100
111
387  
388 761 my ( $num, $exp ) = $number =~ /^([^e]+)(?:e([^e]+))?$/i;
389  
390 761 ▶ return 0 unless _is_dec_number($num);
Branch: 1 branch
BranchTrueFalseTotal
unless _is_dec_number($num) 0 761 761
391  
392 761 ▶ return _is_dec_number($exp) if defined $exp;
Branch: 1 branch
BranchTrueFalseTotal
if defined $exp 4 757 761
393  
394 757 return 1;
395 }
396  
397 =begin comment
398  
399 Title : _sci_to_dec
400 Usage : $decimal = _sci_to_dec($scientic_notation);
401 Function: Changes scientific notation to decimal notation
402 Returns : scalar (a number)
403 Args : scalar (a number), possibly in scientific notation
404  
405 =end comment
406  
407 =cut
408  
409 88 ▶sub _sci_to_dec {
Subroutine _sci_to_dec: called CC=4 SCAR=14.2
410 88 my ($sci_num) = @_;
411  
412 88 $sci_num =~ s/\s//g;
413 88 ▶ return $sci_num if _is_dec_number($sci_num);
Branch: 1 branch
BranchTrueFalseTotal
if _is_dec_number($sci_num) 84 4 88
414  
415 4 my ( $num, $exp ) = $sci_num =~ /^ ([^e]+) e ([^e]+) $/ix;
416  
417 4 ▶ return 0 unless ( _is_dec_number($num) && _is_dec_number($exp) );
Branch: 1 branch
BranchTrueFalseTotal
unless _is_dec_number($num) and _is_dec_number($exp) 0 4 4
Condition33%1/3
_is_dec_number($num) and _is_dec_number($exp)
!ll&&!rl&&r
004
MC/DC0%0/2
_is_dec_number($num) and _is_dec_number($exp)
_is_dec_number($num) _is_dec_number($exp)
Truth table33%1/3
A and B
A= _is_dec_number($num)B= _is_dec_number($exp)
ABresult
0X0
100
111
418  
419 4 my $dec_num = $num * ( 10**$exp );
420 4 return $dec_num;
421 }
422  
423 ## ARRAY FUNCTIONS:
424  
425 =begin comment
426  
427 Name : _any
428 Usage : _any($filename);
429 Function: reads an entire file into memory
430 Returns : none
431 Args : file name (string)
432  
433 =end comment
434  
435 =cut
436  
437 0 ▶sub _unique {
Subroutine _unique: not called CC=1 SCAR=6.9
438 0 my (@array) = @_;
439 0 my %seen = ();
440  
441 # from perl cookbook. fast, and preserves order
442 0 my @unique = grep { !$seen{$_}++ } @array;
443 0 return @unique;
444 }
445  
446 0 ▶sub _nonunique {
Subroutine _nonunique: not called CC=1 SCAR=6.9
447 0 my (@array) = @_;
448 0 my %seen = ();
449 0 my @nonunique = grep { $seen{$_}++ } @array;
450 0 return @nonunique;
451 }
452  
453 0 ▶sub _share_elements {
Subroutine _share_elements: not called CC=3 SCAR=24.8
454 0 my ( $array1, $array2 ) = @_;
455 0 for my $element1 (@$array1) {
456 0 ▶ if ( &in_array( $array2, $element1 ) ) { return 1; }
Branch: 1 branch
BranchTrueFalseTotal
if (&in_array($array2, $element1)) 0 0 0
457 }
458 0 return 0;
459 }
460  
461 0 ▶sub _fast_in_array {
Subroutine _fast_in_array: not called CC=3 SCAR=24.8
462 0 my ( $array, $element ) = @_;
463 0 for (@$array) {
464 0 ▶ if ( $element eq $_ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($element eq $_) 0 0 0
465 0 return 1;
466 }
467 }
468 0 return 0;
469 }
470  
471 0 ▶sub _in_array {
Subroutine _in_array: not called CC=3 SCAR=24.8
472 0 my ( $array, $test ) = @_;
473 0 my $match = 0;
474 0 for (@$array) {
475 0 ▶ $match++ if $_ eq $test;
Branch: 1 branch
BranchTrueFalseTotal
if $_ eq $test 0 0 0
476 }
477 0 return $match;
478 }
479  
480 0 ▶sub _is_same_array {
Subroutine _is_same_array: not called CC=4 SCAR=30.0
481 0 my ( $array, $test ) = @_;
482 0 ▶ return 1 if $array eq $test;
Branch: 1 branch
BranchTrueFalseTotal
if $array eq $test 0 0 0
483 0 ▶ return 0 unless scalar @$array == scalar @$test;
Branch: 1 branch
BranchTrueFalseTotal
unless scalar @$array == scalar @$test 0 0 0
484  
485 0 my $astr = join '', sort @$array;
486 0 my $tstr = join '', sort @$test;
487 0 ▶ return 1 if $astr eq $tstr;
Branch: 1 branch
BranchTrueFalseTotal
if $astr eq $tstr 0 0 0
488 0 return 0;
489 }
490  
491 35 1;
« lib/Bio/NEXUS/UnalignedBlock.pm ↑ Summary lib/Bio/NEXUS.pm »