]>
iEval git - text-levenshtein-edlib.git/blob - lib/Text/Levenshtein/Edlib.pm
1 package Text
::Levenshtein
::Edlib
;
7 use parent qw
/Exporter/;
27 (all
=> [ @constants, qw
/align distance to_cigar/ ], constants
=> \
@constants);
28 our @EXPORT_OK = ( @
{ $EXPORT_TAGS{'all'} } );
29 our @EXPORT = ( @
{ $EXPORT_TAGS{'constants'} } );
30 our $VERSION = '0.001';
33 XSLoader
::load
('Text::Levenshtein::Edlib', $VERSION);
36 # This AUTOLOAD is used to 'autoload' constants from the constant()
41 ($constname = $AUTOLOAD) =~ s/.*:://;
42 croak
"&Text::Levenshtein::Edlib::constant not defined" if $constname eq 'constant';
43 my ($error, $val) = constant
($constname);
44 if ($error) { croak
$error; }
47 *$AUTOLOAD = sub { $val };
53 my ($q, $t, $k, $mode, $task) = @_;
55 $mode //= EDLIB_MODE_NW
();
56 $task //= EDLIB_TASK_PATH
();
57 my $result = edlibAlign
($q, $t, $k, $mode, $task);
58 my ($dist, $alpha_len, $end, $start, $align) = @
$result;
59 return {} if $dist == -1;
61 $ret{editDistance
} = $dist;
62 $ret{alphabetLength
} = $alpha_len;
63 $ret{endLocations
} = $end if defined $end;
64 $ret{startLocations
} = $start if defined $start;
65 $ret{alignment
} = $align if defined $align;
71 align
($q, $t, $k)->{editDistance
}
75 my ($align, $format) = @_;
76 $align = pack 'C*', @
$align;
77 $format //= EDLIB_CIGAR_STANDARD
();
78 edlibAlignmentToCigar
($align, $format);
88 Text::Levenshtein::Edlib - XS edit distance and optimal alignment path calculation
94 use Text::Levenshtein::Edlib qw/:all/;
95 say distance 'kitten', 'sitting'; # prints '3'
97 if !defined distance 'kitten', 'sitting', 2; # prints 'Distance > 2!'
99 my $align = align('kitten', 'sitting');
100 say "Edit distance is: $align->{editDistance}";
101 say "Alphabet length is: $align->{alphabetLength}";
102 say "Start locations are: @{$align->{startLocations}}";
103 say "End locations are: @{$align->{endLocations}}";
104 say "Alignment path is: @{$align->{alignment}}";
105 say "Alignment path (in CIGAR format): ", to_cigar $align->{alignment};
106 say "Alignment path (in extended CIGAR format): ",
107 to_cigar $align->{alignment}, EDLIB_CIGAR_EXTENDED;
111 Text::Levenshtein::Edlib is a wrapper around the edlib library that
112 computes Levenshtein edit distance and optimal alignment path for a
115 It B<does not handle UTF-8 strings>, for those
116 L<Text::Levenshtein::XS> can compute edit distance but not alignment
119 This module has two functions:
123 =item B<distance>(I<$query>, I<$target>, [I<$max_distance>])
125 This is the basic interface to the library. It is compatible with the
126 function of the same name in L<Text::Levenshtein::XS>.
128 It returns the edit distance between the two given strings. If the
129 third argument is specified, and the edit distance is greater than the
130 value of the third argument, then the function finishes the
131 computation early and returns undef.
133 =item B<align>(I<$query>, I<$target>, [I<$max_distance>, [I<$mode>, [I<$task>]]])
135 This is the full-featured interface to the library.
137 It returns a hashref with the following keys:
141 =item C<editDistance>
143 The edit distance of the two strings.
145 =item C<alphabetLength>
147 The number of different characters in the query and target together.
149 =item C<endLocations>
151 Array of zero-based positions in target where optimal alignment paths
152 end. If gap after query is penalized, gap counts as part of query
155 =item C<startLocations>
157 Array of zero-based positions in target where optimal alignment paths
158 start, they correspond to endLocations. If gap before query is
159 penalized, gap counts as part of query (NW), otherwise not.
163 Alignment is found for first pair of start and end locations.
164 Alignment is sequence of numbers: 0, 1, 2, 3. 0 stands for match. 1
165 stands for insertion to target. 2 stands for insertion to query. 3
166 stands for mismatch. You can use the C<EDLIB_EDOP_*> constants instead
167 of 0, 1, 2, and 3. Alignment aligns query to target from begining of
168 query till end of query. If gaps are not penalized, they are not in
173 The third argument, I<$max_distance>, works similarly to the third
174 argument of B<distance>: if the distance is more than its value, this
175 function returns an empty hashref. Default value is -1, which disables
178 The fourth argument, I<$mode>, chooses how Edlib should treat gaps
179 before and after query. The options are:
183 =item C<EDLIB_MODE_NW> (default)
185 Global method - gaps are not ignored. This is the standard Levenshtein
186 distance, and is the default if I<$mode> is not specified.
188 =item C<EDLIB_MODE_SHW>
190 Prefix method - gaps at query end are ignored. So the edit distance
191 between C<AACT> and C<AACTGGC> is 0, because we can ignore the C<GGC>
194 =item C<EDLIB_MODE_HW>
196 Infix method - gaps at both query start and end are ignored. So the
197 edit distance between C<ACT> and C<CGACTGAC> is 0, because C<CG> at
198 the beginning and C<GAC> at the end of the target are ignored.
202 The fifth argument, I<$task>, chooses what we want to compute.
203 If set to C<EDLIB_TASK_PATH> (default), all the keys described above will be computed.
204 If set to C<EDLIB_TASK_LOC>, all keys except for C<alignment> will be computed.
205 If set to C<EDLIB_TASK_DISTANCE>, all keys except for C<alignment> and C<startLocations> will be computed.
206 The less we compute, the faster the function will run.
212 All constants by default. You can export the functions C<align> and
213 C<distance> and any of the constants below. You can use the tags
214 C<:constants> to export every constant, and C<:all> to export every
215 constant, C<align> and C<distance>.
217 =head2 Exportable constants
236 L<https://github.com/Martinsos/edlib/>, L<http://martinsosic.com/edlib/edlib_8h.html>
240 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
242 =head1 COPYRIGHT AND LICENSE
244 Copyright (C) 2017 by Marius Gavrilescu
246 This library is free software; you can redistribute it and/or modify
247 it under the same terms as Perl itself, either Perl version 5.22.3 or,
248 at your option, any later version of Perl 5 you may have available.
This page took 0.073527 seconds and 4 git commands to generate.