Repository navigation
Expand file tree
/
Copy pathlang.lua
More file actions
260 lines (219 loc) · 7.08 KB
/
Copy pathlang.lua
File metadata and controls
260 lines (219 loc) · 7.08 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
------------
-- Language-dependent parsing of code.
-- This encapsulates the different strategies needed for parsing C and Lua
-- source code.
local class = require 'pl.class'
local utils = require 'pl.utils'
local tools = require 'ldoc.tools'
local lexer = require 'ldoc.lexer'
local tnext = lexer.skipws
class.Lang()
function Lang:trim_comment (s)
return s:gsub(self.line_comment,'')
end
function Lang:start_comment (v)
local line = v:match (self.start_comment_)
local block = v:match(self.block_comment)
return line or block, block
end
function Lang:empty_comment (v)
return v:match(self.empty_comment_)
end
function Lang:grab_block_comment(v,tok)
v = v:gsub(self.block_comment,'')
return tools.grab_block_comment(v,tok,self.end_comment)
end
function Lang:find_module(tok,t,v)
return '...',t,v
end
function Lang:item_follows(t,v)
return false
end
function Lang:finalize()
self.empty_comment_ = self.start_comment_..'%s*$'
end
function Lang:search_for_token (tok,type,value,t,v)
while t and not (t == type and v == value) do
if t == 'comment' and self:start_comment(v) then return nil,t,v end
t,v = tnext(tok)
end
return t ~= nil,t,v
end
function Lang:parse_extra (tags,tok)
end
function Lang:is_module_modifier ()
return false
end
function Lang:parse_module_modifier (tags, tok)
return nil, "@usage or @exports deduction not implemented for this language"
end
class.Lua(Lang)
function Lua:_init()
self.line_comment = '^%-%-+' -- used for stripping
self.start_comment_ = '^%-%-%-+' -- used for doc comment line start
self.block_comment = '^%-%-%[=*%[%-+' -- used for block doc comments
self:finalize()
end
function Lua.lexer(fname)
local f,e = io.open(fname)
if not f then quit(e) end
return lexer.lua(f,{}),f
end
function Lua:grab_block_comment(v,tok)
local equals = v:match('^%-%-%[(=*)%[')
v = v:gsub(self.block_comment,'')
return tools.grab_block_comment(v,tok,'%]'..equals..'%]')
end
function Lua:parse_module_call(tok,t,v)
t,v = tnext(tok)
if t == '(' then t,v = tnext(tok) end
if t == 'string' then -- explicit name, cool
return v,t,v
elseif t == '...' then -- we have to guess!
return '...',t,v
end
end
-- If a module name was not provided, then we look for an explicit module()
-- call. However, we should not try too hard; if we hit a doc comment then
-- we should go back and process it. Likewise, module(...) also means
-- that we must infer the module name.
function Lua:find_module(tok,t,v)
local res
res,t,v = self:search_for_token(tok,'iden','module',t,v)
if not res then return nil,t,v end
return self:parse_module_call(tok,t,v)
end
local function parse_lua_parameters (tags,tok)
tags.formal_args = tools.get_parameters(tok)
tags:add('class','function')
end
local function parse_lua_function_header (tags,tok)
if not tags.name then
tags:add('name',tools.get_fun_name(tok))
end
if not tags.name then return 'function has no name' end
parse_lua_parameters(tags,tok)
end
local function parse_lua_table (tags,tok)
tags.formal_args = tools.get_parameters(tok,'}',function(s)
return s == ',' or s == ';'
end)
end
--------------- function and variable inferrence -----------
-- After a doc comment, there may be a local followed by:
-- [1] (l)function: function NAME
-- [2] (l)function: NAME = function
-- [3] table: NAME = {
-- [4] field: NAME = <anything else> (this is a module-level field)
--
-- Depending on the case successfully detected, returns a function which
-- will be called later to fill in inferred item tags
function Lua:item_follows(t,v,tok)
local parser, case
local is_local = t == 'keyword' and v == 'local'
if is_local then t,v = tnext(tok) end
if t == 'keyword' and v == 'function' then -- case [1]
case = 1
parser = parse_lua_function_header
elseif t == 'iden' then
local name,t,v = tools.get_fun_name(tok,v)
if t ~= '=' then return nil end -- probably invalid code...
t,v = tnext(tok)
if t == 'keyword' and v
9BF9
== 'function' then -- case [2]
tnext(tok) -- skip '('
case = 2
parser = function(tags,tok)
tags:add('name',name)
parse_lua_parameters(tags,tok)
end
elseif t == '{' then -- case [3]
case = 3
parser = function(tags,tok)
tags:add('class','table')
tags:add('name',name)
parse_lua_table (tags,tok)
end
else -- case [4]
case = 4
parser = function(tags)
tags:add('class','field')
tags:add('name',name)
end
end
elseif t == 'keyword' and v == 'return' then
t, v = tnext(tok)
if t == 'keyword' and v == 'function' then
-- return function(a, b, c)
tnext(tok) -- skip '('
case = 2
parser = parse_lua_parameters
elseif t == '{' then
-- return {...}
case = 5
parser = function(tags,tok)
tags:add('class','table')
parse_lua_table(tags,tok)
end
else
return nil
end
end
return parser, is_local, case
end
-- we only call the function returned by the item_follows above if there
-- is not already a name and a type.
-- Otherwise, this is called. Currrently only tries to fill in the fields
-- of a table from a table definition as identified above
function Lua:parse_extra (tags,tok,case)
if tags.class == 'table' and not tags.field and case == 3 then
parse_lua_table(tags,tok)
end
end
-- For Lua, a --- @usage comment means that a long
-- string containing the usage follows, which we
-- use to update the module usage tag. Likewise, the @export
-- tag alone in a doc comment refers to the following returned
-- Lua table of functions
function Lua:is_module_modifier (tags)
return tags.summary == '' and (tags.usage or tags.export)
end
-- Allow for private name convention.
function Lua:is_private_var (name)
return name:match '^_' or name:match '_$'
end
function Lua:parse_module_modifier (tags, tok, F)
if tags.usage then
if tags.class ~= 'field' then return nil,"cannot deduce @usage" end
local t1= tnext(tok)
if t1 ~= '[' then return nil, t1..' '..': not a long string' end
t, v = tools.grab_block_comment('',tok,'%]%]')
return true, v, 'usage'
elseif tags.export then
if tags.class ~= 'table' then return nil, "cannot deduce @export" end
for f in tags.formal_args:iter() do
if not self:is_private_var(f) then
F:export_item(f)
end
end
return true
end
end
-- note a difference here: we scan C/C++ code in full-text mode, not line by line.
-- This is because we can't detect multiline comments in line mode
class.CC(Lang)
function CC:_init()
self.line_comment = '^//+'
self.start_comment_ = '^///+'
self.block_comment = '^/%*%*+'
self:finalize()
end
function CC.lexer(f)
f,err = utils.readfile(f)
if not f then quit(err) end
return lexer.cpp(f,{})
end
function CC:grab_block_comment(v,tok)
v = v:gsub(self.block_comment,'')
return 'comment',v:sub(1,-3)
end
return { lua = Lua(), cc = CC() }