Merge pull request #10 from wqferr/rename-from-iter-call

Create from to transform vanilla iter into func iter

LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 William Quelho Ferreira
+Copyright (c) 2021 William Quelho Ferreira
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

config.ld

@@ -2,4 +2,4 @@ project = "functional"
 file = "functional.lua"
 dir = "docs"
 title = "functional documentation"
-description = "Functional programming utilities written in pure lua"
+description = "Functional programming utilities written in pure Lua"

docs/index.html

@@ -30,7 +30,6 @@ <h1>functional</h1>
 <h2>Contents</h2>
 <ul>
 <li><a href="#Functions">Functions</a></li>
-<li><a href="#Fields">Fields</a></li>
 <li><a href="#Class_Iterator">Class Iterator </a></li>
 </ul>
 
@@ -80,7 +79,7 @@ <h4>Iterable</h4>
     <h3>Info:</h3>
     <ul>
         <li><strong>Copyright</strong>: 2021</li>
-        <li><strong>Release</strong>: 1.2.0</li>
+        <li><strong>Release</strong>: 1.3.0</li>
         <li><strong>License</strong>: MIT</li>
         <li><strong>Author</strong>: William Quelho Ferreira</li>
     </ul>
@@ -93,7 +92,7 @@ <h2><a href="#Functions">Functions</a></h2>
 	<td class="summary">Create an <code><a href="index.html#Iterator">Iterator</a></code> for the <code>iterable</code>.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#exports.counter">exports.counter (...)</a></td>
+	<td class="name" nowrap><a href="#exports.counter">exports.counter ()</a></td>
 	<td class="summary">Iterate over the naturals starting at 1.</td>
 	</tr>
 	<tr>
@@ -179,20 +178,21 @@ <h2><a href="#Functions">Functions</a></h2>
  functions into global scope.</td>
 	</tr>
 </table>
-<h2><a href="#Fields">Fields</a></h2>
+<h2><a href="#Class_Iterator">Class Iterator </a></h2>
 <table class="function_list">
 	<tr>
-	<td class="name" nowrap><a href="#_VERSION">_VERSION</a></td>
+	<td class="name" nowrap><a href="#Iterator._VERSION">Iterator._VERSION</a></td>
 	<td class="summary">Module version.</td>
 	</tr>
-</table>
-<h2><a href="#Class_Iterator">Class Iterator </a></h2>
-<table class="function_list">
 	<tr>
 	<td class="name" nowrap><a href="#Iterator.create">Iterator.create (iterable)</a></td>
 	<td class="summary">Iterate over the given <code>iterable</code>.</td>
 	</tr>
 	<tr>
+	<td class="name" nowrap><a href="#Iterator:next">Iterator:next ()</a></td>
+	<td class="summary">Retrieve the next element from the iterator.</td>
+	</tr>
+	<tr>
 	<td class="name" nowrap><a href="#Iterator.counter">Iterator.counter ()</a></td>
 	<td class="summary">Iterate over the naturals starting at 1.</td>
 	</tr>
@@ -205,8 +205,12 @@ <h2><a href="#Class_Iterator">Class Iterator </a></h2>
 	<td class="summary">Iterate over the <code>coroutine</code>'s yielded values.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Iterator.from_iterated_call">Iterator.from_iterated_call (func)</a></td>
-	<td class="summary">Iterate over the function's returned values upon repeated calls</td>
+	<td class="name" nowrap><a href="#Iterator.from">Iterator.from (func, is, var)</a></td>
+	<td class="summary">Iterate over the function's returned values upon repeated calls.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#Iterator.packed_from">Iterator.packed_from (func, is, var)</a></td>
+	<td class="summary">Iterate over the function's returned values (packed into a table) upon repeated calls.</td>
 	</tr>
 	<tr>
 	<td class="name" nowrap><a href="#Iterator.clone">Iterator.clone (iterable)</a></td>
@@ -320,18 +324,12 @@ <h3>Returns:</h3>
 </dd>
     <dt>
     <a name = "exports.counter"></a>
-    <strong>exports.counter (...)</strong>
+    <strong>exports.counter ()</strong>
     </dt>
     <dd>
     Iterate over the naturals starting at 1.
 
 
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">...</span>
-
-        </li>
-    </ul>
 
     <h3>Returns:</h3>
     <ol>
@@ -1060,12 +1058,12 @@ <h3>Returns:</h3>
 
 </dd>
 </dl>
-    <h2 class="section-header "><a name="Fields"></a>Fields</h2>
+    <h2 class="section-header "><a name="Class_Iterator"></a>Class Iterator </h2>
 
     <dl class="function">
     <dt>
-    <a name = "_VERSION"></a>
-    <strong>_VERSION</strong>
+    <a name = "Iterator._VERSION"></a>
+    <strong>Iterator._VERSION</strong>
     </dt>
     <dd>
     Module version.
@@ -1077,10 +1075,6 @@ <h2 class="section-header "><a name="Fields"></a>Fields</h2>
 
 
 </dd>
-</dl>
-    <h2 class="section-header "><a name="Class_Iterator"></a>Class Iterator </h2>
-
-    <dl class="function">
     <dt>
     <a name = "Iterator.create"></a>
     <strong>Iterator.create (iterable)</strong>
@@ -1110,6 +1104,25 @@ <h3>Returns:</h3>
 
 
 
+</dd>
+    <dt>
+    <a name = "Iterator:next"></a>
+    <strong>Iterator:next ()</strong>
+    </dt>
+    <dd>
+    Retrieve the next element from the iterator.
+
+
+
+    <h3>Returns:</h3>
+    <ol>
+
+        the next value in the sequence
+    </ol>
+
+
+
+
 </dd>
     <dt>
     <a name = "Iterator.counter"></a>
@@ -1206,11 +1219,13 @@ <h3>Returns:</h3>
 
 </dd>
     <dt>
-    <a name = "Iterator.from_iterated_call"></a>
-    <strong>Iterator.from_iterated_call (func)</strong>
+    <a name = "Iterator.from"></a>
+    <strong>Iterator.from (func, is, var)</strong>
     </dt>
     <dd>
-    Iterate over the function's returned values upon repeated calls
+    Iterate over the function's returned values upon repeated calls.
+ This can effectively convert a vanilla-Lua iterator into a functional-style
+ one (e.g., <code>Iterator.from(io.lines "my_file.txt")</code> gives you a string iterator).
 
 
     <h3>Parameters:</h3>
@@ -1219,6 +1234,12 @@ <h3>Parameters:</h3>
             <span class="types"><span class="type">function</span></span>
          the function to call
         </li>
+        <li><span class="parameter">is</span>
+         invariant state passed to func
+        </li>
+        <li><span class="parameter">var</span>
+         initial variable passed to func
+        </li>
     </ul>
 
     <h3>Returns:</h3>
@@ -1231,6 +1252,42 @@ <h3>Returns:</h3>
 
 
 
+</dd>
+    <dt>
+    <a name = "Iterator.packed_from"></a>
+    <strong>Iterator.packed_from (func, is, var)</strong>
+    </dt>
+    <dd>
+    Iterate over the function's returned values (packed into a table) upon repeated calls.
+ This is similar to <a href="index.html#Iterator.from">Iterator.from</a>, but instead of the created Iterator
+ generating multiple return values per call, it returns them all
+ packed into an array.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">func</span>
+            <span class="types"><span class="type">function</span></span>
+         the function to call
+        </li>
+        <li><span class="parameter">is</span>
+         invariant state passed to func
+        </li>
+        <li><span class="parameter">var</span>
+         initial variable passed to fund
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><span class="type">iterator</span></span>
+        the new <code><a href="index.html#Iterator">Iterator</a></code>
+    </ol>
+
+
+
+
 </dd>
     <dt>
     <a name = "Iterator.clone"></a>
@@ -1737,7 +1794,7 @@ <h3>Returns:</h3>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2021-09-05 23:41:35 </i>
+<i style="float:right;">Last updated 2021-09-09 18:35:44 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

functional-1.2-0.rockspec → functional-1.3-0.rockspec

@@ -1,8 +1,8 @@
 package = "functional"
-version = "1.2-0"
+version = "1.3-0"
 source = {
   url = "git://github.com/wqferr/functional",
-  tag = "v1.2.0"
+  tag = "v1.3.0"
 }
 
 description = {

functional.d.tl

@@ -6,13 +6,24 @@ local record module
   type mapping = function<T, U>(T): U
   type reducer = function<T, A>(A, T): A
 
+  type vanilla_singlearg_iter = function<IS, T>(IS, T): T
+
+  -- FIXME in order to properly support iterators with multiple
+  -- types per return,
+  --    https://github.com/teal-language/tl/pull/449
+  -- needs to be merged
+  type vanilla_multiarg_iter = function<IS, T>(IS, ...: T): T...
+
   record Iterator<T>
     create: function({T}): Iterator<T>
     create: function(Iterator<T>): Iterator<T>
     counter: function(): Iterator<integer>
-    range: function(integer, integer, integer): Iterator<integer>
+
+    from: function<IS>(vanilla_singlearg_iter<IS, T>, IS, T): Iterator<T>
+    packed_from: function<IS>(vanilla_multiarg_iter<IS, T>, IS, T): Iterator<{T}>
+
     from_coroutine: function(thread): Iterator<any>
-    from_iterated_call: function(producer<T>): Iterator<T>
+    range: function(integer, integer, integer): Iterator<integer>
     clone: function(Iterator<T>): Iterator<T>
 
     is_complete: function(Iterator<T>): boolean
@@ -23,7 +34,6 @@ local record module
 
     filter: function(Iterator<T>, predicate<T>): Iterator<T>
     map: function<U>(Iterator<T>, mapping<T, U>): Iterator<U>
-    reduce: function(Iterator<T>, reducer<T, T>): T
     reduce: function<A>(Iterator<T>, reducer<T, A>, A): A
     foreach: function(Iterator<T>, consumer<T>)
 
@@ -72,10 +82,14 @@ local record module
   every: function<T>(Iterator<T>, integer): Iterator<T>
 
   any: function<T>({T}, predicate<T>): boolean
+  any: function<T>(Iterator<T>, predicate<T>): boolean
   all: function<T>({T}, predicate<T>): boolean
+  all: function<T>(Iterator<T>, predicate<T>): boolean
 
-  to_array: function<T>({T}): {T}
+  -- Suggestion to change order of these declarations by
+  -- GitHub user FractalU
   to_array: function<T>(Iterator<T>): {T}
+  to_array: function<T>({T}): {T}
 
   to_coroutine: function<T>({T}): thread
   to_coroutine: function<T>(Iterator<T>): thread