release 1.10.0 docs1.10.0

10 files changed, 515 insertions, 46 deletions

diff --git a/docs/classes/pl.Date.html b/docs/classes/pl.Date.html
index 9771577..47d3d65 100644
--- a/docs/classes/pl.Date.html
+++ b/docs/classes/pl.Date.html
@@ -122,6 +122,9 @@
 <p>Date and Date Format classes.</p>
 <p> See  <a href="../manual/05-dates.md.html#">the Guide</a>.</p>
 
+<p> NOTE: the date module is deprecated! see
+ https://github.com/lunarmodules/Penlight/issues/285</p>
+
 <p> Dependencies: <a href="../libraries/pl.class.html#">pl.class</a>, <a href="../libraries/pl.stringx.html#">pl.stringx</a>, <a href="../libraries/pl.utils.html#">pl.utils</a></p>
 
 
diff --git a/docs/index.html b/docs/index.html
index 00eaac7..ec08e4d 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -114,7 +114,7 @@
 <div id="content">
 
 
-  <h2>Penlight Lua Libraries 1.9.2</h2>
+  <h2>Penlight Lua Libraries 1.10.0</h2>
   <p>Penlight is a set of pure Lua libraries for making it easier to work with common tasks like iterating over directories, reading configuration files and the like. Provides functional operations on tables and sequences. Visit the <a href="https://github.com/lunarmodules/Penlight">GitHub project</a> to review the code or file issues. Skip to the <a href="manual/01-introduction.md.html#">introduction</a>.</p>
 
 <h2>Libraries</h2>
diff --git a/docs/libraries/pl.array2d.html b/docs/libraries/pl.array2d.html
index 399139a..8ee905b 100644
--- a/docs/libraries/pl.array2d.html
+++ b/docs/libraries/pl.array2d.html
@@ -121,20 +121,30 @@
 <p>Operations on two-dimensional arrays.</p>
 <p> See <a href="../manual/02-arrays.md.html#Operations_on_two_dimensional_tables">The Guide</a></p>
 
+<p> The size of the arrays is determined by using the length operator <code>#</code> hence
+ the module is not <code>nil</code> safe, and the usual precautions apply.</p>
+
+<p> Note: all functions taking <code>i1,j1,i2,j2</code> as arguments will normalize the
+ arguments using <a href="../libraries/pl.array2d.html#default_range">default_range</a>.</p>
+
 <p> Dependencies: <a href="../libraries/pl.utils.html#">pl.utils</a>, <a href="../libraries/pl.tablex.html#">pl.tablex</a>, <a href="../libraries/pl.types.html#">pl.types</a></p>
 
 
 <h2><a href="#Functions">Functions</a></h2>
 <table class="function_list">
 	<tr>
-	<td class="name" nowrap><a href="#size">size (t)</a></td>
+	<td class="name" nowrap><a href="#size">size (a)</a></td>
 	<td class="summary">return the row and column size.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#column">column (a, key)</a></td>
+	<td class="name" nowrap><a href="#column">column (a, j)</a></td>
 	<td class="summary">extract a column from the 2D array.</td>
 	</tr>
 	<tr>
+	<td class="name" nowrap><a href="#row">row (a, i)</a></td>
+	<td class="summary">extract a row from the 2D array.</td>
+	</tr>
+	<tr>
 	<td class="name" nowrap><a href="#map">map (f, a, arg)</a></td>
 	<td class="summary">map a function over a 2D array</td>
 	</tr>
@@ -167,6 +177,10 @@
 	<td class="summary">reshape a 2D array.</td>
 	</tr>
 	<tr>
+	<td class="name" nowrap><a href="#transpose">transpose (t)</a></td>
+	<td class="summary">transpose a 2D array.</td>
+	</tr>
+	<tr>
 	<td class="name" nowrap><a href="#swap_rows">swap_rows (t, i1, i2)</a></td>
 	<td class="summary">swap two rows of an array.</td>
 	</tr>
@@ -199,6 +213,10 @@
 	<td class="summary">get a slice of a 2D array using spreadsheet range notation.</td>
 	</tr>
 	<tr>
+	<td class="name" nowrap><a href="#default_range">default_range (t, i1, j1, i2, j2)</a></td>
+	<td class="summary">normalizes coordinates to valid positive entries and defaults.</td>
+	</tr>
+	<tr>
 	<td class="name" nowrap><a href="#slice">slice (t, i1, j1, i2, j2)</a></td>
 	<td class="summary">get a slice of a 2D array.</td>
 	</tr>
@@ -227,6 +245,10 @@
 	<td class="summary">iterate over all columns.</td>
 	</tr>
 	<tr>
+	<td class="name" nowrap><a href="#rows">rows (a)</a></td>
+	<td class="summary">iterate over all rows.</td>
+	</tr>
+	<tr>
 	<td class="name" nowrap><a href="#new">new (rows, cols, val)</a></td>
 	<td class="summary">new array of specified dimensions</td>
 	</tr>
@@ -241,15 +263,17 @@
     <dl class="function">
     <dt>
     <a name = "size"></a>
-    <strong>size (t)</strong>
+    <strong>size (a)</strong>
     </dt>
     <dd>
     return the row and column size.
+ Size is calculated using the Lua length operator #, so usual precautions
+ regarding <code>nil</code> values apply.
 
 
     <h3>Parameters:</h3>
     <ul>
-        <li><span class="parameter">t</span>
+        <li><span class="parameter">a</span>
             <span class="types"><span class="type">array</span></span>
          a 2d array
         </li>
@@ -259,10 +283,10 @@
     <ol>
         <li>
            <span class="types"><span class="type">int</span></span>
