Added Lua autocompletion support.

9 files changed, 451 insertions, 0 deletions

diff --git a/modules/lua/api/_G.luadoc b/modules/lua/api/_G.luadoc
new file mode 100644
index 00000000..45fbe8fc
--- /dev/null
+++ b/modules/lua/api/_G.luadoc
@@ -0,0 +1,64 @@
+-- * `_G`: Holds global environment, setfenv changes environments.
+-- * `_VERSION`: Current interpreter version "Lua 5.0".
+--- Error if v nil or false, otherwise returns v.
+function assert(v [, message])
+--- Set threshold to limit KBytes, default 0, may run GC.
+function collectgarbage([limit])
+--- Executes as Lua chunk, default stdin, returns value.
+function dofile(filename)
+--- Terminates protected func, never returns, level 1(default), 2=parent.
+function error(message [, level])
+--- Returns dynamic mem in use(KB), and current GC threshold(KB).
+function gcinfo()
+---
+-- Gets env, f can be a function or number(stack level, default=1), 0=global
+-- env.
+function getfenv(f)
+--- Returns metatable of given object, otherwise nil.
+function getmetatable(object)
+--- Returns an iterator function, table t and 0.
+function ipairs(t)
+---
+-- Loads chunk without execution, returns chunk as function, else nil plus
+-- error.
+function loadfile(filename)
+--- Links to dynamic library libname, returns funcname as a C function.
+function loadlib(libname, funcname)
+--- Loads string as chunk, returns chunk as function, else nil plus error.
+function loadstring(string [, chunkname])
+--- Returns next index,value pair, if index=nil(default), returns first index.
+function next(table [, index])
+---
+-- Returns the next function and table t plus a nil, iterates over all key-value
+-- pairs.
+function pairs(t)
+---
+-- Protected mode call, catches errors, returns status code first
+--(true=success).
+function pcall(f, arg1, arg2, ...)
+--- Prints values to stdout using tostring.
+function print(e1, e2, ...)
+--- Non-metamethod v1==v2, returns boolean.
+function rawequal(v1, v2)
+--- Non-metamethod get value of table[index], index != nil.
+function rawget(table, index)
+--- Non-metamethod set value of table[index], index != nil.
+function rawset(table, index, value)
+--- Loads package, updates _LOADED, returns boolean.
+function require(packagename)
+---
+-- Sets env, f can be a function or number(stack level, default=1), 0=global
+-- env.
+function setfenv(f, table)
+--- Sets metatable, nil to remove metatable.
+function setmetatable(table, metatable)
+--- Convert to number, returns number, nil if non-convertible, 2<=base<=36.
+function tonumber(e [, base])
+--- Convert to string, returns string.
+function tostring(e)
+--- Returns type of v as a string.
+function type(v)
+--- Returns all elements from list.
+function unpack(list)
+--- pcall function f with new error handler err.
+function xpcall(f, err)
diff --git a/modules/lua/api/coroutine.luadoc b/modules/lua/api/coroutine.luadoc
new file mode 100644
index 00000000..7e60f275
--- /dev/null
+++ b/modules/lua/api/coroutine.luadoc
@@ -0,0 +1,10 @@
+--- Creates coroutine from function f, returns coroutine.
+function create(f)
+-- Continues execution of co, returns bool status plus any values.
+function resume(co, val1, ...)
+--- Returns co status: "running", "suspended" or "dead".
+function status(co)
+--- Creates coroutine with body f, returns function that resumes co.
+function wrap(f)
+--- Suspend execution of calling coroutine.
+function yield(val1, ...)
diff --git a/modules/lua/api/debug.luadoc b/modules/lua/api/debug.luadoc
new file mode 100644
index 00000000..fb7c83f3
--- /dev/null
+++ b/modules/lua/api/debug.luadoc
@@ -0,0 +1,18 @@
+--- Enters interactive debug mode, line with only "cont" terminates.
+function debug()
+--- Returns current hook function, hook mask, hook count.
+function gethook()
+--- Returns table with information about a function.
+function getinfo(function [, what])
+--- Returns name and value of local variable with index local at stack level.
+function getlocal(level, local)
+--- Returns name and value of upvalue with index up of function func.
+function getupvalue(func, up)
+--- Sets given function as a hook, mask="[crl]".
+function sethook(hook, mask [, count])
+--- Sets local variable with index local at stack level with value.
+function setlocal(level, local, value)
+--- Sets upvalue with index up of function func with value.
+function setupvalue(func, up, value)
+--- Returns a string with a traceback of the call stack.
+function traceback([message])
diff --git a/modules/lua/api/io.luadoc b/modules/lua/api/io.luadoc
new file mode 100644
index 00000000..adf4edfe
--- /dev/null
+++ b/modules/lua/api/io.luadoc
@@ -0,0 +1,50 @@
+--- Closes file, or the default output file.
+function close([file])
+--- Flushes the default output file.
+function flush()
+---
+-- Opens file in text mode, sets as default input file, or returns current
+-- default input file.
+function input([file])
+--- Open file in read mode, returns iterator function to return lines, nil ends.
+function lines([filename])
+--- Opens file in specified mode "[rawb+]", returns handle or nil.
+function open(filename [, mode])
+---
+-- Opens file in text mode, sets as default output file, or returns current
+-- default output file.
+function output([file])
+--- Reads file according to given formats, returns read values or nil.
+function read(format1, ...)
+-- * `stderr`: File descriptor for STDERR.
+-- * `stdin`: File descriptor for STDIN.
+-- * `stdout`: File descriptor for STDOUT.
+--- Returns a handle for a temporary file, opened in update mode.
+function tmpfile()
+---
+-- Returns "file" if obj is an open file handle, "close file" if closed, or nil
+-- if not a file handle.
+function type(obj)
+--- Writes strings or numbers to file.
+function write(value1, ...)
+
+---
+-- Opens a list of files.
+-- @param utf8_filenames A '\n' separated list of filenames to open. If none
+--   specified, the user is prompted to open files from a dialog. These paths
+--   must be encoded in UTF-8.
+-- @usage io.open_file(utf8_encoded_filename)
+function open_file(utf8_filenames)
+
+---
+-- Saves all dirty buffers to their respective files.
+-- @usage io.save_all()
+function save_all()
+
+---
+-- Closes all open buffers.
+-- If any buffer is dirty, the user is prompted to continue. No buffers are
+-- saved automatically. They must be saved manually.
+-- @usage io.close_all()
+-- @return true if user did not cancel.
+function close_all()
diff --git a/modules/lua/api/math.luadoc b/modules/lua/api/math.luadoc
new file mode 100644
index 00000000..7c84a80e
--- /dev/null
+++ b/modules/lua/api/math.luadoc
@@ -0,0 +1,48 @@
+--- Returns absolute value of v.
+function abs(v)
+--- Returns arc cosine value of v in radians.
+function acos(v)
+--- Returns arc sine value of v in radians.
+function asin(v)
+--- Returns arc tangent value of v in radians.
+function atan(v)
+--- Returns arc tangent value of v1/v2 in radians.
+function atan2(v1, v2)
+--- Returns smallest integer >= v.
+function ceil(v)
+--- Returns cosine value of angle rad.
+function cos(rad)
+--- Returns angle in degrees of radians rad.
+function deg(rad)
+--- Returns e^v.
+function exp(v)
+--- Returns largest integer <= v.
+function floor(v)
+--- Returns mantissa [0.5,1) and exponent values of v.
+function frexp(v)
+--- Returns v1*2^v2.
+function ldexp(v1, v2)
+--- Returns natural logarithm of v.
+function log(v)
+--- Returns logarithm 10 of v.
+function log10(v)
+--- Returns maximum in a list of one or more values.
+function max(v1, ...)
+--- Returns minimum in a list of one or more values.
+function min(v1, ...)
+--- Returns remainder of v1/v2 which is v1 - iV2 for some integer i.
+function mod(v1, v2)
+--- Returns v1 raised to the power of v2.
+function pow(v1, v2)
+--- Returns angle in radians of degrees deg.
+function rad(deg)
+--- Returns random real [0,1), integer [1,n] or real [1,u](with n=1).
+function random([n [, u]])
+--- Sets seed for pseudo-random number generator.
+function randomseed(seed)
+--- Returns sine value of angle rad .
+function sin(rad)
+--- Returns square root of v.
+function sqrt(v)
+--- Returns tangent value of angle rad.
+function tan(rad)
diff --git a/modules/lua/api/os.luadoc b/modules/lua/api/os.luadoc
new file mode 100644
index 00000000..cb8ca275
--- /dev/null
+++ b/modules/lua/api/os.luadoc
@@ -0,0 +1,24 @@
+--- Returns CPU time used by program in seconds.
+function clock()
+--- Returns a string or table containing date and time, "*t" returns a table.
+function date([format [, time]])
+--- Returns number of seconds from time t1 to time t2.
+function difftime(t2, t1)
+--- Executes command using C function system, returns status code.
+function execute(command)
+--- Terminates host program with optional code, default is success code.
+function exit([code])
+--- Returns value of environment variable varname. nil if not defined.
+function getenv(varname)
+--- Deletes file with given name, nil if fails.
+function remove(filename)
+--- Renames file oldname to newname, nil if fails.
+function rename(oldname, newname)
+--- Set current locale of program, returns name of new locate or nil.
+function setlocale(locale [, category])
+--- Returns current time(usually seconds) or time as represented by table.
+function time([table])
+---
+-- Returns a string with a filename for a temporary file(dangerous! tmpfile is
+-- better).
+function tmpname()
diff --git a/modules/lua/api/string.luadoc b/modules/lua/api/string.luadoc
new file mode 100644
index 00000000..e1f99e82
--- /dev/null
+++ b/modules/lua/api/string.luadoc
@@ -0,0 +1,33 @@
+--- Returns numerical code, nil if index out of range, default i=1.
+function byte(s [, i])
+--- Returns a string built from 0 or more integers.
+function char(i1, i2, ...)
+--- Returns binary representation of function, used with loadstring.
+function dump(function)
+--- Matches pattern in s, returns start,end indices, else nil.
+function find(s, pattern [, init [, plain]])
+--- Returns formatted string, printf-style.
+function format(formatstring, e1, e2, ...)
+--- Returns iterator function that returns next captures from pattern pat on s.
+function gfind(s, pat)
+--- Returns copy of s with pat replaced by repl, and substitutions made.
+function gsub(s, pat, repl [, n])
+--- Returns string length.
+function len(s)
+--- Returns string with letters in lower case.
+function lower(s)
+--- Returns string with n copies of string s.
+function rep(s, n)
+--- Returns substring from index i to j of s, default j=-1(string length).
+function sub(s, i [, j])
+--- Returns string with letters in upper case.
+function upper(s)
+
+---
+-- Converts a string from one character set to another using iconv().
+-- Valid character sets are ones GLib's g_convert() accepts, typically GNU
+-- iconv's character sets.
+-- @param text The text to convert.
+-- @param to The character set to convert to.
+-- @param from The character set to convert from.
+function iconv(text, to, from) end
diff --git a/modules/lua/api/table.luadoc b/modules/lua/api/table.luadoc
new file mode 100644
index 00000000..81f5a369
--- /dev/null
+++ b/modules/lua/api/table.luadoc
@@ -0,0 +1,22 @@
+--- Returns concatenated table elements i to j separated by sep.
+function concat(table [, sep [, i [, j]]])
+---
+-- Executes f(index,value) over all elements of table, returns first non-nil of
+-- f.
+function foreach(table, f)
+---
+-- Executes f(index,value) in sequential order 1 to n, returns first non-nil of
+-- f.
+function foreachi(table, f)
+---
+-- Returns size of table, or n field, or table.setn value, or 1 less first index
+-- with nil value.
+function getn(table)
+--- Insert value at location pos in table, default pos=n+1.
+function insert(table, [pos,] value)
+--- Removes element at pos from table, default pos=n.
+function remove(table [, pos])
+--- Sets size of table, n field of table if it exists.
+function setn(table, n)
+--- Sorts in-place elements 1 to n, comp(v1,v2) true if v1<v2, default <.
+function sort(table [, comp])
diff --git a/modules/lua/commands.lua b/modules/lua/commands.lua
index 0489ea56..f1902764 100644
--- a/modules/lua/commands.lua
+++ b/modules/lua/commands.lua
@@ -4,6 +4,68 @@
 -- Commands for the lua module.
 module('_m.lua.commands', package.seeall)
 
