akkartik
/
teliva
1
1
Fork 0
Code Issues Pull Requests Releases Activity

rip out most references to C and userdata in docs

This commit is contained in:
Kartik K. Agaram 2022-03-13 14:08:27 -07:00
parent 23e7cf9c52
commit 35a6794386
1 changed files with 30 additions and 143 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

173
doc/manual.html
View File

@ -269,24 +269,11 @@ including embedded zeros ('<code>\0</code>') (see <a href="#2.1">&sect;2.1</a>).
<p> <p>
Lua can call (and manipulate) functions written in Lua and <div class='teliva'>The type <em>userdata</em> is opaque to Teliva, and
functions written in C used by low-level code to manage details of C&nbsp;data stored in Lua
(see <a href="#2.5.8">&sect;2.5.8</a>). variables. Unlike Lua, Teliva doesn't support creating or managing userdata
since it doesn't permit extension by C libraries. This manual doesn't allude
to userdata further.</div>
<p>
The type <em>userdata</em> is provided to allow arbitrary C&nbsp;data to
be stored in Lua variables.
This type corresponds to a block of raw memory
and has no pre-defined operations in Lua,
except assignment and identity test.
However, by using <em>metatables</em>,
the programmer can define operations for userdata values
(see <a href="#2.8">&sect;2.8</a>).
Userdata values cannot be created or modified in Lua,
only through the C&nbsp;API.
This guarantees the integrity of data owned by the host program.
<p> <p>
The type <em>thread</em> represents independent threads of execution The type <em>thread</em> represents independent threads of execution
@ -322,7 +309,7 @@ Thus tables can also carry <em>methods</em> (see <a href="#2.5.9">&sect;2.5.9</a
<p> <p>
Tables, functions, threads, and (full) userdata values are <em>objects</em>: Tables, functions and threads are <em>objects</em>:
variables do not actually <em>contain</em> these values, variables do not actually <em>contain</em> these values,
only <em>references</em> to them. only <em>references</em> to them.
Assignment, parameter passing, and function returns Assignment, parameter passing, and function returns
@ -424,8 +411,6 @@ To get the environment table of a Lua function,
you call <a href="#pdf-getfenv"><code>getfenv</code></a>. you call <a href="#pdf-getfenv"><code>getfenv</code></a>.
To replace it, To replace it,
you call <a href="#pdf-setfenv"><code>setfenv</code></a>. you call <a href="#pdf-setfenv"><code>setfenv</code></a>.
(You can only manipulate the environment of C&nbsp;functions
through the debug library; (see <a href="#5.9">&sect;5.9</a>).)
<p> <p>
@ -973,17 +958,17 @@ Equality (<code>==</code>) first compares the type of its operands.
If the types are different, then the result is <b>false</b>. If the types are different, then the result is <b>false</b>.
Otherwise, the values of the operands are compared. Otherwise, the values of the operands are compared.
Numbers and strings are compared in the usual way. Numbers and strings are compared in the usual way.
Objects (tables, userdata, threads, and functions) Objects (tables, threads, and functions)
are compared by <em>reference</em>: are compared by <em>reference</em>:
two objects are considered equal only if they are the <em>same</em> object. two objects are considered equal only if they are the <em>same</em> object.
Every time you create a new object Every time you create a new object
(a table, userdata, thread, or function), (a table, thread, or function),
this new object is different from any previously existing object. this new object is different from any previously existing object.
<p> <p>
You can change the way that Lua compares tables and userdata You can change the way that Lua compares tables by using the "eq" metamethod
by using the "eq" metamethod (see <a href="#2.8">&sect;2.8</a>). (see <a href="#2.8">&sect;2.8</a>).
<p> <p>
@ -1482,13 +1467,10 @@ while all of them share the same <code>x</code>.
<h2>2.7 - <a name="2.7">Error Handling</a></h2> <h2>2.7 - <a name="2.7">Error Handling</a></h2>
<p> <p>
Because Lua is an embedded extension language, <div class='teliva'>
all Lua actions start from C&nbsp;code in the host program Errors returned by Teliva code should display on screen in red. Please report
calling a function from the Lua library (see <a href="#lua_pcall"><code>lua_pcall</code></a>). crashes or other behavior.
Whenever an error occurs during Lua compilation or execution, </div>
control returns to C,
which can take appropriate measures
(such as printing an error message).
<p> <p>
@ -1532,14 +1514,11 @@ through the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function.
You can replace the metatable of tables You can replace the metatable of tables
through the <a href="#pdf-setmetatable"><code>setmetatable</code></a> through the <a href="#pdf-setmetatable"><code>setmetatable</code></a>
function. function.
You cannot change the metatable of other types from Lua
(except by using the debug library);
you must use the C&nbsp;API for that.
<p> <p>
Tables and full userdata have individual metatables Tables have individual metatables
(although multiple tables and userdata can share their metatables). (although multiple tables can share their metatables).
Values of all other types share one single metatable per type; Values of all other types share one single metatable per type;
that is, there is one single metatable for all numbers, that is, there is one single metatable for all numbers,
one for all strings, etc. one for all strings, etc.
@ -1548,8 +1527,6 @@ one for all strings, etc.
<p> <p>
A metatable controls how an object behaves in arithmetic operations, A metatable controls how an object behaves in arithmetic operations,
order comparisons, concatenation, length operation, and indexing. order comparisons, concatenation, length operation, and indexing.
A metatable also can define a function to be called when a userdata
is garbage collected.
For each of these operations Lua associates a specific key For each of these operations Lua associates a specific key
called an <em>event</em>. called an <em>event</em>.
When Lua performs one of these operations over a value, When Lua performs one of these operations over a value,
@ -1909,44 +1886,23 @@ called when Lua calls a value.
<h2>2.9 - <a name="2.9">Environments</a></h2> <h2>2.9 - <a name="2.9">Environments</a></h2>
<p> <p>
Besides metatables, Besides metatables, objects of types thread and function
objects of types thread, function, and userdata have another table associated with them, called their
have another table associated with them, <em>environment</em>.
called their <em>environment</em>.
Like metatables, environments are regular tables and Like metatables, environments are regular tables and
multiple objects can share the same environment. multiple objects can share the same environment.
<p> <p>
Threads are created sharing the environment of the creating thread. Threads are created sharing the environment of the creating thread.
Userdata and C&nbsp;functions are created sharing the environment
of the creating C&nbsp;function.
Non-nested Lua functions
(created by <a href="#pdf-loadfile"><code>loadfile</code></a>, <a href="#pdf-loadstring"><code>loadstring</code></a> or <a href="#pdf-load"><code>load</code></a>)
are created sharing the environment of the creating thread.
Nested Lua functions are created sharing the environment of Nested Lua functions are created sharing the environment of
the creating Lua function. the creating Lua function.
<p>
Environments associated with userdata have no meaning for Lua.
It is only a convenience feature for programmers to associate a table to
a userdata.
<p> <p>
Environments associated with threads are called Environments associated with threads are called
<em>global environments</em>. <em>global environments</em>.
They are used as the default environment for threads and They are used as the default environment for threads.
non-nested Lua functions created by the thread
and can be directly accessed by C&nbsp;code (see <a href="#3.3">&sect;3.3</a>).
<p>
The environment associated with a C&nbsp;function can be directly
accessed by C&nbsp;code (see <a href="#3.3">&sect;3.3</a>).
It is used as the default environment for other C&nbsp;functions
and userdata created by the function.
<p> <p>
@ -1961,9 +1917,6 @@ You can change the environment of a Lua function or the
running thread by calling <a href="#pdf-setfenv"><code>setfenv</code></a>. running thread by calling <a href="#pdf-setfenv"><code>setfenv</code></a>.
You can get the environment of a Lua function or the running thread You can get the environment of a Lua function or the running thread
by calling <a href="#pdf-getfenv"><code>getfenv</code></a>. by calling <a href="#pdf-getfenv"><code>getfenv</code></a>.
To manipulate the environment of other objects
(userdata, C&nbsp;functions, other threads) you must
use the C&nbsp;API.
@ -1981,7 +1934,7 @@ a <em>garbage collector</em> from time to time
to collect all <em>dead objects</em> to collect all <em>dead objects</em>
(that is, objects that are no longer accessible from Lua). (that is, objects that are no longer accessible from Lua).
All memory used by Lua is subject to automatic management: All memory used by Lua is subject to automatic management:
tables, userdata, functions, threads, strings, etc. tables, functions, threads, strings, etc.
<p> <p>
@ -2016,52 +1969,8 @@ the speed of memory allocation.
<p> <p>
You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C <div class='teliva'>Modifying these parameters requires changes to Teliva's C
or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua. souces.</div>
With these functions you can also control
the collector directly (e.g., stop and restart it).
<h3>2.10.1 - <a name="2.10.1">Garbage-Collection Metamethods</a></h3>
<p>
Using the C&nbsp;API,
you can set garbage-collector metamethods for userdata (see <a href="#2.8">&sect;2.8</a>).
These metamethods are also called <em>finalizers</em>.
Finalizers allow you to coordinate Lua's garbage collection
with external resource management
(such as closing files, network or database connections,
or freeing your own memory).
<p>
Garbage userdata with a field <code>__gc</code> in their metatables are not
collected immediately by the garbage collector.
Instead, Lua puts them in a list.
After the collection,
Lua does the equivalent of the following function
for each userdata in that list:
<pre>
function gc_event (udata)
local h = metatable(udata).__gc
if h then
h(udata)
end
end
</pre>
<p>
At the end of each garbage-collection cycle,
the finalizers for userdata are called in <em>reverse</em>
order of their creation,
among those collected in that cycle.
That is, the first finalizer to be called is the one associated
with the userdata created last in the program.
The userdata itself is freed only in the next garbage-collection cycle.
@ -2219,15 +2128,15 @@ When you run it, it produces the following output:
<h1>3 - <a name="3">C API</a></h1> <h1>3 - <a name="3">C API</a></h1>
Unlike Lua, Teliva isn't intended to be modified at the C level. However, <div class='teliva'>Unlike Lua, Teliva isn't intended to be modified at the C
forks of Teliva are encouraged. level. However, forks of Teliva are encouraged.</div>
<h1>5 - <a name="5">Standard Libraries</a></h1> <h1>5 - <a name="5">Standard Libraries</a></h1>
<p> <p>
The standard Lua libraries provide useful functions The standard Lua libraries provide useful functions
that are implemented directly through the C&nbsp;API. that are implemented directly in C.
Some of these functions provide essential services to the language Some of these functions provide essential services to the language
(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>);
others provide access to "outside" services (e.g., I/O); others provide access to "outside" services (e.g., I/O);
@ -2237,8 +2146,6 @@ deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort
<p> <p>
All libraries are implemented through the official C&nbsp;API
and are provided as separate C&nbsp;modules.
Currently, Lua has the following standard libraries: Currently, Lua has the following standard libraries:
<ul> <ul>
@ -2265,27 +2172,6 @@ each library provides all its functions as fields of a global table
or as methods of its objects. or as methods of its objects.
<p>
To have access to these libraries,
the C&nbsp;host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function,
which opens all standard libraries.
Alternatively,
it can open them individually by calling
<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library),
<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library),
<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library),
<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library),
<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library),
<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library),
<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the Operating System library),
and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library).
These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>
and should not be called directly:
you must call them like any other Lua C&nbsp;function,
e.g., by using <a href="#lua_call"><code>lua_call</code></a>.
<h2>5.1 - <a name="5.1">Basic Functions</a></h2> <h2>5.1 - <a name="5.1">Basic Functions</a></h2>
<p> <p>
@ -2580,7 +2466,7 @@ In this case, <code>setfenv</code> returns no values.
<p> <p>
Sets the metatable for the given table. Sets the metatable for the given table.
(You cannot change the metatable of other types from Lua, only from&nbsp;C.) (You cannot change the metatable of other types.)
If <code>metatable</code> is <b>nil</b>, If <code>metatable</code> is <b>nil</b>,
removes the metatable of the given table. removes the metatable of the given table.
If the original metatable has a <code>"__metatable"</code> field, If the original metatable has a <code>"__metatable"</code> field,
@ -2772,8 +2658,8 @@ In case of error, propagates the error.
<p> <p>
Suspends the execution of the calling coroutine. Suspends the execution of the calling coroutine.
The coroutine cannot be running a C&nbsp;function, The coroutine cannot be running a primitive implemented in
a metamethod, or an iterator. C, a metamethod, or an iterator.
Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>. Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>.
@ -4213,6 +4099,7 @@ violate some assumptions about Lua code
cannot be accessed from outside or cannot be accessed from outside or
that userdata metatables cannot be changed by Lua code) that userdata metatables cannot be changed by Lua code)
and therefore can compromise otherwise secure code. and therefore can compromise otherwise secure code.
<div class='teliva'>TODO: what do we need to secure here?</div>
<p> <p>