| 1 | # | ||||||||||
| 2 | # Copyright (c) 2021 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 | =head1 NAME | ||||||||||
| 11 | |||||||||||
| 12 | FP::Either - keep two kinds of values in one kind of place | ||||||||||
| 13 | |||||||||||
| 14 | =head1 SYNOPSIS | ||||||||||
| 15 | |||||||||||
| 16 | 1 | ▶ | use FP::Either; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 17 | my $a = Left 1; | ||||||||||
| 18 | my $b = Right 1; | ||||||||||
| 19 | ok is_Left $a; | ||||||||||
| 20 | ok !is_Right $a; | ||||||||||
| 21 | ok is_Right $b; | ||||||||||
| 22 | ok $a->isa("FP::_::Either"); | ||||||||||
| 23 | ok $a->isa("FP::Either::Left"); | ||||||||||
| 24 | is $a->value, 1; | ||||||||||
| 25 | is $b->value, 1; | ||||||||||
| 26 | |||||||||||
| 27 | 1 | ▶ | use FP::List; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 28 | 1 | ▶ | use FP::Equal; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 29 | 1 | ▶ | use FP::Either ":all"; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 30 | my $l = list Left(9), Left(-8), Right(5); | ||||||||||
| 31 | ok equal rights($l), list 5; | ||||||||||
| 32 | ok equal lefts($l), list 9, -8; | ||||||||||
| 33 | |||||||||||
| 34 | =head1 DESCRIPTION | ||||||||||
| 35 | |||||||||||
| 36 | These are used to mark (wrap) two different kinds of data for proper | ||||||||||
| 37 | distinction in a place that should hold either. | ||||||||||
| 38 | |||||||||||
| 39 | `Right` is typically used for the 'right' way, or successful path, or | ||||||||||
| 40 | similar. `Left` would be for the other case, for example to indicate a | ||||||||||
| 41 | failure, or whatever suits the situation at hands. | ||||||||||
| 42 | |||||||||||
| 43 | The naming used here (`Either` with `Left` and `Right` members) is the | ||||||||||
| 44 | one for the data types that the Haskell language uses for error | ||||||||||
| 45 | handling. Rust calls the corresponding types `Result`, with `Err` and | ||||||||||
| 46 | `Ok` members. But given that, especially in Perl, there's less use of | ||||||||||
| 47 | such a module for error handling, but more for other purposes, the | ||||||||||
| 48 | Haskell naming seems like a better match. | ||||||||||
| 49 | |||||||||||
| 50 | =head1 SEE ALSO | ||||||||||
| 51 | |||||||||||
| 52 | L<FP::Failure> (which only wraps the error case). | ||||||||||
| 53 | |||||||||||
| 54 | Implements: L<FP::Abstract::Pure>, L<FP::Struct::Show> | ||||||||||
| 55 | |||||||||||
| 56 | =head1 NOTE | ||||||||||
| 57 | |||||||||||
| 58 | This is alpha software! Read the status section in the package README | ||||||||||
| 59 | or on the L<website|http://functional-perl.org/>. | ||||||||||
| 60 | |||||||||||
| 61 | =cut | ||||||||||
| 62 | |||||||||||
| 63 | package FP::Either; | ||||||||||
| 64 | 4 | ▶ | use strict; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 65 | 4 | ▶ | use utf8; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 66 | 4 | ▶ | use warnings; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 67 | 4 | ▶ | use warnings FATAL => 'uninitialized'; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 68 | 4 | ▶ | use Exporter "import"; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 69 | |||||||||||
| 70 | 4 | our @EXPORT = qw(Left Right is_Left is_Right); | |||||||||
| 71 | 4 | our @EXPORT_OK = qw(lefts rights); | |||||||||
| 72 | 4 | our %EXPORT_TAGS = (all => [@EXPORT, @EXPORT_OK]); | |||||||||
| 73 | |||||||||||
| 74 | 4 | ▶ | use FP::Carp; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 75 | 4 | ▶ | use FP::Predicates qw(instance_of); | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 76 | |||||||||||
| 77 | 4 | package FP::_::Either { | |||||||||
| 78 | 4 | ▶ | use FP::Struct ["value"] => | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 79 | 4 | ("FP::Abstract::Pure", "FP::Struct::Show", "FP::Struct::Equal"); | |||||||||
| 80 | 4 | _END_ | |||||||||
| 81 | } | ||||||||||
| 82 | |||||||||||
| 83 | 4 | package FP::Either::Left { | |||||||||
| 84 | 4 | ▶ | use FP::Struct [] => "FP::_::Either"; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 85 | 4 | _END_ | |||||||||
| 86 | } | ||||||||||
| 87 | 4 | FP::Either::Left::constructors->import; | |||||||||
| 88 | |||||||||||
| 89 | 4 | *is_Left = instance_of "FP::Either::Left"; | |||||||||
| 90 | |||||||||||
| 91 | 4 | package FP::Either::Right { | |||||||||
| 92 | 4 | ▶ | use FP::Struct [] => "FP::_::Either"; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 93 | 4 | _END_ | |||||||||
| 94 | } | ||||||||||
| 95 | 4 | FP::Either::Right::constructors->import; | |||||||||
| 96 | |||||||||||
| 97 | 4 | *is_Right = instance_of "FP::Either::Right"; | |||||||||
| 98 | |||||||||||
| 99 | 8 | ▶ | sub make_lefts_rights { | ||||||||
|
Subroutine
make_lefts_rights: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||
| 100 | 8 | my ($is) = @_; | |||||||||
| 101 | 30 | ▶ | sub { | ||||||||
|
Subroutine
__ANON__: called CC=2 SCAR=7.2
| |||||||||||
| 102 | 30 | ▶ | @_ == 1 or fp_croak_arity 1; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 103 | |||||||||||
| 104 | # XX could use filter_map as optimization here, too! Even | ||||||||||
| 105 | # better a map_filter. | ||||||||||
| 106 | # XX evil to use the value method directly? This saves one | ||||||||||
| 107 | # additional sub call. | ||||||||||
| 108 | 30 | $_[0]->filter($is)->map(\&FP::_::Either::value) | |||||||||
| 109 | } | ||||||||||
| 110 | 8 | } | |||||||||
| 111 | |||||||||||
| 112 | 4 | *lefts = make_lefts_rights \&is_Left; | |||||||||
| 113 | 4 | *rights = make_lefts_rights \&is_Right; | |||||||||
| 114 | |||||||||||
| 115 | 4 | 1 | |||||||||