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 Dec 4, 2024
1 parent 2cd9794 commit ff5c3df
Show file tree
Hide file tree
Showing 4 changed files with 110 additions and 5 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
25 changes: 23 additions & 2 deletions lib/feature.pm

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

62 changes: 62 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,67 @@ 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<all> feature|feature/"The 'all' feature"> is enabled.

It is currently considered B<experimental>, and will issue a compile-time
warning in the category C<experimental::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> feature|feature/"The 'any' feature"> is enabled.

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

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

Expand Down
25 changes: 23 additions & 2 deletions regen/feature.pl
Original file line number Diff line number Diff line change
Expand Up @@ -985,11 +985,32 @@ =head2 The 'apostrophe_as_package_separator' feature
=head2 The 'any' 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";
This feature enables the L<C<any>|perlfunc/any BLOCK LIST> operator keyword.
This allow testing whether any of the values in a list satisfy a given
condition, with short-circuiting behaviour as soon as it finds one.
=head2 The '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::all";
This feature enables the L<C<all>|perlfunc/all BLOCK LIST> operator keyword.
This allow testing whether all of the values in a list satisfy a given
condition, with short-circuiting behaviour as soon as it finds one that does
not.
B<Note:> remember that this enables one specific feature whose name is C<all>;
it does not enable all of the features. This is not C<use feature ':all'>.
For that, see the section below.
=head1 FEATURE BUNDLES
Expand Down

0 comments on commit ff5c3df

Please sign in to comment.