Merge remote-tracking branch 'upstream/master' into usermarksusermarks

1 files changed, 159 insertions, 213 deletions

diff --git a/scripts/lua2dox.lua b/scripts/lua2dox.lua
index 6a206066b8..19f8f8141d 100644
--- a/scripts/lua2dox.lua
+++ b/scripts/lua2dox.lua
@@ -27,14 +27,13 @@ http://search.cpan.org/~alec/Doxygen-Lua-0.02/lib/Doxygen/Lua.pm
 Running
 -------
 
-This file "lua2dox.lua" gets called by "lua2dox_filter" (bash).
+This script "lua2dox.lua" gets called by "gen_vimdoc.py".
 
 Doxygen must be on your system. You can experiment like so:
 
 - Run "doxygen -g" to create a default Doxyfile.
-- Then alter it to let it recognise lua. Add the two following lines:
+- Then alter it to let it recognise lua. Add the following line:
     FILE_PATTERNS   = *.lua
-    FILTER_PATTERNS = *.lua=lua2dox_filter
 - Then run "doxygen".
 
 The core function reads the input file (filename or stdin) and outputs some pseudo C-ish language.
@@ -50,108 +49,46 @@ However I have put in a hack that will insert the "missing" close paren.
 The effect is that you will get the function documented, but not with the parameter list you might expect.
 ]]
 
-local function class(BaseClass, ClassInitialiser)
-  local newClass = {}    -- a new class newClass
-  if not ClassInitialiser and type(BaseClass) == 'function' then
-    ClassInitialiser = BaseClass
-    BaseClass = nil
-  elseif type(BaseClass) == 'table' then
-    -- our new class is a shallow copy of the base class!
-    for i,v in pairs(BaseClass) do
-      newClass[i] = v
-    end
-    newClass._base = BaseClass
-  end
+local function class()
+  local newClass = {} -- a new class newClass
   -- the class will be the metatable for all its newInstanceects,
   -- and they will look up their methods in it.
   newClass.__index = newClass
 
   -- expose a constructor which can be called by <classname>(<args>)
-  local classMetatable = {}
-  classMetatable.__call = function(class_tbl, ...)
-    local newInstance = {}
-    setmetatable(newInstance,newClass)
-    --if init then
-    --  init(newInstance,...)
-    if class_tbl.init then
-      class_tbl.init(newInstance,...)
-    else
-      -- make sure that any stuff from the base class is initialized!
-      if BaseClass and BaseClass.init then
-        BaseClass.init(newInstance, ...)
+  setmetatable(newClass, {
+    __call = function(class_tbl, ...)
+      local newInstance = {}
+      setmetatable(newInstance, newClass)
+      --if init then
+      --  init(newInstance,...)
+      if class_tbl.init then
+        class_tbl.init(newInstance, ...)
       end
+      return newInstance
     end
-    return newInstance
-  end
-  newClass.init = ClassInitialiser
-  newClass.is_a = function(this, klass)
-    local thisMetatable = getmetatable(this)
-    while thisMetatable do
-      if thisMetatable == klass then
-        return true
-      end
-      thisMetatable = thisMetatable._base
-    end
-    return false
-  end
-  setmetatable(newClass, classMetatable)
+  })
   return newClass
 end
 
---! \class TCore_Clock
---! \brief a clock
-local TCore_Clock = class()
-
---! \brief get the current time
-function TCore_Clock.GetTimeNow()
-  local gettimeofday = os.gettimeofday  -- luacheck: ignore 143 Accessing an undefined field of a global variable.
-  if gettimeofday then
-    return gettimeofday()
-  else
-    return os.time()
-  end
-end
-
---! \brief constructor
-function TCore_Clock.init(this,T0)
-  if T0 then
-    this.t0 = T0
-  else
-    this.t0 = TCore_Clock.GetTimeNow()
-  end
-end
-
---! \brief get time string
-function TCore_Clock.getTimeStamp(this,T0)
-  local t0
-  if T0 then
-    t0 = T0
-  else
-    t0 = this.t0
-  end
-  return os.date('%c %Z',t0)
-end
-
-
 --! \brief write to stdout
 local function TCore_IO_write(Str)
-  if (Str) then
+  if Str then
     io.write(Str)
   end
 end
 
 --! \brief write to stdout
 local function TCore_IO_writeln(Str)
-  if (Str) then
+  if Str then
     io.write(Str)
   end
-  io.write("\n")
+  io.write('\n')
 end
 
-
 --! \brief trims a string
 local function string_trim(Str)
-  return Str:match("^%s*(.-)%s*$")
+  return Str:match('^%s*(.-)%s*$')
 end
 
 --! \brief split a string
@@ -159,46 +96,26 @@ end
 --! \param Str
 --! \param Pattern
 --! \returns table of string fragments
+---@return string[]
 local function string_split(Str, Pattern)
   local splitStr = {}
-  local fpat = "(.-)" .. Pattern
+  local fpat = '(.-)' .. Pattern
   local last_end = 1
-  local str, e, cap = string.find(Str,fpat, 1)
+  local str, e, cap = string.find(Str, fpat, 1)
   while str do
-    if str ~= 1 or cap ~= "" then
-      table.insert(splitStr,cap)
+    if str ~= 1 or cap ~= '' then
+      table.insert(splitStr, cap)
     end
-    last_end = e+1
-    str, e, cap = string.find(Str,fpat, last_end)
+    last_end = e + 1
+    str, e, cap = string.find(Str, fpat, last_end)
   end
   if last_end <= #Str then
-    cap = string.sub(Str,last_end)
+    cap = string.sub(Str, last_end)
     table.insert(splitStr, cap)
   end
   return splitStr
 end
 
-
---! \class TCore_Commandline
---! \brief reads/parses commandline
-local TCore_Commandline = class()
-
---! \brief constructor
-function TCore_Commandline.init(this)
-  this.argv = arg
-  this.parsed = {}
-  this.params = {}
-end
-
---! \brief get value
-function TCore_Commandline.getRaw(this,Key,Default)
-  local val = this.argv[Key]
-  if not val then
-    val = Default
-  end
-  return val
-end
-
 -------------------------------
 --! \brief file buffer
 --!
@@ -208,14 +125,13 @@ local TStream_Read = class()
 --! \brief get contents of file
 --!
 --! \param Filename name of file to read (or nil == stdin)
-function    TStream_Read.getContents(this,Filename)
-  assert(Filename)
+function TStream_Read.getContents(this, Filename)
+  assert(Filename, ('invalid file: %s'):format(Filename))
   -- get lines from file
   -- syphon lines to our table
-  --TCore_Debug_show_var('Filename',Filename)
-  local filecontents={}
+  local filecontents = {}
   for line in io.lines(Filename) do
-    table.insert(filecontents,line)
+    table.insert(filecontents, line)
   end
 
   if filecontents then
@@ -240,7 +156,7 @@ function TStream_Read.getLine(this)
     this.currentLine = nil
   else
     -- get line
-    if this.currentLineNo<=this.contentsLen then
+    if this.currentLineNo <= this.contentsLen then
       line = this.filecontents[this.currentLineNo]
       this.currentLineNo = this.currentLineNo + 1
     else
@@ -251,13 +167,13 @@ function TStream_Read.getLine(this)
 end
 
 --! \brief save line fragment
-function TStream_Read.ungetLine(this,LineFrag)
+function TStream_Read.ungetLine(this, LineFrag)
   this.currentLine = LineFrag
 end
 
 --! \brief is it eof?
 function TStream_Read.eof(this)
-  if this.currentLine or this.currentLineNo<=this.contentsLen then
+  if this.currentLine or this.currentLineNo <= this.contentsLen then
     return false
   end
   return true
@@ -272,32 +188,32 @@ function TStream_Write.init(this)
 end
 
 --! \brief write immediately
-function TStream_Write.write(_,Str)
+function TStream_Write.write(_, Str)
   TCore_IO_write(Str)
 end
 
 --! \brief write immediately
-function TStream_Write.writeln(_,Str)
+function TStream_Write.writeln(_, Str)
   TCore_IO_writeln(Str)
 end
 
 --! \brief write immediately
-function TStream_Write.writelnComment(_,Str)
+function TStream_Write.writelnComment(_, Str)
   TCore_IO_write('// ZZ: ')
   TCore_IO_writeln(Str)
 end
 
 --! \brief write to tail
-function TStream_Write.writelnTail(this,Line)
+function TStream_Write.writelnTail(this, Line)
   if not Line then
     Line = ''
   end
-  table.insert(this.tailLine,Line)
+  table.insert(this.tailLine, Line)
 end
 
 --! \brief output tail lines
 function TStream_Write.write_tailLines(this)
-  for _,line in ipairs(this.tailLine) do
+  for _, line in ipairs(this.tailLine) do
     TCore_IO_writeln(line)
   end
   TCore_IO_write('// Lua2DoX new eof')
@@ -307,9 +223,9 @@ end
 local TLua2DoX_filter = class()
 
 --! \brief allow us to do errormessages
-function TLua2DoX_filter.warning(this,Line,LineNo,Legend)
+function TLua2DoX_filter.warning(this, Line, LineNo, Legend)
   this.outStream:writelnTail(
-  '//! \todo warning! ' .. Legend .. ' (@' .. LineNo .. ')"' .. Line .. '"'
+    '//! \todo warning! ' .. Legend .. ' (@' .. LineNo .. ')"' .. Line .. '"'
   )
 end
 
@@ -318,47 +234,47 @@ end
 --! If the string has a comment on the end, this trims it off.
 --!
 local function TString_removeCommentFromLine(Line)
-  local pos_comment = string.find(Line,'%-%-')
+  local pos_comment = string.find(Line, '%-%-')
   local tailComment
   if pos_comment then
-    Line = string.sub(Line,1,pos_comment-1)
-    tailComment = string.sub(Line,pos_comment)
+    Line = string.sub(Line, 1, pos_comment - 1)
+    tailComment = string.sub(Line, pos_comment)
   end
-  return Line,tailComment
+  return Line, tailComment
 end
 
 --! \brief get directive from magic
 local function getMagicDirective(Line)
-  local macro,tail
+  local macro, tail
   local macroStr = '[\\@]'
-  local pos_macro = string.find(Line,macroStr)
+  local pos_macro = string.find(Line, macroStr)
   if pos_macro then
     --! ....\\ macro...stuff
     --! ....\@ macro...stuff
-    local line = string.sub(Line,pos_macro+1)
-    local space = string.find(line,'%s+')
+    local line = string.sub(Line, pos_macro + 1)
+    local space = string.find(line, '%s+')
     if space then
-      macro = string.sub(line,1,space-1)
-      tail  = string_trim(string.sub(line,space+1))
+      macro = string.sub(line, 1, space - 1)
+      tail = string_trim(string.sub(line, space + 1))
     else
       macro = line
-      tail  = ''
+      tail = ''
     end
   end
-  return macro,tail
+  return macro, tail
 end
 
 --! \brief check comment for fn
-local function checkComment4fn(Fn_magic,MagicLines)
+local function checkComment4fn(Fn_magic, MagicLines)
   local fn_magic = Fn_magic
   --    TCore_IO_writeln('// checkComment4fn "' .. MagicLines .. '"')
 
-  local magicLines = string_split(MagicLines,'\n')
+  local magicLines = string_split(MagicLines, '\n')
 
-  local macro,tail
+  local macro, tail
 
   for _, line in ipairs(magicLines) do
-    macro,tail = getMagicDirective(line)
+    macro, tail = getMagicDirective(line)
     if macro == 'fn' then
       fn_magic = tail
       --    TCore_IO_writeln('// found fn "' .. fn_magic .. '"')
@@ -369,13 +285,16 @@ local function checkComment4fn(Fn_magic,MagicLines)
 
   return fn_magic
 end
+
+local types = { 'number', 'string', 'table', 'list', 'boolean', 'function' }
+
 --! \brief run the filter
-function TLua2DoX_filter.readfile(this,AppStamp,Filename)
+function TLua2DoX_filter.readfile(this, AppStamp, Filename)
   local inStream = TStream_Read()
   local outStream = TStream_Write()
   this.outStream = outStream -- save to this obj
 
-  if (inStream:getContents(Filename)) then
+  if inStream:getContents(Filename) then
     -- output the file
     local line
     local fn_magic -- function name/def from  magic comment
@@ -385,13 +304,14 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename)
     outStream:writelnTail('// #######################')
     outStream:writelnTail()
 
-    local state = ''  -- luacheck: ignore 231 variable is set but never accessed.
+    local state = '' -- luacheck: ignore 231 variable is set but never accessed.
     local offset = 0
+    local generic = {}
+    local l = 0
     while not (inStream:eof()) do
       line = string_trim(inStream:getLine())
-      --            TCore_Debug_show_var('inStream',inStream)
-      --            TCore_Debug_show_var('line',line )
-      if string.sub(line,1,2) == '--' then -- it's a comment
+      l = l + 1
+      if string.sub(line, 1, 2) == '--' then -- it's a comment
         -- Allow people to write style similar to EmmyLua (since they are basically the same)
         -- instead of silently skipping things that start with ---
         if string.sub(line, 3, 3) == '@' then -- it's a magic comment
@@ -405,55 +325,87 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename)
           local magic = string.sub(line, 4 + offset)
 
           local magic_split = string_split(magic, ' ')
-
-          local type_index = 2
           if magic_split[1] == 'param' then
-            type_index = type_index + 1
+            for _, type in ipairs(types) do
+              magic = magic:gsub('^param%s+([a-zA-Z_?]+)%s+.*%((' .. type .. ')%)', 'param %1 %2')
+              magic =
+                magic:gsub('^param%s+([a-zA-Z_?]+)%s+.*%((' .. type .. '|nil)%)', 'param %1 %2')
+            end
+            magic_split = string_split(magic, ' ')
+          elseif magic_split[1] == 'return' then
+            for _, type in ipairs(types) do
+              magic = magic:gsub('^return%s+.*%((' .. type .. ')%)', 'return %1')
+              magic = magic:gsub('^return%s+.*%((' .. type .. '|nil)%)', 'return %1')
+            end
+            magic_split = string_split(magic, ' ')
           end
 
-          if magic_split[type_index] == 'number' or
-              magic_split[type_index] == 'number|nil' or
-              magic_split[type_index] == 'string' or
-              magic_split[type_index] == 'string|nil' or
-              magic_split[type_index] == 'table' or
-              magic_split[type_index] == 'table|nil' or
-              magic_split[type_index] == 'boolean' or
-              magic_split[type_index] == 'boolean|nil' or
-              magic_split[type_index] == 'function' or
-              magic_split[type_index] == 'function|nil'
-              then
-            magic_split[type_index] = '(' .. magic_split[type_index] .. ')'
+          if magic_split[1] == 'generic' then
+            local generic_name, generic_type = line:match('@generic%s*(%w+)%s*:?%s*(.*)')
+            if generic_type == '' then
+              generic_type = 'any'
+            end
+            generic[generic_name] = generic_type
+          else
+            local type_index = 2
+            if magic_split[1] == 'param' then
+              type_index = type_index + 1
+            end
+
+            if magic_split[type_index] then
+              -- fix optional parameters
+              if magic_split[type_index] and magic_split[2]:find('%?$') then
+                if not magic_split[type_index]:find('nil') then
+                  magic_split[type_index] = magic_split[type_index] .. '|nil'
+                end
+                magic_split[2] = magic_split[2]:sub(1, -2)
+              end
+              -- replace generic types
+              if magic_split[type_index] then
+                for k, v in pairs(generic) do
+                  magic_split[type_index] = magic_split[type_index]:gsub(k, v)
+                end
+              end
+              -- surround some types by ()
+              for _, type in ipairs(types) do
+                magic_split[type_index] =
+                  magic_split[type_index]:gsub('^(' .. type .. '|nil):?$', '(%1)')
+                magic_split[type_index] =
+                  magic_split[type_index]:gsub('^(' .. type .. '):?$', '(%1)')
+              end
+            end
+
+            magic = table.concat(magic_split, ' ')
+
+            outStream:writeln('/// @' .. magic)
+            fn_magic = checkComment4fn(fn_magic, magic)
           end
-          magic = table.concat(magic_split, ' ')
-
-          outStream:writeln('/// @' .. magic)
-          fn_magic = checkComment4fn(fn_magic,magic)
-        elseif string.sub(line,3,3)=='-' then -- it's a nonmagic doc comment
-          local comment = string.sub(line,4)
-          outStream:writeln('/// '.. comment)
-        elseif string.sub(line,3,4)=='[[' then -- it's a long comment
-          line = string.sub(line,5) -- nibble head
+        elseif string.sub(line, 3, 3) == '-' then -- it's a nonmagic doc comment
+          local comment = string.sub(line, 4)
+          outStream:writeln('/// ' .. comment)
+        elseif string.sub(line, 3, 4) == '[[' then -- it's a long comment
+          line = string.sub(line, 5) -- nibble head
           local comment = ''
-          local closeSquare,hitend,thisComment
-          while (not hitend) and (not inStream:eof()) do
-            closeSquare = string.find(line,']]')
+          local closeSquare, hitend, thisComment
+          while not hitend and (not inStream:eof()) do
+            closeSquare = string.find(line, ']]')
             if not closeSquare then -- need to look on another line
               thisComment = line .. '\n'
               line = inStream:getLine()
             else
-              thisComment = string.sub(line,1,closeSquare-1)
+              thisComment = string.sub(line, 1, closeSquare - 1)
               hitend = true
 
               -- unget the tail of the line
               -- in most cases it's empty. This may make us less efficient but
               -- easier to program
-              inStream:ungetLine(string_trim(string.sub(line,closeSquare+2)))
+              inStream:ungetLine(string_trim(string.sub(line, closeSquare + 2)))
             end
             comment = comment .. thisComment
           end
-          if string.sub(comment,1,1)=='@' then -- it's a long magic comment
+          if string.sub(comment, 1, 1) == '@' then -- it's a long magic comment
             outStream:write('/*' .. comment .. '*/  ')
-            fn_magic = checkComment4fn(fn_magic,comment)
+            fn_magic = checkComment4fn(fn_magic, comment)
           else -- discard
             outStream:write('/* zz:' .. comment .. '*/  ')
             fn_magic = nil
@@ -467,76 +419,74 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename)
           fn_magic = nil
         end
       elseif string.find(line, '^function') or string.find(line, '^local%s+function') then
-        state = 'in_function'  -- it's a function
-        local pos_fn = string.find(line,'function')
+        generic = {}
+        state = 'in_function' -- it's a function
+        local pos_fn = string.find(line, 'function')
         -- function
         -- ....v...
         if pos_fn then
           -- we've got a function
-          local fn_type
-          if string.find(line,'^local%s+') then
-            fn_type = ''--'static ' -- static functions seem to be excluded
-          else
-            fn_type = ''
-          end
-          local fn = TString_removeCommentFromLine(string_trim(string.sub(line,pos_fn+8)))
+          local fn = TString_removeCommentFromLine(string_trim(string.sub(line, pos_fn + 8)))
           if fn_magic then
             fn = fn_magic
           end
 
-          if string.sub(fn,1,1)=='(' then
+          if string.sub(fn, 1, 1) == '(' then
             -- it's an anonymous function
             outStream:writelnComment(line)
           else
             -- fn has a name, so is interesting
 
             -- want to fix for iffy declarations
-            local open_paren = string.find(fn,'[%({]')
+            local open_paren = string.find(fn, '[%({]')
             if open_paren then
               -- we might have a missing close paren
-              if not string.find(fn,'%)') then
+              if not string.find(fn, '%)') then
                 fn = fn .. ' ___MissingCloseParenHere___)'
               end
             end
 
             -- Big hax
-            if string.find(fn, ":") then
+            if string.find(fn, ':') then
               -- TODO: We need to add a first parameter of "SELF" here
               -- local colon_place = string.find(fn, ":")
               -- local name = string.sub(fn, 1, colon_place)
-              fn = fn:gsub(":", ".", 1)
-              outStream:writeln("/// @param self")
+              fn = fn:gsub(':', '.', 1)
+              outStream:writeln('/// @param self')
 
-              local paren_start = string.find(fn, "(", 1, true)
-              local paren_finish = string.find(fn, ")", 1, true)
+              local paren_start = string.find(fn, '(', 1, true)
+              local paren_finish = string.find(fn, ')', 1, true)
 
               -- Nothing in between the parens
               local comma
               if paren_finish == paren_start + 1 then
-                comma = ""
+                comma = ''
               else
-                comma = ", "
+                comma = ', '
               end
-              fn = string.sub(fn, 1, paren_start) .. "self" .. comma .. string.sub(fn, paren_start + 1)
+              fn = string.sub(fn, 1, paren_start)
+                .. 'self'
+                .. comma
+                .. string.sub(fn, paren_start + 1)
             end
 
             -- add vanilla function
-            outStream:writeln(fn_type .. 'function ' .. fn .. '{}')
+            outStream:writeln('function ' .. fn .. '{}')
           end
         else
-          this:warning(inStream:getLineNo(),'something weird here')
+          this:warning(inStream:getLineNo(), 'something weird here')
         end
-        fn_magic = nil -- mustn't indavertently use it again
+        fn_magic = nil -- mustn't inadvertently use it again
 
       -- TODO: If we can make this learn how to generate these, that would be helpful.
       -- elseif string.find(line, "^M%['.*'%] = function") then
       --   state = 'in_function'  -- it's a function
       --   outStream:writeln("function textDocument/publishDiagnostics(...){}")
 
-      --   fn_magic = nil -- mustn't indavertently use it again
+      --   fn_magic = nil -- mustn't inadvertently use it again
       else
-        state = ''  -- unknown
-        if #line>0 then  -- we don't know what this line means, so just comment it out
+        state = '' -- unknown
+        if #line > 0 then -- we don't know what this line means, so just comment it out
           outStream:writeln('// zz: ' .. line)
         else
           outStream:writeln() -- keep this line blank
@@ -556,16 +506,14 @@ local TApp = class()
 
 --! \brief constructor
 function TApp.init(this)
-  local t0 = TCore_Clock()
-  this.timestamp = t0:getTimeStamp()
+  this.timestamp = os.date('%c %Z', os.time())
   this.name = 'Lua2DoX'
   this.version = '0.2 20130128'
   this.copyright = 'Copyright (c) Simon Dales 2012-13'
 end
 
 function TApp.getRunStamp(this)
-  return this.name .. ' (' .. this.version .. ') '
-  .. this.timestamp
+  return this.name .. ' (' .. this.version .. ') ' .. this.timestamp
 end
 
 function TApp.getVersion(this)
@@ -579,15 +527,14 @@ end
 local This_app = TApp()
 
 --main
-local cl = TCore_Commandline()
 
-local argv1 = cl:getRaw(2)
+local argv1 = arg[1]
 if argv1 == '--help' then
   TCore_IO_writeln(This_app:getVersion())
   TCore_IO_writeln(This_app:getCopyright())
   TCore_IO_writeln([[
   run as:
-  lua2dox_filter <param>
+  nvim -l scripts/lua2dox.lua <param>
   --------------
   Param:
   <filename> : interprets filename
@@ -602,8 +549,7 @@ else
   local filename = argv1
 
   local filter = TLua2DoX_filter()
-  filter:readfile(appStamp,filename)
+  filter:readfile(appStamp, filename)
 end
 
-
 --eof