-        number of rows</li>
+        number of rows (<code>#a</code>)</li>
         <li>
            <span class="types"><span class="type">int</span></span>
-        number of cols</li>
+        number of cols (<code>#a[1]</code>)</li>
     </ol>
 
 
@@ -271,7 +295,7 @@
 </dd>
     <dt>
     <a name = "column"></a>
-    <strong>column (a, key)</strong>
+    <strong>column (a, j)</strong>
     </dt>
     <dd>
     extract a column from the 2D array.
@@ -283,8 +307,8 @@
             <span class="types"><span class="type">array</span></span>
          2d array
         </li>
-        <li><span class="parameter">key</span>
-         an index or key
+        <li><span class="parameter">j</span>
+         column index
         </li>
     </ul>
 
@@ -299,6 +323,37 @@
 
 </dd>
     <dt>
+    <a name = "row"></a>
+    <strong>row (a, i)</strong>
+    </dt>
+    <dd>
+    extract a row from the 2D array.
+ Added in line with <a href="../libraries/pl.array2d.html#column">column</a>, for read-only purposes directly
+ accessing a[i] is more performant.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">a</span>
+            <span class="types"><span class="type">array</span></span>
+         2d array
+        </li>
+        <li><span class="parameter">i</span>
+         row index
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+        1d array (copy of the row)
+    </ol>
+
+
+
+
+</dd>
+    <dt>
     <a name = "map"></a>
     <strong>map (f, a, arg)</strong>
     </dt>
@@ -444,11 +499,11 @@
         </li>
         <li><span class="parameter">ad</span>
             <span class="types"><span class="type">int</span></span>
-         order of first array (1 or 2)
+         order of first array (<code>1</code> if <code>a</code> is a list/array, <code>2</code> if it is a 2d array)
         </li>
         <li><span class="parameter">bd</span>
             <span class="types"><span class="type">int</span></span>
-         order of second array (1 or 2)
+         order of second array (<code>1</code> if <code>b</code> is a list/array, <code>2</code> if it is a 2d array)
         </li>
         <li><span class="parameter">a</span>
             <span class="types"><span class="type">tab</span></span>
@@ -547,7 +602,7 @@
     <strong>reshape (t, nrows, co)</strong>
     </dt>
     <dd>
-    reshape a 2D array.
+    reshape a 2D array.  Reshape the aray by specifying a new nr of rows.
 
 
     <h3>Parameters:</h3>
@@ -562,7 +617,33 @@
         </li>
         <li><span class="parameter">co</span>
             <span class="types"><span class="type">bool</span></span>
-         column-order (Fortran-style) (default false)
+         use column-order (Fortran-style) (default false)
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+        a new 2d array
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "transpose"></a>
+    <strong>transpose (t)</strong>
+    </dt>
+    <dd>
+    transpose a 2D array.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">t</span>
+            <span class="types"><span class="type">array</span></span>
+         2d array
         </li>
     </ul>
 
@@ -600,6 +681,11 @@
         </li>
     </ul>
 
+    <h3>Returns:</h3>
+    <ol>
+
+        t (same, modified 2d array)
+    </ol>
 
 
 
@@ -629,6 +715,11 @@
         </li>
     </ul>
 
+    <h3>Returns:</h3>
+    <ol>
+
+        t (same, modified 2d array)
+    </ol>
 
 
 
@@ -654,6 +745,11 @@
         </li>
     </ul>
 
+    <h3>Returns:</h3>
+    <ol>
+
+        a new 2d array with the extracted rows
+    </ol>
 
 
 
@@ -679,6 +775,11 @@
         </li>
     </ul>
 
+    <h3>Returns:</h3>
+    <ol>
+
+        a new 2d array with the extracted colums
+    </ol>
 
 
 
@@ -748,7 +849,7 @@
     <ul>
         <li><span class="parameter">s</span>
             <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-         a range.
+         a range (case insensitive).
         </li>
     </ul>
 
@@ -756,16 +857,16 @@
     <ol>
         <li>
            <span class="types"><span class="type">int</span></span>
-        start col</li>
-        <li>
-           <span class="types"><span class="type">int</span></span>
         start row</li>
         <li>
            <span class="types"><span class="type">int</span></span>
-        end col</li>
+        start col</li>
         <li>
            <span class="types"><span class="type">int</span></span>
         end row</li>
+        <li>
+           <span class="types"><span class="type">int</span></span>
+        end col</li>
     </ol>
 
 
@@ -808,6 +909,46 @@
 
 </dd>
     <dt>
+    <a name = "default_range"></a>
+    <strong>default_range (t, i1, j1, i2, j2)</strong>
+    </dt>
+    <dd>
+    normalizes coordinates to valid positive entries and defaults.
+ Negative indices will be counted from the end, too low, or too high
+ will be limited by the array sizes.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">t</span>
+            <span class="types"><span class="type">array</span></span>
+         a 2D array
+        </li>
+        <li><span class="parameter">i1</span>
+            <span class="types"><span class="type">int</span></span>
+         start row (default 1)
+        </li>
+        <li><span class="parameter">j1</span>
+            <span class="types"><span class="type">int</span></span>
+         start col (default 1)
+        </li>
+        <li><span class="parameter">i2</span>
+            <span class="types"><span class="type">int</span></span>
+         end row   (default N)
+        </li>
+        <li><span class="parameter">j2</span>
+            <span class="types"><span class="type">int</span></span>
+         end col   (default M)
+ return i1, j1, i2, j2
+        </li>
+    </ul>
+
+
+
+
+
+</dd>
+    <dt>
     <a name = "slice"></a>
     <strong>slice (t, i1, j1, i2, j2)</strong>
     </dt>
@@ -865,7 +1006,7 @@
          a 2D array
         </li>
         <li><span class="parameter">value</span>
-         the value (may be a function)
+         the value (may be a function, called as <code>val(i,j)</code>)
         </li>
         <li><span class="parameter">i1</span>
             <span class="types"><span class="type">int</span></span>
@@ -954,11 +1095,11 @@
         </li>
         <li><span class="parameter">row_op</span>
             <span class="types"><span class="type">func</span></span>
-         function to call on each value
+         function to call on each value; <code>row_op(row,j)</code>
         </li>
         <li><span class="parameter">end_row_op</span>
             <span class="types"><span class="type">func</span></span>
-         function to call at end of each row
+         function to call at end of each row; <code>end_row_op(i)</code>
         </li>
         <li><span class="parameter">i1</span>
             <span class="types"><span class="type">int</span></span>
@@ -1047,7 +1188,7 @@
          2D array
         </li>
         <li><span class="parameter">indices</span>
-            <span class="types"><span class="type">{int}</span></span>
+            <span class="types"><span class="type">bool</span></span>
          with indices (default false)
         </li>
         <li><span class="parameter">i1</span>
@@ -1071,7 +1212,7 @@
     <h3>Returns:</h3>
     <ol>
 
-        either value or i,j,value depending on indices
+        either <code>value</code> or <code>i,j,value</code> depending on the value of <code>indices</code>
     </ol>
 
 
@@ -1097,7 +1238,35 @@
     <h3>Returns:</h3>
     <ol>
 
-        each column in turn
+        column, column-index
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "rows"></a>
+    <strong>rows (a)</strong>
+    </dt>
+    <dd>
+    iterate over all rows.
+ Returns a copy of the row, for read-only purrposes directly iterating
+ is more performant; <code>ipairs(a)</code>
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">a</span>
+            <span class="types"><span class="type">array</span></span>
+         a 2D array
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+        row, row-index
     </ol>
 
 
diff --git a/docs/libraries/pl.compat.html b/docs/libraries/pl.compat.html
index eb417bc..6680030 100644
--- a/docs/libraries/pl.compat.html
+++ b/docs/libraries/pl.compat.html
@@ -36,6 +36,7 @@
 <li><a href="#Functions">Functions</a></li>
 <li><a href="#Fields">Fields</a></li>
 <li><a href="#Global_exported_functions__for_Lua_5_1___LuaJIT_">Global exported functions (for Lua 5.1 & LuaJIT) </a></li>
+<li><a href="#Global_exported_functions__for_Lua___5_4_">Global exported functions (for Lua < 5.4) </a></li>
 </ul>
 
 
@@ -186,6 +187,13 @@
 	<td class="summary">return the full path where a file name would be matched.</td>
 	</tr>
 </table>
+<h2><a href="#Global_exported_functions__for_Lua___5_4_">Global exported functions (for Lua < 5.4) </a></h2>
+<table class="function_list">
+	<tr>
+	<td class="name" nowrap><a href="#warn">warn (...)</a></td>
+	<td class="summary">raise a warning message.</td>
+	</tr>
+</table>
 
 <br/>
 <br/>
@@ -535,6 +543,31 @@
 
 </dd>
 </dl>
+    <h2 class="section-header "><a name="Global_exported_functions__for_Lua___5_4_"></a>Global exported functions (for Lua < 5.4) </h2>
+
+    <dl class="function">
+    <dt>
+    <a name = "warn"></a>
+    <strong>warn (...)</strong>
+    </dt>
+    <dd>
+    raise a warning message.
+ This functions mimics the <a href="../libraries/pl.compat.html#warn">warn</a> function added in Lua 5.4.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">...</span>
+         any arguments
+        </li>
+    </ul>
+
+
+
+
+
+</dd>
+</dl>
 
 
 </div> <!-- id="content" -->
diff --git a/docs/libraries/pl.dir.html b/docs/libraries/pl.dir.html
index 6c0d727..5dfa0f6 100644
--- a/docs/libraries/pl.dir.html
+++ b/docs/libraries/pl.dir.html
@@ -436,13 +436,14 @@
     </dt>
     <dd>
     remove a whole directory tree.
+ Symlinks in the tree will be deleted without following them.
 
 
     <h3>Parameters:</h3>
     <ul>
         <li><span class="parameter">fullpath</span>
             <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-         A directory path
+         A directory path (must be an actual directory, not a symlink)
         </li>
     </ul>
 
diff --git a/docs/libraries/pl.permute.html b/docs/libraries/pl.permute.html
index 6b94435..afb887e 100644
--- a/docs/libraries/pl.permute.html
+++ b/docs/libraries/pl.permute.html
@@ -125,12 +125,28 @@
 <h2><a href="#Functions">Functions</a></h2>
 <table class="function_list">
 	<tr>
-	<td class="name" nowrap><a href="#iter">iter (a)</a></td>
-	<td class="summary">an iterator over all permutations of the elements of a list.</td>
+	<td class="name" nowrap><a href="#order_iter">order_iter (a)</a></td>
+	<td class="summary">an iterator over all order-permutations of the elements of a list.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#table">table (a)</a></td>
-	<td class="summary">construct a table containing all the permutations of a list.</td>
+	<td class="name" nowrap><a href="#order_table">order_table (a)</a></td>
+	<td class="summary">construct a table containing all the order-permutations of a list.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#list_iter">list_iter (...)</a></td>
+	<td class="summary">an iterator over all permutations of the elements of the given lists.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#list_table">list_table (...)</a></td>
+	<td class="summary">construct a table containing all the permutations of a set of lists.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#iter">iter (...)</a></td>
+	<td class="summary">deprecated.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#table">table (...)</a></td>
+	<td class="summary">deprecated.</td>
 	</tr>
 </table>
 
@@ -142,11 +158,11 @@
 
     <dl class="function">
     <dt>
-    <a name = "iter"></a>
-    <strong>iter (a)</strong>
+    <a name = "order_iter"></a>
+    <strong>order_iter (a)</strong>
     </dt>
     <dd>
-    an iterator over all permutations of the elements of a list.
+    an iterator over all order-permutations of the elements of a list.
  Please note that the same list is returned each time, so do not keep references!
 
 
@@ -168,11 +184,11 @@
 
 </dd>
     <dt>
-    <a name = "table"></a>
-    <strong>table (a)</strong>
+    <a name = "order_table"></a>
+    <strong>order_table (a)</strong>
     </dt>
     <dd>
-    construct a table containing all the permutations of a list.
+    construct a table containing all the order-permutations of a list.
 
 
     <h3>Parameters:</h3>
@@ -192,9 +208,138 @@
 
     <h3>Usage:</h3>
     <ul>
-        <pre class="example">permute.<span class="global">table</span> {<span class="number">1</span>,<span class="number">2</span>,<span class="number">3</span>} <span class="comment">--&gt; {{2,3,1},{3,2,1},{3,1,2},{1,3,2},{2,1,3},{1,2,3}}</span></pre>
+        <pre class="example">permute.order_table {<span class="number">1</span>,<span class="number">2</span>,<span class="number">3</span>} <span class="comment">--&gt; {{2,3,1},{3,2,1},{3,1,2},{1,3,2},{2,1,3},{1,2,3}}</span></pre>
+    </ul>
+
+</dd>
+    <dt>
+    <a name = "list_iter"></a>
+    <strong>list_iter (...)</strong>
+    </dt>
+    <dd>
+    an iterator over all permutations of the elements of the given lists.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">...</span>
+         list-like tables, they are nil-safe if a length-field <code>n</code> is provided (see <a href="../libraries/pl.utils.html#pack">utils.pack</a>)
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+        an iterator which provides the next permutation as return values in the same order as the provided lists, preceeded by an index
+    </ol>
+
+
+
+    <h3>Usage:</h3>
+    <ul>
+        <pre class="example"><span class="keyword">local</span> strs = utils.pack(<span class="string">"one"</span>, <span class="keyword">nil</span>, <span class="string">"three"</span>)  <span class="comment">-- adds an 'n' field for nil-safety
+</span><span class="keyword">local</span> bools = utils.pack(<span class="keyword">true</span>, <span class="keyword">false</span>)
+<span class="keyword">local</span> iter = permute.list_iter(strs, bools)
+
+<span class="global">print</span>(iter())    <span class="comment">--&gt; 1, one, true
+</span><span class="global">print</span>(iter())    <span class="comment">--&gt; 2, nil, true
+</span><span class="global">print</span>(iter())    <span class="comment">--&gt; 3, three, true
+</span><span class="global">print</span>(iter())    <span class="comment">--&gt; 4, one, false
+</span><span class="global">print</span>(iter())    <span class="comment">--&gt; 5, nil, false
+</span><span class="global">print</span>(iter())    <span class="comment">--&gt; 6, three, false</span></pre>
+    </ul>
+
+</dd>
+    <dt>
+    <a name = "list_table"></a>
+    <strong>list_table (...)</strong>
+    </dt>
+    <dd>
+    construct a table containing all the permutations of a set of lists.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">...</span>
+         list-like tables, they are nil-safe if a length-field <code>n</code> is provided
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+        a list of lists, the sub-lists have an 'n' field for nil-safety
+    </ol>
+
+
+
+    <h3>Usage:</h3>
+    <ul>
+        <pre class="example"><span class="keyword">local</span> strs = utils.pack(<span class="string">"one"</span>, <span class="keyword">nil</span>, <span class="string">"three"</span>)  <span class="comment">-- adds an 'n' field for nil-safety
+</span><span class="keyword">local</span> bools = utils.pack(<span class="keyword">true</span>, <span class="keyword">false</span>)
+<span class="keyword">local</span> results = permute.list_table(strs, bools)
+<span class="comment">-- results = {
+</span><span class="comment">--   { "one, true, n = 2 }
+</span><span class="comment">--   { nil, true, n = 2 },
+</span><span class="comment">--   { "three, true, n = 2 },
+</span><span class="comment">--   { "one, false, n = 2 },
+</span><span class="comment">--   { nil, false, n = 2 },
+</span><span class="comment">--   { "three", false, n = 2 },
+</span><span class="comment">-- }</span></pre>
+    </ul>
+
+</dd>
+    <dt>
+    <a name = "iter"></a>
+    <strong>iter (...)</strong>
+    </dt>
+    <dd>
+    deprecated.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">...</span>
+
+
+
+        </li>
+    </ul>
+
+
+
+    <h3>See also:</h3>
+    <ul>
+         <a href="../libraries/pl.permute.html#order_iter">permute.order_iter</a>
+    </ul>
+
+
+</dd>
+    <dt>
+    <a name = "table"></a>
+    <strong>table (...)</strong>
+    </dt>
+    <dd>
+    deprecated.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">...</span>
+
+
+
+        </li>
+    </ul>
+
+
+
+    <h3>See also:</h3>
+    <ul>
+         <a href="../libraries/pl.permute.html#order_iter">permute.order_iter</a>
     </ul>
 
+
 </dd>
 </dl>
 
diff --git a/docs/libraries/pl.utils.html b/docs/libraries/pl.utils.html
index c692b32..35c9419 100644
--- a/docs/libraries/pl.utils.html
+++ b/docs/libraries/pl.utils.html
@@ -40,6 +40,7 @@
 <li><a href="#OS_functions">OS functions </a></li>
 <li><a href="#String_functions">String functions </a></li>
 <li><a href="#Functional">Functional </a></li>
+<li><a href="#Deprecation">Deprecation </a></li>
 </ul>
 
 
@@ -241,7 +242,7 @@
 	<td class="summary">split a string into a list of strings separated by a delimiter.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#splitv">splitv (s, re)</a></td>
+	<td class="name" nowrap><a href="#splitv">splitv (s, re, plain, n)</a></td>
 	<td class="summary">split a string into a number of return values.</td>
 	</tr>
 </table>
@@ -268,6 +269,17 @@
 	<td class="summary">bind the second argument of the function to a value.</td>
 	</tr>
 </table>
+<h2><a href="#Deprecation">Deprecation </a></h2>
+<table class="function_list">
+	<tr>
+	<td class="name" nowrap><a href="#set_deprecation_func">set_deprecation_func (func)</a></td>
+	<td class="summary">Sets a deprecation warning function.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#raise_deprecation">raise_deprecation (opts)</a></td>
+	<td class="summary">raises a deprecation warning.</td>
+	</tr>
+</table>
 
 <br/>
 <br/>
@@ -1020,13 +1032,13 @@ utils.is_type(my_obj, my_mt)  <span class="comment">--&gt; true</span></pre>
          The input string
         </li>
         <li><span class="parameter">re</span>
-         A Lua string pattern; defaults to '%s+'
+         optional A Lua string pattern; defaults to '%s+'
         </li>
         <li><span class="parameter">plain</span>
-         don't use Lua patterns
+         optional If truthy don't use Lua patterns
         </li>
         <li><span class="parameter">n</span>
-         optional maximum number of splits
+         optional maximum number of elements (if there are more, the last will remian un-split)
         </li>
     </ul>
 
@@ -1039,15 +1051,21 @@ utils.is_type(my_obj, my_mt)  <span class="comment">--&gt; true</span></pre>
     <h3>Raises:</h3>
     error if s is not a string
 
+    <h3>See also:</h3>
+    <ul>
+         <a href="../libraries/pl.utils.html#splitv">splitv</a>
+    </ul>
 
 
 </dd>
     <dt>
     <a name = "splitv"></a>
-    <strong>splitv (s, re)</strong>
+    <strong>splitv (s, re, plain, n)</strong>
     </dt>
     <dd>
     split a string into a number of return values.
+ Identical to <a href="../libraries/pl.utils.html#split">split</a> but returns multiple sub-strings instead of
+ a single list of sub-strings.
 
 
     <h3>Parameters:</h3>
@@ -1056,7 +1074,13 @@ utils.is_type(my_obj, my_mt)  <span class="comment">--&gt; true</span></pre>
          the string
         </li>
         <li><span class="parameter">re</span>
-         the delimiter, default space
+         A Lua string pattern; defaults to '%s+'
+        </li>
+        <li><span class="parameter">plain</span>
+         don't use Lua patterns
+        </li>
+        <li><span class="parameter">n</span>
+         optional maximum number of splits
         </li>
     </ul>
 
@@ -1074,7 +1098,9 @@ utils.is_type(my_obj, my_mt)  <span class="comment">--&gt; true</span></pre>
 
     <h3>Usage:</h3>
     <ul>
-        <pre class="example">first,<span class="global">next</span> = splitv(<span class="string">'jane:doe'</span>,<span class="string">':'</span>)</pre>
+        <pre class="example">first,<span class="global">next</span> = splitv(<span class="string">'user=jane=doe'</span>,<span class="string">'='</span>, <span class="keyword">false</span>, <span class="number">2</span>)
+<span class="global">assert</span>(first == <span class="string">"user"</span>)
+<span class="global">assert</span>(<span class="global">next</span> == <span class="string">"jane=doe"</span>)</pre>
     </ul>
 
 </dd>
@@ -1255,6 +1281,96 @@ string_lambda <span class="string">'_+1'</span> (<span class="number">2</span>)
 
 </dd>
 </dl>
+    <h2 class="section-header "><a name="Deprecation"></a>Deprecation </h2>
+
+    <dl class="function">
+    <dt>
+    <a name = "set_deprecation_func"></a>
+    <strong>set_deprecation_func (func)</strong>
+    </dt>
+    <dd>
+    Sets a deprecation warning function.
+ An application can override this function to support proper output of
+ deprecation warnings. The warnings can be generated from libraries or
+ functions by calling <a href="../libraries/pl.utils.html#raise_deprecation">utils.raise_deprecation</a>. The default function
+ will write to the 'warn' system (introduced in Lua 5.4, or the compatibility
+ function from the <a href="../libraries/pl.compat.html">compat</a> module for earlier versions).</p>
+
+<p> Note: only applications should set/change this function, libraries should not.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">func</span>
+         a callback with signature: <code>function(msg, trace)</code> both arguments are strings.
+        </li>
+    </ul>
+
+
+
+    <h3>See also:</h3>
+    <ul>
+         <a href="../libraries/pl.utils.html#raise_deprecation">utils.raise_deprecation</a>
+    </ul>
+
+    <h3>Usage:</h3>
+    <ul>
+        <pre class="example"><span class="comment">-- write to the Nginx logs with OpenResty
+</span>utils.set_deprecation_func(<span class="keyword">function</span>(msg, trace)
+  ngx.log(ngx.WARN, msg, <span class="string">" "</span>, trace)
+<span class="keyword">end</span>)
+
+<span class="comment">-- disable deprecation warnings
+</span>utils.set_deprecation_func()</pre>
+    </ul>
+
+</dd>
+    <dt>
+    <a name = "raise_deprecation"></a>
+    <strong>raise_deprecation (opts)</strong>
+    </dt>
+    <dd>
+    raises a deprecation warning.
+ For options see the usage example below.</p>
+
+<p> Note: the <code>opts.deprecated_after</code> field is the last version in which
+ a feature or option was NOT YET deprecated! Because when writing the code it
+ is quite often not known in what version the code will land. But the last
+ released version is usually known.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">opts</span>
+         options table
+        </li>
+    </ul>
+
+
+
+    <h3>See also:</h3>
+    <ul>
+         <a href="../libraries/pl.utils.html#set_deprecation_func">utils.set_deprecation_func</a>
+    </ul>
+
+    <h3>Usage:</h3>
+    <ul>
+        <pre class="example">warn(<span class="string">"@on"</span>)   <span class="comment">-- enable Lua warnings, they are usually off by default
+</span>
+<span class="keyword">function</span> stringx.islower(str)
+  raise_deprecation {
+    source = <span class="string">"Penlight "</span> .. utils._VERSION,                  <span class="comment">-- optional
+</span>    message = <span class="string">"function 'islower' was renamed to 'is_lower'"</span> <span class="comment">-- required
+</span>    version_removed = <span class="string">"2.0.0"</span>,                               <span class="comment">-- optional
+</span>    deprecated_after = <span class="string">"1.2.3"</span>,                              <span class="comment">-- optional
+</span>  }
+  <span class="keyword">return</span> stringx.is_lower(str)
+<span class="keyword">end</span>
+<span class="comment">-- output: "[Penlight 1.9.2] function 'islower' was renamed to 'is_lower' (deprecated after 1.2.3, scheduled for removal in 2.0.0)"</span></pre>
+    </ul>
+
+</dd>
+</dl>
 
 
 </div> <!-- id="content" -->
diff --git a/docs/manual/01-introduction.md.html b/docs/manual/01-introduction.md.html
index 0045f9d..fe42256 100644
--- a/docs/manual/01-introduction.md.html
+++ b/docs/manual/01-introduction.md.html
@@ -161,7 +161,7 @@ throw errors, to simplify coding, and so should be wrapped in <a href="https://w
 <p>If you are used to Python conventions, please note that all indices consistently
 start at 1.</p>
 
-<p>The Lua function <code>table.foreach</code> has been deprecated in favour of the <code>for in</code>
+<p>The Lua function <a href="https://www.lua.org/manual/5.1/manual.html#pdf-table.foreach">table.foreach</a> has been deprecated in favour of the <code>for in</code>
 statement, but such an operation becomes particularly useful with the
 higher-order function support in Penlight. Note that <a href="../libraries/pl.tablex.html#foreach">tablex.foreach</a> reverses
 the order, so that the function is passed the value and then the key. Although
diff --git a/docs/manual/05-dates.md.html b/docs/manual/05-dates.md.html
index a0fa0f3..c04b036 100644
--- a/docs/manual/05-dates.md.html
+++ b/docs/manual/05-dates.md.html
@@ -122,6 +122,8 @@
 
 <p><a id="date"></a></p>
 
+<p>NOTE: the Date module is deprecated</p>
+
 <p><a name="Creating_and_Displaying_Dates"></a></p>
 <h3>Creating and Displaying Dates</h3>
 
diff --git a/lua/pl/array2d.lua b/lua/pl/array2d.lua
index db55b39..2bc13b9 100644
--- a/lua/pl/array2d.lua
+++ b/lua/pl/array2d.lua
@@ -497,7 +497,7 @@ end
 
 --- iterate over all elements in a 2D array, with optional indices.
 -- @array2d a 2D array
--- @tparam {int} indices with indices (default false)
+-- @bool indices with indices (default false)
 -- @int i1 start row (default 1)
 -- @int j1 start col (default 1)
 -- @int i2 end row   (default N)