From 35a6794386d347baec5349fceeb419f940361b87 Mon Sep 17 00:00:00 2001 From: "Kartik K. Agaram" Date: Sun, 13 Mar 2022 14:08:27 -0700 Subject: [PATCH] rip out most references to C and userdata in docs --- doc/manual.html | 173 +++++++++--------------------------------------- 1 file changed, 30 insertions(+), 143 deletions(-) diff --git a/doc/manual.html b/doc/manual.html index a69c914..fe40d5d 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -269,24 +269,11 @@ including embedded zeros ('\0') (see §2.1).

-Lua can call (and manipulate) functions written in Lua and -functions written in C -(see §2.5.8). - - -

-The type userdata is provided to allow arbitrary C 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 metatables, -the programmer can define operations for userdata values -(see §2.8). -Userdata values cannot be created or modified in Lua, -only through the C API. -This guarantees the integrity of data owned by the host program. - +

The type userdata is opaque to Teliva, and +used by low-level code to manage details of C data stored in Lua +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.

The type thread represents independent threads of execution @@ -322,7 +309,7 @@ Thus tables can also carry methods (see §2.5.9 -Tables, functions, threads, and (full) userdata values are objects: +Tables, functions and threads are objects: variables do not actually contain these values, only references to them. Assignment, parameter passing, and function returns @@ -424,8 +411,6 @@ To get the environment table of a Lua function, you call getfenv. To replace it, you call setfenv. -(You can only manipulate the environment of C functions -through the debug library; (see §5.9).)

@@ -973,17 +958,17 @@ Equality (==) first compares the type of its operands. If the types are different, then the result is false. Otherwise, the values of the operands are compared. Numbers and strings are compared in the usual way. -Objects (tables, userdata, threads, and functions) +Objects (tables, threads, and functions) are compared by reference: two objects are considered equal only if they are the same 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.

-You can change the way that Lua compares tables and userdata -by using the "eq" metamethod (see §2.8). +You can change the way that Lua compares tables by using the "eq" metamethod +(see §2.8).

@@ -1482,13 +1467,10 @@ while all of them share the same x.

2.7 - Error Handling

-Because Lua is an embedded extension language, -all Lua actions start from C code in the host program -calling a function from the Lua library (see lua_pcall). -Whenever an error occurs during Lua compilation or execution, -control returns to C, -which can take appropriate measures -(such as printing an error message). +

+Errors returned by Teliva code should display on screen in red. Please report +crashes or other behavior. +

@@ -1532,14 +1514,11 @@ through the getmetatable function. You can replace the metatable of tables through the setmetatable function. -You cannot change the metatable of other types from Lua -(except by using the debug library); -you must use the C API for that.

-Tables and full userdata have individual metatables -(although multiple tables and userdata can share their metatables). +Tables have individual metatables +(although multiple tables can share their metatables). Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. @@ -1548,8 +1527,6 @@ one for all strings, etc.

A metatable controls how an object behaves in arithmetic operations, 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 called an event. When Lua performs one of these operations over a value, @@ -1909,44 +1886,23 @@ called when Lua calls a value.

2.9 - Environments

-Besides metatables, -objects of types thread, function, and userdata -have another table associated with them, -called their environment. +Besides metatables, objects of types thread and function +have another table associated with them, called their +environment. Like metatables, environments are regular tables and multiple objects can share the same environment.

Threads are created sharing the environment of the creating thread. -Userdata and C functions are created sharing the environment -of the creating C function. -Non-nested Lua functions -(created by loadfile, loadstring or load) -are created sharing the environment of the creating thread. Nested Lua functions are created sharing the environment of the creating Lua function. -

-Environments associated with userdata have no meaning for Lua. -It is only a convenience feature for programmers to associate a table to -a userdata. - -

Environments associated with threads are called global environments. -They are used as the default environment for threads and -non-nested Lua functions created by the thread -and can be directly accessed by C code (see §3.3). - - -

-The environment associated with a C function can be directly -accessed by C code (see §3.3). -It is used as the default environment for other C functions -and userdata created by the function. +They are used as the default environment for threads.

@@ -1961,9 +1917,6 @@ You can change the environment of a Lua function or the running thread by calling setfenv. You can get the environment of a Lua function or the running thread by calling getfenv. -To manipulate the environment of other objects -(userdata, C functions, other threads) you must -use the C API. @@ -1981,7 +1934,7 @@ a garbage collector from time to time to collect all dead objects (that is, objects that are no longer accessible from Lua). All memory used by Lua is subject to automatic management: -tables, userdata, functions, threads, strings, etc. +tables, functions, threads, strings, etc.

@@ -2016,52 +1969,8 @@ the speed of memory allocation.

-You can change these numbers by calling lua_gc in C -or collectgarbage in Lua. -With these functions you can also control -the collector directly (e.g., stop and restart it). - - - -

2.10.1 - Garbage-Collection Metamethods

- -

-Using the C API, -you can set garbage-collector metamethods for userdata (see §2.8). -These metamethods are also called finalizers. -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). - - -

-Garbage userdata with a field __gc 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: - -

-     function gc_event (udata)
-       local h = metatable(udata).__gc
-       if h then
-         h(udata)
-       end
-     end
-
- -

-At the end of each garbage-collection cycle, -the finalizers for userdata are called in reverse -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. - - +

Modifying these parameters requires changes to Teliva's C +souces.
@@ -2219,15 +2128,15 @@ When you run it, it produces the following output:

3 - C API

-Unlike Lua, Teliva isn't intended to be modified at the C level. However, -forks of Teliva are encouraged. +
Unlike Lua, Teliva isn't intended to be modified at the C +level. However, forks of Teliva are encouraged.

5 - Standard Libraries

The standard Lua libraries provide useful functions -that are implemented directly through the C API. +that are implemented directly in C. Some of these functions provide essential services to the language (e.g., type and getmetatable); others provide access to "outside" services (e.g., I/O); @@ -2237,8 +2146,6 @@ deserve an implementation in C (e.g., table.sort

-All libraries are implemented through the official C API -and are provided as separate C modules. Currently, Lua has the following standard libraries: