Added iterator

6 files changed, 105 insertions, 11 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9ba74e2..0d626d8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,13 +2,15 @@
 
 ##1.5.0 (04/04/17)
 
-* Improved `_.select` (cd9237c710c485d87a0bdb46e3d4eaae6f45b37c)
-* Fixed `_.compose` (452d519a4f66038eb13e403fdb6ba58b868cfa88)
-* Made `_.contains` as an alias to `_.include` (5622dac6ee2760d99654a4b575ef5dc9c3fdac11)
-* Improved `_.all` (8df3f7c6f6d0d4e395b936a4d804ad608db28072)
-* Fixed _.size (34eada9c525e589e7596ac5c8fc75e4447fa583e)
-* Added `_.bind2` (749f2b4c80663fef50d1f27062be5f230b3ff3f3)
-* Improved `_.map` to map key-value pairs to key-value pairs (e9d15840b4a84558e2ce1d1e6233b0f008071d17)
+* Improved `_.select`
+* Fixed `_.compose`
+* Made `_.contains` as an alias to `_.include`
+* Improved `_.all`
+* Fixed `_.size`
+* Added `_.bind2`
+* Improved `_.map` to map key-value pairs to key-value pairs
+* Added `_.reduceby`
+* Added `_.iterator` (and alias `_.iter`)
 
 ##1.4.0 (07/14/14)
 
diff --git a/doc/index.html b/doc/index.html
index 2dac4e7..df741b8 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -402,6 +402,10 @@
 	<td class="name" nowrap><a href="#uniqueId">uniqueId ([template[, ...]])</a></td>
 	<td class="summary">Generates an unique ID for the current session.</td>
 	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#iterate">iterate (f, x)</a></td>
+	<td class="summary">Produces an iterator which repeatedly apply a function <code>f</code> onto an input.</td>
+	</tr>
 </table>
 <h2><a href="#Object_functions">Object functions </a></h2>
 <table class="function_list">
@@ -3244,6 +3248,36 @@
 
 
 </dd>
+    <dt>
+    <a name = "iterate"></a>
+    <strong>iterate (f, x)</strong>
+    </dt>
+    <dd>
+    Produces an iterator which repeatedly apply a function <code>f</code> onto an input.<br/>
+ Yields x, then f(x), then f(f(x)), continuously.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">f</span>
+         a function
+        </li>
+        <li><span class="parameter">x</span>
+         an initial input to <code>f</code>
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+        an iterator fnction
+ <br/><em>Aliased as <code>iter</code></em>.
+    </ol>
+
+
+
+
+</dd>
 </dl>
     <h2 class="section-header "><a name="Object_functions"></a>Object functions </h2>
 
@@ -4050,7 +4084,7 @@
 </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 2017-04-07 14:21:19 </i>
+<i style="float:right;">Last updated 2017-04-07 15:13:09 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/doc/topics/tutorial.md.html b/doc/topics/tutorial.md.html
index fcd74b4..41cd643 100644
--- a/doc/topics/tutorial.md.html
+++ b/doc/topics/tutorial.md.html
@@ -324,7 +324,7 @@ For example,let us define a set of values.</p>
 </pre>
 
 
-<p>Using <a href="../index.html#reduceby">reduceby</a>, we can perform reduction considering only negative values :</p>
+<p>Then we can perform reduction considering only negative values :</p>
 
 <pre>
 _.reduceby(val, <span class="keyword">function</span>(memo,v)
@@ -1366,6 +1366,22 @@ _.uniqueId(formatter) <span class="comment">-- =&gt; '$ID1$'</span>
 </pre>
 
 
+<h3>iterator(f, x)</h3>
+
+<p><em>Aliases: <code>_.iter</code></em>.</p>
+
+<p>Returns an iterator function which constinuously applies a function <code>f</code> onto an input <code>x</code>.
+For example, let us go through the powers of two.</p>
+
+<pre>
+<span class="keyword">local</span> <span class="keyword">function</span> po2(x) <span class="keyword">return</span> x*<span class="number">2</span> <span class="keyword">end</span>
+<span class="keyword">local</span> <span class="keyword">function</span> iter_po2 = _.iterator(po2, <span class="number">1</span>)
+iter_po2() <span class="comment">-- =&gt; 2
+</span>iter_po2() <span class="comment">-- =&gt; 4
+</span>iter_po2() <span class="comment">-- =&gt; 8</span>
+</pre>
+
+
 <p><strong><a href="#TOC">[⬆]</a></strong></p>
 
 <p><a name="_a_name__object__Object_functions__a_"></a></p>
@@ -1773,7 +1789,7 @@ _.import(context, <span class="keyword">true</span>)
 </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 2017-04-07 14:21:19 </i>
+<i style="float:right;">Last updated 2017-04-07 15:13:09 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/doc/tutorial.md b/doc/tutorial.md
index fe0663d..a0fffef 100644
--- a/doc/tutorial.md
+++ b/doc/tutorial.md
@@ -1159,6 +1159,20 @@ local formatter = function(ID) return '$'..ID..'$' end
 _.uniqueId(formatter) -- => '$ID1$'
 ````
 
+### iterator(f, x)
+*Aliases: `_.iter`*.
+
+Returns an iterator function which constinuously applies a function `f` onto an input `x`.
+For example, let us go through the powers of two.
+
+```lua
+local function po2(x) return x*2 end
+local function iter_po2 = _.iterator(po2, 1)
+iter_po2() -- => 2
+iter_po2() -- => 4
+iter_po2() -- => 8
+````
+
 **[[⬆]](#TOC)**
 
 ## <a name='object'>Object functions</a>
diff --git a/moses.lua b/moses.lua
index 497a07e..f26a5f8 100644
--- a/moses.lua
+++ b/moses.lua
@@ -1316,6 +1316,20 @@ function _.uniqueId(template, ...)
   return unique_id_counter
 end
 
+--- Produces an iterator which repeatedly apply a function `f` onto an input. 
+-- Yields x, then f(x), then f(f(x)), continuously.
+-- @name iterate
+-- @param f a function 
+-- @param x an initial input to `f`
+-- @return an iterator fnction
+-- <br/><em>Aliased as `iter`</em>.
+function _.iterator(f, x)
+	return function()
+		x = f(x)
+		return x
+	end
+end
+
 --- Object functions
 --@section Object functions
 
@@ -1717,7 +1731,8 @@ do
   _.cache       = _.memoize
   _.juxt        = _.juxtapose
   _.uid         = _.uniqueId
-  
+  _.iter        = _.iterator
+	
   -- Object functions aliases
   _.methods     = _.functions
   _.choose      = _.pick
diff --git a/spec/func_spec.lua b/spec/func_spec.lua
index 6d86320..7a554db 100644
--- a/spec/func_spec.lua
+++ b/spec/func_spec.lua
@@ -260,4 +260,17 @@ context('Utility functions specs', function()
     
   end)  
   
+	context('iterator', function()
+
+		test('creates an iterator which continuously applies f on an input',function()
+			local next_even = _.iterator(function(x) return x + 2 end, 0)
+			assert_equal(next_even(), 2)
+			assert_equal(next_even(), 4)
+			assert_equal(next_even(), 6)
+			assert_equal(next_even(), 8)
+			assert_equal(next_even(),10)
+		end)
+		
+	end)
+	
 end)
\ No newline at end of file