.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "CPS::Functional 3pm" .TH CPS::Functional 3pm "2022-06-30" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "CPS::Functional" \- functional utilities in Continuation\-Passing Style .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use CPS::Functional qw( kmap ); \& \& use Example::HTTP::Client qw( k_get_http ); \& use List::Util qw( sum ); \& \& my @URLs = ( \& "http://www.foo.com", \& "http://www.bar.com", \& ); \& \& kmap( \e@URLs, \& sub { \& my ( $item, $kret ) = @_; \& \& k_get_http( uri => $item, on_response => sub { \& my ( $response ) = @_; \& \& $kret\->( $response\->content_length ); \& } ); \& }, \& sub { \& my ( @sizes ) = @_; \& \& say "Total length of all URLs: " . sum(@sizes); \& }, \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides \s-1CPS\s0 versions of data-flow functionals, such as Perl's \&\f(CW\*(C`map\*(C'\fR and \f(CW\*(C`grep\*(C'\fR, where function bodies are invoked and expected to return data, which the functional manages. They are built on top of the control-flow functionals provided by the \f(CW\*(C`CPS\*(C'\fR module itself. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .ie n .SS "kmap( \e@items, \e&body, $k )" .el .SS "kmap( \e@items, \e&body, \f(CW$k\fP )" .IX Subsection "kmap( @items, &body, $k )" \&\s-1CPS\s0 version of perl's \f(CW\*(C`map\*(C'\fR statement. Calls the \f(CW\*(C`body\*(C'\fR code once for each element in \f(CW@items\fR, capturing the list of values the body passes into its continuation. When the items are exhausted, \f(CW$k\fR is invoked and passed a list of all the collected values. .PP .Vb 2 \& $body\->( $item, $kret ) \& $kret\->( @items_out ) \& \& $k\->( @all_items_out ) .Ve .ie n .SS "kgrep( \e@items, \e&body, $k )" .el .SS "kgrep( \e@items, \e&body, \f(CW$k\fP )" .IX Subsection "kgrep( @items, &body, $k )" \&\s-1CPS\s0 version of perl's \f(CW\*(C`grep\*(C'\fR statement. Calls the \f(CW\*(C`body\*(C'\fR code once for each element in \f(CW@items\fR, capturing those elements where the body's continuation was invoked with a true value. When the items are exhausted, \f(CW$k\fR is invoked and passed a list of the subset of \f(CW@items\fR which were selected. .PP .Vb 2 \& $body\->( $item, $kret ) \& $kret\->( $select ) \& \& $k\->( @chosen_items ) .Ve .ie n .SS "kfoldl( \e@items, \e&body, $k )" .el .SS "kfoldl( \e@items, \e&body, \f(CW$k\fP )" .IX Subsection "kfoldl( @items, &body, $k )" \&\s-1CPS\s0 version of \f(CW\*(C`List::Util::reduce\*(C'\fR, which collapses (or \*(L"folds\*(R") a list of values down to a single scalar, by successively accumulating values together. .PP If \f(CW@items\fR is empty, invokes \f(CW$k\fR immediately, passing in \f(CW\*(C`undef\*(C'\fR. .PP If \f(CW@items\fR contains a single value, invokes \f(CW$k\fR immediately, passing in just that single value. .PP Otherwise, initialises an accumulator variable with the first value in \&\f(CW@items\fR, then for each additional item, invokes the \f(CW\*(C`body\*(C'\fR passing in the accumulator and the next item, storing back into the accumulator the value that \f(CW\*(C`body\*(C'\fR passed to its continuation. When the \f(CW@items\fR are exhausted, it invokes \f(CW$k\fR, passing in the final value of the accumulator. .PP .Vb 2 \& $body\->( $acc, $item, $kret ) \& $kret\->( $new_acc ) \& \& $k\->( $final_acc ) .Ve .PP Technically, this is not a true Scheme/Haskell\-style \f(CW\*(C`foldl\*(C'\fR, as it does not take an initial value. (It is what Haskell calls \f(CW\*(C`foldl1\*(C'\fR.) However, if such an initial value is required, this can be provided by .PP .Vb 1 \& kfoldl( [ $initial, @items ], \e&body, $k ) .Ve .ie n .SS "kfoldr( \e@items, \e&body, $k )" .el .SS "kfoldr( \e@items, \e&body, \f(CW$k\fP )" .IX Subsection "kfoldr( @items, &body, $k )" A right-associative version of \f(CW\*(C`kfoldl()\*(C'\fR. Where \f(CW\*(C`kfoldl()\*(C'\fR starts with the first two elements in \f(CW@items\fR and works forward, \f(CW\*(C`kfoldr()\*(C'\fR starts with the last two and works backward. .PP .Vb 2 \& $body\->( $item, $acc, $kret ) \& $kret\->( $new_acc ) \& \& $k\->( $final_acc ) .Ve .PP As before, an initial value can be provided by modifying the \f(CW@items\fR array, though note it has to be last this time: .PP .Vb 1 \& kfoldr( [ @items, $initial ], \e&body, $k ) .Ve .ie n .SS "kunfold( $seed, \e&body, $k )" .el .SS "kunfold( \f(CW$seed\fP, \e&body, \f(CW$k\fP )" .IX Subsection "kunfold( $seed, &body, $k )" An inverse operation to \f(CW\*(C`kfoldl()\*(C'\fR; turns a single scalar into a list of items. Repeatedly calls the \f(CW\*(C`body\*(C'\fR code, capturing the values it returns, until it indicates the end of the loop, then invoke \f(CW$k\fR with the collected values. .PP .Vb 3 \& $body\->( $seed, $kmore, $kdone ) \& $kmore\->( $new_seed, @items ) \& $kdone\->( @items ) \& \& $k\->( @all_items ) .Ve .PP With each iteration, the \f(CW\*(C`body\*(C'\fR is invoked and passed the current \f(CW$seed\fR value and two continuations, \f(CW$kmore\fR and \f(CW$kdone\fR. If \f(CW$kmore\fR is invoked, the passed items, if any, are appended to the eventual result list. The \&\f(CW\*(C`body\*(C'\fR is then re-invoked with the new \f(CW$seed\fR value. If \f(CW$klast\fR is invoked, the passed items, if any, are appended to the return list, then the entire list is passed to \f(CW$k\fR. .SH "EXAMPLES" .IX Header "EXAMPLES" The following aren't necessarily examples of code which would be found in real programs, but instead, demonstrations of how to use the above functions as ways of controlling program flow. .PP Without dragging in large amount of detail on an asynchronous or event-driven framework, it is difficult to give a useful example of behaviour that \s-1CPS\s0 allows that couldn't be done just as easily without. Nevertheless, I hope the following examples will be useful to demonstrate use of the above functions, in a way which hints at their use in a real program. .ie n .SS "Implementing ""join()"" using ""kfoldl()""" .el .SS "Implementing \f(CWjoin()\fP using \f(CWkfoldl()\fP" .IX Subsection "Implementing join() using kfoldl()" .Vb 1 \& use CPS::Functional qw( kfoldl ); \& \& my @words = qw( My message here ); \& \& kfoldl( \& \e@words, \& sub { \& my ( $left, $right, $k ) = @_; \& \& $k\->( "$left $right" ); \& }, \& sub { \& my ( $str ) = @_; \& \& print "Joined up words: $str\en"; \& } \& ); .Ve .ie n .SS "Implementing ""split()"" using ""kunfold()""" .el .SS "Implementing \f(CWsplit()\fP using \f(CWkunfold()\fP" .IX Subsection "Implementing split() using kunfold()" The following program illustrates the way that \f(CW\*(C`kunfold()\*(C'\fR can split a string, in a reverse way to the way \f(CW\*(C`kfoldl()\*(C'\fR can join it. .PP .Vb 1 \& use CPS::Functional qw( kunfold ); \& \& my $str = "My message here"; \& \& kunfold( \& $str, \& sub { \& my ( $s, $kmore, $kdone ) = @_; \& \& if( $s =~ s/^(.*?) // ) { \& return $kmore\->( $s, $1 ); \& } \& else { \& return $kdone\->( $s ); \& } \& }, \& sub { \& my @words = @_; \& print "Words in message:\en"; \& print "$_\en" for @words; \& } \& ); .Ve .SS "Generating Prime Numbers" .IX Subsection "Generating Prime Numbers" While the design of \f(CW\*(C`kunfold()\*(C'\fR is symmetric to \f(CW\*(C`kfoldl()\*(C'\fR, the seed value doesn't have to be successively broken apart into pieces. Another valid use for it may be storing intermediate values in computation, such as in this example, storing a list of known primes, to help generate the next one: .PP .Vb 1 \& use CPS::Functional qw( kunfold ); \& \& kunfold( \& [ 2, 3 ], \& sub { \& my ( $vals, $kmore, $kdone ) = @_; \& \& return $kdone\->() if @$vals >= 50; \& \& PRIME: for( my $n = $vals\->[\-1] + 2; ; $n += 2 ) { \& $n % $_ == 0 and next PRIME for @$vals; \& \& push @$vals, $n; \& return $kmore\->( $vals, $n ); \& } \& }, \& sub { \& my @primes = ( 2, 3, @_ ); \& print "Primes are @primes\en"; \& } \& ); .Ve .SS "Forward-reading Program Flow" .IX Subsection "Forward-reading Program Flow" One side benefit of the \s-1CPS\s0 control-flow methods which is unassociated with asynchronous operation, is that the flow of data reads in a more natural left-to-right direction, instead of the right-to-left flow in functional style. Compare .PP .Vb 2 \& sub square { $_ * $_ } \& sub add { $a + $b } \& \& print reduce( \e&add, map( square, primes(10) ) ); .Ve .PP (because \f(CW\*(C`map\*(C'\fR is a language builtin but \f(CW\*(C`reduce\*(C'\fR is a function with \f(CW\*(C`(&)\*(C'\fR prototype, it has a different way to pass in the named functions) .PP with .PP .Vb 2 \& my $ksquare = liftk { $_[0] * $_[0] }; \& my $kadd = liftk { $_[0] + $_[1] }; \& \& kprimes 10, sub { \& kmap \e@_, $ksquare, sub { \& kfoldl \e@_, $kadd, sub { \& print $_[0]; \& } \& } \& }; .Ve .PP This translates roughly to a functional vs imperative way to describe the problem: .PP .Vb 1 \& Print the sum of the squares of the first 10 primes. \& \& Take the first 10 primes. Square them. Sum them. Print. .Ve .PP Admittedly the closure creation somewhat clouds the point in this small example, but in a larger example, the real problem-solving logic would be larger, and stand out more clearly against the background boilerplate. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 \&\s-1CPS\s0 \- manage flow of control in Continuation-Passing Style .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans