Merge pull request #168 from ChaitanyaD48/documentation

Docs : To-Be-Closed Objects and `:close()` Method Return Types

doc/br/examples.html

@@ -150,6 +150,21 @@ <h3><a name="iterator_example"></a>Uso do iterador</h3>
 exemplo) ou para fechar explicitamente o cursor (verificando
 se ainda existem mais linhas).</p>
 
+<h3><a name="To_be_closed"></a>Objetos a serem fechados</h3>
+
+<p>
+	<strong style="color: red;">Nota de Compatibilidade:</strong>
+	Variáveis a serem fechadas é um recurso introduzido no Lua 5.4. Portanto, essa funcionalidade só pode ser usada se o LuaSQL (versão > 2.6) for compilado contra a versão 5.4 ou superior do Lua.
+</p>
+
+<pre class="example">
+function getName(db, id)
+  -- Este código requer Lua 5.4 ou superior devido ao uso de variáveis a serem fechadas.
+  local cur &lt;close&gt; = db:execute("SELECT name FROM contacts WHERE id = " .. id)
+  return cur:fetch()
+end
+</pre>
+
 </div> <!-- id="content" -->
 
 </div> <!-- id="main" -->

doc/br/manual.html

@@ -188,8 +188,7 @@ <h4>M&eacute;todos</h4>
     <dt><a name="env_close"></a><strong><code>env:close()</code></strong></dt>
     <dd>Fecha o ambiente <code>env</code>. S&oacute; &eacute; bem sucedido se todas as suas
         conex&otilde;es j&aacute; tiverem sido fechadas anteriormente.<br/>
-        Retorna: <code>true</code>, em caso de sucesso; <code>false</code>, quando o ambiente
-        j&aacute; estiver fechado.
+        Retorna: <code>true</code> em caso de sucesso e em caso de falha retorna <code>false</code> com uma <code>mensagem de string</code> indicando o motivo da falha.
     </dd>
 
     <dt><a name="env_connect"></a><strong><code>env:connect(sourcename[,username[,password]])</code></strong></dt>
@@ -220,7 +219,7 @@ <h4>M&eacute;todos</h4>
     <dt><a name="conn_close"></a><strong><code>conn:close()</code></strong></dt>
     <dd>Fecha a conex&atilde;o <code>conn</code>. S&oacute; &eacute; bem sucedido se todos
         os seus cursores tiverem sido fechados anteriormente e se a conex&atilde;o ainda estiver aberta.<br/>
-        Retorna: <code>true</code>, em caso de sucesso; <code>false</code> em caso de fracasso.
+        Retorna: <code>true</code> em caso de sucesso e em caso de falha retorna <code>false</code> com uma <code>mensagem de string</code> indicando o motivo da falha.
     </dd>
 
     <dt><a name="conn_commit"></a><strong><code>conn:commit()</code></strong></dt>
@@ -267,8 +266,7 @@ <h4>M&eacute;todos</h4>
 <dl class="reference">
     <dt><a name="cur_close"></a><strong><code>cur:close()</code></strong></dt>
     <dd>Fecha esse cursor.<br/>
-        Retorna: <code>true</code>, em caso de sucesso; <code>false</code>, quando o cursor
-        j&aacute; est&aacute; fechado.
+        Retorna: <code>true</code> em caso de sucesso e em caso de falha retorna <code>false</code> com uma <code>mensagem de string</code> indicando o motivo da falha.
     </dd>
 
     <dt><a name="cur_fetch"></a><strong><code>cur:fetch([table[,modestring]])</code></strong></dt>

doc/fr/examples.html

@@ -146,6 +146,21 @@ <h3><a name="iterator_example"></a>Iterator</h3>
 
 <p>Obviously, the code above only works if there is a table called contacts with the columns id, name and address in this order. At the end of the loop the cursor will be automatically closed by the driver.</p>
 
+<h3><a name="To_be_closed"></a>To-be-closed Objects</h3>
+
+<p>
+	<strong style="color: red;">Compatibility Note:</strong>
+	To-be-closed variables is a feature introduced in Lua 5.4. Therefore, this functionality can only be used if LuaSQL (version > 2.6) is compiled against Lua version 5.4 or higher.
+</p>
+
+<pre class="example">
+function getName(db, id)
+  -- This code requires Lua 5.4 or higher due to the use of to-be-closed variables.
+  local cur &lt;close&gt; = db:execute("SELECT name FROM contacts WHERE id = " .. id)
+  return cur:fetch()
+end
+</pre>
+
 </div> <!-- id="content" -->
 
 </div> <!-- id="main" -->

doc/fr/manual.html

@@ -183,8 +183,7 @@ <h4>Methods</h4>
 	<dt><a name="env_close"></a><strong><code>env:close()</code></strong></dt>
 	<dd>Closes the environment <code>env</code>.
 	Only successful if all connections pertaining to it were closed first.<br/>
-	Returns: <code>true</code> in case of success; <code>false</code> when
-	the object is already closed.</dd>
+	Returns: <code>true</code> in case of success and in case of failure it returns <code>false</code> with a <code>string message</code> stating the failure reason.</dd>
 
 	<dt><a name="env_connect"></a><strong><code>env:connect(sourcename[,username[,password]])</code></strong></dt>
 	<dd>Connects to a data source specified in <code>sourcename</code> using
@@ -215,7 +214,7 @@ <h4>Methods</h4>
 	<dt><a name="conn_close"></a><strong><code>conn:close()</code></strong></dt>
 	<dd>Closes the connection <code>conn</code>.
 	Only successful if all cursors pertaining to it have been closed and the connection is still open.<br/>
-	Returns: <code>true</code> in case of success and <code>false</code> in case of failure.</dd>
+	Returns: <code>true</code> in case of success and in case of failure it returns <code>false</code> with a <code>string message</code> stating the failure reason.</dd>
 
 
 	<dt><a name="conn_commit"></a><strong><code>conn:commit()</code></strong></dt>
@@ -268,8 +267,7 @@ <h4>Methods</h4>
 
 	<dt><a name="cur_close"></a><strong><code>cur:close()</code></strong></dt>
 	<dd>Closes this cursor.<br/>
-	Returns: <code>true</code> in case of success and <code>false</code> when
-	the object is already closed.</dd>
+	Returns: <code>true</code> in case of success and in case of failure it returns <code>false</code> with a <code>string message</code> stating the failure reason.</dd>
 
 
 	<dt><a name="cur_fetch"></a><strong><code>cur:fetch([table[,modestring]])</code></strong></dt>

doc/us/examples.html

@@ -125,6 +125,21 @@ <h3><a name="iterator_example"></a>Iterator</h3>
 
 <p>Obviously, the code above only works if there is a table called contacts with the columns id, name and address in this order. At the end of the loop the cursor will be automatically closed by the driver.</p>
 
+<h3><a name="To_be_closed"></a>To-be-closed Objects</h3>
+
+<p>
+	<strong style="color: red;">Compatibility Note:</strong>
+	To-be-closed variables is a feature introduced in Lua 5.4. Therefore, this functionality can only be used if LuaSQL (version > 2.6) is compiled against Lua version 5.4 or higher.
+</p>
+
+<pre class="example">
+function getName(db, id)
+  -- This code requires Lua 5.4 or higher due to the use of to-be-closed variables.
+  local cur &lt;close&gt; = db:execute("SELECT name FROM contacts WHERE id = " .. id)
+  return cur:fetch()
+end
+</pre>
+
 </div> <!-- id="content" -->
 
 </div> <!-- id="main" -->

doc/us/history.html

@@ -44,6 +44,15 @@ <h1>LuaSQL</h1>
 <h2><a name="history"></a>History</h2>
 
 <dl class="history">
+    <dt><strong>LuaSQL</strong> []</dt>
+    <dd>
+      <ul>
+        <li>LuaSQL is adapted to Lua version 5.4 and all the drivers are compatible with To-be-closed variables.</li>
+        <li>Bug-fix - <code>:close()</code> method does not invoke the __gc metamethod in case of related open objects. </li>
+        <li>The <code>:close()</code> method now returns false and a string with appropriate message instead of raising an error when there are related open objects.</li>
+      </ul>
+    </dd>
+
     <dt><strong>LuaSQL 2.6.1</strong> [07/Feb/2024]</dt>
     <dd>
       <ul>

