pkulchenko/ZeroBraneStudio — pull request #84 by Fringale (2012-12-04 23:13:32+00:00)
Title: Lua api

As a follow-up on issue #79, I updated the Lua spec (spec/lua.lua) and API (api/lua/baselib.lua) to Lua 5.2.

As you'll see, there's not much to say about spc/lua.lua. However, baselib.lua deserves an explanation, as the file was, well, totally refactored.

Changes and reasoning for baselib.lua:
* Descriptions: I took them straight from the Lua 5.2 reference manual, as was done for some of the libraries in the previous version of the file. For values or functions deprecated in 5.2, they were taken from the 5.1 manual instead. A few modifications were made though:
- The sequence '\n\n' was used to break the descriptions in paragraphs like in the manual. It was also used to separate the first line or so of the description when it could be taken as a summary of sort.
- Examples were removed from descriptions due to readability concerns. I know that I modified at least `modules, debug.getinfo, file:lines, package.loaders, package.searchers, package.searchpath, string.format, string.gmatch, string.gsub`, but there may be others I forgot to note.
- Also removed all references to other paragraphs of the manual, generally in the form of _see §2.6_.
- I completed some descriptions that merely referenced another function (since this is OK for a manual, but quite impractical int the case of tooltips), by taking what's needed from the other description. Affected functions should be: `loadfile, loadstring, xpcall, bit32.replace, io.close, io.flush, io.lines, io.output, io.read, io.write`.
- Differences between Lua 5.2 and 5.1 were annotated mostly using the following form: FUNCTION/ARGUMENT/VALUE ADDED/DEPRECATED IN LUA 5.2. You can find them all by searching the string 'LUA 5.2'.
* Arguments: I added their type, as was done in love2d / moai APIs. When an argument could have several types, they were listed separated by a '|'. If an argument could be of any type, the type was labeled 'any'. Also, I put an additional first parameter 'file' in the `file` functions, since they are actually methods (`.flush()` being equivalent to `:flush()`).
* Returns: they are only listed as a type (no name), as most functions have only one return, and in my opinion adding a name for each return would have decreased readability.
* Compared to the previous version, I did not set the 'valuetype' field for any of the functions or values. I wasn't sure about the purpose of this API field, and I saw that recent APIs (love2d / moai / etc. did not use it either.

Due to these changes / additions, the previous code organization became quite impractical (returns and arguments on the same line as the description) and I switched to something more standardized and hierarchical.

The result is not perfect, but in the end I find it an improvement over the previous version, which was not complete, and ambiguous in places.

Hope this is OK for you!

Fringale

---
By the way, here's a quick breakdown of the keyword / library changes between Lua 5.1 and 5.2, in case someone might have a use for it in the future:

**Deprecated in 5.2:**
* getfenv
* loadstring
* module
* setfenv
* unpack _(actually moved to table.unpack)_
* debug.getfenv
* debug.setfenv
* math.log10
* package.loaders _(actually renamed to package.searchers)_
* package.seeall
* table.maxn

**Added in 5.2:**
* _ENV
* goto
* rawlen
* bit32.arshift
* bit32.band
* bit32.bnot
* bit32.bor
* bit32.btest
* bit32.bxor
* bit32.extract
* bit32.lrotate
* bit32.lshift
* bit32.replace
* bit32.rrotate
* bit32.rshift
* debug.getuservalue
* debug.setuservalue
* debug.upvalueid
* debug.upvaluejoin
* package.config
* package.searchers _(actually renamed from package.loaders)_
* table.pack
* table.unpack _(actually moved from unpack)_

**Arguments, returns or behavior changed in 5.2:**
* collectgarbage
* ipairs
* load
* loadfile
* pairs
* select
* xpcall
* coroutine.running
* debug.getlocal
* debut.setmetatable
* io.close / file:close
* io.lines / file:lines
* io.read / file:read
* io.write / file:write
* math.log
* os.execute
* os.exit
* package.loadlib
* string.format
* string.rep

Beyond 5.1 / 5.2 manuals, I used the following resources as reference :
* http://www.lua.org/manual/5.2/readme.html#changes
* http://www.lua.org/manual/5.2/manual.html#8
* http://lua-users.org/lists/lua-l/2011-06/msg01143.html (see both links in the email)
* http://luajit.org/extensions.html (the "Extensions" chapter)