diff --git a/polymer/eduke32/source/lunatic/doc/lunatic.txt b/polymer/eduke32/source/lunatic/doc/lunatic.txt index 732f9db66..b00dd4a0e 100644 --- a/polymer/eduke32/source/lunatic/doc/lunatic.txt +++ b/polymer/eduke32/source/lunatic/doc/lunatic.txt @@ -117,6 +117,7 @@ function instead of looking it up in the global environment. *`printf(fmt, ...)`*:: Calls `print` with the result of `string.format(fmt, ...)`. +[[modules]] Writing and using modules ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -137,6 +138,7 @@ a named module is requested by passing its name to `require`. This searches for a matching module, loading and running it if the request happens for the first time. +[[require]] ==== The function `require(modname, ...)` Attempts to find a Lua or Lunatic module named `modname`. The name can refer to @@ -331,7 +333,7 @@ Contains the following members: `pos`, `dist`, `clock`, `ang`, `horiz`, `sect`. [[gv_RETURN]] `gv.RETURN`:: A special variable that is used by the game to pass specific values to game events, or to examine values passed back from events and act upon them -accordingly. Refer to <> for a list of how the various +accordingly. Refer to <> for a list of how the various events interpret this variable. Functions @@ -1107,6 +1109,7 @@ horizontal and vertical texel sizes of each tile. Lunatic functions ~~~~~~~~~~~~~~~~~ +[[engine_iterators]] Engine-side iterators ^^^^^^^^^^^^^^^^^^^^^ @@ -1794,7 +1797,131 @@ APPENDICES FOLLOW :numbered!: [appendix] -[[Appendix_A]] +[[Appendix_Howto_read_PIL]] +How to read _Programming in Lua_ +-------------------------------- + +:PiL50: http://www.lua.org/pil/contents.html + +On the Lua homepage, the first edition of _Programming in Lua_ is +{PiL50}[available] online. While targeting Lua 5.0, it still remains applicable +to Lua 5.1 to a large extent. This section gives hints for reading it when +learning to code for Lunatic. + +[float] +==== http://www.lua.org/pil/p1.html[Preface] + +May be interesting to get an idea of the philisophy behind Lua. +http://www.lua.org/pil/p1.3.html[A Few Typographical Conventions] should be +read to be familiar with them. + +[float] +==== http://www.lua.org/pil/1.html[1 -- Getting Started] + +Mentions the stand-alone Lua interpreter. When none is available, a LuaJIT +stand-alone binary can be used for experimentation as well. + +[float] +==== http://www.lua.org/pil/1.1.html[1.1 -- Chunks] + +Introduces chunks as the basic ``blocks'' of Lua code and notes how whitespace +is treated. Mentions `dofile`, which is not available in Lunatic +(<> is preferred). + +[float] +==== http://www.lua.org/pil/1.2.html[1.2 -- Global Variables] + +Section may be read, but usage of *`local`* variables is strongly recommended +whereever possible. Also, trying to read a non-existent global or to write any +value to the global environment gives an error in Lunatic (except that global +writes are allowed in in <> context, i.e. after `module(...)`). + +[float] +==== http://www.lua.org/pil/1.3.html[_1.3 -- Some Lexical Conventions_] + +Must read. + +[float] +==== http://www.lua.org/pil/2.html[_2 -- Types and Values_] + +Must read, also subsections. However, ``2.7 -- Userdata and Threads'' is +not relevant. + +[float] +==== http://www.lua.org/pil/3.html[_3 -- Expressions_] + +Must read, also all subsections. + +[float] +==== http://www.lua.org/pil/4.html[_4 -- Statements_] + +Must read, also all subsections. + +[float] +==== http://www.lua.org/pil/5.htmlhttp://www.lua.org/pil/5.html[_5 -- Functions_] + +Must read, also all subsections. Subsection 5.2 mentions `io.write`, which is +not available in Lunatic. + +[float] +==== http://www.lua.org/pil/6.html[6 -- More about Functions] + +May be read (subsections as well) for a more complete understanding of +functions in Lua, as well as the utility of lexical scoping. + +[float] +==== http://www.lua.org/pil/7.html[_7 -- Iterators and the Generic_ `for`] + +May be read (subsections as well), but for basic programming, the knowledge of +how to merely use (as opposed to write) iterators such as +<> suffices. + +[float] +==== http://www.lua.org/pil/8.3.html[8.3 -- Errors] + +May be read. Provides guidelines on how to write error handling (status code +vs. error). + +[float] +==== http://www.lua.org/pil/8.4.html[8.4 -- Error Handling and Exceptions] + +May be read. Discusses protected calls, which should be used sparingly. + +[float] +==== http://www.lua.org/pil/11.html[_11 -- Data Structures_] + +May be read, also subsections. The most relevant subsections are +http://www.lua.org/pil/11.1.html[11.1 -- Arrays], +http://www.lua.org/pil/11.5.html[11.5 -- Sets and Bags] and to some extent, +http://www.lua.org/pil/11.6.html[11.6 -- String Buffers]. The way ``11.2 -- +Matrices and Multi-Dimensional Arrays'' suggests to construct matrices is +rather memory-intensive; also it and ``11.3 -- Linked Lists'' and ``11.4 -- +Queues and Double Queues'' are not relevant to simple Lunatic coding. + +[float] +==== http://www.lua.org/pil/15.html[15 -- Packages] + +Lua package system received various additions in 5.1, so the PiL first +edition's section is out-of-sync. For Lunatic, the <> section +of this manual should be consulted. + + + + +(The rest of Part II deals with advanced concepts not needed for simple Lunatic +coding.) + +[float] +==== http://www.lua.org/pil/19.3.html[19.3 -- Sort] + +May be read if needed. + +[float] +==== http://www.lua.org/pil/20.html[20 -- The String Library] + +May be skimmed (also subsections), though ultimately the Lua Reference should +be consulted for the exact semantics. + +[appendix] +[[Appendix_event_RETURN]] Game event `RETURN` usage -------------------------