| 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
| |||||||||||||
| 223 | 30 | my ($tag, $seen_tags, $seen_modules) = @_; | |||||||||||
| 224 | 30 | ▶ | my $vals = $$export_desc{$tag} or do { | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 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
| |||||||||||||
| 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
| |||||||||||||
| 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
| |||||||||||||
| 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"
MC/DC0%0/1
$maybe_tags // ":all"
$maybe_tags
Truth table0%0/2
A
A= $maybe_tags
| |||||||||||||
| 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
| |||||||||||||
| 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
| |||||||||||||
| 319 | 0 | warn "NOTE: can't load $module: $estr"; | |||||||||||
| 320 | } | ||||||||||||
| 321 | } | ||||||||||||
| 322 | } | ||||||||||||
| 323 | |||||||||||||
| 324 | 3 | 1 | |||||||||||