+-- Markdown:
+-- ## Key Commands
+--
+-- + `Alt+l, m`: Open this module for editing.
+-- + `Alt+l, g`: Goto file being 'require'd on the current line.
+-- + `Shift+Return`: Try to autocomplete an `if`, `for`, etc. statement with
+--   `end`.
+-- + `.`: When to the right of a known identifier, show an autocompletion list
+--   of fields.
+-- + `:`: When to the right of a known identifier, show an autocompletion list
+--   of functions.
+-- + `Tab`: When the caret is to the right of a `(` in a known function call,
+--   show a calltip with documentation for the function.
+--
+-- ## Autocompletion of Fields and Functions
+--
+-- This module parses files in the `api_files` table for LuaDoc documentation.
+-- Currently all Textadept and Lua identifiers are supported.
+--
+-- #### Syntax
+--
+-- Fields are recognized as Lua line comments of the form ``-- * `field_name` ``.
+-- Functions are recognized as Lua functions of the form `function func(args)`
+-- or `function namespace:func(args)`. `.`-completion shows autocompletion for
+-- both fields and functions using the first function syntax. `:`-completion
+-- shows completions for functions only. Any LuaDoc starting with `---` and
+-- including any subsequent comments up until the function declaration will be
+-- shown with a calltip when requested.
+--
+-- In order to be recognized, all comments and functions MUST begin the line.
+--
+-- Syntatically valid Lua code is not necessary for parsing; only the patterns
+-- described above are necessary.
+--
+-- For example:
+--
+-- In file `~/.textadept/modules/foo/foo.luadoc`:
+--
+--     -- * `bar`: Bar field.
+--
+--     --- LuaDoc for bar.
+--     function baz()
+--
+--     ---
+--     -- LuaDoc for foobar.
+--     -- @param barfoo First arg.
+--     function foobar(barfoo)
+--
+--     ---
+--     -- LuaDoc for foo:barbaz.
+--     -- @param foo Foo table.
+--     function foo:barbaz()
+--
+-- In file `_HOME/modules/lua/commands.lua` below `api_files` declaration:
+--
+--     api_files['foo'] = _USERHOME..'/modules/foo/foo.luadoc'
+--
+-- In any Lua file:
+--
+--     foo. -- shows autocompletion list with [bar, baz, foobar].
+--     foo: -- shows autocompletion list with [foobar, barbaz].
+
 local m_editing, m_run = _m.textadept.editing, _m.textadept.run
 -- Comment string tables use lexer names.
 m_editing.comment_string.lua = '--'
