First commitHEADmaster

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.
+