doc/us/index.html

@@ -93,6 +93,11 @@ <h2><a name="download"></a>Download</h2>
 <h2><a name="credits"></a>Credits</h2>
 
 <h4>LuaSQL 2.x</h4>
+
+<p>
+Version __ introduces support for To-be-closed variables and all the Drivers are adapted to Lua version 5.4. <br>This was developed by Chaitanya Deshmukh (GSoC 2024) under the mentorship of Tom&aacute;s Guisasola.
+</p>
+
 <p>
 Version 2.5 incorporates support in MySQL driver for seeking in the result set.
 </p>

doc/us/manual.html

@@ -176,8 +176,7 @@ <h4>Methods</h4>
 	<dt><a name="env_close"></a><strong><code>env:close()</code></strong></dt>
 	<dd>Closes the environment <code>env</code>.
 	Only successful if all connections pertaining to it were closed first.<br/>
-	Returns: <code>true</code> in case of success; <code>false</code> when
-	the object is already closed.</dd>
+	Returns: <code>true</code> in case of success and in case of failure it returns <code>false</code> with a <code>string message</code> stating the failure reason.</dd>
 
 	<dt><a name="env_connect"></a><strong><code>env:connect(sourcename[,username[,password]])</code></strong></dt>
 	<dd>Connects to a data source specified in <code>sourcename</code> using
@@ -208,7 +207,7 @@ <h4>Methods</h4>
 	<dt><a name="conn_close"></a><strong><code>conn:close()</code></strong></dt>
 	<dd>Closes the connection <code>conn</code>.
 	Only successful if all cursors pertaining to it have been closed and the connection is still open.<br/>
-	Returns: <code>true</code> in case of success and <code>false</code> in case of failure.</dd>
+	Returns: <code>true</code> in case of success and in case of failure it returns <code>false</code> with a <code>string message</code> stating the failure reason.</dd>
 
 
 	<dt><a name="conn_commit"></a><strong><code>conn:commit()</code></strong></dt>
@@ -261,8 +260,7 @@ <h4>Methods</h4>
 
 	<dt><a name="cur_close"></a><strong><code>cur:close()</code></strong></dt>
 	<dd>Closes this cursor.<br/>
-	Returns: <code>true</code> in case of success and <code>false</code> when
-	the object is already closed.</dd>
+	Returns: <code>true</code> in case of success and in case of failure it returns <code>false</code> with a <code>string message</code> stating the failure reason.</dd>
 
 
 	<dt><a name="cur_fetch"></a><strong><code>cur:fetch([table[,modestring]])</code></strong></dt>
@@ -404,8 +402,6 @@ <h2><a name="mysql_extensions"></a>MySQL Extensions</h2>
 
 <p>Notes:</p>
 
-<p>I </p>
-
 <p>This driver is compatible with versions 4.0, 4.1 and 5.0 of the
 MySQL API. Only from version 4.1 MySQL provides support for transactions by using
 BDB or INNODB tables.
@@ -433,7 +429,8 @@ <h2><a name="sqlite3_extensions"></a>SQLite3 Extensions</h2>
 <p>Besides the basic functionality provided by all drivers,
 the SQLite3 driver also offers this extra feature:</p>
 
-<dt><strong><code>env:connect(sourcename[,locktimeout,readOnlyMode])</code></strong></dt>
+<dl class="reference">
+  <dt><strong><code>env:connect(sourcename[,locktimeout,readOnlyMode])</code></strong></dt>
   <dd>In the SQLite3 driver, this method adds an optional parameter
     that indicate the amount of milliseconds to wait for a write lock if one cannot be obtained immediately.
 	  To connect in readOnlyMode, set readOnlyMode to true.<br/>
@@ -446,7 +443,7 @@ <h2><a name="sqlite3_extensions"></a>SQLite3 Extensions</h2>
     See also: Official documentation of function <a href="http://www.sqlite.org/c3ref/mprintf.html">sqlite3_mprintf</a><br/>
     Returns: the escaped string.
   </dd>
-
+</dl>
 </div> <!-- id="content" -->
 
 </div> <!-- id="main" -->