lib/FunctionalPerl.pm

filter: Statementstmt 67.6% 48 / 71 Branchbran 28.5% 4 / 14 Conditioncond 0.0% 0 / 2 MC/DCmcdc 0.0% 0 / 1 Subroutinesub 80.0% 8 / 10 Podpod 0.0% 0 / 4 totaltotal 58.8% 60 / 102 CC 12 SCAR 18.1
CC
12
Cov
60%
import
16.0
split_moduledesc
6.0
export_desc2pod
6.0
CRAP 6.1
« lib/FP/Git/Repository.pm ↑ Summary intro/.expansion-more_tailcalls »
1 #
2 # Copyright (c) 2015-2023 Christian Jaeger, copying@christianjaeger.ch
3 #
4 # This is free software, offered under either the same terms as perl 5
5 # or the terms of the Artistic License version 2 or the terms of the
6 # MIT License (Expat version). See the file COPYING.md that came
7 # bundled with this file.
8 #
9  
10 # Depends: ()
11  
12 =head1 NAME
13  
14 FunctionalPerl - functional programming in Perl
15  
16 =head1 SYNOPSIS
17  
18 1 ▶ use FunctionalPerl;
Subroutine BEGIN: called CC=1 SCAR=0.0
19 FunctionalPerl->VERSION # or $FunctionalPerl::VERSION
20  
21 # The actual modules are in the FP:: namespace hierarchy, like:
22 use FP::List;
23  
24 # But you can also import sets of modules from here, e.g.:
25 #use FunctionalPerl qw(:sequences :repl);
26  
27 =head1 DESCRIPTION
28  
29 Allows Perl programs to be written with fewer side effects.
30  
31 See the L<Functional Perl|http://functional-perl.org/> home page.
32  
33 =head1 EXPORTS
34  
35 L<FunctionalPerl> also acts as a convenience re-exporter, offering
36 tags to load sets of modules. (It also has one normal export:
37 `expand_import_tags`, see below.)
38  
39 Note that the tags and the sets of modules are very much alpha. If you
40 want to have a better chance of code not breaking, import the modules
41 you want directly.
42  
43 Tags can be expanded via:
44  
45 =for test
46  
47 use FunctionalPerl qw(expand_import_tags);
48 my ($modules, $unused_tags, $nontags) = expand_import_tags(qw(:dev :most not_a_tag));
49 is $$modules{"FP::Failure"}, 2; # number of times used.
50 is_deeply $unused_tags,
51 [':all', ':all_sequences', ':ast', ':csv', ':dbi', ':fix', ':git', ':io', ':paths', ':pxml', ':rare', ':trampolines', ':transparentlazy'];
52 is_deeply $nontags, ['not_a_tag'];
53  
54 =head1 SEE ALSO
55  
56 This is the list of supported import tags and the modules and other tags that they import:
57  
58 C<:all> -> C<:dev>, C<:io>, C<:most>, C<:rare>
59  
60 C<:all_sequences> -> C<:primary_sequences>, L<FP::SortedPureArray>, L<FP::StrictList>
61  
62 C<:ast> -> L<FP::AST::Perl>
63  
64 C<:autobox> -> L<FP::autobox>
65  
66 C<:chars> -> L<FP::Char>
67  
68 C<:csv> -> L<FP::Text::CSV>
69  
70 C<:datastructures> -> C<:chars>, C<:maps>, C<:numbers>, C<:sequences>, C<:sets>, C<:tries>
71  
72 C<:dbi> -> L<FP::DBI>
73  
74 C<:debug> -> C<:equal>, C<:show>, L<Chj::Backtrace>, L<Chj::pp>, L<Chj::time_this>
75  
76 C<:dev> -> C<:debug>, C<:repl>, C<:test>, L<Chj::ruse>
77  
78 C<:doc> -> L<FP::Docstring>
79  
80 C<:equal> -> L<FP::Equal>
81  
82 C<:failures> -> L<FP::Either>, L<FP::Failure>
83  
84 C<:fix> -> L<FP::fix>
85  
86 C<:functions> -> C<:equal>, C<:failures>, C<:show>, L<FP::Cmp>, L<FP::Combinators>, L<FP::Combinators2>, L<FP::Currying>, L<FP::Div>, L<FP::Memoizing>, L<FP::Ops>, L<FP::Optional>, L<FP::Predicates>, L<FP::Untainted>, L<FP::Values>
87  
88 C<:git> -> L<FP::Git::Repository>
89  
90 C<:io> -> L<Chj::tempdir>, L<Chj::xIO>, L<Chj::xhome>, L<Chj::xopen>, L<Chj::xopendir>, L<Chj::xoutpipe>, L<Chj::xperlfunc>, L<Chj::xpipe>, L<Chj::xtmpfile>, L<FP::IOStream>
91  
92 C<:lazy> -> C<:streams>, L<FP::Lazy>, L<FP::Weak>
93  
94 C<:maps> -> L<FP::Hash>, L<FP::PureHash>
95  
96 C<:most> -> C<:autobox>, C<:datastructures>, C<:debug>, C<:doc>, C<:equal>, C<:failures>, C<:functions>, C<:lazy>, C<:show>
97  
98 C<:numbers> -> L<FP::BigInt>
99  
100 C<:paths> -> L<FP::Path>
101  
102 C<:pxml> -> L<PXML::Serialize>, L<PXML::Util>, L<PXML::XHTML>
103  
104 C<:rare> -> C<:csv>, C<:dbi>, C<:fix>, C<:git>, C<:paths>, C<:trampolines>
105  
106 C<:repl> -> L<FP::Repl>, L<FP::Repl::AutoTrap>
107  
108 C<:sequences> -> C<:streams>, L<FP::Array>, L<FP::Array_sort>, L<FP::List>, L<FP::MutableArray>, L<FP::PureArray>
109  
110 C<:sets> -> L<FP::HashSet>, L<FP::OrderedCollection>
111  
112 C<:show> -> L<FP::Show>
113  
114 C<:streams> -> L<FP::IOStream>, L<FP::Stream>, L<FP::Weak>
115  
116 C<:test> -> L<Chj::TEST>
117  
118 C<:trampolines> -> L<FP::Trampoline>
119  
120 C<:transparentlazy> -> C<:streams>, L<FP::TransparentLazy>, L<FP::Weak>
121  
122 C<:tries> -> L<FP::Trie>
123  
124 =head1 NOTE
125  
126 This is alpha software! Read the status section in the package README
127 or on the L<website|http://functional-perl.org/>.
128  
129 =cut
130  
131 # **NOTE** there is no need to keep SEE ALSO in sync with the definitions,
132 # **NOTE** running meta/update-pod (at release time) will take care of it.
133  
134 package FunctionalPerl;
135 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
136 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
137 3 ▶use warnings FATAL => 'uninitialized';
Subroutine BEGIN: called CC=1 SCAR=0.0
138 3 ▶use base "Exporter";
Subroutine BEGIN: called CC=1 SCAR=0.0
139  
140 3 our @EXPORT = ();
141 3 our @EXPORT_OK = qw(expand_import_tags);
142 3 our %EXPORT_TAGS = ();
143  
144 3 our $VERSION = "0.72.76";
145  
146 # Export tag to modules and/or other tags; each module will be
147 # imported with ":all" by default. Where a module name contains " = ",
148 # the part after the " = " is the comma-separated list of tag names to
149 # import.
150 # NOTE: the documentation in "SEE ALSO" is auto-generated from this,
151 # you do not need to keep it in sync manually.
152 3 our $export_desc = +{
153 ":autobox" => [qw(FP::autobox=)],
154  
155 ":streams" => [qw(FP::Stream FP::IOStream FP::Weak)],
156 ":lazy" => [qw(FP::Lazy :streams FP::Weak)],
157 ":transparentlazy" => [qw(FP::TransparentLazy :streams FP::Weak)],
158 ":failures" => [qw(FP::Failure FP::Either)],
159  
160 ":doc" => [qw(FP::Docstring)],
161 ":show" => [qw(FP::Show)],
162 ":equal" => [qw(FP::Equal)],
163 ":debug" => [qw(:show :equal Chj::Backtrace Chj::time_this Chj::pp)],
164 ":test" => [qw(Chj::TEST)],
165 ":repl" => [qw(FP::Repl FP::Repl::AutoTrap)],
166 ":dev" => [qw(:repl :test :debug Chj::ruse)],
167  
168 ":functions" => [
169 qw(FP::Combinators FP::Combinators2
170 FP::Cmp
171 FP::Ops FP::Div
172 FP::Predicates
173 FP::Optional FP::Values
174 FP::Memoizing FP::Currying
175 FP::Untainted
176 :show :equal :failures)
177 ],
178 ":git" => [qw(FP::Git::Repository)],
179 ":pxml" => [qw(PXML::Util PXML::XHTML PXML::Serialize)],
180 ":ast" => [qw(FP::AST::Perl)],
181  
182 ":numbers" => [qw(FP::BigInt)],
183 ":chars" => [qw(FP::Char)],
184 ":sequences" => [
185 qw(FP::List FP::MutableArray
186 FP::Array FP::Array_sort
187 FP::PureArray
188 :streams)
189 ],
190 ":all_sequences" => [
191 qw(:primary_sequences
192 FP::StrictList
193 FP::SortedPureArray)
194 ],
195 ":maps" => [qw(FP::Hash FP::PureHash)],
196 ":sets" => [qw(FP::HashSet FP::OrderedCollection)],
197 ":tries" => [qw(FP::Trie)],
198 ":datastructures" => [qw(:chars :numbers :sequences :maps :sets :tries)],
199  
200 ":io" => [
201 qw(Chj::xIO Chj::xopen Chj::xtmpfile= Chj::tempdir
202 Chj::xpipe= Chj::xoutpipe= Chj::xopendir= Chj::xperlfunc
203 Chj::xhome
204 FP::IOStream)
205 ],
206 ":dbi" => [qw(FP::DBI=)],
207 ":csv" => [qw(FP::Text::CSV)],
208  
209 ":fix" => [qw(FP::fix)],
210 ":trampolines" => [qw(FP::Trampoline)],
211 ":paths" => [qw(FP::Path)],
212  
213 ":most" => [
214 qw(:lazy :datastructures :equal :show :functions :failures :debug
215 :autobox :doc)
216 ],
217 ":rare" => [qw(:csv :paths :git :dbi :trampolines :fix)],
218 ":all" => [qw(:most :rare :io :dev)],
219 };
220  
221 30 ▶sub check_off {
Subroutine check_off: called CC=5 SCAR=16.2
Pod undocumented
222 30 ▶ @_ == 3 or die "bug";
Branch: 1 branch
BranchTrueFalseTotal
@_ == 3 or die "bug" 29 0 29
223 30 my ($tag, $seen_tags, $seen_modules) = @_;
224 30 ▶ my $vals = $$export_desc{$tag} or do {
Branch: 1 branch
BranchTrueFalseTotal
my $vals = $FunctionalPerl::export_desc->{$tag} or do { require Carp; Carp::croak("unknown tag '${tag}'") } 29 0 29
225 1 require Carp;
226 1 Carp::croak("unknown tag '$tag'");
227 };
228 30 for my $tag_or_module (@$vals) {
229 82 ▶ if ($tag_or_module =~ /^:/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($tag_or_module =~ /^:/) { } 27 55 82
230 27 $$seen_tags{$tag_or_module}++;
231 27 check_off($tag_or_module, $seen_tags, $seen_modules);
232 } else {
233 55 $$seen_modules{$tag_or_module}++;
234 }
235 }
236 }
237  
238 5 ▶sub expand_import_tags {
Subroutine expand_import_tags: called CC=2 SCAR=6.9
Pod undocumented
239  
240 # Arguments: tag names and other things. Returns (which tag names
241 # are unused, used modules, the other things).
242 4 my @tags = grep {/^:/} @_;
243 4 my $seen_tags = +{ map { $_ => 1 } @tags };
244 4 my $seen_modules = +{};
245 4 for my $tag (@tags) {
246 2 check_off $tag, $seen_tags, $seen_modules;
247 }
248 4 require FP::HashSet;
249 (
250 $seen_modules,
251 [
252 sort keys
253 4 %{ FP::HashSet::hashset_difference($export_desc, $seen_tags) }
254 ],
255 4 [grep { not /^:/ } @_]
256 )
257 }
258  
259 0 ▶sub split_moduledesc {
Subroutine split_moduledesc: not called CC=2 SCAR=17.9
Pod undocumented
260 0 my ($module_and_perhaps_tags) = @_;
261 0 ▶ my ($module, $maybe_tags)
Branch: 1 branch
BranchTrueFalseTotal
() = $module_and_perhaps_tags =~ /^([^=]+)(?:=(.*))?/ or die "no match" 0 0 0
262 = $module_and_perhaps_tags =~ m{^([^=]+)(?:=(.*))?}
263 or die "no match";
264 0 ($module, $maybe_tags)
265 }
266  
267 0 ▶sub export_desc2pod {
Subroutine export_desc2pod: not called CC=2 SCAR=17.9
Pod undocumented
268 join(
269 "",
270 map {
271 0 my $a = $$export_desc{$_};
272 "C<$_> -> " . join(
273 ", ",
274 map {
275 0 ▶ if (/^:/) {
Branch: 1 branch
BranchTrueFalseTotal
if (/^:/) { } 0 0 0
276 0 "C<$_>"
277 } else {
278 0 my ($module, $maybe_tags) = split_moduledesc $_;
279 0 "L<$module>"
280 }
281 } sort @$a
282 )
283 . "\n\n"
284 } (sort keys %$export_desc)
285 )
286 }
287  
288 3 ▶sub import {
Subroutine import: called CC=5 SCAR=27.7
289 3 my $pack = shift;
290 3 my $caller = caller;
291  
292 3 my ($modules, $_unused_tags, $nontags) = expand_import_tags(@_);
293  
294 3 $pack->export_to_level(1, $caller, @$nontags);
295  
296 3 require Import::Into;
297  
298 3 for my $module_and_perhaps_tags (sort keys %$modules) {
299 0 my ($module, $maybe_tags) = split_moduledesc $module_and_perhaps_tags;
300 0 ▶ my @tags = split /,/, $maybe_tags // ":all";
Condition0%0/2
$maybe_tags // ":all"
l!l
00
MC/DC0%0/1
$maybe_tags // ":all"
$maybe_tags
Truth table0%0/2
A
A= $maybe_tags
Aresult
11
00
301 0 my $path = $module;
302 0 $path =~ s/::/\//sg;
303 0 $path .= ".pm";
304  
305 # Do not die right away in an attempt at making this more
306 # usable for users where some of the modules don't work:
307 0 ▶ if (
Branch: 1 branch
BranchTrueFalseTotal
if (eval { do { require $path; 1 } }) { } 0 0 0
308 eval {
309 0 require $path;
310 0 1
311 }
312 )
313 {
314 0 $module->import::into($caller, @tags)
315 } else {
316 0 my $e = $@;
317 0 my $estr = "$e";
318 0 ▶ $estr =~ s/\n.*//s unless $ENV{FUNCTIONALPERL_VERBOSE};
Branch: 1 branch
BranchTrueFalseTotal
unless $ENV{"FUNCTIONALPERL_VERBOSE"} 0 0 0
319 0 warn "NOTE: can't load $module: $estr";
320 }
321 }
322 }
323  
324 3 1
« lib/FP/Git/Repository.pm ↑ Summary intro/.expansion-more_tailcalls »