aboutsummaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorJohn Ankarström <john@ankarstrom.se>2021-05-05 20:02:23 +0200
committerJohn Ankarström <john@ankarstrom.se>2021-05-05 20:02:23 +0200
commitbdc020126a6b59f3a7b866ba72f6ca22a52f8e6c (patch)
treece17b96a7dc3c4b737339d79c2d3dfc786231ffa /README
downloadList-Gather-Simple-bdc020126a6b59f3a7b866ba72f6ca22a52f8e6c.tar.gz
First commitHEADmaster
Diffstat (limited to 'README')
-rw-r--r--README69
1 files changed, 69 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..46cb38b
--- /dev/null
+++ b/README
@@ -0,0 +1,69 @@
+NAME
+ List::Gather::Simple - Simple implementation of gather/take
+
+SYNOPSIS
+ use List::Gather::Simple;
+ print gather {
+ take for gather {
+ take 'Hello ', 'world!';
+ };
+ unshift @gathered, 'Test message: ';
+ }, "\n";
+ # -> Test message: Hello world!
+
+DESCRIPTION
+ List::Gather::Simple is yet another Perl 5 implementation of the
+ "gather"/"take" construct in Perl 6/Raku. It differs from other
+ implementations in that it is, as the name suggests, very simple.
+
+ "gather" and "take" are implemented as normal subroutines, operating on
+ a localized variable called @gathered. All three of these are imported
+ when List::Gather::Simple is "use"d.
+
+ The benefit of exporting @gathered as a variable (rather than a
+ subroutine called "gathered") is that @gathered is very clearly a normal
+ Perl array, which can be used as an lvalue too, unlike the "gathered"
+ subroutine of other implementations. That means that the following is
+ valid:
+
+ gather { @gathered = merge(@gathered, @x) while @x }
+
+DIAGNOSTICS
+ Warning: Useless use of 'gather' in void context
+ This warning is issued if "use warnings 'void'" is active and
+ "gather" is called in void context.
+
+ Note that the warning will be associated with the line on which
+ "gather" is called. This can lead to the following unintuitive
+ behavior: If you return the results of "gather" from a subroutine
+ and then call that subroutine in void context, the warning will
+ still be issued, but it will refer to the line of the "gather" call
+ inside the subroutine.
+
+ Exception: Call to 'take' outside of 'gather'
+ This exception is raised if "take" is called outside of a "gather"
+ block.
+
+ Note that this is a runtime error.
+
+SEE ALSO
+ All of the following modules have inspired List::Gather::Simple:
+
+ * List::Gather
+
+ * Perl6::Gather
+
+ * Perl6::Take
+
+ * Syntax::Keyword::Gather
+
+AUTHOR
+ John Ankarström, <john+spam@ankarstrom.se> (remove +spam)
+
+COPYRIGHT AND LICENSE
+ Copyright (C) 2021 by John Ankarström
+
+ This library is free software; you can redistribute it and/or modify it
+ under the same terms as Perl itself, either Perl version 5.32.1 or, at
+ your option, any later version of Perl 5 you may have available.
+