Skip to content

Commit

Permalink
release 1.13.0 docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Tieske
Tieske committed Jul 22, 2022
1 parent b7beeba commit 2670414
Show file tree
Hide file tree
Showing 4 changed files with 117 additions and 20 deletions.
2 changes: 1 addition & 1 deletion docs/index.html
View file
Expand Up @@ -114,7 +114,7 @@ <h2>Examples</h2>
<div id="content">


<h2>Penlight Lua Libraries 1.12.0</h2>
<h2>Penlight Lua Libraries 1.13.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>
Expand Down
8 changes: 6 additions & 2 deletions docs/libraries/pl.app.html
View file
Expand Up @@ -131,7 +131,7 @@ <h2><a href="#Functions">Functions</a></h2>
<td class="summary">return the name of the current script running.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#require_here">require_here (base)</a></td>
<td class="name" nowrap><a href="#require_here">require_here (base, nofollow)</a></td>
<td class="summary">prefixes the current script's path to the Lua module path.</td>
</tr>
<tr>
Expand Down Expand Up @@ -181,7 +181,7 @@ <h3>Returns:</h3>
</dd>
<dt>
<a name = "require_here"></a>
<strong>require_here (base)</strong>
<strong>require_here (base, nofollow)</strong>
</dt>
<dd>
prefixes the current script's path to the Lua module path.
Expand All @@ -200,6 +200,10 @@ <h3>Parameters:</h3>
<span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
optional base directory (absolute, or relative path).
</li>
<li><span class="parameter">nofollow</span>
<span class="types"><span class="type">bool</span></span>
always use the invocation's directory, even if the invoked file is a symlink
</li>
</ul>

<h3>Returns:</h3>
Expand Down
4 changes: 2 additions & 2 deletions docs/libraries/pl.tablex.html
View file
Expand Up @@ -1794,7 +1794,7 @@ <h3>Parameters:</h3>
<ul>
<li><span class="parameter">t</span>
<span class="types"><span class="type">tab</span></span>
A table
A list-like table where the values are the keys of the input table
</li>
</ul>

Expand All @@ -1815,7 +1815,7 @@ <h3>Parameters:</h3>
<ul>
<li><span class="parameter">t</span>
<span class="types"><span class="type">tab</span></span>
A table
A list-like table where the values are the values of the input table
</li>
</ul>

Expand Down
123 changes: 108 additions & 15 deletions docs/libraries/pl.utils.html
View file
Expand Up @@ -170,6 +170,10 @@ <h2><a href="#Functions">Functions</a></h2>
<td class="name" nowrap><a href="#npairs">npairs (t[, i_start=1[, i_end=t.n or #t[, step=1]]])</a></td>
<td class="summary">an iterator with indices, similar to <a href="https://www.lua.org/manual/5.1/manual.html#pdf-ipairs">ipairs</a>, but with a range.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#kpairs">kpairs (t)</a></td>
<td class="summary">an iterator over all non-integer keys (inverse of <a href="https://www.lua.org/manual/5.1/manual.html#pdf-ipairs">ipairs</a>).</td>
</tr>
</table>
<h2><a href="#Tables">Tables</a></h2>
<table class="function_list">
Expand All @@ -190,7 +194,7 @@ <h2><a href="#Error_handling">Error handling </a></h2>
</tr>
<tr>
<td class="name" nowrap><a href="#enum">enum (...)</a></td>
<td class="summary">creates an Enum table.</td>
<td class="summary">creates an Enum or constants lookup table for improved error handling.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#function_arg">function_arg (idx, f, msg)</a></td>
Expand Down Expand Up @@ -606,6 +610,63 @@ <h3>Usage:</h3>
<span class="comment">-- t = { n = 3, [2] = "123", [3] = "nil" }</span></pre>
</ul>

</dd>
<dt>
<a name = "kpairs"></a>
<strong>kpairs (t)</strong>
</dt>
<dd>
an iterator over all non-integer keys (inverse of <a href="https://www.lua.org/manual/5.1/manual.html#pdf-ipairs">ipairs</a>).
It will skip any key that is an integer number, so negative indices or an
array with holes will not return those either (so it returns slightly less than
'the inverse of <a href="https://www.lua.org/manual/5.1/manual.html#pdf-ipairs">ipairs</a>').</p>

<p> This uses <a href="https://www.lua.org/manual/5.1/manual.html#pdf-pairs">pairs</a> under the hood, so any value that is iterable using <a href="https://www.lua.org/manual/5.1/manual.html#pdf-pairs">pairs</a>
will work with this function.


<h3>Parameters:</h3>
<ul>
<li><span class="parameter">t</span>
<span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
the table to iterate over
</li>
</ul>

<h3>Returns:</h3>
<ol>
<li>
<span class="types"><span class="type">key</span></span>


</li>
<li>
<span class="types"><span class="type">value</span></span>


</li>
</ol>



<h3>Usage:</h3>
<ul>
<pre class="example"><span class="keyword">local</span> t = {
<span class="string">"hello"</span>,
<span class="string">"world"</span>,
hello = <span class="string">"hallo"</span>,
world = <span class="string">"Welt"</span>,
}

<span class="keyword">for</span> k, v <span class="keyword">in</span> utils.kpairs(t) <span class="keyword">do</span>
<span class="global">print</span>(<span class="string">"German: "</span>, v)
<span class="keyword">end</span>

<span class="comment">-- output;
</span><span class="comment">-- German: hallo
</span><span class="comment">-- German: Welt</span></pre>
</ul>

</dd>
</dl>
<h2 class="section-header "><a name="Tables"></a>Tables</h2>
Expand Down Expand Up @@ -726,34 +787,38 @@ <h3>Usage:</h3>
<strong>enum (...)</strong>
</dt>
<dd>
creates an Enum table.
creates an Enum or constants lookup table for improved error handling.
This helps prevent magic strings in code by throwing errors for accessing
non-existing values.</p>
non-existing values, and/or converting strings/identifiers to other values.</p>

<p> Calling on the object does the same, but returns a soft error; <code>nil + err</code>.</p>
<p> Calling on the object does the same, but returns a soft error; <code>nil + err</code>, if
the call is succesful (the key exists), it will return the value.</p>

<p> The values are equal to the keys. The enum object is
read-only.
<p> When calling with varargs or an array the values will be equal to the keys.
The enum object is read-only.


<h3>Parameters:</h3>
<ul>
<li><span class="parameter">...</span>
strings that make up the enumeration.
<span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a> or <span class="type">vararg</span></span>
the input for the Enum. If varargs or an array then the
values in the Enum will be equal to the names (must be strings), if a hash-table
then values remain (any type), and the keys must be strings.
</li>
</ul>

<h3>Returns:</h3>
<ol>

Enum object
Enum object (read-only table/object)
</ol>



<h3>Usage:</h3>
<ul>
<li><pre class="example"><span class="comment">-- accessing at runtime
<li><pre class="example"><span class="comment">-- Enum access at runtime
</span><span class="keyword">local</span> obj = {}
obj.MOVEMENT = utils.enum(<span class="string">"FORWARD"</span>, <span class="string">"REVERSE"</span>, <span class="string">"LEFT"</span>, <span class="string">"RIGHT"</span>)

Expand All @@ -765,12 +830,40 @@ <h3>Usage:</h3>
</span> <span class="comment">-- "'REVERES' is not a valid value (expected one of: 'FORWARD', 'REVERSE', 'LEFT', 'RIGHT')"
</span>
<span class="keyword">end</span></pre></li>
<li><pre class="example"><span class="comment">-- validating user-input
</span><span class="keyword">local</span> parameter = <span class="string">"...some user provided option..."</span>
<span class="keyword">local</span> ok, err = obj.MOVEMENT(parameter) <span class="comment">-- calling on the object
</span><span class="keyword">if</span> <span class="keyword">not</span> ok <span class="keyword">then</span>
<span class="global">print</span>(<span class="string">"bad 'parameter', "</span> .. err)
<span class="global">os</span>.exit(<span class="number">1</span>)
<li><pre class="example"><span class="comment">-- standardized error codes
</span><span class="keyword">local</span> obj = {
ERR = utils.enum {
NOT_FOUND = <span class="string">"the item was not found"</span>,
OUT_OF_BOUNDS = <span class="string">"the index is outside the allowed range"</span>
},

some_method = <span class="keyword">function</span>(self)
<span class="keyword">return</span> self.ERR.OUT_OF_BOUNDS
<span class="keyword">end</span>,
}

<span class="keyword">local</span> result, err = obj:some_method()
<span class="keyword">if</span> <span class="keyword">not</span> result <span class="keyword">then</span>
<span class="keyword">if</span> err == obj.ERR.NOT_FOUND <span class="keyword">then</span>
<span class="comment">-- check on error code, not magic strings
</span>
<span class="keyword">else</span>
<span class="comment">-- return the error description, contained in the constant
</span> <span class="keyword">return</span> <span class="keyword">nil</span>, <span class="string">"error: "</span>..err <span class="comment">-- "error: the index is outside the allowed range"
</span> <span class="keyword">end</span>
<span class="keyword">end</span></pre></li>
<li><pre class="example"><span class="comment">-- validating/converting user-input
</span><span class="keyword">local</span> color = <span class="string">"purple"</span>
<span class="keyword">local</span> ansi_colors = utils.enum {
black = <span class="number">30</span>,
red = <span class="number">31</span>,
green = <span class="number">32</span>,
}
<span class="keyword">local</span> color_code, err = ansi_colors(color) <span class="comment">-- calling on the object, returns the value from the enum
</span><span class="keyword">if</span> <span class="keyword">not</span> color_code <span class="keyword">then</span>
<span class="global">print</span>(<span class="string">"bad 'color', "</span> .. err)
<span class="comment">-- "bad 'color', 'purple' is not a valid value (expected one of: 'black', 'red', 'green')"
</span> <span class="global">os</span>.exit(<span class="number">1</span>)
<span class="keyword">end</span></pre></li>
</ul>

Expand Down

0 comments on commit 2670414

Please sign in to comment.