release 1.0.0

Author: Tieske

.luacov

@@ -1,5 +1,5 @@
-modules = {
-   ["uuid.*"] = "src"
+include = {
+   "src%/.+$",
 }
 
 runreport = true

CHANGELOG.md

@@ -30,7 +30,7 @@ The scope of what is covered by the version number excludes:
 
 ## Version history
 
-### Version 1.0.0, unreleased
+### Version 1.0.0, released 9-Oct-2024
 
 - BREAKING: no default rng will be picked anymore, one must be set explicitly, see `set_rng`
 - BREAKING: calling on the module table `uuid()` will now call `v4()` instead of `new()`
@@ -44,6 +44,7 @@ The scope of what is covered by the version number excludes:
   additional input for seeding the Lua rng (eg. pass in a mac address).
 - Feat: new `rng.luasystem` rng that uses LuaSystem for random number generation (Posix + Windows)
 - Feat: new `rng.urandom` rng that uses /dev/urandom for random number generation (Posix, no Windows)
+- Feat: new `rng.win_ffi` rng that uses the ffi for random number generation (Windows, no Posix)
 - Feat: new `rng.math_random` rng that replaces the old rng used, based on Lua's `math.random` function.
 - Feat: improved seeding, using LuaSystem, or /dev/urandom if available. If not, the fallback now uses
   more inputs (including a user provided one, eg. a mac address) and calculates a SHA1 used as seed.

LICENSE.md

@@ -188,7 +188,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright  2012 Rackspace, 2013-2021 Thijs Schreijer
+   Copyright  2012 Rackspace, 2013-2024 Thijs Schreijer
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

docs/index.html

@@ -27,211 +27,60 @@
 <h1>uuid</h1>
 
 
-<h2>Contents</h2>
-<ul>
-<li><a href="#Functions">Functions</a></li>
-</ul>
+
 
 
 <h2>Modules</h2>
 <ul class="nowrap">
-  <li><strong>uuid</strong></li>
+  <li><a href="modules/uuid.html">uuid</a></li>
+  <li><a href="modules/uuid.rng.html">uuid.rng</a></li>
 </ul>
 <h2>Topics</h2>
 <ul class="">
-  <li><a href="topics/readme.md.html">readme</a></li>
+  <li><a href="topics/01-introduction.md.html">1. Introduction</a></li>
+  <li><a href="topics/CHANGELOG.md.html">CHANGELOG</a></li>
+  <li><a href="topics/LICENSE.md.html">Apache 2.0 License</a></li>
 </ul>
 
 </div>
 
 <div id="content">
 
-<h1>Module <code>uuid</code></h1>
-<p>Copyright 2012 Rackspace (original), 2013-2021 Thijs Schreijer (modifications)</p>
-
-<p> Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.</p>
-<p> You may obtain a copy of the License at</p>
-
-
-<pre>
-http://www.apache.org/licenses/LICENSE-<span class="number">2.0</span>
-</pre>
-
-<p> Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS-IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.</p>
-
-<p> see http://www.ietf.org/rfc/rfc4122.txt</p>
 
-<p> Note that this is not a true version 4 (random) UUID.  Since <code>os.time()</code> precision is only 1 second, it would be hard
- to guarantee spacial uniqueness when two hosts generate a uuid after being seeded during the same second.  This
- is solved by using the node field from a version 1 UUID.  It represents the mac address.</p>
+  <h2>Module to generate uuids in pure Lua</h2>
 
-<p> 28-apr-2013 modified by Thijs Schreijer from the original <a href="https://github.com/kans/zirgo/blob/807250b1af6725bad4776c931c89a784c1e34db2/util/uuid.lua">Rackspace code</a> as a generic Lua module.
- Regarding the above mention on <code>os.time()</code>; the modifications use the <code>socket.gettime()</code> function from LuaSocket
- if available and hence reduce that problem (provided LuaSocket has been loaded before uuid).</p>
-
-<p> <strong>Important:</strong> the random seed is a global piece of data. Hence setting it is
- an application level responsibility, libraries should never set it!</p>
-
-<p> See this issue; <a href="https://github.com/Kong/kong/issues/478">https://github.com/Kong/kong/issues/478</a>
- It demonstrates the problem of using time as a random seed. Specifically when used from multiple processes.
- So make sure to seed only once, application wide. And to not have multiple processes do that
- simultaneously.</p>
-
-
-<h2><a href="#Functions">Functions</a></h2>
-<table class="function_list">
+<h2>Modules</h2>
+<table class="module_list">
 	<tr>
-	<td class="name" nowrap><a href="#new">new (hwaddr)</a></td>
-	<td class="summary">Creates a new uuid.</td>
+		<td class="name"  nowrap><a href="modules/uuid.html">uuid</a></td>
+		<td class="summary">Copyright 2012 Rackspace (original), 2013-2024 Thijs Schreijer (modifications)</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#randomseed">randomseed (seed)</a></td>
-	<td class="summary">Improved randomseed function.</td>
+		<td class="name"  nowrap><a href="modules/uuid.rng.html">uuid.rng</a></td>
+		<td class="summary">Random number generator utilities with different properties and uses.</td>
 	</tr>
+</table>
+<h2>Topics</h2>
+<table class="module_list">
 	<tr>
-	<td class="name" nowrap><a href="#seed">seed ()</a></td>
-	<td class="summary">Seeds the random generator.</td>
+		<td class="name"  nowrap><a href="topics/01-introduction.md.html">01-introduction.md</a></td>
+		<td class="summary"></td>
+	</tr>
+	<tr>
+		<td class="name"  nowrap><a href="topics/CHANGELOG.md.html">CHANGELOG.md</a></td>
+		<td class="summary"></td>
+	</tr>
+	<tr>
+		<td class="name"  nowrap><a href="topics/LICENSE.md.html">LICENSE.md</a></td>
+		<td class="summary"></td>
 	</tr>
 </table>
 
-<br/>
-<br/>
-
-
-    <h2 class="section-header "><a name="Functions"></a>Functions</h2>
-
-    <dl class="function">
-    <dt>
-    <a name = "new"></a>
-    <strong>new (hwaddr)</strong>
-    </dt>
-    <dd>
-
-<p>Creates a new uuid.  Either provide a unique hex string, or make sure the
- random seed is properly set. The module table itself is a shortcut to this
- function, so <code>my_uuid = uuid.new()</code> equals <code>my_uuid = uuid()</code>.</p>
-
-<p> For proper use there are 3 options;</p>
-
-<ol>
-    <li>first require <code>luasocket</code>, then call <code>uuid.seed()</code>, and request a uuid using no
-    parameter, eg. <code>my_uuid = uuid()</code></li>
-    <li>use <a href="index.html#">uuid</a> without <code>luasocket</code>, set a random seed using <code>uuid.randomseed(some_good_seed)</code>,
-    and request a uuid using no parameter, eg. <code>my_uuid = uuid()</code></li>
-    <li>use <a href="index.html#">uuid</a> without <code>luasocket</code>, and request a uuid using an unique hex string,
-    eg. <code>my_uuid = uuid(my_networkcard_macaddress)</code></li>
-</ol>
-
-
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">hwaddr</span>
-         (optional) string containing a unique hex value (e.g.: <code>00:0c:29:69:41:c6</code>), to be used to compensate for the lesser <code>math_random()</code> function. Use a mac address for solid results. If omitted, a fully randomized uuid will be generated, but then you must ensure that the random seed is set properly!
-        </li>
-    </ul>
-
-    <h3>Returns:</h3>
-    <ol>
-
-        a properly formatted uuid string
-    </ol>
-
-
-
-    <h3>Usage:</h3>
-    <ul>
-        <pre class="example"><span class="keyword">local</span> uuid = <span class="global">require</span>(<span class="string">"uuid"</span>)
-<span class="global">print</span>(<span class="string">"here's a new uuid: "</span>,uuid())</pre>
-    </ul>
-
-</dd>
-    <dt>
-    <a name = "randomseed"></a>
-    <strong>randomseed (seed)</strong>
-    </dt>
-    <dd>
-    Improved randomseed function.
- Lua 5.1 and 5.2 both truncate the seed given if it exceeds the integer
- range. If this happens, the seed will be 0 or 1 and all randomness will
- be gone (each application run will generate the same sequence of random
- numbers in that case). This improved version drops the most significant
- bits in those cases to get the seed within the proper range again.
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">seed</span>
-         the random seed to set (integer from 0 - 2^32, negative values will be made positive)
-        </li>
-    </ul>
-
-    <h3>Returns:</h3>
-    <ol>
-
-        the (potentially modified) seed used
-    </ol>
-
-
-
-    <h3>Usage:</h3>
-    <ul>
-        <pre class="example"><span class="keyword">local</span> socket = <span class="global">require</span>(<span class="string">"socket"</span>)  <span class="comment">-- gettime() has higher precision than os.time()
-</span><span class="keyword">local</span> uuid = <span class="global">require</span>(<span class="string">"uuid"</span>)
-<span class="comment">-- see also example at uuid.seed()
-</span>uuid.randomseed(socket.gettime()*<span class="number">10000</span>)
-<span class="global">print</span>(<span class="string">"here's a new uuid: "</span>,uuid())</pre>
-    </ul>
-
-</dd>
-    <dt>
-    <a name = "seed"></a>
-    <strong>seed ()</strong>
-    </dt>
-    <dd>
-    Seeds the random generator.
- It does so in 3 possible ways;</p>
-
-<ol>
-    <li>if in ngx_lua, use <code>ngx.time() + ngx.worker.pid()</code> to ensure a unique seed
-    for each worker. It should ideally be called from the <code>init_worker</code> context.</li>
-    <li>use luasocket <code>gettime()</code> function, but it only does so when LuaSocket
-    has been required already.</li>
-    <li>use <code>os.time()</code>: this only offers resolution to one second (used when
-    LuaSocket hasn't been loaded)</li>
-</ol>
-
-<p> <strong>Important:</strong> the random seed is a global piece of data. Hence setting it is
- an application level responsibility, libraries should never set it!
-
-
-
-
-
-
-    <h3>Usage:</h3>
-    <ul>
-        <pre class="example"><span class="keyword">local</span> socket = <span class="global">require</span>(<span class="string">"socket"</span>)  <span class="comment">-- gettime() has higher precision than os.time()
-</span><span class="comment">-- LuaSocket loaded, so below line does the same as the example from randomseed()
-</span>uuid.seed()
-<span class="global">print</span>(<span class="string">"here's a new uuid: "</span>,uuid())</pre>
-    </ul>
-
-</dd>
-</dl>
-
-
 </div> <!-- id="content" -->
 </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-07-11 08:59:24 </i>
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2024-10-09 13:35:51 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/ldoc.css

@@ -1,4 +1,4 @@
-body { 
+body {
     color: #47555c;
     font-size: 16px;
     font-family: "Open Sans", sans-serif;