@@ -73,6 +135,111 @@ function goto_required()
   end
 end
 
+---
+-- LuaDoc to load API from.
+-- Keys are Lua table names with LuaDoc file values.
+-- @class table
+-- @name api_files
+local api_files = {
+  ['args'] = _HOME..'/core/args.lua',
+  ['buffer'] = _HOME..'/core/.buffer.luadoc',
+  ['events'] = _HOME..'/core/events.lua',
+  ['gui'] = _HOME..'/core/.gui.luadoc',
+  ['gui.find'] = _HOME..'/core/.find.luadoc',
+  ['gui.command_entry'] = _HOME..'/core/.command_entry.luadoc',
+  ['l'] = _HOME..'/lexers/lexer.lua',
+  ['view'] = _HOME..'/core/.view.luadoc',
+}
+-- Add API for loaded textadept modules.
+for p, _ in pairs(package.loaded) do
+  if p:find('^_m%.textadept%.') then
+    api_files[p] = _HOME..'/modules/textadept/'..p:match('[^%.]+$')..'.lua'
+  end
+end
+-- Add Lua API
+local lua = { 'coroutine', 'debug', 'io', 'math', 'os', 'string', 'table' }
+for _, m in ipairs(lua) do
+  api_files[m] = _HOME..'/modules/lua/api/'..m..'.luadoc'
+end
+api_files[''] = _HOME..'/modules/lua/api/_G.luadoc'
+
+local lfs = require 'lfs'
+
+-- Load API.
+local apis = {}
+local current_doc = ''
+local f_args = {}
+for word, api_file in pairs(api_files) do
+  if lfs.attributes(api_file) then
+    apis[word] = { fields = {}, funcs = {} }
+    for line in io.lines(api_file) do
+      if line:match('^%-%- %* `([^`]+)`') then -- field
+        local fields = apis[word].fields
+        fields[#fields + 1] = line:match('^%-%- %* `([^`]+)`')..'?2'
+      elseif line:match('^function ') then -- function
+        local f, n = line:match('^function [%w_]+:(([%w_]+)%([^)]*%))')
+        if not f then
+          f, n = line:match('^function (([%w_]+)%([^)]*%))')
+          local fields = apis[word].fields
+          fields[#fields + 1] = n..'?1'
+        end
+        local funcs = apis[word].funcs
+        funcs[#funcs + 1] = n..'?1'
+        if f and #current_doc > 0 then
+          f = f..current_doc
+          current_doc = ''
+        end
+        local c = line:find(':') and ':' or '.'
+        if word == '' then c = '' end
+        f_args[word..c..n] = f
+      elseif line:match('^%-%-%-? (.+)$') then
+        current_doc = current_doc..'\n'..line:match('^%-%-%-? (.+)$')
+      elseif #current_doc > 0 then
+        current_doc = ''
+      end
+    end
+    table.sort(apis[word].fields)
+    table.sort(apis[word].funcs)
+  end
+end
+
+local f_xpm = '/* XPM */\nstatic char *function[] = {\n/* columns rows colors chars-per-pixel */\n"16 16 5 1",\n"  c black",\n". c #E0BC38",\n"X c #F0DC5C",\n"o c #FCFC80",\n"O c None",\n/* pixels */\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOOO  OOOO",\n"OOOOOOOOO oo  OO",\n"OOOOOOOO ooooo O",\n"OOOOOOO ooooo. O",\n"OOOO  O XXoo.. O",\n"OOO oo  XXX... O",\n"OO ooooo XX.. OO",\n"O ooooo.  X. OOO",\n"O XXoo.. O  OOOO",\n"O XXX... OOOOOOO",\n"O XXX.. OOOOOOOO",\n"OO  X. OOOOOOOOO",\n"OOOO  OOOOOOOOOO"\n};'
+local v_xpm = '/* XPM */\nstatic char *field[] = {\n/* columns rows colors chars-per-pixel */\n"16 16 5 1",\n"  c black",\n". c #8C748C",\n"X c #9C94A4",\n"o c #ACB4C0",\n"O c None",\n/* pixels */\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOOOOOOOOO",\n"OOOOOOOOO  OOOOO",\n"OOOOOOOO oo  OOO",\n"OOOOOOO ooooo OO",\n"OOOOOO ooooo. OO",\n"OOOOOO XXoo.. OO",\n"OOOOOO XXX... OO",\n"OOOOOO XXX.. OOO",\n"OOOOOOO  X. OOOO",\n"OOOOOOOOO  OOOOO",\n"OOOOOOOOOOOOOOOO"\n};'
+
+---
+-- [Local function] Returns word specified by patt behind the caret.
+-- @param patt Lua pattern containing word characters.
+-- @param pos Optional position to start from.
+-- @return word.
+local function prev_word(patt, pos)
+  local e = pos or buffer.current_pos - 1
+  local s = e - 1
+  while s >= 0 and string.char(buffer.char_at[s]):find(patt) do s = s - 1 end
+  return buffer:text_range(s + 1, e)
+end
+
+---
+-- [Local function] Shows autocompletion list.
+-- @param len Length passed to buffer:auto_c_show.
+-- @param completions Table of completions.
+-- @see buffer:auto_c_show.
+local function auto_c_show(len, completions)
+  buffer:clear_registered_images()
+  buffer:register_image(1, f_xpm)
+  buffer:register_image(2, v_xpm)
+  buffer:auto_c_show(len, table.concat(completions, ' '))
+end
+
+events.connect('char_added',
+  function(c) -- show autocomplete list or calltip
+    if c == 46 or c == 58 then -- '.' or ':'
+      if buffer:get_lexer() ~= 'lua' then return end
+      local word = prev_word('[%w_%.]')
+      if word == '' or not apis[word] then return end
+      auto_c_show(0, c == 46 and apis[word].fields or apis[word].funcs)
+    end
+  end)
+
 -- Lua-specific key commands.
 local keys = _G.keys
 if type(keys) == 'table' then
@@ -83,5 +250,20 @@ if type(keys) == 'table' then
       g = { goto_required },
     },
     ['s\n'] = { try_to_autocomplete_end },
+    [not MAC and 'c\n' or 'esc'] = { function() -- complete API
+      local part = prev_word('[%w_]', buffer.current_pos)
+      local pos = buffer.current_pos - #part - 1
+      if pos > 0 then
+        local word = prev_word('[%w_%.]', pos)
+        if word == '' or not apis[word] then return false end -- handle normally
+        local c = buffer.char_at[pos]
+        auto_c_show(#part, c == 46 and apis[word].fields or apis[word].funcs)
+      end
+    end },
+    ['\t'] = { function() -- show API calltip
+      local func = prev_word('[%w_%.:]')
+      if not f_args[func] then return false end -- handle normally
+      buffer:call_tip_show(buffer.current_pos, f_args[func])
+    end },
   }
 end