[
{
"path": ".gitattributes",
"content": "*.teliva linguist-language=Lua\n*.tlv linguist-language=Lua\n"
},
{
"path": ".gitignore",
"content": "*.o\n*.a\n"
},
{
"path": "COPYRIGHT.md",
"content": "Lua License\n-----------\n\nLua is licensed under the terms of the MIT license reproduced below.\nThis means that Lua is free software and can be used for both academic\nand commercial purposes at absolutely no cost.\n\nFor details and rationale, see http://www.lua.org/license.html .\n\n===============================================================================\n\nCopyright (C) 1994-2012 Lua.org, PUC-Rio.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n\n===============================================================================\n"
},
{
"path": "Makefile",
"content": "# makefile for installing Lua\n# see INSTALL for installation instructions\n# see src/Makefile and src/luaconf.h for further customization\n\n# == CHANGE THE SETTINGS BELOW TO SUIT YOUR ENVIRONMENT =======================\n\n# Your platform. See PLATS for possible values.\nPLAT= none\n\n# Where to install. The installation starts in the src and doc directories,\n# so take care if INSTALL_TOP is not an absolute path.\nINSTALL_TOP= /usr/local\nINSTALL_BIN= $(INSTALL_TOP)/bin\nINSTALL_INC= $(INSTALL_TOP)/include\nINSTALL_LIB= $(INSTALL_TOP)/lib\nINSTALL_MAN= $(INSTALL_TOP)/man/man1\n#\n# You probably want to make INSTALL_LMOD and INSTALL_CMOD consistent with\n# LUA_ROOT, LUA_LDIR, and LUA_CDIR in luaconf.h (and also with etc/lua.pc).\nINSTALL_LMOD= $(INSTALL_TOP)/share/lua/$V\nINSTALL_CMOD= $(INSTALL_TOP)/lib/lua/$V\n\n# How to install. If your install program does not support \"-p\", then you\n# may have to run ranlib on the installed liblua.a (do \"make ranlib\").\nINSTALL= install -p\nINSTALL_EXEC= $(INSTALL) -m 0755\nINSTALL_DATA= $(INSTALL) -m 0644\n#\n# If you don't have install you can use cp instead.\n# INSTALL= cp -p\n# INSTALL_EXEC= $(INSTALL)\n# INSTALL_DATA= $(INSTALL)\n\n# Utilities.\nMKDIR= mkdir -p\nRANLIB= ranlib\n\n# == END OF USER SETTINGS. NO NEED TO CHANGE ANYTHING BELOW THIS LINE =========\n\n# Keep this sync'd with src/Makefile\nPLATS= freebsd linux macosx netbsd openbsd\n\n# What to install.\nTO_BIN= lua luac\nTO_INC= lua.h luaconf.h lualib.h lauxlib.h ../etc/lua.hpp\nTO_LIB= liblua.a\nTO_MAN= lua.1 luac.1\n\n# Lua version and release.\nV= 5.1\nR= 5.1.5\n\nall:\t$(PLAT)\n\n$(PLATS) clean:\n\tcd src && $(MAKE) $@\n\ninstall: dummy\n\tcd src && $(MKDIR) $(INSTALL_BIN) $(INSTALL_INC) $(INSTALL_LIB) $(INSTALL_MAN) $(INSTALL_LMOD) $(INSTALL_CMOD)\n\tcd src && $(INSTALL_EXEC) $(TO_BIN) $(INSTALL_BIN)\n\tcd src && $(INSTALL_DATA) $(TO_INC) $(INSTALL_INC)\n\tcd src && $(INSTALL_DATA) $(TO_LIB) $(INSTALL_LIB)\n\tcd doc && $(INSTALL_DATA) $(TO_MAN) $(INSTALL_MAN)\n\nranlib:\n\tcd src && cd $(INSTALL_LIB) && $(RANLIB) $(TO_LIB)\n\nlocal:\n\t$(MAKE) install INSTALL_TOP=..\n\nnone:\n\t@echo \"Please do\"\n\t@echo \" make PLATFORM\"\n\t@echo \"where PLATFORM is one of these:\"\n\t@echo \" $(PLATS)\"\n\t@echo \"See INSTALL for complete instructions.\"\n\n# make may get confused with test/ and INSTALL in a case-insensitive OS\ndummy:\n\n# echo config parameters\necho:\n\t@echo \"\"\n\t@echo \"These are the parameters currently set in src/Makefile to build Lua $R:\"\n\t@echo \"\"\n\t@cd src && $(MAKE) -s echo\n\t@echo \"\"\n\t@echo \"These are the parameters currently set in Makefile to install Lua $R:\"\n\t@echo \"\"\n\t@echo \"PLAT = $(PLAT)\"\n\t@echo \"INSTALL_TOP = $(INSTALL_TOP)\"\n\t@echo \"INSTALL_BIN = $(INSTALL_BIN)\"\n\t@echo \"INSTALL_INC = $(INSTALL_INC)\"\n\t@echo \"INSTALL_LIB = $(INSTALL_LIB)\"\n\t@echo \"INSTALL_MAN = $(INSTALL_MAN)\"\n\t@echo \"INSTALL_LMOD = $(INSTALL_LMOD)\"\n\t@echo \"INSTALL_CMOD = $(INSTALL_CMOD)\"\n\t@echo \"INSTALL_EXEC = $(INSTALL_EXEC)\"\n\t@echo \"INSTALL_DATA = $(INSTALL_DATA)\"\n\t@echo \"\"\n\t@echo \"See also src/luaconf.h .\"\n\t@echo \"\"\n\n# echo private config parameters\npecho:\n\t@echo \"V = $(V)\"\n\t@echo \"R = $(R)\"\n\t@echo \"TO_BIN = $(TO_BIN)\"\n\t@echo \"TO_INC = $(TO_INC)\"\n\t@echo \"TO_LIB = $(TO_LIB)\"\n\t@echo \"TO_MAN = $(TO_MAN)\"\n\n# echo config parameters as Lua code\n# uncomment the last sed expression if you want nil instead of empty strings\nlecho:\n\t@echo \"-- installation parameters for Lua $R\"\n\t@echo \"VERSION = '$V'\"\n\t@echo \"RELEASE = '$R'\"\n\t@$(MAKE) echo | grep = | sed -e 's/= /= \"/' -e 's/$$/\"/' #-e 's/\"\"/nil/'\n\t@echo \"-- EOF\"\n\n# list targets that do not create files (but not all makes understand .PHONY)\n.PHONY: all $(PLATS) clean test install local none dummy echo pecho lecho\n\n# (end of Makefile)\n"
},
{
"path": "README.md",
"content": "# Teliva - an environment for end-user programming\n\n> “Enable all people to modify the software they use in the course of using it.”\n> — https://futureofcoding.org/episodes/033.html\n\n> “What if we, and all computer users, could reach in and modify our favorite apps?”\n> — https://www.inkandswitch.com/end-user-programming\n\n> “Software must be as easy to change as it is to use.”\n> — https://malleable.systems\n\n## What's this, then?\n\nTeliva is the most naive way to make software as easy to change as it is to\nuse: an interpreted environment for running shareable little text-mode apps.\nIts language of choice is Lua, excluding all features that can conceivably\nintroduce moving parts in running a Lua program.\n\nHere's how you run one of the example apps (the [Tower of Hanoi](https://en.wikipedia.org/wiki/Tower_of_Hanoi)):\n\n```sh\ngit clone https://github.com/akkartik/teliva\ncd teliva\nmake linux # replace with 'macosx', etc. depending on your OS\nsrc/teliva hanoi.tlv\n```\n\n\n\nNo matter what app you run, you are always guaranteed access to a single\nobvious, consistent way (currently the hotkey `ctrl-u`) to inspect its\nsources.\n\nWhen you look under the hood of an app, the first thing you see is a\n_big-picture view_ which shows the app's major data structures and a top-down\nview of the app's code.\n\n\n\nSelect a definition, make a change, hit `ctrl-x`, and the app will run with\nyour updates. ([video](https://archive.org/details/akkartik-2021-11-14))\n\nYou will need some Unix-like platform with a C compiler and the ncurses and\nopenssl libraries. Some possible commands to install them, depending on your\nOS and package manager of choice:\n\n* `guix shell -D lua openssl -- make linux`\n* `nix-shell --pure` (from a directory containing shell.nix in this repo)\n* `sudo apt install libncursesw6-dev openssl`\n* `brew install ncurses openssl`\n\nSo far I've tested Teliva on Linux, Mac OS X, OpenBSD, NetBSD and FreeBSD; it\nshould work on other flavors of BSD, WSL on Windows, etc. with only minor\nmodifications.\n\n## What else can it do?\n\nAnything! Some more sample apps to try out:\n\n* Conway's Game of Life, as an example of an animated local app.\n ```\n src/teliva life.tlv\n ```\n\n [video](https://merveilles.town/@akkartik/107277755421024772)\n\n* A viewer for [LiChess TV](https://lichess.org/tv), as an example of\n animation and accessing a remote API over a network.\n ```\n src/teliva chesstv.tlv\n ```\n\n [video](https://merveilles.town/@akkartik/107319684018301051)\n\n* A browser for the [Gemini protocol](https://gemini.circumlunar.space).\n ```\n src/teliva gemini.tlv\n ```\n\n [video](https://merveilles.town/@akkartik/107489728557201145)\n\nThese are just a start. The sky is the limit.\n\n## So, just a programming language, then?\n\nThere's one big difference with other programming languages: Teliva apps are\nsandboxed like a browser. Most languages assume the fiction that the person\nrunning a program trusts all the code in the program. This assumption hasn't\nbeen valid since a decade after the Unix big bang, if then. Teliva takes on\nthe reality that apps can get complex and use code written by strangers. In\nresponse, Teliva tries to always summarize for you what the program you're\nrunning is trying to do, and to ask you before a random app tries to do\nsomething sensitive. Permissions you grant a Teliva app will be _flexible_ and\n_easy to understand_. Browsers and mobile apps today tend to make you choose\nbetween those two properties.\n\nThe sandboxing experience is still under construction. See [this talk](https://archive.org/details/akkartik-2022-01-16-fosdem)\n(15 minutes) for a rundown of current thinking. It isn't yet safe to run\nuntrusted Teliva apps you download from the internet. (Fortunately you're\nunlikely to run into any such apps.)\n\n## Isn't this just an IDE?\n\nThere's one big difference: these apps are not intended to be runnable outside\nof the Teliva environment. Editing the sources and visualizing permissions\ngranted will always be core features that are front and center in the UI.\n\nA second, more subtle difference: it's primarily an environment for _running_\napps, and only secondarily for editing them. Starting up the environment puts\nyou in a running app by default. Creating an app from a clean slate is a\nlow-priority use case, as is lots of specialized support for developing\ncomplex apps. The sweet spot for Teliva is simple apps that people will want\nto edit after using for a while.\n\n## Who are we trusting by trusting you?\n\nTeliva is designed to have a shallow, manageable software supply chain. I\nrely on packages distributed by the following reputable brands:\n\n* A well-known Posix OS, either Linux or BSD.\n* A standard C library, usually GNU libc.\n* The [ncurses](https://tldp.org/HOWTO/NCURSES-Programming-HOWTO) library for\n building text-mode user interfaces. ([Alternative documentation](https://tldp.org/LDP/lpg-0.4.pdf))\n\nTeliva's codebase also includes forks of the following reputable brands:\n\n* [Lua 5.1](https://www.lua.org/manual/5.1)\n* The [Kilo](https://github.com/antirez/kilo) text editor, modified to use\n ncurses. (Read more about it in this [fantastic walk-through](https://viewsourcecode.org/snaptoken/kilo).)\n* The [lcurses](https://github.com/lcurses/lcurses) binding for ncurses (as\n module `curses`).\n* The [luasocket](https://w3.impa.br/~diego/software/luasocket) library of\n networking primitives (modules `socket`, `http`, `url`, `headers`, `mime`,\n `ltn12`).\n* The [luasec](https://github.com/brunoos/luasec) library for HTTPS support\n (modules `https` and `ssl`).\n* The [json.lua](https://github.com/rxi/json.lua) library for\n serializing/deserializing to JSON (modules `json` and `jsonf`).\n\nI only add to this list with great deliberation. Since it includes indirect\nsuppliers (suppliers of suppliers), I have an incentive to only include\nsuppliers who also have shallow supply chains. Minimizing the size of the\nsupply chain should result in more reliable software that requires less\nfrequent upgrades.\n\n(Look in [the manual](https://akkartik.github.io/teliva/doc/manual.html) for\nmore details of what's available.)\n\n## Why Lua?\n\nIt's reputedly the fastest interpreted language per line of implementation\ncode.\n\n## Will it run any Lua program?\n\nNot quite. My priority is providing a good experience for newcomers to\ncomprehend and modify the programs they use. If it's not clear how to provide\nthat experience for some kinds of Lua programs, I'd rather disable support for\nthem in Teliva and let people use regular Lua. Or other platforms!\n\n- This approach doesn't make sense for batch programs, I think. I also don't\n yet have a good story for building server programs in this way.\n\n- I don't know how to obtain a simple, shallow graphics stack, so there's no\n support for graphics at the moment.\n\n- Teliva initializes the ncurses library by default, so apps should assume\n they have access to a (color, UTF-8) text-mode window for printing text to,\n and a keyboard for reading keystrokes from.\n\n- Teliva doesn't use files for source code, so the `require` keyword no longer\n makes sense. You get some libraries preloaded (see below). Beyond those,\n apps should include all Lua code they want to use.\n\n- To create a well-behaved sandbox, Teliva doesn't support adding libraries\n with C bindings beyond the few it starts up with.\n\n- Functions that start with `test_` are special. They're considered automated\n tests and called without arguments every time an app starts up.\n\n- The function `main` is special. It runs every time an app starts up, if all\n its automated tests pass.\n\n- Some functions are disabled because I don't know how to sandbox them\n effectively:\n - `os.execute`, `os.getenv`, `io.popen`\n - `io.lines` (not a security issue; just difficult to distinguish missing\n files from sandboxing issues)\n\n- Some functions are disabled because they don't seem to make sense in an\n ncurses environment. This includes the Lua notions of default files, which\n start out as stdin/stdout.\n - `io.input`, `io.read`\n - `io.output`, `io.write`, `io.flush`\n - `curses.getstr()`, `curses.mvgetstr()` (When using these it's easy for the\n screen to get confusing.)\n\n- Some functions in lcurses have [additional smarts](https://github.com/lcurses/lcurses/blob/master/lib/curses.lua).\n Teliva is [consistent with the underlying ncurses](https://github.com/akkartik/teliva/blob/main/src/lcurses/curses.lua).\n\nLook in [the manual](https://akkartik.github.io/teliva/doc/manual.html) for\nmore details of what's available.\n\nI may delete more capabilities throughout this stack as I discover features\nthat don't fit well with the Teliva experience. If you find Teliva of use,\nplease [introduce yourself](http://akkartik.name/contact) to me so that I am\naware of your use cases. Anybody who is interested can gain a say in its\nfuture direction.\n\n## What's with the name?\n\nTeliva is the Tamil root for ‘clear’. Very much aspirational.\n\n## Known issues\n\n* Colors are currently hardcoded. You get a light background even if your\n terminal started out dark. To tweak colors, look for calls to\n `assume_default_colors()` and `init_pair()`, either in .tlv files for a\n specific app, or in the C sources for the standard code browser/editor.\n\n* Backspace is known to not work in some configurations. As a workaround,\n typing `ctrl-h` tends to work in those situations.\n\n* Keys outside the main keyboard area are mostly not supported. This includes\n the delete key when it's set away from the main keyboard area. (Macs call\n the backspace key “delete”; it should behave like backspace. As\n a consequence the menu sometimes mentions keys that don't work, just to\n encourage people to try options.)\n\n* chesstv.tlv silently fails on OpenBSD and NetBSD for some reason I haven't\n investigated yet. Interestingly, I'm running Teliva with curses on NetBSD\n but ncurses on OpenBSD, so that is probably not an issue.\n\n* life.tlv looks terrible on OpenBSD and NetBSD, with lines wrapping halfway.\n\n## Mirrors and Forks\n\nUpdates to Teliva can be downloaded from the following mirrors:\n* https://github.com/akkartik/teliva\n* https://repo.or.cz/teliva.git\n* https://codeberg.org/akkartik/teliva\n* https://tildegit.org/akkartik/teliva\n* https://git.tilde.institute/akkartik/teliva\n* https://git.sr.ht/~akkartik/teliva\n* https://pagure.io/teliva\n\nForks of Teliva are encouraged. If you show me your fork, I'll link to it\nhere.\n\n## Feedback\n\n[Most appreciated.](http://akkartik.name/contact)\n"
},
{
"path": "anagrams.tlv",
"content": "# .tlv file generated by https://github.com/akkartik/teliva\n# You may edit it if you are careful; however, you may see cryptic errors if you\n# violate Teliva's assumptions.\n#\n# .tlv files are representations of Teliva programs. Teliva programs consist of\n# sequences of definitions. Each definition is a table of key/value pairs. Keys\n# and values are both strings.\n#\n# Lines in .tlv files always follow exactly one of the following forms:\n# - comment lines at the top of the file starting with '#' at column 0\n# - beginnings of definitions starting with '- ' at column 0, followed by a\n# key/value pair\n# - key/value pairs consisting of ' ' at column 0, containing either a\n# spaceless value on the same line, or a multi-line value\n# - multiline values indented by more than 2 spaces, starting with a '>'\n#\n# If these constraints are violated, Teliva may unceremoniously crash. Please\n# report bugs at http://akkartik.name/contact\n- __teliva_timestamp: original\n str_helpers:\n >-- some string helpers from http://lua-users.org/wiki/StringIndexing\n >\n >-- index characters using []\n >getmetatable('').__index = function(str,i)\n > if type(i) == 'number' then\n > return str:sub(i,i)\n > else\n > return string[i]\n > end\n >end\n >\n >-- ranges using (), selected bytes using {}\n >getmetatable('').__call = function(str,i,j)\n > if type(i)~='table' then\n > return str:sub(i,j)\n > else\n > local t={}\n > for k,v in ipairs(i) do\n > t[k]=str:sub(v,v)\n > end\n > return table.concat(t)\n > end\n >end\n >\n >-- iterate over an ordered sequence\n >function q(x)\n > if type(x) == 'string' then\n > return x:gmatch('.')\n > else\n > return ipairs(x)\n > end\n >end\n >\n >-- insert within string\n >function string.insert(str1, str2, pos)\n > return str1:sub(1,pos)..str2..str1:sub(pos+1)\n >end\n >\n >function string.remove(s, pos)\n > return s:sub(1,pos-1)..s:sub(pos+1)\n >end\n >\n >function string.pos(s, sub)\n > return string.find(s, sub, 1, true) -- plain=true to disable regular expressions\n >end\n >\n >-- TODO: backport utf-8 support from Lua 5.3\n- __teliva_timestamp: original\n debugy:\n >debugy = 5\n- __teliva_timestamp: original\n dbg:\n >-- helper for debug by print; overlay debug information towards the right\n >-- reset debugy every time you refresh screen\n >function dbg(window, s)\n > local oldy = 0\n > local oldx = 0\n > oldy, oldx = window:getyx()\n > window:mvaddstr(debugy, 60, s)\n > debugy = debugy+1\n > window:mvaddstr(oldy, oldx, '')\n >end\n- __teliva_timestamp: original\n check:\n >function check(x, msg)\n > if x then\n > Window:addch('.')\n > else\n > print('F - '..msg)\n > print(' '..str(x)..' is false/nil')\n > teliva_num_test_failures = teliva_num_test_failures + 1\n > -- overlay first test failure on editors\n > if teliva_first_failure == nil then\n > teliva_first_failure = msg\n > end\n > end\n >end\n- __teliva_timestamp: original\n check_eq:\n >function check_eq(x, expected, msg)\n > if eq(x, expected) then\n > Window:addch('.')\n > else\n > print('F - '..msg)\n > print(' expected '..str(expected)..' but got '..str(x))\n > teliva_num_test_failures = teliva_num_test_failures + 1\n > -- overlay first test failure on editors\n > if teliva_first_failure == nil then\n > teliva_first_failure = msg\n > end\n > end\n >end\n- __teliva_timestamp: original\n eq:\n >function eq(a, b)\n > if type(a) ~= type(b) then return false end\n > if type(a) == 'table' then\n > if #a ~= #b then return false end\n > for k, v in pairs(a) do\n > if b[k] ~= v then\n > return false\n > end\n > end\n > for k, v in pairs(b) do\n > if a[k] ~= v then\n > return false\n > end\n > end\n > return true\n > end\n > return a == b\n >end\n- __teliva_timestamp: original\n str:\n >-- smarter tostring\n >-- slow; used only for debugging\n >function str(x)\n > if type(x) == 'table' then\n > local result = ''\n > result = result..#x..'{'\n > for k, v in pairs(x) do\n > result = result..str(k)..'='..str(v)..', '\n > end\n > result = result..'}'\n > return result\n > elseif type(x) == 'string' then\n > return '\"'..x..'\"'\n > end\n > return tostring(x)\n >end\n- __teliva_timestamp: original\n find_index:\n >function find_index(arr, x)\n > for n, y in ipairs(arr) do\n > if x == y then\n > return n\n > end\n > end\n >end\n- __teliva_timestamp: original\n trim:\n >function trim(s)\n > return s:gsub('^%s*', ''):gsub('%s*$', '')\n >end\n- __teliva_timestamp: original\n split:\n >function split(s, d)\n > result = {}\n > for match in (s..d):gmatch(\"(.-)\"..d) do\n > table.insert(result, match);\n > end\n > return result\n >end\n- __teliva_timestamp: original\n map:\n >-- only for arrays\n >function map(l, f)\n > result = {}\n > for _, x in ipairs(l) do\n > table.insert(result, f(x))\n > end\n > return result\n >end\n- __teliva_timestamp: original\n reduce:\n >-- only for arrays\n >function reduce(l, f, init)\n > result = init\n > for _, x in ipairs(l) do\n > result = f(result, x)\n > end\n > return result\n >end\n- __teliva_timestamp: original\n filter:\n >function filter(h, f)\n > result = {}\n > for k, v in pairs(h) do\n > if f(k, v) then\n > result[k] = v\n > end\n > end\n > return result\n >end\n- __teliva_timestamp: original\n ifilter:\n >-- only for arrays\n >function ifilter(l, f)\n > result = {}\n > for _, x in ipairs(l) do\n > if f(x) then\n > table.insert(result, x)\n > end\n > end\n > return result\n >end\n- __teliva_timestamp: original\n sort_letters:\n >function sort_letters(s)\n > tmp = {}\n > for i=1,#s do\n > table.insert(tmp, s[i])\n > end\n > table.sort(tmp)\n > local result = ''\n > for _, c in pairs(tmp) do\n > result = result..c\n > end\n > return result\n >end\n >\n >function test_sort_letters(s)\n > check_eq(sort_letters(''), '', 'test_sort_letters: empty')\n > check_eq(sort_letters('ba'), 'ab', 'test_sort_letters: non-empty')\n > check_eq(sort_letters('abba'), 'aabb', 'test_sort_letters: duplicates')\n >end\n- __teliva_timestamp: original\n count_letters:\n >-- TODO: handle unicode\n >function count_letters(s)\n > local result = {}\n > for i=1,s:len() do\n > local c = s[i]\n > if result[c] == nil then\n > result[c] = 1\n > else\n > result[c] = result[c] + 1\n > end\n > end\n > return result\n >end\n- __teliva_timestamp: original\n count:\n >-- turn an array of elements into a map from elements to their frequency\n >-- analogous to count_letters for non-strings\n >function count(a)\n > local result = {}\n > for i, v in ipairs(a) do\n > if result[v] == nil then\n > result[v] = 1\n > else\n > result[v] = result[v] + 1\n > end\n > end\n > return result\n >end\n- __teliva_timestamp: original\n union:\n >function union(a, b)\n > for k, v in pairs(b) do\n > a[k] = v\n > end\n > return a\n >end\n- __teliva_timestamp: original\n subtract:\n >-- set subtraction\n >function subtract(a, b)\n > for k, v in pairs(b) do\n > a[k] = nil\n > end\n > return a\n >end\n- __teliva_timestamp: original\n all:\n >-- universal quantifier on sets\n >function all(s, f)\n > for k, v in pairs(s) do\n > if not f(k, v) then\n > return false\n > end\n > end\n > return true\n >end\n- __teliva_timestamp: original\n to_array:\n >-- turn a set into an array\n >-- drops values\n >function to_array(h)\n > local result = {}\n > for k, _ in pairs(h) do\n > table.insert(result, k)\n > end\n > return result\n >end\n- __teliva_timestamp: original\n append:\n >-- concatenate list 'elems' into 'l', modifying 'l' in the process\n >function append(l, elems)\n > for i=1,#elems do\n > table.insert(l, elems[i])\n > end\n >end\n- __teliva_timestamp: original\n prepend:\n >-- concatenate list 'elems' into the start of 'l', modifying 'l' in the process\n >function prepend(l, elems)\n > for i=1,#elems do\n > table.insert(l, i, elems[i])\n > end\n >end\n- __teliva_timestamp: original\n all_but:\n >function all_but(x, idx)\n > if type(x) == 'table' then\n > local result = {}\n > for i, elem in ipairs(x) do\n > if i ~= idx then\n > table.insert(result,elem)\n > end\n > end\n > return result\n > elseif type(x) == 'string' then\n > if idx < 1 then return x:sub(1) end\n > return x:sub(1, idx-1) .. x:sub(idx+1)\n > else\n > error('all_but: unsupported type '..type(x))\n > end\n >end\n >\n >function test_all_but()\n > check_eq(all_but('', 0), '', 'all_but: empty')\n > check_eq(all_but('abc', 0), 'abc', 'all_but: invalid low index')\n > check_eq(all_but('abc', 4), 'abc', 'all_but: invalid high index')\n > check_eq(all_but('abc', 1), 'bc', 'all_but: first index')\n > check_eq(all_but('abc', 3), 'ab', 'all_but: final index')\n > check_eq(all_but('abc', 2), 'ac', 'all_but: middle index')\n >end\n- __teliva_timestamp: original\n set:\n >function set(l)\n > local result = {}\n > for i, elem in ipairs(l) do\n > result[elem] = true\n > end\n > return result\n >end\n- __teliva_timestamp: original\n set_eq:\n >function set_eq(l1, l2)\n > return eq(set(l1), set(l2))\n >end\n >\n >function test_set_eq()\n > check(set_eq({1}, {1}), 'set_eq: identical')\n > check(not set_eq({1, 2}, {1, 3}), 'set_eq: different')\n > check(set_eq({1, 2}, {2, 1}), 'set_eq: order')\n > check(set_eq({1, 2, 2}, {2, 1}), 'set_eq: duplicates')\n >end\n- __teliva_timestamp: original\n clear:\n >function clear(lines)\n > while #lines > 0 do\n > table.remove(lines)\n > end\n >end\n- __teliva_timestamp: original\n zap:\n >function zap(target, src)\n > clear(target)\n > append(target, src)\n >end\n- __teliva_timestamp: original\n mfactorial:\n >-- memoized version of factorial\n >-- doesn't memoize recursive calls, but may be good enough\n >mfactorial = memo1(factorial)\n- __teliva_timestamp: original\n factorial:\n >function factorial(n)\n > local result = 1\n > for i=1,n do\n > result = result*i\n > end\n > return result\n >end\n- __teliva_timestamp: original\n memo1:\n >-- a higher-order function that takes a function of a single arg\n >-- (that never returns nil)\n >-- and returns a memoized version of it\n >function memo1(f)\n > local memo = {}\n > return function(x)\n > if memo[x] == nil then\n > memo[x] = f(x)\n > end\n > return memo[x]\n > end\n >end\n >\n >-- mfactorial doesn't seem noticeably faster\n >function test_memo1()\n > for i=0,30 do\n > check_eq(mfactorial(i), factorial(i), 'memo1 over factorial: '..str(i))\n > end\n >end\n- __teliva_timestamp: original\n num_permutations:\n >-- number of permutations of n distinct objects, taken r at a time\n >function num_permutations(n, r)\n > return factorial(n)/factorial(n-r)\n >end\n >\n >-- mfactorial doesn't seem noticeably faster\n >function test_memo1()\n > for i=0,30 do\n > for j=0,i do\n > check_eq(num_permutations(i, j), mfactorial(i)/mfactorial(i-j), 'num_permutations memoizes: '..str(i)..'P'..str(j))\n > end\n > end\n >end\n- __teliva_timestamp: original\n menu:\n >-- To show app-specific hotkeys in the menu bar, add hotkey/command\n >-- arrays of strings to the menu array.\n >menu = {\n > {'^h', 'backspace'},\n >}\n- __teliva_timestamp: original\n Window:\n >Window = curses.stdscr()\n- __teliva_timestamp: original\n doc:blurb:\n >Show all anagrams of a given word\n- __teliva_timestamp: original\n word:\n >word = ''\n- __teliva_timestamp: original\n cursor:\n >cursor = 1\n- __teliva_timestamp: original\n main:\n >function main()\n > Window:nodelay(true)\n > while true do\n > render(Window)\n > update(Window)\n > end\n >end\n- __teliva_timestamp: original\n update:\n >function update(window)\n > local key\n > while true do\n > key = window:getch()\n > if key then break end\n > end\n > if key == curses.KEY_LEFT then\n > if cursor > 1 then\n > cursor = cursor-1\n > end\n > elseif key == curses.KEY_RIGHT then\n > if cursor <= #word then\n > cursor = cursor+1\n > end\n > elseif key == curses.KEY_BACKSPACE or key == 8 or key == 127 then -- ctrl-h, ctrl-?, delete\n > if cursor > 1 then\n > cursor = cursor-1\n > word = word:remove(cursor)\n > end\n > elseif key >= 32 and key < 127 then\n > word = word:insert(string.char(key), cursor-1)\n > cursor = cursor+1\n > end\n >end\n- __teliva_timestamp: original\n render:\n >function render(window)\n > window:clear()\n >\n > local prompt_str = ' what is your name? '\n > window:attron(curses.A_REVERSE)\n > window:mvaddstr(0, 0, prompt_str)\n > window:attroff(curses.A_REVERSE)\n > window:addstr(' ')\n > window:attron(curses.A_BOLD)\n > window:addstr(word)\n > window:attroff(curses.A_BOLD)\n > window:mvaddstr(2, 0, '')\n > local results = anagrams(word)\n > if #results > 0 then\n > window:attron(curses.A_REVERSE)\n > print(#results..' anagrams')\n > window:attroff(curses.A_REVERSE)\n > for i, w in ipairs(results) do\n > window:addstr(w)\n > window:addstr(' ')\n > end\n > end\n >\n > window:mvaddstr(0, string.len(prompt_str)+cursor, '')\n > window:refresh()\n >end\n- __teliva_timestamp:\n >Mon Feb 21 17:42:28 2022\n anagrams:\n >function anagrams(word)\n > return gather(sort_letters(word))\n >end\n- __teliva_timestamp:\n >Mon Feb 21 18:18:07 2022\n gather:\n >function gather(s)\n > if s == '' then return {} end\n > local result = {}\n > for i=1, #s do\n > if i == 1 or s[i] ~= s[i-1] then\n > append(result, combine(s[i], gather(all_but(s, i))))\n > end\n > end\n > return result\n >end\n- __teliva_timestamp: original\n __teliva_note:\n >basic version\n combine:\n >-- return 'l' with each element prefixed with 'prefix'\n >function combine(prefix, l)\n > if #l == 0 then return {prefix} end\n > local result = {}\n > for _, elem in ipairs(l) do\n > table.insert(result, prefix..elem)\n > end\n > return result\n >end\n >\n >function test_combine()\n > check_eq(combine('abc', {}), {'abc'}, 'test_combine: empty list')\n >end\n- __teliva_timestamp:\n >Sat Mar 5 15:24:00 2022\n count_anagrams:\n >function count_anagrams(s)\n > local result = factorial(s:len())\n > local letter_counts = count_letters(s)\n > for l, cnt in pairs(letter_counts) do\n > result = result / factorial(cnt)\n > end\n > return result\n >end\n- __teliva_timestamp:\n >Sat Mar 5 15:53:23 2022\n key_pressed:\n >-- only works when nodelay (non-blocking keyboard)\n >function key_pressed(window)\n > local c = window:getch()\n > if c == nil then return false end\n > window:ungetch(c)\n > return true\n >end\n- __teliva_timestamp:\n >Sat Mar 5 15:55:34 2022\n render:\n >function render(window)\n > window:clear()\n >\n > local prompt_str = ' what is your name? '\n > window:attron(curses.A_REVERSE)\n > window:mvaddstr(0, 0, prompt_str)\n > window:attroff(curses.A_REVERSE)\n > window:addstr(' ')\n > window:attron(curses.A_BOLD)\n > window:addstr(word)\n > window:attroff(curses.A_BOLD)\n > window:mvaddstr(2, 0, '')\n > if #word > 0 then\n > local num_anagrams = count_anagrams(word)\n > window:attron(curses.A_REVERSE)\n > print(num_anagrams..' anagrams')\n > window:attroff(curses.A_REVERSE)\n > local results = anagrams(word)\n > if results == nil then -- interrupted\n > window:addstr('...')\n > else\n > assert(#results == num_anagrams, \"something's wrong; the count is unexpected\")\n > for i, w in ipairs(results) do\n > window:addstr(w)\n > window:addstr(' ')\n > if key_pressed(window) then\n > break\n > end\n > end\n > end\n > end\n >\n > window:mvaddstr(0, string.len(prompt_str)+cursor, '')\n > window:refresh()\n >end\n- __teliva_timestamp:\n >Sat Mar 5 15:56:35 2022\n __teliva_note:\n >restart computation when a key is pressed\n gather:\n >-- return a list of unique permutations of a sorted string 's'\n >-- the letters in 's' must be in alphabetical order, so that duplicates are adjacent\n >-- this function can take a long time for long strings, so we make it interruptible\n >-- if a key is pressed, it returns nil\n >-- since it's recursive, we also need to handle recursive calls returning nil\n >function gather(s)\n > if s == '' then return {} end\n > local result = {}\n > for i=1, #s do\n > if i == 1 or s[i] ~= s[i-1] then\n > local subresult = gather(all_but(s, i))\n > if subresult == nil then return nil end -- interrupted\n > append(result, combine(s[i], subresult))\n > end\n > if key_pressed(Window) then return nil end -- interrupted\n > end\n > return result\n >end\n"
},
{
"path": "break.tlv",
"content": "# .tlv file generated by https://github.com/akkartik/teliva\n# You may edit it if you are careful; however, you may see cryptic errors if you\n# violate Teliva's assumptions.\n#\n# .tlv files are representations of Teliva programs. Teliva programs consist of\n# sequences of definitions. Each definition is a table of key/value pairs. Keys\n# and values are both strings.\n#\n# Lines in .tlv files always follow exactly one of the following forms:\n# - comment lines at the top of the file starting with '#' at column 0\n# - beginnings of definitions starting with '- ' at column 0, followed by a\n# key/value pair\n# - key/value pairs consisting of ' ' at column 0, containing either a\n# spaceless value on the same line, or a multi-line value\n# - multiline values indented by more than 2 spaces, starting with a '>'\n#\n# If these constraints are violated, Teliva may unceremoniously crash. Please\n# report bugs at http://akkartik.name/contact\n- __teliva_timestamp: original\n str_helpers:\n >-- some string helpers from http://lua-users.org/wiki/StringIndexing\n >\n >-- index characters using []\n >getmetatable('').__index = function(str,i)\n > if type(i) == 'number' then\n > return str:sub(i,i)\n > else\n > return string[i]\n > end\n >end\n >\n >-- ranges using (), selected bytes using {}\n >getmetatable('').__call = function(str,i,j)\n > if type(i)~='table' then\n > return str:sub(i,j)\n > else\n > local t={}\n > for k,v in ipairs(i) do\n > t[k]=str:sub(v,v)\n > end\n > return table.concat(t)\n > end\n >end\n >\n >-- iterate over an ordered sequence\n >function q(x)\n > if type(x) == 'string' then\n > return x:gmatch('.')\n > else\n > return ipairs(x)\n > end\n >end\n >\n >-- insert within string\n >function string.insert(str1, str2, pos)\n > return str1:sub(1,pos)..str2..str1:sub(pos+1)\n >end\n >\n >function string.remove(s, pos)\n > return s:sub(1,pos-1)..s:sub(pos+1)\n >end\n >\n >function string.pos(s, sub)\n > return string.find(s, sub, 1, true) -- plain=true to disable regular expressions\n >end\n >\n >-- TODO: backport utf-8 support from Lua 5.3\n- __teliva_timestamp: original\n debugy:\n >debugy = 5\n- __teliva_timestamp: original\n dbg:\n >-- helper for debug by print; overlay debug information towards the right\n >-- reset debugy every time you refresh screen\n >function dbg(window, s)\n > local oldy = 0\n > local oldx = 0\n > oldy, oldx = window:getyx()\n > window:mvaddstr(debugy, 60, s)\n > debugy = debugy+1\n > window:mvaddstr(oldy, oldx, '')\n >end\n- __teliva_timestamp: original\n check:\n >function check(x, msg)\n > if x then\n > Window:addch('.')\n > else\n > print('F - '..msg)\n > print(' '..str(x)..' is false/nil')\n > teliva_num_test_failures = teliva_num_test_failures + 1\n > -- overlay first test failure on editors\n > if teliva_first_failure == nil then\n > teliva_first_failure = msg\n > end\n > end\n >end\n- __teliva_timestamp: original\n check_eq:\n >function check_eq(x, expected, msg)\n > if eq(x, expected) then\n > Window:addch('.')\n > else\n > print('F - '..msg)\n > print(' expected '..str(expected)..' but got '..str(x))\n > teliva_num_test_failures = teliva_num_test_failures + 1\n > -- overlay first test failure on editors\n > if teliva_first_failure == nil then\n > teliva_first_failure = msg\n > end\n > end\n >end\n- __teliva_timestamp: original\n eq:\n >function eq(a, b)\n > if type(a) ~= type(b) then return false end\n > if type(a) == 'table' then\n > if #a ~= #b then return false end\n > for k, v in pairs(a) do\n > if b[k] ~= v then\n > return false\n > end\n > end\n > for k, v in pairs(b) do\n > if a[k] ~= v then\n > return false\n > end\n > end\n > return true\n > end\n > return a == b\n >end\n- __teliva_timestamp: original\n str:\n >-- smarter tostring\n >-- slow; used only for debugging\n >function str(x)\n > if type(x) == 'table' then\n > local result = ''\n > result = result..#x..'{'\n > for k, v in pairs(x) do\n > result = result..str(k)..'='..str(v)..', '\n > end\n > result = result..'}'\n > return result\n > elseif type(x) == 'string' then\n > return '\"'..x..'\"'\n > end\n > return tostring(x)\n >end\n- __teliva_timestamp: original\n find_index:\n >function find_index(arr, x)\n > for n, y in ipairs(arr) do\n > if x == y then\n > return n\n > end\n > end\n >end\n- __teliva_timestamp: original\n trim:\n >function trim(s)\n > return s:gsub('^%s*', ''):gsub('%s*$', '')\n >end\n- __teliva_timestamp: original\n split:\n >function split(s, d)\n > result = {}\n > for match in (s..d):gmatch(\"(.-)\"..d) do\n > table.insert(result, match);\n > end\n > return result\n >end\n- __teliva_timestamp: original\n map:\n >-- only for arrays\n >function map(l, f)\n > result = {}\n > for _, x in ipairs(l) do\n > table.insert(result, f(x))\n > end\n > return result\n >end\n- __teliva_timestamp: original\n reduce:\n >-- only for arrays\n >function reduce(l, f, init)\n > result = init\n > for _, x in ipairs(l) do\n > result = f(result, x)\n > end\n > return result\n >end\n- __teliva_timestamp: original\n filter:\n >function filter(h, f)\n > result = {}\n > for k, v in pairs(h) do\n > if f(k, v) then\n > result[k] = v\n > end\n > end\n > return result\n >end\n- __teliva_timestamp: original\n ifilter:\n >-- only for arrays\n >function ifilter(l, f)\n > result = {}\n > for _, x in ipairs(l) do\n > if f(x) then\n > table.insert(result, x)\n > end\n > end\n > return result\n >end\n- __teliva_timestamp: original\n sort_letters:\n >function sort_letters(s)\n > tmp = {}\n > for i=1,#s do\n > table.insert(tmp, s[i])\n > end\n > table.sort(tmp)\n > local result = ''\n > for _, c in pairs(tmp) do\n > result = result..c\n > end\n > return result\n >end\n >\n >function test_sort_letters(s)\n > check_eq(sort_letters(''), '', 'test_sort_letters: empty')\n > check_eq(sort_letters('ba'), 'ab', 'test_sort_letters: non-empty')\n > check_eq(sort_letters('abba'), 'aabb', 'test_sort_letters: duplicates')\n >end\n- __teliva_timestamp: original\n count_letters:\n >-- TODO: handle unicode\n >function count_letters(s)\n > local result = {}\n > for i=1,s:len() do\n > local c = s[i]\n > if result[c] == nil then\n > result[c] = 1\n > else\n > result[c] = result[c] + 1\n > end\n > end\n > return result\n >end\n- __teliva_timestamp: original\n count:\n >-- turn an array of elements into a map from elements to their frequency\n >-- analogous to count_letters for non-strings\n >function count(a)\n > local result = {}\n > for i, v in ipairs(a) do\n > if result[v] == nil then\n > result[v] = 1\n > else\n > result[v] = result[v] + 1\n > end\n > end\n > return result\n >end\n- __teliva_timestamp: original\n union:\n >function union(a, b)\n > for k, v in pairs(b) do\n > a[k] = v\n > end\n > return a\n >end\n- __teliva_timestamp: original\n subtract:\n >-- set subtraction\n >function subtract(a, b)\n > for k, v in pairs(b) do\n > a[k] = nil\n > end\n > return a\n >end\n- __teliva_timestamp: original\n all:\n >-- universal quantifier on sets\n >function all(s, f)\n > for k, v in pairs(s) do\n > if not f(k, v) then\n > return false\n > end\n > end\n > return true\n >end\n- __teliva_timestamp: original\n to_array:\n >-- turn a set into an array\n >-- drops values\n >function to_array(h)\n > local result = {}\n > for k, _ in pairs(h) do\n > table.insert(result, k)\n > end\n > return result\n >end\n- __teliva_timestamp: original\n append:\n >-- concatenate list 'elems' into 'l', modifying 'l' in the process\n >function append(l, elems)\n > for i=1,#elems do\n > table.insert(l, elems[i])\n > end\n >end\n- __teliva_timestamp: original\n prepend:\n >-- concatenate list 'elems' into the start of 'l', modifying 'l' in the process\n >function prepend(l, elems)\n > for i=1,#elems do\n > table.insert(l, i, elems[i])\n > end\n >end\n- __teliva_timestamp: original\n all_but:\n >function all_but(x, idx)\n > if type(x) == 'table' then\n > local result = {}\n > for i, elem in ipairs(x) do\n > if i ~= idx then\n > table.insert(result,elem)\n > end\n > end\n > return result\n > elseif type(x) == 'string' then\n > if idx < 1 then return x:sub(1) end\n > return x:sub(1, idx-1) .. x:sub(idx+1)\n > else\n > error('all_but: unsupported type '..type(x))\n > end\n >end\n >\n >function test_all_but()\n > check_eq(all_but('', 0), '', 'all_but: empty')\n > check_eq(all_but('abc', 0), 'abc', 'all_but: invalid low index')\n > check_eq(all_but('abc', 4), 'abc', 'all_but: invalid high index')\n > check_eq(all_but('abc', 1), 'bc', 'all_but: first index')\n > check_eq(all_but('abc', 3), 'ab', 'all_but: final index')\n > check_eq(all_but('abc', 2), 'ac', 'all_but: middle index')\n >end\n- __teliva_timestamp: original\n set:\n >function set(l)\n > local result = {}\n > for i, elem in ipairs(l) do\n > result[elem] = true\n > end\n > return result\n >end\n- __teliva_timestamp: original\n set_eq:\n >function set_eq(l1, l2)\n > return eq(set(l1), set(l2))\n >end\n >\n >function test_set_eq()\n > check(set_eq({1}, {1}), 'set_eq: identical')\n > check(not set_eq({1, 2}, {1, 3}), 'set_eq: different')\n > check(set_eq({1, 2}, {2, 1}), 'set_eq: order')\n > check(set_eq({1, 2, 2}, {2, 1}), 'set_eq: duplicates')\n >end\n- __teliva_timestamp: original\n clear:\n >function clear(lines)\n > while #lines > 0 do\n > table.remove(lines)\n > end\n >end\n- __teliva_timestamp: original\n zap:\n >function zap(target, src)\n > clear(target)\n > append(target, src)\n >end\n- __teliva_timestamp: original\n mfactorial:\n >-- memoized version of factorial\n >-- doesn't memoize recursive calls, but may be good enough\n >mfactorial = memo1(factorial)\n- __teliva_timestamp: original\n factorial:\n >function factorial(n)\n > local result = 1\n > for i=1,n do\n > result = result*i\n > end\n > return result\n >end\n- __teliva_timestamp: original\n memo1:\n >-- a higher-order function that takes a function of a single arg\n >-- (that never returns nil)\n >-- and returns a memoized version of it\n >function memo1(f)\n > local memo = {}\n > return function(x)\n > if memo[x] == nil then\n > memo[x] = f(x)\n > end\n > return memo[x]\n > end\n >end\n >\n >-- mfactorial doesn't seem noticeably faster\n >function test_memo1()\n > for i=0,30 do\n > check_eq(mfactorial(i), factorial(i), 'memo1 over factorial: '..str(i))\n > end\n >end\n- __teliva_timestamp: original\n num_permutations:\n >-- number of permutations of n distinct objects, taken r at a time\n >function num_permutations(n, r)\n > return factorial(n)/factorial(n-r)\n >end\n >\n >-- mfactorial doesn't seem noticeably faster\n >function test_memo1()\n > for i=0,30 do\n > for j=0,i do\n > check_eq(num_permutations(i, j), mfactorial(i)/mfactorial(i-j), 'num_permutations memoizes: '..str(i)..'P'..str(j))\n > end\n > end\n >end\n- __teliva_timestamp: original\n menu:\n >-- To show app-specific hotkeys in the menu bar, add hotkey/command\n >-- arrays of strings to the menu array.\n >menu = {}\n- __teliva_timestamp: original\n Window:\n >Window = curses.stdscr()\n- __teliva_timestamp: original\n window:\n >-- constructor for fake screen and window\n >-- call it like this:\n >-- local w = window{\n >-- kbd=kbd('abc'),\n >-- scr=scr{h=5, w=4},\n >-- }\n >-- eventually it'll do everything a real ncurses window can\n >function window(h)\n > h.__index = h\n > setmetatable(h, h)\n > h.__index = function(table, key)\n > return rawget(h, key)\n > end\n > h.attrset = function(self, x)\n > self.scr.attrs = x\n > end\n > h.attron = function(self, x)\n > -- currently same as attrset since Lua 5.1 doesn't have bitwise operators\n > -- doesn't support multiple attrs at once\n >-- local old = self.scr.attrs\n >-- self.scr.attrs = old|x\n > self.scr.attrs = x\n > end\n > h.attroff = function(self, x)\n > -- currently borked since Lua 5.1 doesn't have bitwise operators\n > -- doesn't support multiple attrs at once\n >-- local old = self.scr.attrs\n >-- self.scr.attrs = old & (~x)\n > self.scr.attrs = curses.A_NORMAL\n > end\n > h.getch = function(self)\n > local c = table.remove(h.kbd, 1)\n > if c == nil then return c end\n > return string.byte(c) -- for verisimilitude with ncurses\n > end\n > h.addch = function(self, c)\n > local scr = self.scr\n > if c == '\\n' then\n > scr.cursy = scr.cursy+1\n > scr.cursx = 0\n > return\n > end\n > if scr.cursy <= scr.h then\n > scr[scr.cursy][scr.cursx] = {data=c, attrs=scr.attrs}\n > scr.cursx = scr.cursx+1\n > if scr.cursx > scr.w then\n > scr.cursy = scr.cursy+1\n > scr.cursx = 1\n > end\n > end\n > end\n > h.addstr = function(self, s)\n > for i=1,s:len() do\n > self:addch(s[i])\n > end\n > end\n > h.mvaddch = function(self, y, x, c)\n > self.scr.cursy = y\n > self.scr.cursx = x\n > self:addch(c)\n > end\n > h.mvaddstr = function(self, y, x, s)\n > self.scr.cursy = y\n > self.scr.cursx = x\n > self:addstr(s)\n > end\n > h.clear = function(self)\n > clear_scr(self.scr)\n > end\n > h.refresh = function(self)\n > -- nothing\n > end\n > return h\n >end\n- __teliva_timestamp: original\n kbd:\n >function kbd(keys)\n > local result = {}\n > for i=1,keys:len() do\n > table.insert(result, keys[i])\n > end\n > return result\n >end\n- __teliva_timestamp: original\n scr:\n >function scr(props)\n > props.cursx = 1\n > props.cursy = 1\n > clear_scr(props)\n > return props\n >end\n- __teliva_timestamp: original\n clear_scr:\n >function clear_scr(props)\n > props.cursy = 1\n > props.cursx = 1\n > for y=1,props.h do\n > props[y] = {}\n > for x=1,props.w do\n > props[y][x] = {data=' ', attrs=curses.A_NORMAL}\n > end\n > end\n > return props\n >end\n- __teliva_timestamp: original\n check_screen:\n >function check_screen(window, contents, message)\n > local x, y = 1, 1\n > for i=1,contents:len() do\n > check_eq(window.scr[y][x].data, contents[i], message..'/'..y..','..x)\n > x = x+1\n > if x > window.scr.w then\n > y = y+1\n > x = 1\n > end\n > end\n >end\n >\n >-- putting it all together, an example test of both keyboard and screen\n >function test_check_screen()\n > local lines = {\n > c='123',\n > d='234',\n > a='345',\n > b='456',\n > }\n > local w = window{\n > kbd=kbd('abc'),\n > scr=scr{h=3, w=5},\n > }\n > local y = 1\n > while true do\n > local b = w:getch()\n > if b == nil then break end\n > w:mvaddstr(y, 1, lines[string.char(b)])\n > y = y+1\n > end\n > check_screen(w, '345 '..\n > '456 '..\n > '123 ',\n > 'test_check_screen')\n >end\n- __teliva_timestamp: original\n check_reverse:\n >function check_reverse(window, contents, message)\n > local x, y = 1, 1\n > for i=1,contents:len() do\n > if contents[i] ~= ' ' then\n > -- hacky version while we're without bitwise operators on Lua 5.1\n >-- check(window.scr[y][x].attrs & curses.A_REVERSE, message..'/'..y..','..x)\n > check_eq(window.scr[y][x].attrs, curses.A_REVERSE, message..'/'..y..','..x)\n > else\n > -- hacky version while we're without bitwise operators on Lua 5.1\n >-- check(window.scr[y][x].attrs & (~curses.A_REVERSE), message..'/'..y..','..x)\n > check(window.scr[y][x].attrs ~= curses.A_REVERSE, message..'/'..y..','..x)\n > end\n > x = x+1\n > if x > window.scr.w then\n > y = y+1\n > x = 1\n > end\n > end\n >end\n- __teliva_timestamp: original\n check_bold:\n >function check_bold(window, contents, message)\n > local x, y = 1, 1\n > for i=1,contents:len() do\n > if contents[i] ~= ' ' then\n > -- hacky version while we're without bitwise operators on Lua 5.1\n >-- check(window.scr[y][x].attrs & curses.A_BOLD, message..'/'..y..','..x)\n > check_eq(window.scr[y][x].attrs, curses.A_BOLD, message..'/'..y..','..x)\n > else\n > -- hacky version while we're without bitwise operators on Lua 5.1\n >-- check(window.scr[y][x].attrs & (~curses.A_BOLD), message..'/'..y..','..x)\n > check(window.scr[y][x].attrs ~= curses.A_BOLD, message..'/'..y..','..x)\n > end\n > x = x+1\n > if x > window.scr.w then\n > y = y+1\n > x = 1\n > end\n > end\n >end\n- __teliva_timestamp: original\n check_color:\n >-- check which parts of a screen have the given color_pair\n >function check_color(window, cp, contents, message)\n > local x, y = 1, 1\n > for i=1,contents:len() do\n > if contents[i] ~= ' ' then\n > -- hacky version while we're without bitwise operators on Lua 5.1\n >-- check(window.scr[y][x].attrs & curses.color_pair(cp), message..'/'..y..','..x)\n > check_eq(window.scr[y][x].attrs, curses.color_pair(cp), message..'/'..y..','..x)\n > else\n > -- hacky version while we're without bitwise operators on Lua 5.1\n >-- check(window.scr[y][x].attrs & (~curses.A_BOLD), message..'/'..y..','..x)\n > check(window.scr[y][x].attrs ~= curses.color_pair(cp), message..'/'..y..','..x)\n > end\n > x = x+1\n > if x > window.scr.w then\n > y = y+1\n > x = 1\n > end\n > end\n >end\n- __teliva_timestamp: original\n sep:\n >-- horizontal separator\n >function sep(window)\n > local y, _ = window:getyx()\n > window:mvaddstr(y+1, 0, '')\n > local _, cols = window:getmaxyx()\n > for col=1,cols do\n > window:addstr('_')\n > end\n >end\n- __teliva_timestamp: original\n render:\n >function render(window)\n > window:clear()\n > -- draw stuff to screen here\n > window:attron(curses.A_BOLD)\n > window:mvaddstr(1, 5, \"example app\")\n > window:attrset(curses.A_NORMAL)\n > for i=0,15 do\n > window:attrset(curses.color_pair(i))\n > window:mvaddstr(3+i, 5, \"========================\")\n > end\n > window:refresh()\n >end\n- __teliva_timestamp: original\n update:\n >function update(window)\n > local key = window:getch()\n > -- process key here\n >end\n- __teliva_timestamp: original\n init_colors:\n >function init_colors()\n > for i=0,7 do\n > curses.init_pair(i, i, -1)\n > end\n > curses.init_pair(8, 7, 0)\n > curses.init_pair(9, 7, 1)\n > curses.init_pair(10, 7, 2)\n > curses.init_pair(11, 7, 3)\n > curses.init_pair(12, 7, 4)\n > curses.init_pair(13, 7, 5)\n > curses.init_pair(14, 7, 6)\n > curses.init_pair(15, -1, 15)\n >end\n- __teliva_timestamp: original\n main:\n >function main()\n > init_colors()\n >\n > while true do\n > render(Window)\n > update(Window)\n > end\n >end\n- __teliva_timestamp:\n >Thu Mar 17 21:21:29 2022\n program:\n >program = {lines = nil, cursor = nil}\n >-- lines: [line]\n >-- cursor: int, index into lines\n >-- line: {[word], cursor}\n >-- word: {string, cursor}\n- __teliva_timestamp:\n >Thu Mar 17 21:27:38 2022\n render:\n >function render(window)\n > local key = window:getch()\n > for row, line in ipair(program.lines) do\n > for col, word in ipair(line.words) do\n > window:addstr(word)\n > window:addstr(' ')\n > end\n > window:addstr('\\n')\n > end\n >end\n- __teliva_timestamp:\n >Thu Mar 17 21:28:39 2022\n render:\n >function render(window)\n > local key = window:getch()\n > for row, line in ipairs(program.lines) do\n > for col, word in pairs(line.words) do\n > window:addstr(word)\n > window:addstr(' ')\n > end\n > window:addstr('\\n')\n > end\n >end\n- __teliva_timestamp:\n >Thu Mar 17 21:31:33 2022\n Program:\n >Program = {\n > cursor_y = 1,\n > lines = {\n > {\n > cursor_x = 1,\n > words = {\n > {\n > cursor = 0,\n > data = '',\n > },\n > },\n > },\n > },\n >}\n >\n >\n >\n >\n >\n- __teliva_timestamp:\n >Thu Mar 17 21:32:05 2022\n render:\n >function render(window)\n > window:clear()\n > for row, line in ipairs(program.lines) do\n > for col, word in pairs(line.words) do\n > window:addstr(word)\n > window:addstr(' ')\n > end\n > window:addstr('\\n')\n > end\n > window:refresh()\n >end\n- __teliva_timestamp:\n >Thu Mar 17 21:32:22 2022\n render:\n >function render(window)\n > window:clear()\n > for row, line in ipairs(program.lines) do\n > for col, word in pairs(line.words) do\n > window:addstr(word.data)\n > window:addstr(' ')\n > end\n > window:addstr('\\n')\n > end\n > window:refresh()\n >end\n- __teliva_timestamp:\n >Thu Mar 17 21:33:00 2022\n update:\n >function update(window)\n > local key = window:getch()\n > if key == ' ' then\n > print('space')\n > window:getch()\n > end\n >end\n- __teliva_timestamp:\n >Thu Mar 17 21:33:17 2022\n update:\n >function update(window)\n > local key = window:getch()\n > if key == string.byte(' ') then\n > print('space')\n > window:getch()\n > end\n >end\n- __teliva_timestamp:\n >Thu Mar 17 21:33:31 2022\n update:\n >function update(window)\n > local key = string.char(window:getch())\n > if key == ' ' then\n > print('space')\n > window:getch()\n > end\n >end\n- __teliva_timestamp:\n >Thu Mar 17 21:36:14 2022\n __teliva_note:\n >very initial skeleton\n >- just render, no eval\n >- no stack rendering\n >- no cursor (just appends)\n update:\n >function update(window)\n > local key = string.char(window:getch())\n > if key == ' ' then\n > table.insert(program.lines[1].words, {data='', cursor=0})\n > else\n > local words = program.lines[1].words\n > words[#words].data = words[#words].data .. key\n > end\n >end\n- __teliva_timestamp:\n >Thu Mar 17 21:39:24 2022\n main:\n >function main()\n > init_colors()\n >\n > while true do\n > render(Window)\n > update(Window)\n > end\n >end\n >\n >function test_basic_render()\n > \n- __teliva_timestamp:\n >Thu Mar 17 21:43:05 2022\n main:\n >function main()\n > init_colors()\n >\n > while true do\n > render(Window, Program)\n > update(Window, Program)\n > end\n >end\n- __teliva_timestamp:\n >Thu Mar 17 21:43:11 2022\n render:\n >function render(window, program)\n > window:clear()\n > for row, line in ipairs(program.lines) do\n > for col, word in pairs(line.words) do\n > window:addstr(word.data)\n > window:addstr(' ')\n > end\n > window:addstr('\\n')\n > end\n > window:refresh()\n >end\n >\n >function test_render()\n > local w = window{\n > kbd=kbd(''),\n > scr=scr{h=3, w=5},\n > }\n >end\n- __teliva_timestamp:\n >Thu Mar 17 21:43:20 2022\n update:\n >function update(window, program, key)\n > if key == ' ' then\n > table.insert(program.lines[1].words, {data='', cursor=0})\n > else\n > local words = program.lines[1].words\n > words[#words].data = words[#words].data .. key\n > end\n >end\n- __teliva_timestamp:\n >Thu Mar 17 21:58:10 2022\n Program:\n >Program = empty_program()\n- __teliva_timestamp:\n >Thu Mar 17 21:58:10 2022\n empty_program:\n >function empty_program()\n > return {\n > cursor_y = 1,\n > lines = {\n > {\n > cursor_x = 1,\n > words = {\n > {\n > cursor = 0,\n > data = '',\n > },\n > },\n > },\n > },\n > }\n >end\n- __teliva_timestamp:\n >Thu Mar 17 22:36:24 2022\n render:\n >function render(window, program)\n > window:clear()\n > for row, line in ipairs(program.lines) do\n > for col, word in pairs(line.words) do\n > window:addstr(word.data)\n > window:addstr(' ')\n > end\n > window:addstr('\\n')\n > end\n > window:refresh()\n >end\n- __teliva_timestamp:\n >Thu Mar 17 22:41:01 2022\n __teliva_note:\n >a passing test\n main:\n >function main()\n > init_colors()\n >\n > while true do\n > render(Window, Program)\n > local key = string.char(Window:getch()) -- nodelay can't be set\n > update(Window, Program, key)\n > end\n >end\n >\n >function test_incomplete()\n > local w = window{\n > kbd=kbd('ab c'),\n > scr=scr{h=3, w=5},\n > }\n > local prog = empty_program()\n > while true do\n > render(w, prog)\n > local key = w:getch()\n > if key == nil then break end\n > update(w, prog, string.char(key))\n > end\n > check_screen(w, 'ab c '..\n > ' '..\n > ' ',\n > 'test_main_incomplete')\n >end\n- __teliva_timestamp: original\n doc:blurb:\n >A concatenative programming language with a live-updating debug UI.\n >by Kartik Agaram and Sumeet Agarwal\n >\n >Highly incomplete.\n >\n >Previous prototypes:\n > - https://archive.org/details/akkartik-2min-2020-12-06\n > - https://merveilles.town/@akkartik/105759816342173743\n"
},
{
"path": "chesstv.tlv",
"content": "# .tlv file generated by https://github.com/akkartik/teliva\n# You may edit it if you are careful; however, you may see cryptic errors if you\n# violate Teliva's assumptions.\n#\n# .tlv files are representations of Teliva programs. Teliva programs consist of\n# sequences of definitions. Each definition is a table of key/value pairs. Keys\n# and values are both strings.\n#\n# Lines in .tlv files always follow exactly one of the following forms:\n# - comment lines at the top of the file starting with '#' at column 0\n# - beginnings of definitions starting with '- ' at column 0, followed by a\n# key/value pair\n# - key/value pairs consisting of ' ' at column 0, containing either a\n# spaceless value on the same line, or a multi-line value\n# - multiline values indented by more than 2 spaces, starting with a '>'\n#\n# If these constraints are violated, Teliva may unceremoniously crash. Please\n# report bugs at http://akkartik.name/contact\n- __teliva_timestamp: original\n check:\n >function check(x, msg)\n > if x then\n > Window:addch('.')\n > else\n > print('F - '..msg)\n > print(' '..str(x)..' is false/nil')\n > teliva_num_test_failures = teliva_num_test_failures + 1\n > -- overlay first test failure on editors\n > if teliva_first_failure == nil then\n > teliva_first_failure = msg\n > end\n > end\n >end\n- __teliva_timestamp: original\n check_eq:\n >function check_eq(x, expected, msg)\n > if eq(x, expected) then\n > Window:addch('.')\n > else\n > print('F - '..msg)\n > print(' expected '..str(expected)..' but got '..str(x))\n > teliva_num_test_failures = teliva_num_test_failures + 1\n > -- overlay first test failure on editors\n > if teliva_first_failure == nil then\n > teliva_first_failure = msg\n > end\n > end\n >end\n- __teliva_timestamp: original\n eq:\n >function eq(a, b)\n > if type(a) ~= type(b) then return false end\n > if type(a) == 'table' then\n > if #a ~= #b then return false end\n > for k, v in pairs(a) do\n > if b[k] ~= v then\n > return false\n > end\n > end\n > for k, v in pairs(b) do\n > if a[k] ~= v then\n > return false\n > end\n > end\n > return true\n > end\n > return a == b\n >end\n- __teliva_timestamp: original\n str:\n >-- smarter tostring\n >-- slow; used only for debugging\n >function str(x)\n > if type(x) == 'table' then\n > local result = ''\n > result = result..#x..'{'\n > for k, v in pairs(x) do\n > result = result..str(k)..'='..str(v)..', '\n > end\n > result = result..'}'\n > return result\n > elseif type(x) == 'string' then\n > return '\"'..x..'\"'\n > end\n > return tostring(x)\n >end\n- __teliva_timestamp: original\n Window:\n >Window = curses.stdscr()\n >-- animation-based app\n >Window:nodelay(true)\n >lines, cols = Window:getmaxyx()\n- __teliva_timestamp: original\n current_game:\n >current_game = {}\n- __teliva_timestamp: original\n piece_glyph:\n >piece_glyph = {\n > -- for legibility, white pieces also use unicode glyphs for black pieces\n > -- we rely on colors to distinguish them\n > K = 0x265a,\n > Q = 0x265b,\n > R = 0x265c,\n > B = 0x265d,\n > N = 0x265e,\n > P = 0x265f,\n > k = 0x265a,\n > q = 0x265b,\n > r = 0x265c,\n > b = 0x265d,\n > n = 0x265e,\n > p = 0x265f,\n >}\n- __teliva_timestamp: original\n top_player:\n >function top_player(current_game)\n > if current_game.players[1].color == \"black\" then\n > return current_game.players[1]\n > end\n > return current_game.players[2]\n >end\n- __teliva_timestamp: original\n bottom_player:\n >function bottom_player(current_game)\n > if current_game.players[1].color == \"white\" then\n > return current_game.players[1]\n > end\n > return current_game.players[2]\n >end\n- __teliva_timestamp: original\n render_player:\n >function render_player(y, x, player)\n > Window:mvaddstr(y, x, player.user.name)\n > Window:addstr(\" · \")\n > Window:addstr(tostring(player.rating))\n >end\n- __teliva_timestamp: original\n render_square:\n >function render_square(current_game, rank, file, highlighted_squares)\n > -- decide whether to highlight\n > local hl = 0\n > if (rank == highlighted_squares.from.rank and file == highlighted_squares.from.file)\n > or (rank == highlighted_squares.to.rank and file == highlighted_squares.to.file) then\n > hl = 4\n > end\n > if (rank+file)%2 == 1 then\n > -- light square\n > Window:attrset(curses.color_pair(1+hl))\n > else\n > -- dark square\n > Window:attrset(curses.color_pair(3+hl))\n > end\n > Window:mvaddstr((8 - rank + 1)*3, file*5, \" \")\n > Window:mvaddstr((8 - rank + 1)*3+1, file*5, \" \")\n > Window:mvaddstr((8 - rank + 1)*3+2, file*5, \" \")\n > Window:attrset(curses.A_NORMAL)\n >end\n- __teliva_timestamp: original\n render_fen_rank:\n >function render_fen_rank(rank, fen_rank, highlighted_squares)\n > local file = 1\n > for x in fen_rank:gmatch(\".\") do\n > if x:match(\"%d\") then\n > file = file + tonumber(x)\n > else\n > -- decide whether to highlight\n > local hl = 0\n > if (rank == highlighted_squares.from.rank and file == highlighted_squares.from.file)\n > or (rank == highlighted_squares.to.rank and file == highlighted_squares.to.file) then\n > hl = 4\n > end\n > if (rank+file)%2 == 1 then\n > if x < 'Z' then\n > -- white piece on light square\n > Window:attrset(curses.color_pair(1+hl))\n > else\n > -- black piece on light square\n > Window:attrset(curses.color_pair(2+hl))\n > end\n > else\n > if x < 'Z' then\n > -- white piece on dark square\n > Window:attrset(curses.color_pair(3+hl))\n > else\n > -- black piece on dark square\n > Window:attrset(curses.color_pair(4+hl))\n > end\n > end\n > Window:mvaddstr((8 - rank + 1)*3+1, file*5+2, utf8(piece_glyph[x]))\n > Window:attrset(curses.A_NORMAL)\n > file = file + 1\n > end\n > end\n >end\n- __teliva_timestamp: original\n render_time:\n >function render_time(y, x, seconds)\n > if seconds == nil then return end\n > Window:mvaddstr(y, x, tostring(math.floor(seconds/60)))\n > Window:addstr(string.format(\":%02d\", seconds%60))\n >end\n- __teliva_timestamp: original\n render_board:\n >function render_board(current_game)\n >--? Window:mvaddstr(1, 50, dump(current_game.fen))\n >--? Window:mvaddstr(6, 50, dump(current_game.previously_moved_squares))\n > render_player(2, 5, top_player(current_game))\n > render_time(2, 35, current_game.bc)\n > for rank=8,1,-1 do\n > for file=1,8 do\n > render_square(current_game, rank, file, current_game.previously_moved_squares)\n > end\n > render_fen_rank(rank, current_game.fen_rank[8-rank+1], current_game.previously_moved_squares)\n > end\n > render_player(27, 5, bottom_player(current_game))\n > render_time(27, 35, current_game.wc)\n >end\n- __teliva_timestamp: original\n parse_lm:\n >function parse_lm(move)\n >--? Window:mvaddstr(4, 50, move)\n > local file1 = string.byte(move:sub(1, 1)) - 96 -- 'a'-1\n > local rank1 = string.byte(move:sub(2, 2)) - 48 -- '0'\n > local file2 = string.byte(move:sub(3, 3)) - 96 -- 'a'-1\n > local rank2 = string.byte(move:sub(4, 4)) - 48 -- '0'\n >--? Window:mvaddstr(5, 50, dump({{rank1, file1}, {rank2, file2}}))\n > return {from={rank=rank1, file=file1}, to={rank=rank2, file=file2}}\n >end\n- __teliva_timestamp: original\n render:\n >function render(chunk)\n > local o = json.decode(chunk)\n > if o.t == \"featured\" then\n > current_game = o.d\n >--? current_game.lm = \"__\"\n > current_game.previously_moved_squares = {from={rank=0, file=0}, to={rank=0, file=0}} -- no highlight\n > else\n > current_game.fen = o.d.fen\n > current_game.wc = o.d.wc\n > current_game.bc = o.d.bc\n >--? current_game.lm = o.d.lm\n > current_game.previously_moved_squares = parse_lm(o.d.lm)\n >--? Window:nodelay(false)\n >--? Window:mvaddstr(3, 50, \"paused\")\n > end\n > current_game.fen_rank = split(current_game.fen, \"%w+\")\n > render_board(current_game)\n > Window:refresh()\n >end\n- __teliva_timestamp: original\n init_colors:\n >function init_colors()\n > -- colors\n > local light_piece = 1\n > local dark_piece = 0\n > local light_square = 252\n > local dark_square = 242\n > local light_last_moved_square = 229\n > local dark_last_moved_square = 226\n > -- initialize colors\n > curses.init_pair(1, light_piece, light_square)\n > curses.init_pair(2, dark_piece, light_square)\n > curses.init_pair(3, light_piece, dark_square)\n > curses.init_pair(4, dark_piece, dark_square)\n > curses.init_pair(5, light_piece, light_last_moved_square)\n > curses.init_pair(6, dark_piece, light_last_moved_square)\n > curses.init_pair(7, light_piece, dark_last_moved_square)\n > curses.init_pair(8, dark_piece, dark_last_moved_square)\n >end\n- __teliva_timestamp: original\n main:\n >function main()\n > init_colors()\n > local request = {\n > url = \"https://lichess.org/api/tv/feed\",\n > sink = function(chunk, err)\n > if chunk then\n > Window:clear()\n > render(chunk)\n > Window:getch()\n > end\n > return 1\n > end,\n > }\n > http.request(request)\n >end\n- __teliva_timestamp: original\n utf8:\n >-- https://stackoverflow.com/questions/7983574/how-to-write-a-unicode-symbol-in-lua\n >function utf8(decimal)\n > local bytemarkers = { {0x7FF,192}, {0xFFFF,224}, {0x1FFFFF,240} }\n > if decimal<128 then return string.char(decimal) end\n > local charbytes = {}\n > for bytes,vals in ipairs(bytemarkers) do\n > if decimal<=vals[1] then\n > for b=bytes+1,2,-1 do\n > local mod = decimal%64\n > decimal = (decimal-mod)/64\n > charbytes[b] = string.char(128+mod)\n > end\n > charbytes[1] = string.char(vals[2]+decimal)\n > break\n > end\n > end\n > return table.concat(charbytes)\n >end\n- __teliva_timestamp: original\n split:\n >function split(s, pat)\n > result = {}\n > for x in s:gmatch(pat) do\n > table.insert(result, x)\n > end\n > return result\n >end\n- __teliva_timestamp: original\n dump:\n >-- https://stackoverflow.com/questions/9168058/how-to-dump-a-table-to-console\n >function dump(o)\n > if type(o) == 'table' then\n > local s = '{ '\n > for k,v in pairs(o) do\n > if type(k) ~= 'number' then k = '\"'..k..'\"' end\n > s = s .. '['..k..'] = ' .. dump(v) .. ','\n > end\n > return s .. '} '\n > else\n > return tostring(o)\n > end\n >end\n- __teliva_timestamp:\n >Sat Feb 12 18:57:02 2022\n __teliva_note:\n >better UX when app isn't permitted to access the network\n main:\n >function main()\n > init_colors()\n > local request = {\n > url = \"https://lichess.org/api/tv/feed\",\n > sink = function(chunk, err)\n > if chunk then\n > Window:clear()\n > -- main event loop is here\n > render(chunk)\n > Window:getch()\n > end\n > return 1\n > end,\n > }\n > http.request(request)\n > -- degenerate event loop just to show errors in sandboxing, etc.\n > while true do Window:getch(); end\n >end\n- __teliva_timestamp:\n >Thu Feb 17 20:00:23 2022\n doc:blurb:\n >A demo of Teliva's support for networking: watch the current live chess game from Lichess TV.\n >\n >Compare with https://lichess.org/tv on a browser.\n"
},
{
"path": "counter.tlv",
"content": "# .tlv file generated by https://github.com/akkartik/teliva\n# You may edit it if you are careful; however, you may see cryptic errors if you\n# violate Teliva's assumptions.\n#\n# .tlv files are representations of Teliva programs. Teliva programs consist of\n# sequences of definitions. Each definition is a table of key/value pairs. Keys\n# and values are both strings.\n#\n# Lines in .tlv files always follow exactly one of the following forms:\n# - comment lines at the top of the file starting with '#' at column 0\n# - beginnings of definitions starting with '- ' at column 0, followed by a\n# key/value pair\n# - key/value pairs consisting of ' ' at column 0, containing either a\n# spaceless value on the same line, or a multi-line value\n# - multiline values indented by more than 2 spaces, starting with a '>'\n#\n# If these constraints are violated, Teliva may unceremoniously crash. Please\n# report bugs at http://akkartik.name/contact\n- __teliva_timestamp: original\n check:\n >function check(x, msg)\n > if x then\n > Window:addch('.')\n > else\n > print('F - '..msg)\n > print(' '..str(x)..' is false/nil')\n > teliva_num_test_failures = teliva_num_test_failures + 1\n > -- overlay first test failure on editors\n > if teliva_first_failure == nil then\n > teliva_first_failure = msg\n > end\n > end\n >end\n- __teliva_timestamp: original\n check_eq:\n >function check_eq(x, expected, msg)\n > if eq(x, expected) then\n > Window:addch('.')\n > else\n > print('F - '..msg)\n > print(' expected '..str(expected)..' but got '..str(x))\n > teliva_num_test_failures = teliva_num_test_failures + 1\n > -- overlay first test failure on editors\n > if teliva_first_failure == nil then\n > teliva_first_failure = msg\n > end\n > end\n >end\n- __teliva_timestamp: original\n eq:\n >function eq(a, b)\n > if type(a) ~= type(b) then return false end\n > if type(a) == 'table' then\n > if #a ~= #b then return false end\n > for k, v in pairs(a) do\n > if b[k] ~= v then\n > return false\n > end\n > end\n > for k, v in pairs(b) do\n > if a[k] ~= v then\n > return false\n > end\n > end\n > return true\n > end\n > return a == b\n >end\n- __teliva_timestamp: original\n str:\n >-- smarter tostring\n >-- slow; used only for debugging\n >function str(x)\n > if type(x) == 'table' then\n > local result = ''\n > result = result..#x..'{'\n > for k, v in pairs(x) do\n > result = result..str(k)..'='..str(v)..', '\n > end\n > result = result..'}'\n > return result\n > elseif type(x) == 'string' then\n > return '\"'..x..'\"'\n > end\n > return tostring(x)\n >end\n- __teliva_timestamp: original\n Window:\n >Window = curses.stdscr()\n- __teliva_timestamp: original\n n:\n >n = 0\n- __teliva_timestamp: original\n render:\n >function render(window)\n > window:clear()\n > window:attron(curses.A_BOLD)\n > window:attron(curses.color_pair(6))\n > window:mvaddstr(10, 10, \" \")\n > window:mvaddstr(10, 11, n)\n > window:attroff(curses.color_pair(6))\n > window:attroff(curses.A_BOLD)\n > window:refresh()\n >end\n- __teliva_timestamp: original\n menu:\n >menu = {\n > {\"Enter\", \"increment\"}\n >}\n- __teliva_timestamp: original\n update:\n >function update(window)\n > local key = window:getch()\n > if key == 10 then\n > n = n+1\n > end\n >end\n- __teliva_timestamp: original\n main:\n >function main()\n > for i=1,7 do\n > curses.init_pair(i, 0, i)\n > end\n >\n > while true do\n > render(Window)\n > update(Window)\n > end\n >end\n- __teliva_timestamp:\n >Thu Feb 17 20:01:19 2022\n doc:blurb:\n >Example app: counter widget\n >\n >Look at the menu below to see what keyboard shortcuts are available.\n"
},
{
"path": "doc/contents.html",
"content": "\n\n\nTeliva Reference Manual - contents\n\n\n\n\n\n\n\n\n
\nTeliva Reference Manual\n
\n\n
\nThis reference manual for Teliva is based on the official definition of the\nLua language.\n\n
\n\nTeliva is a platform based on Lua for sandboxed software packaged with an\nenvironment for making changes to it. For a more detailed introduction, see\nthe Readme.\n\n
\nTeliva is free software, and is provided as usual with no guarantees, as\nstated in its license.\n\n
\nThis manual is based on the Lua manual. Lua features absent in Teliva should\nbe absent in this manual as well. Features added to\nTeliva above and beyond Lua will be described in text like this.\n\n
\nFor a discussion of the decisions behind the design of Lua,\nsee the technical papers available at Lua's web site.\nFor a detailed introduction to programming in Lua,\nsee Roberto's book, Programming in Lua (Second Edition).\n\n\n\n
\nThis section describes the lexis, the syntax, and the semantics of Lua.\nIn other words,\nthis section describes\nwhich tokens are valid,\nhow they can be combined,\nand what their combinations mean.\n\n\n
\nThe language constructs will be explained using the usual extended BNF notation,\nin which\n{a} means 0 or more a's, and\n[a] means an optional a.\nNon-terminals are shown like non-terminal,\nkeywords are shown like kword,\nand other terminal symbols are shown like `=´.\nThe complete syntax of Lua can be found in §8\nat the end of this manual.\n\n\n\n
\nNames\n(also called identifiers)\nin Lua can be any string of letters,\ndigits, and underscores,\nnot beginning with a digit.\nThis coincides with the definition of names in most languages.\n(The definition of letter depends on the current locale:\nany character considered alphabetic by the current locale\ncan be used in an identifier.)\nIdentifiers are used to name variables and table fields.\n\n\n
\nThe following keywords are reserved\nand cannot be used as names:\n\n\n
\n and break do else elseif\n end false for function if\n in local nil not or\n repeat return then true until while\n
\n\n
\nLua is a case-sensitive language:\nand is a reserved word, but And and AND\nare two different, valid names.\nAs a convention, names starting with an underscore followed by\nuppercase letters (such as _VERSION)\nare reserved for internal global variables used by Lua.\n\n\n
\nLiteral strings\ncan be delimited by matching single or double quotes,\nand can contain the following C-like escape sequences:\n'\\a' (bell),\n'\\b' (backspace),\n'\\f' (form feed),\n'\\n' (newline),\n'\\r' (carriage return),\n'\\t' (horizontal tab),\n'\\v' (vertical tab),\n'\\\\' (backslash),\n'\\\"' (quotation mark [double quote]),\nand '\\'' (apostrophe [single quote]).\nMoreover, a backslash followed by a real newline\nresults in a newline in the string.\nA character in a string can also be specified by its numerical value\nusing the escape sequence \\ddd,\nwhere ddd is a sequence of up to three decimal digits.\n(Note that if a numerical escape is to be followed by a digit,\nit must be expressed using exactly three digits.)\nStrings in Lua can contain any 8-bit value, including embedded zeros,\nwhich can be specified as '\\0'.\n\n\n
\nLiteral strings can also be defined using a long format\nenclosed by long brackets.\nWe define an opening long bracket of level n as an opening\nsquare bracket followed by n equal signs followed by another\nopening square bracket.\nSo, an opening long bracket of level 0 is written as [[,\nan opening long bracket of level 1 is written as [=[,\nand so on.\nA closing long bracket is defined similarly;\nfor instance, a closing long bracket of level 4 is written as ]====].\nA long string starts with an opening long bracket of any level and\nends at the first closing long bracket of the same level.\nLiterals in this bracketed form can run for several lines,\ndo not interpret any escape sequences,\nand ignore long brackets of any other level.\nThey can contain anything except a closing bracket of the proper level.\n\n\n
\nFor convenience,\nwhen the opening long bracket is immediately followed by a newline,\nthe newline is not included in the string.\nAs an example, in a system using ASCII\n(in which 'a' is coded as 97,\nnewline is coded as 10, and '1' is coded as 49),\nthe five literal strings below denote the same string:\n\n
\n a = 'alo\\n123\"'\n a = \"alo\\n123\\\"\"\n a = '\\97lo\\10\\04923\"'\n a = [[alo\n 123\"]]\n a = [==[\n alo\n 123\"]==]\n
\n\n
\nA numerical constant can be written with an optional decimal part\nand an optional decimal exponent.\nLua also accepts integer hexadecimal constants,\nby prefixing them with 0x.\nExamples of valid numerical constants are\n\n
\n 3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56\n
\n\n
\nA comment starts with a double hyphen (--)\nanywhere outside a string.\nIf the text immediately after -- is not an opening long bracket,\nthe comment is a short comment,\nwhich runs until the end of the line.\nOtherwise, it is a long comment,\nwhich runs until the corresponding closing long bracket.\nLong comments are frequently used to disable code temporarily.\n\n\n\n\n\n
\nLua is a dynamically typed language.\nThis means that\nvariables do not have types; only values do.\nThere are no type definitions in the language.\nAll values carry their own type.\n\n\n
\nAll values in Lua are first-class values.\nThis means that all values can be stored in variables,\npassed as arguments to other functions, and returned as results.\n\n\n
\nThere are eight basic types in Lua:\nnil, boolean, number,\nstring, function, userdata,\nthread, and table.\nNil is the type of the value nil,\nwhose main property is to be different from any other value;\nit usually represents the absence of a useful value.\nBoolean is the type of the values false and true.\nBoth nil and false make a condition false;\nany other value makes it true.\nNumber represents real (double-precision floating-point) numbers.\n(It is easy to build Lua interpreters that use other\ninternal representations for numbers,\nsuch as single-precision float or long integers;\nsee file luaconf.h.)\nString represents arrays of characters.\n\nLua is 8-bit clean:\nstrings can contain any 8-bit character,\nincluding embedded zeros ('\\0') (see §2.1).\n\n\n
\n
The type userdata is opaque to Teliva, and\nused by low-level code to manage details of C data stored in Lua\nvariables. Unlike Lua, Teliva doesn't support creating or managing userdata\nsince it doesn't permit extension by C libraries. This manual doesn't allude\nto userdata further.
\n\n
\nThe type thread represents independent threads of execution\nand it is used to implement coroutines (see §2.11).\nDo not confuse Lua threads with operating-system threads.\nLua supports coroutines on all systems,\neven those that do not support threads.\n\n\n
\nThe type table implements associative arrays,\nthat is, arrays that can be indexed not only with numbers,\nbut with any value (except nil).\nTables can be heterogeneous;\nthat is, they can contain values of all types (except nil).\nTables are the sole data structuring mechanism in Lua;\nthey can be used to represent ordinary arrays,\nsymbol tables, sets, records, graphs, trees, etc.\nTo represent records, Lua uses the field name as an index.\nThe language supports this representation by\nproviding a.name as syntactic sugar for a[\"name\"].\nThere are several convenient ways to create tables in Lua\n(see §2.5.7).\n\n\n
\nLike indices,\nthe value of a table field can be of any type (except nil).\nIn particular,\nbecause functions are first-class values,\ntable fields can contain functions.\nThus tables can also carry methods (see §2.5.9).\n\n\n
\nTables, functions and threads are objects:\nvariables do not actually contain these values,\nonly references to them.\nAssignment, parameter passing, and function returns\nalways manipulate references to such values;\nthese operations do not imply any kind of copy.\n\n\n
\nThe library function type returns a string describing the type\nof a given value.\n\n\n\n
\nLua provides automatic conversion between\nstring and number values at run time.\nAny arithmetic operation applied to a string tries to convert\nthis string to a number, following the usual conversion rules.\nConversely, whenever a number is used where a string is expected,\nthe number is converted to a string, in a reasonable format.\nFor complete control over how numbers are converted to strings,\nuse the format function from the string library\n(see string.format).\n\n\n\n\n\n\n\n
\nVariables are places that store values.\n\nThere are three kinds of variables in Lua:\nglobal variables, local variables, and table fields.\n\n\n
\nA single name can denote a global variable or a local variable\n(or a function's formal parameter,\nwhich is a particular kind of local variable):\n\n
\n\tvar ::= Name\n
\nName denotes identifiers, as defined in §2.1.\n\n\n
\nAny variable is assumed to be global unless explicitly declared\nas a local (see §2.4.7).\nLocal variables are lexically scoped:\nlocal variables can be freely accessed by functions\ndefined inside their scope (see §2.6).\n\n\n
\nBefore the first assignment to a variable, its value is nil.\n\n\n
\nSquare brackets are used to index a table:\n\n
\n\tvar ::= prefixexp `[´ exp `]´\n
\nThe meaning of accesses to global variables \nand table fields can be changed via metatables.\nAn access to an indexed variable t[i] is equivalent to\na call gettable_event(t,i).\n(See §2.8 for a complete description of the\ngettable_event function.\nThis function is not defined or callable in Lua.\nWe use it here only for explanatory purposes.)\n\n\n
\nThe syntax var.Name is just syntactic sugar for\nvar[\"Name\"]:\n\n
\n\tvar ::= prefixexp `.´ Name\n
\n\n
\nAll global variables live as fields in ordinary Lua tables,\ncalled environment tables or simply\nenvironments (see §2.9).\nEach function has its own reference to an environment,\nso that all global variables in this function\nwill refer to this environment table.\nWhen a function is created,\nit inherits the environment from the function that created it.\nTo get the environment table of a Lua function,\nyou call getfenv.\nTo replace it,\nyou call setfenv.\n\n\n
\nAn access to a global variable x\nis equivalent to _env.x,\nwhich in turn is equivalent to\n\n
\n gettable_event(_env, \"x\")\n
\nwhere _env is the environment of the running function.\n(See §2.8 for a complete description of the\ngettable_event function.\nThis function is not defined or callable in Lua.\nSimilarly, the _env variable is not defined in Lua.\nWe use them here only for explanatory purposes.)\n\n\n\n\n\n
\nLua supports an almost conventional set of statements,\nsimilar to those in Pascal or C.\nThis set includes\nassignments, control structures, function calls,\nand variable declarations.\n\n\n\n
\nThe unit of execution of Lua is called a chunk.\nA chunk is simply a sequence of statements,\nwhich are executed sequentially.\nEach statement can be optionally followed by a semicolon:\n\n
\n\tchunk ::= {stat [`;´]}\n
\nThere are no empty statements and thus ';;' is not legal.\n\n\n
\nLua handles a chunk as the body of an anonymous function \nwith a variable number of arguments\n(see §2.5.9).\nAs such, chunks can define local variables,\nreceive arguments, and return values.\n\n\n
\nA chunk can be stored in a file or in a string inside the host program.\nTo execute a chunk,\nLua first pre-compiles the chunk into instructions for a virtual machine,\nand then it executes the compiled code\nwith an interpreter for the virtual machine.\n\n\n
\nChunks can also be pre-compiled into binary form;\nsee program luac for details.\nPrograms in source and compiled forms are interchangeable;\nLua automatically detects the file type and acts accordingly.\n\n\n\n\n\n\n
\nA block is a list of statements;\nsyntactically, a block is the same as a chunk:\n\n
\n\tblock ::= chunk\n
\n\n
\nA block can be explicitly delimited to produce a single statement:\n\n
\n\tstat ::= do block end\n
\nExplicit blocks are useful\nto control the scope of variable declarations.\nExplicit blocks are also sometimes used to\nadd a return or break statement in the middle\nof another block (see §2.4.4).\n\n\n\n\n\n
\nLua allows multiple assignments.\nTherefore, the syntax for assignment\ndefines a list of variables on the left side\nand a list of expressions on the right side.\nThe elements in both lists are separated by commas:\n\n
\nBefore the assignment,\nthe list of values is adjusted to the length of\nthe list of variables.\nIf there are more values than needed,\nthe excess values are thrown away.\nIf there are fewer values than needed,\nthe list is extended with as many nil's as needed.\nIf the list of expressions ends with a function call,\nthen all values returned by that call enter the list of values,\nbefore the adjustment\n(except when the call is enclosed in parentheses; see §2.5).\n\n\n
\nThe assignment statement first evaluates all its expressions\nand only then are the assignments performed.\nThus the code\n\n
\n i = 3\n i, a[i] = i+1, 20\n
\nsets a[3] to 20, without affecting a[4]\nbecause the i in a[i] is evaluated (to 3)\nbefore it is assigned 4.\nSimilarly, the line\n\n
\n x, y = y, x\n
\nexchanges the values of x and y,\nand\n\n
\n x, y, z = y, z, x\n
\ncyclically permutes the values of x, y, and z.\n\n\n
\nThe meaning of assignments to global variables\nand table fields can be changed via metatables.\nAn assignment to an indexed variable t[i] = val is equivalent to\nsettable_event(t,i,val).\n(See §2.8 for a complete description of the\nsettable_event function.\nThis function is not defined or callable in Lua.\nWe use it here only for explanatory purposes.)\n\n\n
\nAn assignment to a global variable x = val\nis equivalent to the assignment\n_env.x = val,\nwhich in turn is equivalent to\n\n
\n settable_event(_env, \"x\", val)\n
\nwhere _env is the environment of the running function.\n(The _env variable is not defined in Lua.\nWe use it here only for explanatory purposes.)\n\n\n\n\n\n
\nThe control structures\nif, while, and repeat have the usual meaning and\nfamiliar syntax:\n\n\n\n\n
\n\tstat ::= while exp do block end\n\tstat ::= repeat block until exp\n\tstat ::= if exp then block {elseif exp then block} [else block] end\n
\nLua also has a for statement, in two flavors (see §2.4.5).\n\n\n
\nThe condition expression of a\ncontrol structure can return any value.\nBoth false and nil are considered false.\nAll values different from nil and false are considered true\n(in particular, the number 0 and the empty string are also true).\n\n\n
\nIn the repeat–until loop,\nthe inner block does not end at the until keyword,\nbut only after the condition.\nSo, the condition can refer to local variables\ndeclared inside the loop block.\n\n\n
\nThe return statement is used to return values\nfrom a function or a chunk (which is just a function).\n\nFunctions and chunks can return more than one value,\nand so the syntax for the return statement is\n\n
\n\tstat ::= return [explist]\n
\n\n
\nThe break statement is used to terminate the execution of a\nwhile, repeat, or for loop,\nskipping to the next statement after the loop:\n\n\n
\n\tstat ::= break\n
\nA break ends the innermost enclosing loop.\n\n\n
\nThe return and break\nstatements can only be written as the last statement of a block.\nIf it is really necessary to return or break in the\nmiddle of a block,\nthen an explicit inner block can be used,\nas in the idioms\ndo return end and do break end,\nbecause now return and break are the last statements in\ntheir (inner) blocks.\n\n\n\n\n\n
\n\nThe for statement has two forms:\none numeric and one generic.\n\n\n
\nThe numeric for loop repeats a block of code while a\ncontrol variable runs through an arithmetic progression.\nIt has the following syntax:\n\n
\n\tstat ::= for Name `=´ exp `,´ exp [`,´ exp] do block end\n
\nThe block is repeated for name starting at the value of\nthe first exp, until it passes the second exp by steps of the\nthird exp.\nMore precisely, a for statement like\n\n
\n for v = e1, e2, e3 do block end\n
\nis equivalent to the code:\n\n
\n do\n local var, limit, step = tonumber(e1), tonumber(e2), tonumber(e3)\n if not (var and limit and step) then error() end\n while (step > 0 and var <= limit) or (step <= 0 and var >= limit) do\n local v = var\n block\n var = var + step\n end\n end\n
\nNote the following:\n\n
\n\n
\nAll three control expressions are evaluated only once,\nbefore the loop starts.\nThey must all result in numbers.\n
\n\n
\nvar, limit, and step are invisible variables.\nThe names shown here are for explanatory purposes only.\n
\n\n
\nIf the third expression (the step) is absent,\nthen a step of 1 is used.\n
\n\n
\nYou can use break to exit a for loop.\n
\n\n
\nThe loop variable v is local to the loop;\nyou cannot use its value after the for ends or is broken.\nIf you need this value,\nassign it to another variable before breaking or exiting the loop.\n
\n\n
\n\n
\nThe generic for statement works over functions,\ncalled iterators.\nOn each iteration, the iterator function is called to produce a new value,\nstopping when this new value is nil.\nThe generic for loop has the following syntax:\n\n
\n\tstat ::= for namelist in explist do block end\n\tnamelist ::= Name {`,´ Name}\n
\nA for statement like\n\n
\n for var_1, ···, var_n in explist do block end\n
\nis equivalent to the code:\n\n
\n do\n local f, s, var = explist\n while true do\n local var_1, ···, var_n = f(s, var)\n var = var_1\n if var == nil then break end\n block\n end\n end\n
\nNote the following:\n\n
\n\n
\nexplist is evaluated only once.\nIts results are an iterator function,\na state,\nand an initial value for the first iterator variable.\n
\n\n
\nf, s, and var are invisible variables.\nThe names are here for explanatory purposes only.\n
\n\n
\nYou can use break to exit a for loop.\n
\n\n
\nThe loop variables var_i are local to the loop;\nyou cannot use their values after the for ends.\nIf you need these values,\nthen assign them to other variables before breaking or exiting the loop.\n
\nLocal variables can be declared anywhere inside a block.\nThe declaration can include an initial assignment:\n\n
\n\tstat ::= local namelist [`=´ explist]\n
\nIf present, an initial assignment has the same semantics\nof a multiple assignment (see §2.4.3).\nOtherwise, all variables are initialized with nil.\n\n\n
\nA chunk is also a block (see §2.4.1),\nand so local variables can be declared in a chunk outside any explicit block.\nThe scope of such local variables extends until the end of the chunk.\n\n\n
\nThe visibility rules for local variables are explained in §2.6.\n\n\n\n\n\n\n\n
\nNumbers and literal strings are explained in §2.1;\nvariables are explained in §2.3;\nfunction definitions are explained in §2.5.9;\nfunction calls are explained in §2.5.8;\ntable constructors are explained in §2.5.7.\nVararg expressions,\ndenoted by three dots ('...'), can only be used when\ndirectly inside a vararg function;\nthey are explained in §2.5.9.\n\n\n
\nBinary operators comprise arithmetic operators (see §2.5.1),\nrelational operators (see §2.5.2), logical operators (see §2.5.3),\nand the concatenation operator (see §2.5.4).\nUnary operators comprise the unary minus (see §2.5.1),\nthe unary not (see §2.5.3),\nand the unary length operator (see §2.5.5).\n\n\n
\nBoth function calls and vararg expressions can result in multiple values.\nIf an expression is used as a statement\n(only possible for function calls (see §2.4.6)),\nthen its return list is adjusted to zero elements,\nthus discarding all returned values.\nIf an expression is used as the last (or the only) element\nof a list of expressions,\nthen no adjustment is made\n(unless the call is enclosed in parentheses).\nIn all other contexts,\nLua adjusts the result list to one element,\ndiscarding all values except the first one.\n\n\n
\nHere are some examples:\n\n
\n f() -- adjusted to 0 results\n g(f(), x) -- f() is adjusted to 1 result\n g(x, f()) -- g gets x plus all results from f()\n a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil)\n a,b = ... -- a gets the first vararg parameter, b gets\n -- the second (both a and b can get nil if there\n -- is no corresponding vararg parameter)\n \n a,b,c = x, f() -- f() is adjusted to 2 results\n a,b,c = f() -- f() is adjusted to 3 results\n return f() -- returns all results from f()\n return ... -- returns all received vararg parameters\n return x,y,f() -- returns x, y, and all results from f()\n {f()} -- creates a list with all results from f()\n {...} -- creates a list with all vararg parameters\n {f(), nil} -- f() is adjusted to 1 result\n
\n\n
\nAny expression enclosed in parentheses always results in only one value.\nThus,\n(f(x,y,z)) is always a single value,\neven if f returns several values.\n(The value of (f(x,y,z)) is the first value returned by f\nor nil if f does not return any values.)\n\n\n\n
\nLua supports the usual arithmetic operators:\nthe binary + (addition),\n- (subtraction), * (multiplication),\n/ (division), % (modulo), and ^ (exponentiation);\nand unary - (negation).\nIf the operands are numbers, or strings that can be converted to\nnumbers (see §2.2.1),\nthen all operations have the usual meaning.\nExponentiation works for any exponent.\nFor instance, x^(-0.5) computes the inverse of the square root of x.\nModulo is defined as\n\n
\n a % b == a - math.floor(a/b)*b\n
\nThat is, it is the remainder of a division that rounds\nthe quotient towards minus infinity.\n\n\n\n\n\n
\nThese operators always result in false or true.\n\n\n
\nEquality (==) first compares the type of its operands.\nIf the types are different, then the result is false.\nOtherwise, the values of the operands are compared.\nNumbers and strings are compared in the usual way.\nObjects (tables, threads, and functions)\nare compared by reference:\ntwo objects are considered equal only if they are the same object.\nEvery time you create a new object\n(a table, thread, or function),\nthis new object is different from any previously existing object.\n\n\n
\nYou can change the way that Lua compares tables by using the \"eq\" metamethod\n(see §2.8).\n\n\n
\nThe conversion rules of §2.2.1\ndo not apply to equality comparisons.\nThus, \"0\"==0 evaluates to false,\nand t[0] and t[\"0\"] denote different\nentries in a table.\n\n\n
\nThe operator ~= is exactly the negation of equality (==).\n\n\n
\nThe order operators work as follows.\nIf both arguments are numbers, then they are compared as such.\nOtherwise, if both arguments are strings,\nthen their values are compared according to the current locale.\nOtherwise, Lua tries to call the \"lt\" or the \"le\"\nmetamethod (see §2.8).\nA comparison a > b is translated to b < a\nand a >= b is translated to b <= a.\n\n\n\n\n\n
\nThe logical operators in Lua are\nand, or, and not.\nLike the control structures (see §2.4.4),\nall logical operators consider both false and nil as false\nand anything else as true.\n\n\n
\nThe negation operator not always returns false or true.\nThe conjunction operator and returns its first argument\nif this value is false or nil;\notherwise, and returns its second argument.\nThe disjunction operator or returns its first argument\nif this value is different from nil and false;\notherwise, or returns its second argument.\nBoth and and or use short-cut evaluation;\nthat is,\nthe second operand is evaluated only if necessary.\nHere are some examples:\n\n
\n 10 or 20 --> 10\n 10 or error() --> 10\n nil or \"a\" --> \"a\"\n nil and 10 --> nil\n false and error() --> false\n false and nil --> false\n false or nil --> nil\n 10 and 20 --> 20\n
\n(In this manual,\n--> indicates the result of the preceding expression.)\n\n\n\n\n\n
\nThe string concatenation operator in Lua is\ndenoted by two dots ('..').\nIf both operands are strings or numbers, then they are converted to\nstrings according to the rules mentioned in §2.2.1.\nOtherwise, the \"concat\" metamethod is called (see §2.8).\n\n\n\n\n\n
\nThe length operator is denoted by the unary operator #.\nThe length of a string is its number of bytes\n(that is, the usual meaning of string length when each\ncharacter is one byte).\n\n\n
\nThe length of a table t is defined to be any\ninteger index n\nsuch that t[n] is not nil and t[n+1] is nil;\nmoreover, if t[1] is nil, n can be zero.\nFor a regular array, with non-nil values from 1 to a given n,\nits length is exactly that n,\nthe index of its last value.\nIf the array has \"holes\"\n(that is, nil values between other non-nil values),\nthen #t can be any of the indices that\ndirectly precedes a nil value\n(that is, it may consider any such nil value as the end of\nthe array). \n\n\n\n\n\n
\nAs usual,\nyou can use parentheses to change the precedences of an expression.\nThe concatenation ('..') and exponentiation ('^')\noperators are right associative.\nAll other binary operators are left associative.\n\n\n\n\n\n
\nTable constructors are expressions that create tables.\nEvery time a constructor is evaluated, a new table is created.\nA constructor can be used to create an empty table\nor to create a table and initialize some of its fields.\nThe general syntax for constructors is\n\n
\nEach field of the form [exp1] = exp2 adds to the new table an entry\nwith key exp1 and value exp2.\nA field of the form name = exp is equivalent to\n[\"name\"] = exp.\nFinally, fields of the form exp are equivalent to\n[i] = exp, where i are consecutive numerical integers,\nstarting with 1.\nFields in the other formats do not affect this counting.\nFor example,\n\n
\n a = { [f(1)] = g; \"x\", \"y\"; x = 1, f(x), [30] = 23; 45 }\n
\nIf the last field in the list has the form exp\nand the expression is a function call or a vararg expression,\nthen all values returned by this expression enter the list consecutively\n(see §2.5.8).\nTo avoid this,\nenclose the function call or the vararg expression\nin parentheses (see §2.5).\n\n\n
\nThe field list can have an optional trailing separator,\nas a convenience for machine-generated code.\n\n\n\n\n\n
\nA function call in Lua has the following syntax:\n\n
\n\tfunctioncall ::= prefixexp args\n
\nIn a function call,\nfirst prefixexp and args are evaluated.\nIf the value of prefixexp has type function,\nthen this function is called\nwith the given arguments.\nOtherwise, the prefixexp \"call\" metamethod is called,\nhaving as first parameter the value of prefixexp,\nfollowed by the original call arguments\n(see §2.8).\n\n\n
\nThe form\n\n
\n\tfunctioncall ::= prefixexp `:´ Name args\n
\ncan be used to call \"methods\".\nA call v:name(args)\nis syntactic sugar for v.name(v,args),\nexcept that v is evaluated only once.\n\n\n
\nAll argument expressions are evaluated before the call.\nA call of the form f{fields} is\nsyntactic sugar for f({fields});\nthat is, the argument list is a single new table.\nA call of the form f'string'\n(or f\"string\" or f[[string]])\nis syntactic sugar for f('string');\nthat is, the argument list is a single literal string.\n\n\n
\nAs an exception to the free-format syntax of Lua,\nyou cannot put a line break before the '(' in a function call.\nThis restriction avoids some ambiguities in the language.\nIf you write\n\n
\n a = f\n (g).x(a)\n
\nLua would see that as a single statement, a = f(g).x(a).\nSo, if you want two statements, you must add a semi-colon between them.\nIf you actually want to call f,\nyou must remove the line break before (g).\n\n\n
\nA call of the form returnfunctioncall is called\na tail call.\nLua implements proper tail calls\n(or proper tail recursion):\nin a tail call,\nthe called function reuses the stack entry of the calling function.\nTherefore, there is no limit on the number of nested tail calls that\na program can execute.\nHowever, a tail call erases any debug information about the\ncalling function.\nNote that a tail call only happens with a particular syntax,\nwhere the return has one single function call as argument;\nthis syntax makes the calling function return exactly\nthe returns of the called function.\nSo, none of the following examples are tail calls:\n\n
\n return (f(x)) -- results adjusted to 1\n return 2 * f(x)\n return x, f(x) -- additional results\n f(x); return -- results discarded\n return x or f(x) -- results adjusted to 1\n
\n\tfunction ::= function funcbody\n\tfuncbody ::= `(´ [parlist] `)´ block end\n
\n\n
\nThe following syntactic sugar simplifies function definitions:\n\n
\n\tstat ::= function funcname funcbody\n\tstat ::= localfunction Name funcbody\n\tfuncname ::= Name {`.´ Name} [`:´ Name]\n
\nThe statement\n\n
\n function f () body end\n
\ntranslates to\n\n
\n f = function () body end\n
\nThe statement\n\n
\n function t.a.b.c.f () body end\n
\ntranslates to\n\n
\n t.a.b.c.f = function () body end\n
\nThe statement\n\n
\n local function f () body end\n
\ntranslates to\n\n
\n local f; f = function () body end\n
\nnot to\n\n
\n local f = function () body end\n
\n(This only makes a difference when the body of the function\ncontains references to f.)\n\n\n
\nA function definition is an executable expression,\nwhose value has type function.\nWhen Lua pre-compiles a chunk,\nall its function bodies are pre-compiled too.\nThen, whenever Lua executes the function definition,\nthe function is instantiated (or closed).\nThis function instance (or closure)\nis the final value of the expression.\nDifferent instances of the same function\ncan refer to different external local variables\nand can have different environment tables.\n\n\n
\nParameters act as local variables that are\ninitialized with the argument values:\n\n
\n\tparlist ::= namelist [`,´ `...´] | `...´\n
\nWhen a function is called,\nthe list of arguments is adjusted to\nthe length of the list of parameters,\nunless the function is a variadic or vararg function,\nwhich is\nindicated by three dots ('...') at the end of its parameter list.\nA vararg function does not adjust its argument list;\ninstead, it collects all extra arguments and supplies them\nto the function through a vararg expression,\nwhich is also written as three dots.\nThe value of this expression is a list of all actual extra arguments,\nsimilar to a function with multiple results.\nIf a vararg expression is used inside another expression\nor in the middle of a list of expressions,\nthen its return list is adjusted to one element.\nIf the expression is used as the last element of a list of expressions,\nthen no adjustment is made\n(unless that last expression is enclosed in parentheses).\n\n\n
\nAs an example, consider the following definitions:\n\n
\n function f(a, b) end\n function g(a, b, ...) end\n function r() return 1,2,3 end\n
\nThen, we have the following mapping from arguments to parameters and\nto the vararg expression:\n\n
\nResults are returned using the return statement (see §2.4.4).\nIf control reaches the end of a function\nwithout encountering a return statement,\nthen the function returns with no results.\n\n\n
\nThe colon syntax\nis used for defining methods,\nthat is, functions that have an implicit extra parameter self.\nThus, the statement\n\n
\n\nLua is a lexically scoped language.\nThe scope of variables begins at the first statement after\ntheir declaration and lasts until the end of the innermost block that\nincludes the declaration.\nConsider the following example:\n\n
\n x = 10 -- global variable\n do -- new block\n local x = x -- new 'x', with value 10\n print(x) --> 10\n x = x+1\n do -- another block\n local x = x+1 -- another 'x'\n print(x) --> 12\n end\n print(x) --> 11\n end\n print(x) --> 10 (the global one)\n
\n\n
\nNotice that, in a declaration like local x = x,\nthe new x being declared is not in scope yet,\nand so the second x refers to the outside variable.\n\n\n
\nBecause of the lexical scoping rules,\nlocal variables can be freely accessed by functions\ndefined inside their scope.\nA local variable used by an inner function is called\nan upvalue, or external local variable,\ninside the inner function.\n\n\n
\nNotice that each execution of a local statement\ndefines new local variables.\nConsider the following example:\n\n
\n a = {}\n local x = 20\n for i=1,10 do\n local y = 0\n a[i] = function () y=y+1; return x+y end\n end\n
\nThe loop creates ten closures\n(that is, ten instances of the anonymous function).\nEach of these closures uses a different y variable,\nwhile all of them share the same x.\n\n\n\n\n\n
\nErrors returned by Teliva code should display on screen in red. Please report\ncrashes or other behavior.\n
\n\n\n
\nLua code can explicitly generate an error by calling the\nerror function.\nIf you need to catch errors in Lua,\nyou can use the pcall function.\n\n\n\n\n\n
\nEvery value in Lua can have a metatable.\nThis metatable is an ordinary Lua table\nthat defines the behavior of the original value\nunder certain special operations.\nYou can change several aspects of the behavior\nof operations over a value by setting specific fields in its metatable.\nFor instance, when a non-numeric value is the operand of an addition,\nLua checks for a function in the field \"__add\" in its metatable.\nIf it finds one,\nLua calls this function to perform the addition.\n\n\n
\nWe call the keys in a metatable events\nand the values metamethods.\nIn the previous example, the event is \"add\" \nand the metamethod is the function that performs the addition.\n\n\n
\nYou can query the metatable of any value\nthrough the getmetatable function.\n\n\n
\nYou can replace the metatable of tables\nthrough the setmetatable\nfunction.\n\n\n
\nTables have individual metatables\n(although multiple tables can share their metatables).\nValues of all other types share one single metatable per type;\nthat is, there is one single metatable for all numbers,\none for all strings, etc.\n\n\n
\nA metatable controls how an object behaves in arithmetic operations,\norder comparisons, concatenation, length operation, and indexing.\nFor each of these operations Lua associates a specific key\ncalled an event.\nWhen Lua performs one of these operations over a value,\nit checks whether this value has a metatable with the corresponding event.\nIf so, the value associated with that key (the metamethod)\ncontrols how Lua will perform the operation.\n\n\n
\nMetatables control the operations listed next.\nEach operation is identified by its corresponding name.\nThe key for each operation is a string with its name prefixed by\ntwo underscores, '__';\nfor instance, the key for operation \"add\" is the\nstring \"__add\".\nThe semantics of these operations is better explained by a Lua function\ndescribing how the interpreter executes the operation.\n\n\n
\nThe code shown here in Lua is only illustrative;\nthe real behavior is hard coded in the interpreter\nand it is much more efficient than this simulation.\nAll functions used in these descriptions\n(rawget, tonumber, etc.)\nare described in §5.1.\nIn particular, to retrieve the metamethod of a given object,\nwe use the expression\n\n
\n metatable(obj)[event]\n
\nThis should be read as\n\n
\n rawget(getmetatable(obj) or {}, event)\n
\n\nThat is, the access to a metamethod does not invoke other metamethods,\nand the access to objects with no metatables does not fail\n(it simply results in nil).\n\n\n\n
\n\n
\"add\":\nthe + operation.\n\n\n\n
\nThe function getbinhandler below defines how Lua chooses a handler\nfor a binary operation.\nFirst, Lua tries the first operand.\nIf its type does not define a handler for the operation,\nthen Lua tries the second operand.\n\n
\n function getbinhandler (op1, op2, event)\n return metatable(op1)[event] or metatable(op2)[event]\n end\n
\nBy using this function,\nthe behavior of the op1 + op2 is\n\n
\n function add_event (op1, op2)\n local o1, o2 = tonumber(op1), tonumber(op2)\n if o1 and o2 then -- both operands are numeric?\n return o1 + o2 -- '+' here is the primitive 'add'\n else -- at least one of the operands is not numeric\n local h = getbinhandler(op1, op2, \"__add\")\n if h then\n -- call the handler with both operands\n return (h(op1, op2))\n else -- no handler available: default behavior\n error(···)\n end\n end\n end\n
\n
\n\n
\"sub\":\nthe - operation.\n\nBehavior similar to the \"add\" operation.\n
\n\n
\"mul\":\nthe * operation.\n\nBehavior similar to the \"add\" operation.\n
\n\n
\"div\":\nthe / operation.\n\nBehavior similar to the \"add\" operation.\n
\n\n
\"mod\":\nthe % operation.\n\nBehavior similar to the \"add\" operation,\nwith the operation\no1 - floor(o1/o2)*o2 as the primitive operation.\n
\n\n
\"pow\":\nthe ^ (exponentiation) operation.\n\nBehavior similar to the \"add\" operation,\nwith the function pow (from the C math library)\nas the primitive operation.\n
\n\n
\"unm\":\nthe unary - operation.\n\n\n
\n function unm_event (op)\n local o = tonumber(op)\n if o then -- operand is numeric?\n return -o -- '-' here is the primitive 'unm'\n else -- the operand is not numeric.\n -- Try to get a handler from the operand\n local h = metatable(op).__unm\n if h then\n -- call the handler with the operand\n return (h(op))\n else -- no handler available: default behavior\n error(···)\n end\n end\n end\n
\n function concat_event (op1, op2)\n if (type(op1) == \"string\" or type(op1) == \"number\") and\n (type(op2) == \"string\" or type(op2) == \"number\") then\n return op1 .. op2 -- primitive string concatenation\n else\n local h = getbinhandler(op1, op2, \"__concat\")\n if h then\n return (h(op1, op2))\n else\n error(···)\n end\n end\n end\n
\n
\n\n
\"len\":\nthe # operation.\n\n\n
\n function len_event (op)\n if type(op) == \"string\" then\n return strlen(op) -- primitive string length\n elseif type(op) == \"table\" then\n return #op -- primitive table length\n else\n local h = metatable(op).__len\n if h then\n -- call the handler with the operand\n return (h(op))\n else -- no handler available: default behavior\n error(···)\n end\n end\n end\n
\nSee §2.5.5 for a description of the length of a table.\n
\n\n
\"eq\":\nthe == operation.\n\nThe function getcomphandler defines how Lua chooses a metamethod\nfor comparison operators.\nA metamethod only is selected when both objects\nbeing compared have the same type\nand the same metamethod for the selected operation.\n\n
\n function getcomphandler (op1, op2, event)\n if type(op1) ~= type(op2) then return nil end\n local mm1 = metatable(op1)[event]\n local mm2 = metatable(op2)[event]\n if mm1 == mm2 then return mm1 else return nil end\n end\n
\nThe \"eq\" event is defined as follows:\n\n
\n function eq_event (op1, op2)\n if type(op1) ~= type(op2) then -- different types?\n return false -- different objects\n end\n if op1 == op2 then -- primitive equal?\n return true -- objects are equal\n end\n -- try metamethod\n local h = getcomphandler(op1, op2, \"__eq\")\n if h then\n return (h(op1, op2))\n else\n return false\n end\n end\n
\na ~= b is equivalent to not (a == b).\n
\n\n
\"lt\":\nthe < operation.\n\n\n
\n function lt_event (op1, op2)\n if type(op1) == \"number\" and type(op2) == \"number\" then\n return op1 < op2 -- numeric comparison\n elseif type(op1) == \"string\" and type(op2) == \"string\" then\n return op1 < op2 -- lexicographic comparison\n else\n local h = getcomphandler(op1, op2, \"__lt\")\n if h then\n return (h(op1, op2))\n else\n error(···)\n end\n end\n end\n
\na > b is equivalent to b < a.\n
\n\n
\"le\":\nthe <= operation.\n\n\n
\n function le_event (op1, op2)\n if type(op1) == \"number\" and type(op2) == \"number\" then\n return op1 <= op2 -- numeric comparison\n elseif type(op1) == \"string\" and type(op2) == \"string\" then\n return op1 <= op2 -- lexicographic comparison\n else\n local h = getcomphandler(op1, op2, \"__le\")\n if h then\n return (h(op1, op2))\n else\n h = getcomphandler(op1, op2, \"__lt\")\n if h then\n return not h(op2, op1)\n else\n error(···)\n end\n end\n end\n end\n
\na >= b is equivalent to b <= a.\nNote that, in the absence of a \"le\" metamethod,\nLua tries the \"lt\", assuming that a <= b is\nequivalent to not (b < a).\n
\n\n
\"index\":\nThe indexing access table[key].\n\n\n
\n function gettable_event (table, key)\n local h\n if type(table) == \"table\" then\n local v = rawget(table, key)\n if v ~= nil then return v end\n h = metatable(table).__index\n if h == nil then return nil end\n else\n h = metatable(table).__index\n if h == nil then\n error(···)\n end\n end\n if type(h) == \"function\" then\n return (h(table, key)) -- call the handler\n else return h[key] -- or repeat operation on it\n end\n end\n
\n function settable_event (table, key, value)\n local h\n if type(table) == \"table\" then\n local v = rawget(table, key)\n if v ~= nil then rawset(table, key, value); return end\n h = metatable(table).__newindex\n if h == nil then rawset(table, key, value); return end\n else\n h = metatable(table).__newindex\n if h == nil then\n error(···)\n end\n end\n if type(h) == \"function\" then\n h(table, key,value) -- call the handler\n else h[key] = value -- or repeat operation on it\n end\n end\n
\n
\n\n
\"call\":\ncalled when Lua calls a value.\n\n\n
\n function function_event (func, ...)\n if type(func) == \"function\" then\n return func(...) -- primitive call\n else\n local h = metatable(func).__call\n if h then\n return h(func, ...)\n else\n error(···)\n end\n end\n end\n
\nBesides metatables, objects of types thread and function\nhave another table associated with them, called their\nenvironment.\nLike metatables, environments are regular tables and\nmultiple objects can share the same environment.\n\n\n
\nThreads are created sharing the environment of the creating thread.\nNested Lua functions are created sharing the environment of\nthe creating Lua function.\n\n\n
\nEnvironments associated with threads are called\nglobal environments.\nThey are used as the default environment for threads.\n\n\n
\nEnvironments associated with Lua functions are used to resolve\nall accesses to global variables within the function (see §2.3).\nThey are used as the default environment for nested Lua functions\ncreated by the function.\n\n\n
\nYou can change the environment of a Lua function or the\nrunning thread by calling setfenv.\nYou can get the environment of a Lua function or the running thread\nby calling getfenv.\n\n\n\n\n\n
\nLua performs automatic memory management.\nThis means that\nyou have to worry neither about allocating memory for new objects\nnor about freeing it when the objects are no longer needed.\nLua manages memory automatically by running\na garbage collector from time to time\nto collect all dead objects\n(that is, objects that are no longer accessible from Lua).\nAll memory used by Lua is subject to automatic management:\ntables, functions, threads, strings, etc.\n\n\n
\nLua implements an incremental mark-and-sweep collector.\nIt uses two numbers to control its garbage-collection cycles:\nthe garbage-collector pause and\nthe garbage-collector step multiplier.\nBoth use percentage points as units\n(so that a value of 100 means an internal value of 1).\n\n\n
\nThe garbage-collector pause\ncontrols how long the collector waits before starting a new cycle.\nLarger values make the collector less aggressive.\nValues smaller than 100 mean the collector will not wait to\nstart a new cycle.\nA value of 200 means that the collector waits for the total memory in use\nto double before starting a new cycle.\n\n\n
\nThe step multiplier\ncontrols the relative speed of the collector relative to\nmemory allocation.\nLarger values make the collector more aggressive but also increase\nthe size of each incremental step.\nValues smaller than 100 make the collector too slow and\ncan result in the collector never finishing a cycle.\nThe default, 200, means that the collector runs at \"twice\"\nthe speed of memory allocation.\n\n\n
\n
Modifying these parameters requires changes to Teliva's C\nsources.
\nA weak table is a table whose elements are\nweak references.\nA weak reference is ignored by the garbage collector.\nIn other words,\nif the only references to an object are weak references,\nthen the garbage collector will collect this object.\n\n\n
\nA weak table can have weak keys, weak values, or both.\nA table with weak keys allows the collection of its keys,\nbut prevents the collection of its values.\nA table with both weak keys and weak values allows the collection of\nboth keys and values.\nIn any case, if either the key or the value is collected,\nthe whole pair is removed from the table.\nThe weakness of a table is controlled by the\n__mode field of its metatable.\nIf the __mode field is a string containing the character 'k',\nthe keys in the table are weak.\nIf __mode contains 'v',\nthe values in the table are weak.\n\n\n
\nAfter you use a table as a metatable,\nyou should not change the value of its __mode field.\nOtherwise, the weak behavior of the tables controlled by this\nmetatable is undefined.\n\n\n\n\n\n\n\n
\nLua supports coroutines,\nalso called collaborative multithreading.\nA coroutine in Lua represents an independent thread of execution.\nUnlike threads in multithread systems, however,\na coroutine only suspends its execution by explicitly calling\na yield function.\n\n\n
\nYou create a coroutine with a call to coroutine.create.\nIts sole argument is a function\nthat is the main function of the coroutine.\nThe create function only creates a new coroutine and\nreturns a handle to it (an object of type thread);\nit does not start the coroutine execution.\n\n\n
\nWhen you first call coroutine.resume,\npassing as its first argument\na thread returned by coroutine.create,\nthe coroutine starts its execution,\nat the first line of its main function.\nExtra arguments passed to coroutine.resume are passed on\nto the coroutine main function.\nAfter the coroutine starts running,\nit runs until it terminates or yields.\n\n\n
\nA coroutine can terminate its execution in two ways:\nnormally, when its main function returns\n(explicitly or implicitly, after the last instruction);\nand abnormally, if there is an unprotected error.\nIn the first case, coroutine.resume returns true,\nplus any values returned by the coroutine main function.\nIn case of errors, coroutine.resume returns false\nplus an error message.\n\n\n
\nA coroutine yields by calling coroutine.yield.\nWhen a coroutine yields,\nthe corresponding coroutine.resume returns immediately,\neven if the yield happens inside nested function calls\n(that is, not in the main function,\nbut in a function directly or indirectly called by the main function).\nIn the case of a yield, coroutine.resume also returns true,\nplus any values passed to coroutine.yield.\nThe next time you resume the same coroutine,\nit continues its execution from the point where it yielded,\nwith the call to coroutine.yield returning any extra\narguments passed to coroutine.resume.\n\n\n
\nLike coroutine.create,\nthe coroutine.wrap function also creates a coroutine,\nbut instead of returning the coroutine itself,\nit returns a function that, when called, resumes the coroutine.\nAny arguments passed to this function\ngo as extra arguments to coroutine.resume.\ncoroutine.wrap returns all the values returned by coroutine.resume,\nexcept the first one (the boolean error code).\nUnlike coroutine.resume,\ncoroutine.wrap does not catch errors;\nany error is propagated to the caller.\n\n\n
\nAs an example,\nconsider the following code:\n\n
\n function foo (a)\n print(\"foo\", a)\n return coroutine.yield(2*a)\n end\n \n co = coroutine.create(function (a,b)\n print(\"co-body\", a, b)\n local r = foo(a+1)\n print(\"co-body\", r)\n local r, s = coroutine.yield(a+b, a-b)\n print(\"co-body\", r, s)\n return b, \"end\"\n end)\n \n print(\"main\", coroutine.resume(co, 1, 10))\n print(\"main\", coroutine.resume(co, \"r\"))\n print(\"main\", coroutine.resume(co, \"x\", \"y\"))\n print(\"main\", coroutine.resume(co, \"x\", \"y\"))\n
\nWhen you run it, it produces the following output:\n\n
\n co-body 1 10\n foo 2\n \n main true 4\n co-body r\n main true 11 -9\n co-body x y\n main true 10 end\n main false cannot resume dead coroutine\n
\n\n
\nCoroutines are powerful, but require some experience to use tastefully. Try to\nuse them judiciously. If you find yourself juggling lots of coroutines and\ntrying to decide which one to try to resume, you should probably be using\ntasks and channels instead. On the other hand, tasks have\nsome cognitive overheads. You have to explicitly manage them with\ntask.scheduler, and errors can\nsometimes be hard to track down. For simple generators that emit elements\non demand, a coroutine is likely the best solution.\n
\nThe standard Lua libraries provide useful functions\nthat are implemented directly in C.\nSome of these functions provide essential services to the language\n(e.g., type and getmetatable);\nothers provide access to \"outside\" services (e.g., I/O);\nand others could be implemented in Lua itself,\nbut are quite useful or have critical performance requirements that\ndeserve an implementation in C (e.g., table.sort).\n\n\n
\nCurrently, Lua has the following standard libraries:\n\n
\n\n
basic library, which includes the coroutine sub-library;
\n\n
package library;
\n\n
string manipulation;
\n\n
table manipulation;
\n\n
mathematical functions (sin, log, etc.);
\n\n
input and output;
\n\n
operating system facilities;
\n\n
debug facilities.
\n\n
\nExcept for the basic and package libraries,\neach library provides all its functions as fields of a global table\nor as methods of its objects.\n\n\n
\nThe basic library provides some core functions to Lua.\nIf you do not include this library in your application,\nyou should check carefully whether you need to provide \nimplementations for some of its facilities.\n\n\n
\nIssues an error when\nthe value of its argument v is false (i.e., nil or false);\notherwise, returns all its arguments.\nmessage is an error message;\nwhen absent, it defaults to \"assertion failed!\"\n\n\n\n\n
\nThis function is a generic interface to the garbage collector.\nIt performs different functions according to its first argument, opt:\n\n
\n\n
\"collect\":\nperforms a full garbage-collection cycle.\nThis is the default option.\n
\n\n
\"stop\":\nstops the garbage collector.\n
\n\n
\"restart\":\nrestarts the garbage collector.\n
\n\n
\"count\":\nreturns the total memory in use by Lua (in Kbytes).\n
\n\n
\"step\":\nperforms a garbage-collection step.\nThe step \"size\" is controlled by arg\n(larger values mean more steps) in a non-specified way.\nIf you want to control the step size\nyou must experimentally tune the value of arg.\nReturns true if the step finished a collection cycle.\n
\n\n
\"setpause\":\nsets arg as the new value for the pause of\nthe collector (see §2.10).\nReturns the previous value for pause.\n
\n\n
\"setstepmul\":\nsets arg as the new value for the step multiplier of\nthe collector (see §2.10).\nReturns the previous value for step.\n
\nTerminates the last protected function called\nand returns message as the error message.\nFunction error never returns.\n\n\n
\nUsually, error adds some information about the error position\nat the beginning of the message.\nThe level argument specifies how to get the error position.\nWith level 1 (the default), the error position is where the\nerror function was called.\nLevel 2 points the error to where the function\nthat called error was called; and so on.\nPassing a level 0 avoids the addition of error position information\nto the message.\n\n\n\n\n
\nA global variable that\nholds the global environment (that is, _G._G = _G).\nLua itself does not use this variable;\nchanging its value does not affect any environment,\nnor vice-versa.\n(Use setfenv to change environments.)\n\n\n\n\n
\nReturns the current environment in use by the function.\nf can be a Lua function or a number\nthat specifies the function at that stack level:\nLevel 1 is the function calling getfenv.\nIf the given function is not a Lua function,\nor if f is 0,\ngetfenv returns the global environment.\nThe default for f is 1.\n\n\n\n\n
\nIf object does not have a metatable, returns nil.\nOtherwise,\nif the object's metatable has a \"__metatable\" field,\nreturns the associated value.\nOtherwise, returns the metatable of the given object.\n\n\n\n\n
\nAllows a program to traverse all fields of a table.\nIts first argument is a table and its second argument\nis an index in this table.\nnext returns the next index of the table\nand its associated value.\nWhen called with nil as its second argument,\nnext returns an initial index\nand its associated value.\nWhen called with the last index,\nor with nil in an empty table,\nnext returns nil.\nIf the second argument is absent, then it is interpreted as nil.\nIn particular,\nyou can use next(t) to check whether a table is empty.\n\n\n
\nThe order in which the indices are enumerated is not specified,\neven for numeric indices.\n(To traverse a table in numeric order,\nuse a numerical for or the ipairs function.)\n\n\n
\nThe behavior of next is undefined if,\nduring the traversal,\nyou assign any value to a non-existent field in the table.\nYou may however modify existing fields.\nIn particular, you may clear existing fields.\n\n\n\n\n
\nReceives any number of arguments,\nand prints their values to stdout,\nusing the tostring function to convert them to strings.\nprint is not intended for formatted output,\nbut only as a quick way to show a value,\ntypically for debugging.\nFor formatted output, use string.format.\n\n\n\n\n
\nSets the real value of table[index] to value,\nwithout invoking any metamethod.\ntable must be a table,\nindex any value different from nil,\nand value any Lua value.\n\n\n
\nIf index is a number,\nreturns all arguments after argument number index.\nOtherwise, index must be the string \"#\",\nand select returns the total number of extra arguments it received.\n\n\n\n\n
\nSets the environment to be used by the given function.\nf can be a Lua function or a number\nthat specifies the function at that stack level:\nLevel 1 is the function calling setfenv.\nsetfenv returns the given function.\n\n\n
\nAs a special case, when f is 0 setfenv changes\nthe environment of the running thread.\nIn this case, setfenv returns no values.\n\n\n\n\n
\nSets the metatable for the given table.\n(You cannot change the metatable of other types.)\nIf metatable is nil,\nremoves the metatable of the given table.\nIf the original metatable has a \"__metatable\" field,\nraises an error.\n\n\n
\nTries to convert its argument to a number.\nIf the argument is already a number or a string convertible\nto a number, then tonumber returns this number;\notherwise, it returns nil.\n\n\n
\nAn optional argument specifies the base to interpret the numeral.\nThe base may be any integer between 2 and 36, inclusive.\nIn bases above 10, the letter 'A' (in either upper or lower case)\nrepresents 10, 'B' represents 11, and so forth,\nwith 'Z' representing 35.\nIn base 10 (the default), the number can have a decimal part,\nas well as an optional exponent part (see §2.1).\nIn other bases, only unsigned integers are accepted.\n\n\n\n\n
\nReceives an argument of any type and\nconverts it to a string in a reasonable format.\nFor complete control of how numbers are converted,\nuse string.format.\n\n\n
\nIf the metatable of e has a \"__tostring\" field,\nthen tostring calls the corresponding value\nwith e as argument,\nand uses the result of the call as its result.\n\n\n\n\n
\nReturns the type of its only argument, coded as a string.\nThe possible results of this function are\n\"nil\" (a string, not the value nil),\n\"number\",\n\"string\",\n\"boolean\",\n\"table\",\n\"function\",\n\"thread\",\nand \"userdata\".\n\n\n\n\n
\nReturns the elements from the given table.\nThis function is equivalent to\n\n
\n return list[i], list[i+1], ···, list[j]\n
\nexcept that the above code can be written only for a fixed number\nof elements.\nBy default, i is 1 and j is the length of the list,\nas defined by the length operator (see §2.5.5).\n\n\n\n\n
\nA global variable (not a function) that\nholds a string containing the current interpreter version.\nThe current contents of this variable is \"Lua 5.1\".\n\n\n\n\n
\nThe operations related to coroutines comprise a sub-library of\nthe basic library and come inside the table coroutine.\nSee §2.11 for a general description of coroutines.\n\n\n
\nStarts or continues the execution of coroutine co.\nThe first time you resume a coroutine,\nit starts running its body.\nThe values val1, ··· are passed\nas the arguments to the body function.\nIf the coroutine has yielded,\nresume restarts it;\nthe values val1, ··· are passed\nas the results from the yield.\n\n\n
\nIf the coroutine runs without any errors,\nresume returns true plus any values passed to yield\n(if the coroutine yields) or any values returned by the body function\n(if the coroutine terminates).\nIf there is any error,\nresume returns false plus the error message.\n\n\n\n\n
\nReturns the status of coroutine co, as a string:\n\"running\",\nif the coroutine is running (that is, it called status);\n\"suspended\", if the coroutine is suspended in a call to yield,\nor if it has not started running yet;\n\"normal\" if the coroutine is active but not running\n(that is, it has resumed another coroutine);\nand \"dead\" if the coroutine has finished its body function,\nor if it has stopped with an error.\n\n\n\n\n
\nCreates a new coroutine, with body f.\nf must be a Lua function.\nReturns a function that resumes the coroutine each time it is called.\nAny arguments passed to the function behave as the\nextra arguments to resume.\nReturns the same values returned by resume,\nexcept the first boolean.\nIn case of error, propagates the error.\n\n\n\n\n
\nSuspends the execution of the calling coroutine.\nThe coroutine cannot be running a primitive implemented in\nC, a metamethod, or an iterator.\nAny arguments to yield are passed as extra results to resume.\n\n\n\n\n\n\n\n
\nThis library provides generic functions for string manipulation,\nsuch as finding and extracting substrings, and pattern matching.\nWhen indexing a string in Lua, the first character is at position 1\n(not at 0, as in C).\nIndices are allowed to be negative and are interpreted as indexing backwards,\nfrom the end of the string.\nThus, the last character is at position -1, and so on.\n\n\n
\nThe string library provides all its functions inside the table\nstring.\nIt also sets a metatable for strings\nwhere the __index field points to the string table.\nTherefore, you can use the string functions in object-oriented style.\nFor instance, string.byte(s, i)\ncan be written as s:byte(i).\n\n\n
\nThe string library assumes one-byte character encodings.\n\n\n
\nReceives zero or more integers.\nReturns a string with length equal to the number of arguments,\nin which each character has the internal numerical code equal\nto its corresponding argument.\n\n\n
\nNote that numerical codes are not necessarily portable across platforms.\n\n\n\n
\nLooks for the first match of\npattern in the string s.\nIf it finds a match, then find returns the indices of s\nwhere this occurrence starts and ends;\notherwise, it returns nil.\nA third, optional numerical argument init specifies\nwhere to start the search;\nits default value is 1 and can be negative.\nA value of true as a fourth, optional argument plain\nturns off the pattern matching facilities,\nso the function does a plain \"find substring\" operation,\nwith no characters in pattern being considered \"magic\".\nNote that if plain is given, then init must be given as well.\n\n\n
\nIf the pattern has captures,\nthen in a successful match\nthe captured values are also returned,\nafter the two indices.\n\n\n\n\n
\nReturns a formatted version of its variable number of arguments\nfollowing the description given in its first argument (which must be a string).\nThe format string follows the same rules as the printf family of\nstandard C functions.\nThe only differences are that the options/modifiers\n*, l, L, n, p,\nand h are not supported\nand that there is an extra option, q.\nThe q option formats a string in a form suitable to be safely read\nback by the Lua interpreter:\nthe string is written between double quotes,\nand all double quotes, newlines, embedded zeros,\nand backslashes in the string\nare correctly escaped when written.\nFor instance, the call\n\n
\n string.format('%q', 'a string with \"quotes\" and \\n new line')\n
\nwill produce the string:\n\n
\n \"a string with \\\"quotes\\\" and \\\n new line\"\n
\n\n
\nThe options c, d, E, e, f,\ng, G, i, o, u, X, and x all\nexpect a number as argument,\nwhereas q and s expect a string.\n\n\n
\nThis function does not accept string values\ncontaining embedded zeros,\nexcept as arguments to the q option.\n\n\n\n\n
\nReturns an iterator function that,\neach time it is called,\nreturns the next captures from pattern over string s.\nIf pattern specifies no captures,\nthen the whole match is produced in each call.\n\n\n
\nAs an example, the following loop\n\n
\n s = \"hello world from Lua\"\n for w in string.gmatch(s, \"%a+\") do\n print(w)\n end\n
\nwill iterate over all the words from string s,\nprinting one per line.\nThe next example collects all pairs key=value from the\ngiven string into a table:\n\n
\n t = {}\n s = \"from=world, to=Lua\"\n for k, v in string.gmatch(s, \"(%w+)=(%w+)\") do\n t[k] = v\n end\n
\n\n
\nFor this function, a '^' at the start of a pattern does not\nwork as an anchor, as this would prevent the iteration.\n\n\n\n\n
\nReturns a copy of s\nin which all (or the first n, if given)\noccurrences of the pattern have been\nreplaced by a replacement string specified by repl,\nwhich can be a string, a table, or a function.\ngsub also returns, as its second value,\nthe total number of matches that occurred.\n\n\n
\nIf repl is a string, then its value is used for replacement.\nThe character % works as an escape character:\nany sequence in repl of the form %n,\nwith n between 1 and 9,\nstands for the value of the n-th captured substring (see below).\nThe sequence %0 stands for the whole match.\nThe sequence %% stands for a single %.\n\n\n
\nIf repl is a table, then the table is queried for every match,\nusing the first capture as the key;\nif the pattern specifies no captures,\nthen the whole match is used as the key.\n\n\n
\nIf repl is a function, then this function is called every time a\nmatch occurs, with all captured substrings passed as arguments,\nin order;\nif the pattern specifies no captures,\nthen the whole match is passed as a sole argument.\n\n\n
\nIf the value returned by the table query or by the function call\nis a string or a number,\nthen it is used as the replacement string;\notherwise, if it is false or nil,\nthen there is no replacement\n(that is, the original match is kept in the string).\n\n\n
\nHere are some examples:\n\n
\n x = string.gsub(\"hello world\", \"(%w+)\", \"%1 %1\")\n --> x=\"hello hello world world\"\n \n x = string.gsub(\"hello world\", \"%w+\", \"%0 %0\", 1)\n --> x=\"hello hello world\"\n \n x = string.gsub(\"hello world from Lua\", \"(%w+)%s*(%w+)\", \"%2 %1\")\n --> x=\"world hello Lua from\"\n \n x = string.gsub(\"home = $HOME, user = $USER\", \"%$(%w+)\", os.getenv)\n --> x=\"home = /home/roberto, user = roberto\"\n \n local t = {name=\"lua\", version=\"5.1\"}\n x = string.gsub(\"$name-$version.tar.gz\", \"%$(%w+)\", t)\n --> x=\"lua-5.1.tar.gz\"\n
\nReceives a string and returns its length.\nThe empty string \"\" has length 0.\nEmbedded zeros are counted,\nso \"a\\000bc\\000\" has length 5.\n\n\n\n\n
\nReceives a string and returns a copy of this string with all\nuppercase letters changed to lowercase.\nAll other characters are left unchanged.\nThe definition of what an uppercase letter is depends on the current locale.\n\n\n\n\n
\nLooks for the first match of\npattern in the string s.\nIf it finds one, then match returns\nthe captures from the pattern;\notherwise it returns nil.\nIf pattern specifies no captures,\nthen the whole match is returned.\nA third, optional numerical argument init specifies\nwhere to start the search;\nits default value is 1 and can be negative.\n\n\n\n\n
\nReturns the substring of s that\nstarts at i and continues until j;\ni and j can be negative.\nIf j is absent, then it is assumed to be equal to -1\n(which is the same as the string length).\nIn particular,\nthe call string.sub(s,1,j) returns a prefix of s\nwith length j,\nand string.sub(s, -i) returns a suffix of s\nwith length i.\n\n\n\n\n
\nReceives a string and returns a copy of this string with all\nlowercase letters changed to uppercase.\nAll other characters are left unchanged.\nThe definition of what a lowercase letter is depends on the current locale.\n\n\n\n
\nA character class is used to represent a set of characters.\nThe following combinations are allowed in describing a character class:\n\n
\n\n
x:\n(where x is not one of the magic characters\n^$()%.[]*+-?)\nrepresents the character x itself.\n
\n\n
.: (a dot) represents all characters.
\n\n
%a: represents all letters.
\n\n
%c: represents all control characters.
\n\n
%d: represents all digits.
\n\n
%l: represents all lowercase letters.
\n\n
%p: represents all punctuation characters.
\n\n
%s: represents all space characters.
\n\n
%u: represents all uppercase letters.
\n\n
%w: represents all alphanumeric characters.
\n\n
%x: represents all hexadecimal digits.
\n\n
%z: represents the character with representation 0.
\n\n
%x: (where x is any non-alphanumeric character)\nrepresents the character x.\nThis is the standard way to escape the magic characters.\nAny punctuation character (even the non magic)\ncan be preceded by a '%'\nwhen used to represent itself in a pattern.\n
\n\n
[set]:\nrepresents the class which is the union of all\ncharacters in set.\nA range of characters can be specified by\nseparating the end characters of the range with a '-'.\nAll classes %x described above can also be used as\ncomponents in set.\nAll other characters in set represent themselves.\nFor example, [%w_] (or [_%w])\nrepresents all alphanumeric characters plus the underscore,\n[0-7] represents the octal digits,\nand [0-7%l%-] represents the octal digits plus\nthe lowercase letters plus the '-' character.\n\n\n
\nThe interaction between ranges and classes is not defined.\nTherefore, patterns like [%a-z] or [a-%%]\nhave no meaning.\n
\n\n
[^set]:\nrepresents the complement of set,\nwhere set is interpreted as above.\n
\n\n
\nFor all classes represented by single letters (%a, %c, etc.),\nthe corresponding uppercase letter represents the complement of the class.\nFor instance, %S represents all non-space characters.\n\n\n
\nThe definitions of letter, space, and other character groups\ndepend on the current locale.\nIn particular, the class [a-z] may not be equivalent to %l.\n\n\n\n\n\n
Pattern Item:
\nA pattern item can be\n\n
\n\n
\na single character class,\nwhich matches any single character in the class;\n
\n\n
\na single character class followed by '*',\nwhich matches 0 or more repetitions of characters in the class.\nThese repetition items will always match the longest possible sequence;\n
\n\n
\na single character class followed by '+',\nwhich matches 1 or more repetitions of characters in the class.\nThese repetition items will always match the longest possible sequence;\n
\n\n
\na single character class followed by '-',\nwhich also matches 0 or more repetitions of characters in the class.\nUnlike '*',\nthese repetition items will always match the shortest possible sequence;\n
\n\n
\na single character class followed by '?',\nwhich matches 0 or 1 occurrence of a character in the class;\n
\n\n
\n%n, for n between 1 and 9;\nsuch item matches a substring equal to the n-th captured string\n(see below);\n
\n\n
\n%bxy, where x and y are two distinct characters;\nsuch item matches strings that start with x, end with y,\nand where the x and y are balanced.\nThis means that, if one reads the string from left to right,\ncounting +1 for an x and -1 for a y,\nthe ending y is the first y where the count reaches 0.\nFor instance, the item %b() matches expressions with\nbalanced parentheses.\n
\n\n
\n\n\n\n\n
Pattern:
\nA pattern is a sequence of pattern items.\nA '^' at the beginning of a pattern anchors the match at the\nbeginning of the subject string.\nA '$' at the end of a pattern anchors the match at the\nend of the subject string.\nAt other positions,\n'^' and '$' have no special meaning and represent themselves.\n\n\n\n\n\n
Captures:
\nA pattern can contain sub-patterns enclosed in parentheses;\nthey describe captures.\nWhen a match succeeds, the substrings of the subject string\nthat match captures are stored (captured) for future use.\nCaptures are numbered according to their left parentheses.\nFor instance, in the pattern \"(a*(.)%w(%s*))\",\nthe part of the string matching \"a*(.)%w(%s*)\" is\nstored as the first capture (and therefore has number 1);\nthe character matching \".\" is captured with number 2,\nand the part matching \"%s*\" has number 3.\n\n\n
\nAs a special case, the empty capture () captures\nthe current string position (a number).\nFor instance, if we apply the pattern \"()aa()\" on the\nstring \"flaaap\", there will be two captures: 3 and 5.\n\n\n
\nA pattern cannot contain embedded zeros. Use %z instead.\n\n\n\n\n\n\n\n\n\n\n\n
\nThis library provides generic functions for table manipulation.\nIt provides all its functions inside the table table.\n\n\n
\nMost functions in the table library assume that the table\nrepresents an array or a list.\nFor these functions, when we talk about the \"length\" of a table\nwe mean the result of the length operator.\n\n\n
\nGiven an array where all elements are strings or numbers,\nreturns table[i]..sep..table[i+1] ··· sep..table[j].\nThe default value for sep is the empty string,\nthe default for i is 1,\nand the default for j is the length of the table.\nIf i is greater than j, returns the empty string.\n\n\n\n\n
\nInserts element value at position pos in table,\nshifting up other elements to open space, if necessary.\nThe default value for pos is n+1,\nwhere n is the length of the table (see §2.5.5),\nso that a call table.insert(t,x) inserts x at the end\nof table t.\n\n\n\n\n
\nReturns the largest positive numerical index of the given table,\nor zero if the table has no positive numerical indices.\n(To do its job this function does a linear traversal of\nthe whole table.) \n\n\n\n\n
\nRemoves from table the element at position pos,\nshifting down other elements to close the space, if necessary.\nReturns the value of the removed element.\nThe default value for pos is n,\nwhere n is the length of the table,\nso that a call table.remove(t) removes the last element\nof table t.\n\n\n\n\n
\nSorts table elements in a given order, in-place,\nfrom table[1] to table[n],\nwhere n is the length of the table.\nIf comp is given,\nthen it must be a function that receives two table elements,\nand returns true\nwhen the first is less than the second\n(so that not comp(a[i+1],a[i]) will be true after the sort).\nIf comp is not given,\nthen the standard Lua operator < is used instead.\n\n\n
\nThe sort algorithm is not stable;\nthat is, elements considered equal by the given order\nmay have their relative positions changed by the sort.\n\n\n\n\n\n\n\n
\nReturns the arc tangent of y/x (in radians),\nbut uses the signs of both parameters to find the\nquadrant of the result.\n(It also handles correctly the case of x being zero.)\n\n\n\n\n
\nThis function is an interface to the simple\npseudo-random generator function rand provided by ANSI C.\n(No guarantees can be given for its statistical properties.)\n\n\n
\nWhen called without arguments,\nreturns a uniform pseudo-random real number\nin the range [0,1). \nWhen called with an integer number m,\nmath.random returns\na uniform pseudo-random integer in the range [1, m].\nWhen called with two integer numbers m and n,\nmath.random returns a uniform pseudo-random\ninteger in the range [m, n].\n\n\n\n\n
\nWhile Teliva supports the standard Lua primitives for managing files via\nhandles, idiomatic Teliva uses some slightly different primitives that use a\nsubtly different file object (name tbd).\n\n
\nThis function opens a file exclusively for reading, and returns an object (NOT\na file handle as in Lua) or nil on error. If the returned object is\nstored in variable f, f.read(format) will read from\nthe file. Legal values for format are identical to\nfile:read(format).\n\n
\n(The fs parameter is currently unused. It will be used to pass in\nfake file systems for tests.)\n\n\n
\nThis function opens a file exclusively for writing, and returns an object (NOT\na file handle as in Lua) or nil on error. If the result is stored in\nvariable f, f.write(x) will write x to\nthe file. f.close() will persist the changes and make them\nexternally visible. All changes will be hidden until f.close().\n\n
\n(The fs parameter is currently unused. It will be used to pass in\nfake file systems for tests.)\n\n\n
\nThe rest of this section describes Lua's standard primitives for File I/O.\n
\n\n\n
\nUnless otherwise stated,\nall File I/O functions return nil on failure\n(plus an error message as a second result and\na system-dependent error code as a third result)\nand some value different from nil on success.\n\n\n
\nThis function opens a file,\nin the mode specified in the string mode.\nIt returns a new file handle,\nor, in case of errors, nil plus an error message.\n\n\n
\nThe mode string can be any of the following:\n\n
\n
\"r\": read mode (the default);
\n
\"w\": write mode;
\n
\"a\": append mode;
\n
\"r+\": update mode, all previous data is preserved;
\n
\"w+\": update mode, all previous data is erased;
\n
\"a+\": append update mode, previous data is preserved,\n writing is only allowed at the end of file.
\n
\nThe mode string can also have a 'b' at the end,\nwhich is needed in some systems to open the file in binary mode.\nThis string is exactly what is used in the\nstandard C function fopen.\n\n
\nThis function is sandboxed. It may fail if the computer owner's\npermissions disallow it.\n
\nChecks whether obj is a valid file handle.\nReturns the string \"file\" if obj is an open file handle,\n\"closed file\" if obj is a closed file handle,\nor nil if obj is not a file handle.\n\n\n\n\n
\nCloses file.\nNote that files are automatically closed when\ntheir handles are garbage collected,\nbut that takes an unpredictable amount of time to happen.\n\n\n\n\n
\nReads the file file,\naccording to the given formats, which specify what to read.\nFor each format,\nthe function returns a string (or a number) with the characters read,\nor nil if it cannot read data with the specified format.\nWhen called without formats,\nit uses a default format that reads the entire next line\n(see below).\n\n\n
\nThe available formats are\n\n
\n\n
\"*n\":\nreads a number;\nthis is the only format that returns a number instead of a string.\n
\n\n
\"*a\":\nreads the whole file, starting at the current position.\nOn end of file, it returns the empty string.\n
\n\n
\"*l\":\nreads the next line (skipping the end of line),\nreturning nil on end of file.\nThis is the default format.\n
\n\n
number:\nreads a string with up to this number of characters,\nreturning nil on end of file.\nIf number is zero,\nit reads nothing and returns an empty string,\nor nil on end of file.\n
\nSets and gets the file position,\nmeasured from the beginning of the file,\nto the position given by offset plus a base\nspecified by the string whence, as follows:\n\n
\n
\"set\": base is position 0 (beginning of the file);
\n
\"cur\": base is current position;
\n
\"end\": base is end of file;
\n
\nIn case of success, function seek returns the final file position,\nmeasured in bytes from the beginning of the file.\nIf this function fails, it returns nil,\nplus a string describing the error.\n\n\n
\nThe default value for whence is \"cur\",\nand for offset is 0.\nTherefore, the call file:seek() returns the current\nfile position, without changing it;\nthe call file:seek(\"set\") sets the position to the\nbeginning of the file (and returns 0);\nand the call file:seek(\"end\") sets the position to the\nend of the file, and returns its size.\n\n\n\n\n
\nWrites the value of each of its arguments to\nthe file.\nThe arguments must be strings or numbers.\nTo write other values,\nuse tostring or string.format before write.\n\n\n\n\n\n\n\n
\nReturns a string or a table containing date and time,\nformatted according to the given string format.\n\n\n
\nIf the time argument is present,\nthis is the time to be formatted\n(see the os.time function for a description of this value).\nOtherwise, date formats the current time.\n\n\n
\nIf format starts with '!',\nthen the date is formatted in Coordinated Universal Time.\nAfter this optional character,\nif format is the string \"*t\",\nthen date returns a table with the following fields:\nyear (four digits), month (1--12), day (1--31),\nhour (0--23), min (0--59), sec (0--61),\nwday (weekday, Sunday is 1),\nyday (day of the year),\nand isdst (daylight saving flag, a boolean).\n\n\n
\nIf format is not \"*t\",\nthen date returns the date as a string,\nformatted according to the same rules as the C function strftime.\n\n\n
\nWhen called without arguments,\ndate returns a reasonable date and time representation that depends on\nthe host system and on the current locale\n(that is, os.date() is equivalent to os.date(\"%c\")).\n\n\n\n\n
\nDeletes the file or directory with the given name.\nDirectories must be empty to be removed.\nIf this function fails, it returns nil,\nplus a string describing the error.\n\n\n\n\n
\nSets the current locale of the program.\nlocale is a string specifying a locale;\ncategory is an optional string describing which category to change:\n\"all\", \"collate\", \"ctype\",\n\"monetary\", \"numeric\", or \"time\";\nthe default category is \"all\".\nThe function returns the name of the new locale,\nor nil if the request cannot be honored.\n\n\n
\nIf locale is the empty string,\nthe current locale is set to an implementation-defined native locale.\nIf locale is the string \"C\",\nthe current locale is set to the standard C locale.\n\n\n
\nWhen called with nil as the first argument,\nthis function only returns the name of the current locale\nfor the given category.\n\n\n\n\n
\nReturns the current time when called without arguments,\nor a time representing the date and time specified by the given table.\nThis table must have fields year, month, and day,\nand may have fields hour, min, sec, and isdst\n(for a description of these fields, see the os.date function).\n\n\n
\nThe returned value is a number, whose meaning depends on your system.\nIn POSIX, Windows, and some other systems, this number counts the number\nof seconds since some given start time (the \"epoch\").\nIn other systems, the meaning is not specified,\nand the number returned by time can be used only as an argument to\ndate and difftime.\n\n\n\n\n
\nReturns a string with a file name that can\nbe used for a temporary file.\nThe file must be explicitly opened before its use\nand explicitly removed when no longer needed.\n\n\n
\nOn some systems (POSIX),\nthis function also creates a file with that name,\nto avoid security risks.\n(Someone else might create the file with wrong permissions\nin the time between getting the name and creating the file.)\nYou still have to open the file to use it\nand to remove it (even if you do not use it).\n\n\n
\nWhen possible,\nyou may prefer to use io.tmpfile,\nwhich automatically removes the file when the program ends.\n\n\n\n\n\n\n\n
\n\nTeliva includes curses facilities identical to Lua's lcurses\nlibrary. As there, the top-level module is called curses. All apps\nstart with the terminal window initialized using\ncurses.initscr. Look at the\nsample apps for example usage.\n\n\n
\nInitializes the current terminal to stop scrolling and enable moving the\ncursor. You shouldn't need to ever call this from Teliva; it's always called\nfor you before an app is loaded.\n\n\n
\nReturns a window object for the current terminal. Most curses\noperations require a window. Windows are an app's gateway to both print to\nscreen and read keys from keyboard. Teliva's template.tlv for new applications\nsaves the result in a global called Window, so you should be able\nto avoid calling stdscr directly most of the time.\n\n
\nCurses supports multiple and nested windows. They haven't been tried\nyet in the context of Teliva, but they're expected to work. Please report your\nexperience if you try them out.\n\n\n
\nCreates a fake window suitable for passing around in tests. The table passed\nin should have two keys: a kbd\ncontaining a keyboard, and a scr\ncontaining a screen.\n\n
\nThis helper is implemented in template.tlv, so new apps should pick it up from\nthere.\n\n\n
\nMoves window's cursor to (x, y) before\nprinting character c to it with\nthe current attributes.\nMay not be visible until window:refresh\nis called.\n\n\n
\nMoves window's cursor to (x, y) before\nprinting string str to it with\nthe current attributes.\nMay not be visible until window:refresh is called.\n\n\n
\nAdds the given attribute\nto the set of current attributes for future prints to window. For\nthe list of available attributes see window:attrset.\n\n
\nSince Lua 5.1 has no bitwise operations, this function currently only supports\nadding a single attribute at a time.\n\n\n
\nRemoves the given attribute\nfrom the set of current attributes for future prints to window.\nthe list of available attributes see window:attrset.\n\n
\nSince Lua 5.1 has no bitwise operations, this function currently only supports\nremoving a single attribute at a time.\n\n\n
\nReturns a character from the keyboard. Waits for a key to be pressed by\ndefault, but this behavior can be changed by calling window:nodelay(true).\n\n
\nwindow:getch is the only supported way to get input from\nkeyboard in Teliva, handling Teliva's menu and so on.\n\n\n
\n\nTeliva includes the well-known\njson.lua library (module\njson). It also includes a variant in module jsonf that can\nread JSON from channels opened by\nstart_reading.\n\n
\nReads a value encoded in JSON from a file and returns it.\nf is the type of file object returned by\nstart_reading (i.e. supporting\nf.read(format)).\n\nFor example, suppose file foo contains '[1,2,3,{\"x\":10}]'. Then:\n
\n local infile = start_reading(nil, 'foo')\n jsonf.decode(infile) -- Returns { 1, 2, 3, { x = 10 } }\n
\nRun fun as a coroutine with given parameters. Spawn tasks instead of\njust calling coroutine.create\nwhen you can't statically predict how your coroutines will transfer control to\neach other.\n\n\n
\nStarts running any spawned tasks. Execution transfers to spawned tasks;\nthis function only returns when there are no tasks left to run or when all\ntasks are blocked (deadlock).\n\n\n
\nWrite value to a channel. Blocks the current coroutine if the\nchannel is already full. (Channels with size 0 always block if there isn't\nalready a coroutine trying to recv\nfrom them.)\n\n\n
\nRead a value from a channel. Blocks the current coroutine if the\nchannel is empty and there isn't already a coroutine trying to\nsend to them.\n\n\n
\nBesides these, there are other primitives that have never been used in Teliva\napps, but should still work. Please report if you try them out.\n\n
![\"\"](\"cover.png\" "\\"buy")
\n\nLua 5.1 Reference Manual\n