License/Naming/Custom.pm

filter: Statementstmt 77.9% 46 / 59 Branchbran 62.5% 5 / 8 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 93.3% 14 / 15 Podpod 100% 4 / 4 totaltotal 80.2% 69 / 86 CC 5 SCAR 6.3
CC
5
Cov
76%
__ANON__
4.3
add_scheme
2.2
list_available_schemes
2.0
CRAP 1.9
« License/Naming.pm ↑ Summary License/Naming/SPDX.pm »
1 13 ▶use v5.40;
Subroutine BEGIN: called CC=1 SCAR=0.0
2 13 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
3  
4 13 ▶use feature 'class';
Subroutine BEGIN: called CC=1 SCAR=0.0
5 13 ▶no warnings 'experimental::class';
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 =head1 NAME
8  
9 String::License::Naming - names of licenses and license naming schemes
10  
11 =head1 VERSION
12  
13 Version v0.1.1
14  
15 =head1 SYNOPSIS
16  
17 use String::License::Naming::Custom;
18  
19 my $obj = String::License::Naming::Custom->new( schemes => [qw(spdx internal)] );
20  
21 my $schemes = [ $obj->list_schemes ]; # => is_deeply [ 'spdx', 'internal' ]
22  
23 my $license = [ grep { /^(Expat|Perl)$/ } $obj->list_licenses ]; # => is_deeply ['Perl']
24  
25 # use and prefer Debian-specific identifiers
26 $schemes = [ $obj->add_scheme('debian') ]; # => is_deeply [ 'debian', 'spdx', 'internal' ]
27  
28 $license = [ grep { /^(Expat|Perl)$/ } $obj->list_licenses ]; # => is_deeply [ 'Expat', 'Perl' ]
29  
30 =head1 DESCRIPTION
31  
32 L<String::License::Naming> enumerates supported licenses
33 matching an ordered set of naming schemes,
34 or enumerates the names of supported license naming schemes.
35  
36 Some licenses are known by different names.
37 E.g. the license "MIT" according to SPDX
38 is named "Expat" in Debian.
39  
40 Some licenses are not always represented.
41 E.g. "Perl" is a (discouraged) license in Debian
42 while it is a relationship of several licenses with SPDX
43 (and that expression is recommended in Debian as well).
44  
45 By default,
46 licenses are matched using naming schemes C<[ 'spdx', 'internal' ]>,
47 which lists all supported licenses,
48 preferrably by their SPDX name
49 or as fallback by an internal name.
50  
51 =cut
52  
53 package String::License::Naming::Custom v0.1.1;
54  
55 13 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
56 13 ▶use Log::Any ();
Subroutine BEGIN: called CC=1 SCAR=0.0
57 13 ▶use List::Util qw(uniq);
Subroutine BEGIN: called CC=1 SCAR=0.0
58 13 ▶use Regexp::Pattern::License 3.4.0;
Subroutine BEGIN: called CC=1 SCAR=0.0
59  
60 13 ▶use namespace::clean;
Subroutine BEGIN: called CC=1 SCAR=0.0
61  
62 13 ▶class String::License::Naming::Custom : isa(String::License::Naming);
Subroutine BEGIN: called CC=1 SCAR=0.0
63  
64 13 field $log;
65  
66 =head1 CONSTRUCTOR
67  
68 =over
69  
70 =item new
71  
72 my $names = String::License::Naming->new;
73  
74 my $spdx_names = String::License::Naming->new( schemes => ['spdx'] );
75  
76 Constructs and returns a String::License::Naming object.
77  
78 Takes an optional array as named argument B<schemes>.
79 both ordering by which name licenses should be presented,
80 and limiting which licenses to cover.
81  
82 When omitted,
83 the default schemes array C<[ 'spdx', 'internal' ]> is used,
84 which includes all supported licenses,
85 and they are presented by their SPDX name when defined
86 or otherwise by a semi-stable internal name.
87  
88 When passing an empty array reference,
89 all supported licenses are included,
90 presented by a semi-stable internal potentially multi-word description.
91  
92 =back
93  
94 =cut
95  
96 13 field $schemes : param = undef;
97  
98 # TODO: maybe support seeding explicit keys
99 13 field $keys;
100  
101 10 ▶ADJUST {
Subroutine __ANON__: called CC=4 SCAR=14.6
102 10 $log = Log::Any->get_logger;
103  
104 10 ▶ if ( defined $schemes ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $schemes) { } 8 2 10
105  
106 8 ▶ croak $log->fatal('parameter "schemes" must be an array reference')
Branch: 1 branch
BranchTrueFalseTotal
unless ref $schemes eq "ARRAY" 0 8 8
107 unless ref $schemes eq 'ARRAY';
108  
109 # TODO: die unless each arrayref entry is a string and supported
110  
111 8 my @uniq_schemes = uniq @$schemes;
112 8 ▶ if ( join( ' ', @$schemes ) ne join( ' ', @uniq_schemes ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (join(" ", @$schemes) ne join(" ", @uniq_schemes)) 0 8 8
113 0 $log->warn("duplicate scheme(s) omitted");
114 0 @$schemes = \@uniq_schemes;
115 }
116 }
117 else {
118 2 $schemes = [];
119 }
120  
121 10 $keys = [
122 String::License::Naming::resolve_shortnames( $keys, $schemes, 1 ) ];
123 }
124  
125 =head1 FUNCTIONS
126  
127 =over
128  
129 =item add_scheme
130  
131 Takes a string representing a license naming scheme to use,
132 favored over existing schemes in use.
133  
134 Returns array of schemes in use after addition.
135  
136 =cut
137  
138 3 ▶method add_scheme ($new_scheme)
Subroutine add_scheme: called CC=2 SCAR=7.9
Pod documented
139 {
140 3 ▶ if ( grep { $_ eq $new_scheme } @$schemes ) {
Branch: 1 branch
BranchTrueFalseTotal
if (grep {$_ eq $new_scheme;} @$schemes) 0 3 3
141 0 $log->warn("already included scheme $new_scheme not added");
142 0 return @$schemes;
143 }
144  
145 # TODO: validate new entry is string and supported, or die
146 3 unshift @$schemes, $new_scheme;
147  
148 3 return @$schemes;
149 }
150  
151 =item list_schemes
152  
153 Returns a list of license naming schemes in use.
154  
155 =cut
156  
157 7727 ▶method list_schemes ()
Subroutine list_schemes: called CC=1 SCAR=0.0
Pod documented
158 {
159 7727 return @$schemes;
160 }
161  
162 =item list_available_schemes
163  
164 Returns a list of all license naming schemes available.
165  
166 =cut
167  
168 0 ▶method list_available_schemes ()
Subroutine list_available_schemes: not called CC=1 SCAR=6.9
Pod documented
169 {
170 0 my ( $_prop, $_any, @result );
171  
172 0 $_prop = '(?:[a-z][a-z0-9_]*)';
173 0 $_any = '[a-z0-9_.()]';
174  
175 @result = uniq sort
176 0 map {/^(?:name|caption)\.alt\.org\.($_prop)$_any*/}
177 0 map { keys %{ $Regexp::Pattern::License::RE{$_} } }
178 0 grep {/^[a-z]/} keys %Regexp::Pattern::License::RE;
179  
180 0 return @result;
181 }
182  
183 =item list_licenses
184  
185 Returns a list of licensing patterns covered by this object instance,
186 each labeled by shortname according to current set of schemes.
187  
188 =cut
189  
190 4 ▶method list_licenses ()
Subroutine list_licenses: called CC=1 SCAR=0.0
Pod documented
191 {
192 4 return String::License::Naming::resolve_shortnames( $keys, $schemes );
193 }
194  
195 =back
196  
197 =encoding UTF-8
198  
199 =head1 AUTHOR
200  
201 Jonas Smedegaard C<< <dr@jones.dk> >>
202  
203 =head1 COPYRIGHT AND LICENSE
204  
205 Copyright © 2023 Jonas Smedegaard
206  
207 This program is free software:
208 you can redistribute it and/or modify it
209 under the terms of the GNU Affero General Public License
210 as published by the Free Software Foundation,
211 either version 3, or (at your option) any later version.
212  
213 This program is distributed in the hope that it will be useful,
214 but WITHOUT ANY WARRANTY;
215 without even the implied warranty
216 of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
217 See the GNU Affero General Public License for more details.
218  
219 You should have received a copy
220 of the GNU Affero General Public License along with this program.
221 If not, see <https://www.gnu.org/licenses/>.
222  
223 =cut
224  
225 13 1;
« License/Naming.pm ↑ Summary License/Naming/SPDX.pm »