Skip to content

Commit

Permalink
First attempt at writing documentation for the new operators
Browse files Browse the repository at this point in the history
  • Loading branch information
leonerd committed Nov 22, 2024
1 parent 302c9e0 commit 588fb05
Show file tree
Hide file tree
Showing 4 changed files with 86 additions and 3 deletions.
3 changes: 2 additions & 1 deletion ext/Pod-Functions/t/Functions.t
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,8 @@ Functions for real @ARRAYs:
each, keys, pop, push, shift, splice, unshift, values
Functions for list data:
grep, join, map, qw/STRING/, reverse, sort, unpack
all, any, grep, join, map, qw/STRING/, reverse, sort,
unpack
Functions for real %HASHes:
delete, each, exists, keys, values
Expand Down
11 changes: 10 additions & 1 deletion lib/feature.pm

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

64 changes: 64 additions & 0 deletions pod/perlfunc.pod
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,7 @@ X<list>

=for Pod::Functions =LIST

L<C<all>|/all BLOCK LIST>, L<C<any>|/any BLOCK LIST>,
L<C<grep>|/grep BLOCK LIST>, L<C<join>|/join EXPR,LIST>,
L<C<map>|/map BLOCK LIST>, L<C<qwE<sol>E<sol>>|/qwE<sol>STRINGE<sol>>,
L<C<reverse>|/reverse LIST>, L<C<sort>|/sort SUBNAME LIST>,
Expand Down Expand Up @@ -805,6 +806,69 @@ For more information see L<perlipc>.

Portability issues: L<perlport/alarm>.

=item all BLOCK LIST

=for Pod::Functions test if every value in a list satisfies the given condition

Evaluates the BLOCK for each element of the LIST (locally setting
L<C<$_>|perlvar/$_> to each element) and checks the truth of the result of
that block. Returns true if every element makes the block yield true, or
returns false if at least one element makes the block false.

As soon as any element makes the block yield false, then the result of this
operator is determined. It will short-circuit in that case and not consider
any further elements.

When used as a condition, this is similar to using L<C<grep>|/grep BLOCK LIST>
to count that every value satisfies the condition, except for this
short-circuit behaviour.

if( all { length $_ } @strings ) {
say "Every string is non-empty";
}

is roughly equivalent to

if( @strings == grep { length $_ } @strings ) ...

This operator is only available if the
L<C<any_all> feature|feature/"The 'any_all' feature"> is enabled.

It is currently considered B<experimental>, and will issue a compile-time
warning in the category C<experimental::any_all> unless that category is
silenced.

=item any BLOCK LIST

=for Pod::Functions test if at least one value in a list satisfies the given condition

Evaluates the BLOCK for each element of the LIST (locally setting
L<C<$_>|perlvar/$_> to each element) and checks the truth of the result of
that block. Returns true if at least one element makes the block yield
true, or returns false if no element is found to make it true.

As soon as any element makes the block yield true, then the result of this
operator is determined. It will short-circuit in that case and not consider
any further elements.

When used as a condition, this is similar to L<C<grep>|/grep BLOCK LIST>,
except for this short-circuit behaviour.

if( any { length $_ } @strings ) {
say "At least one string is non-empty";
}

is roughly equivalent to

if( grep { length $_ } @strings ) ...

This operator is only available if the
L<C<any_all> feature|feature/"The 'any_all' feature"> is enabled.

It is currently considered B<experimental>, and will issue a compile-time
warning in the category C<experimental::any_all> unless that category is
silenced.

=item atan2 Y,X
X<atan2> X<arctangent> X<tan> X<tangent>

Expand Down
11 changes: 10 additions & 1 deletion regen/feature.pl
Original file line number Diff line number Diff line change
Expand Up @@ -984,7 +984,16 @@ =head2 The 'apostrophe_as_package_separator' feature
=head2 The 'any_all' feature
TODO write some docs
B<WARNING>: This feature is still experimental and the implementation may
change or be removed in future versions of Perl. For this reason, Perl will
warn when you use the feature, unless you have explicitly disabled the warning:
no warnings "experimental::any_all";
This feature enables the L<C<any>|perlfunc/any BLOCK LIST> and
L<C<all>|perlfunc/all BLOCK LIST> operator keywords. These allow testing
whether values in a list satisfy a given condition, with short-circuiting
behaviour.
=head1 FEATURE BUNDLES
Expand Down

0 comments on commit 588fb05

Please sign in to comment.