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
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
<title>LuaCov Reference</title>
<link rel="stylesheet" href="../ldoc.css" type="text/css" />
</head>
<body>
<div id="container">
<div id="product">
<div id="product_logo"></div>
<div id="product_name"><big><b></b></big></div>
<div id="product_description"></div>
</div> <!-- id="product" -->
<div id="main">
<!-- Menu -->
<div id="navigation">
<br/>
<h1>LuaCov</h1>
<ul>
<li><a href="../index.html">Index</a></li>
</ul>
<h2>Contents</h2>
<ul>
<li><a href="#Functions">Functions</a></li>
<li><a href="#Fields">Fields</a></li>
</ul>
<h2>Modules</h2>
<ul class="nowrap">
<li><a href="../modules/luacov.html">luacov</a></li>
<li><a href="../modules/luacov.defaults.html">luacov.defaults</a></li>
<li><a href="../modules/luacov.reporter.html">luacov.reporter</a></li>
<li><strong>luacov.runner</strong></li>
<li><a href="../modules/luacov.stats.html">luacov.stats</a></li>
<li><a href="../modules/luacov.tick.html">luacov.tick</a></li>
</ul>
</div>
<div id="content">
<h1>Module <code>luacov.runner</code></h1>
<p>Statistics collecting module.</p>
<p> Calling the module table is a shortcut to calling the <a href="../modules/luacov.runner.html#init">init</a> function.</p>
<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#file_included">file_included (filename)</a></td>
<td class="summary">Uses LuaCov's configuration to check if a file is included for
coverage data collection.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#update_stats">update_stats (old_stats, extra_stats)</a></td>
<td class="summary">Adds stats to an existing file stats table.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#debug_hook">debug_hook (_, line_nr[, level])</a></td>
<td class="summary">Debug hook set by LuaCov.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#run_report">run_report ([configuration])</a></td>
<td class="summary">Runs the reporter specified in configuration.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#real_name">real_name (filename)</a></td>
<td class="summary">Returns real name for a source file name
using <a href="../modules/luacov.defaults.html#modules">luacov.defaults.modules</a> option.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#load_config">load_config ([configuration])</a></td>
<td class="summary">Loads a valid configuration.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#pause">pause ()</a></td>
<td class="summary">Pauses saving data collected by LuaCov's runner.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#resume">resume ()</a></td>
<td class="summary">Resumes saving data collected by LuaCov's runner.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#with_luacov">with_luacov (f)</a></td>
<td class="summary">Wraps a function, enabling coverage gathering in it explicitly.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#init">init ([configuration])</a></td>
<td class="summary">Initializes LuaCov runner to start collecting data.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#shutdown">shutdown ()</a></td>
<td class="summary">Shuts down LuaCov's runner.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#excludefile">excludefile (name)</a></td>
<td class="summary">Adds a file to the exclude list (see <a href="../modules/luacov.defaults.html#">luacov.defaults</a>).</td>
</tr>
<tr>
<td class="name" nowrap><a href="#includefile">includefile (name)</a></td>
<td class="summary">Adds a file to the include list (see <a href="../modules/luacov.defaults.html#">luacov.defaults</a>).</td>
</tr>
<tr>
<td class="name" nowrap><a href="#excludetree">excludetree (name, level)</a></td>
<td class="summary">Adds a tree to the exclude list (see <a href="../modules/luacov.defaults.html#">luacov.defaults</a>).</td>
</tr>
<tr>
<td class="name" nowrap><a href="#includetree">includetree (name, level)</a></td>
<td class="summary">Adds a tree to the include list (see <a href="../modules/luacov.defaults.html#">luacov.defaults</a>).</td>
</tr>
</table>
<h2><a href="#Fields">Fields</a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#version">version</a></td>
<td class="summary">LuaCov version in <code>MAJOR.MINOR.PATCH</code> format.</td>
</tr>
</table>
<br/>
<br/>
<h2 class="section-header "><a name="Functions"></a>Functions</h2>
<dl class="function">
<dt>
<a name = "file_included"></a>
<strong>file_included (filename)</strong>
</dt>
<dd>
Uses LuaCov's configuration to check if a file is included for
coverage data collection.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">filename</span>
name of the file.
</li>
</ul>
<h3>Returns:</h3>
<ol>
true if file is included, false otherwise.
</ol>
</dd>
<dt>
<a name = "update_stats"></a>
<strong>update_stats (old_stats, extra_stats)</strong>
</dt>
<dd>
Adds stats to an existing file stats table.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">old_stats</span>
stats to be updated.
</li>
<li><span class="parameter">extra_stats</span>
another stats table, will be broken during update.
</li>
</ul>
</dd>
<dt>
<a name = "debug_hook"></a>
<strong>debug_hook (_, line_nr[, level])</strong>
</dt>
<dd>
Debug hook set by LuaCov.
Acknowledges that a line is executed, but does nothing
if called manually before coverage gathering is started.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">_</span>
event type, should always be "line".
</li>
<li><span class="parameter">line_nr</span>
line number.
</li>
<li><span class="parameter">level</span>
passed to debug.getinfo to get name of processed file,
2 by default. Increase it if this function is called manually
from another debug hook.
(<em>optional</em>)
</li>
</ul>
<h3>Usage:</h3>
<ul>
<pre class="example">
<span class="keyword">local</span> <span class="keyword">function</span> custom_hook(_, line)
runner.debug_hook(_, line, <span class="number">3</span>)
extra_processing(line)
<span class="keyword">end</span></pre>
</ul>
</dd>
<dt>
<a name = "run_report"></a>
<strong>run_report ([configuration])</strong>
</dt>
<dd>
Runs the reporter specified in configuration.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">configuration</span>
if string, filename of config file (used to call <a href="../modules/luacov.runner.html#load_config">load_config</a>).
If table then config table (see file <code>luacov.default.lua</code> for an example).
If <code>configuration.reporter</code> is not set, runs the default reporter;
otherwise, it must be a module name in 'luacov.reporter' namespace.
The module must contain 'report' function, which is called without arguments.
(<em>optional</em>)
</li>
</ul>
</dd>
<dt>
<a name = "real_name"></a>
<strong>real_name (filename)</strong>
</dt>
<dd>
Returns real name for a source file name
using <a href="../modules/luacov.defaults.html#modules">luacov.defaults.modules</a> option.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">filename</span>
name of the file.
</li>
</ul>
</dd>
<dt>
<a name = "load_config"></a>
<strong>load_config ([configuration])</strong>
</dt>
<dd>
Loads a valid configuration.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">configuration</span>
user provided config (config-table or filename)
(<em>optional</em>)
</li>
</ul>
<h3>Returns:</h3>
<ol>
existing configuration if already set, otherwise loads a new
config from the provided data or the defaults.
When loading a new config, if some options are missing, default values
from <a href="../modules/luacov.defaults.html#">luacov.defaults</a> are used instead.
</ol>
</dd>
<dt>
<a name = "pause"></a>
<strong>pause ()</strong>
</dt>
<dd>
Pauses saving data collected by LuaCov's runner.
Allows other processes to write to the same stats file.
Data is still collected during pause.
</dd>
<dt>
<a name = "resume"></a>
<strong>resume ()</strong>
</dt>
<dd>
Resumes saving data collected by LuaCov's runner.
</dd>
<dt>
<a name = "with_luacov"></a>
<strong>with_luacov (f)</strong>
</dt>
<dd>
Wraps a function, enabling coverage gathering in it explicitly.
LuaCov gathers coverage using a debug hook, and patches coroutine
library to set it on created threads when under standard Lua, where each
coroutine has its own hook. If a coroutine is created using Lua C API
or before the monkey-patching, this wrapper should be applied to the
main function of the coroutine. Under LuaJIT this function is redundant,
as there is only one, global debug hook.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">f</span>
a function
</li>
</ul>
<h3>Returns:</h3>
<ol>
a function that enables coverage gathering and calls the original function.
</ol>
<h3>Usage:</h3>
<ul>
<pre class="example"><span class="keyword">local</span> coro = <span class="global">coroutine</span>.create(runner.with_luacov(func))</pre>
</ul>
</dd>
<dt>
<a name = "init"></a>
<strong>init ([configuration])</strong>
</dt>
<dd>
Initializes LuaCov runner to start collecting data.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">configuration</span>
if string, filename of config file (used to call <a href="../modules/luacov.runner.html#load_config">load_config</a>).
If table then config table (see file <code>luacov.default.lua</code> for an example)
(<em>optional</em>)
</li>
</ul>
</dd>
<dt>
<a name = "shutdown"></a>
<strong>shutdown ()</strong>
</dt>
<dd>
Shuts down LuaCov's runner.
This should only be called from daemon processes or sandboxes which have
disabled os.exit and other hooks that are used to determine shutdown.
</dd>
<dt>
<a name = "excludefile"></a>
<strong>excludefile (name)</strong>
</dt>
<dd>
Adds a file to the exclude list (see <a href="../modules/luacov.defaults.html#">luacov.defaults</a>).
If passed a function, then through debuginfo the source filename is collected. In case of a table
it will recursively search the table for a function, which is then resolved to a filename through debuginfo.
If the parameter is a string, it will first check if a file by that name exists. If it doesn't exist
it will call <code>require(name)</code> to load a module by that name, and the result of require (function or
table expected) is used as described above to get the sourcefile.
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">name</span>
<ul>
<li>string; literal filename,</li>
<li>string; modulename as passed to require(),</li>
<li>function; where containing file is looked up,</li>
<li>table; module table where containing file is looked up</li>
</ul>
</li>
</ul>
<h3>Returns:</h3>
<ol>
the pattern as added to the list, or nil + error
</ol>
</dd>
<dt>
<a name = "includefile"></a>
<strong>includefile (name)</strong>
</dt>
<dd>
Adds a file to the include list (see <a href="../modules/luacov.defaults.html#">luacov.defaults</a>).
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">name</span>
see <a href="../modules/luacov.runner.html#excludefile">excludefile</a>
</li>
</ul>
<h3>Returns:</h3>
<ol>
the pattern as added to the list, or nil + error
</ol>
</dd>
<dt>
<a name = "excludetree"></a>
<strong>excludetree (name, level)</strong>
</dt>
<dd>
Adds a tree to the exclude list (see <a href="../modules/luacov.defaults.html#">luacov.defaults</a>).
If <code>name = 'luacov'</code> and <code>level = nil</code> then
module 'luacov' (luacov.lua) and the tree 'luacov' (containing <code>luacov/runner.lua</code> etc.) is excluded.
If <code>name = 'pl.path'</code> and <code>level = true</code> then
module 'pl' (pl.lua) and the tree 'pl' (containing <code>pl/path.lua</code> etc.) is excluded.
NOTE: in case of an 'init.lua' file, the 'level' parameter will always be set
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">name</span>
see <a href="../modules/luacov.runner.html#excludefile">excludefile</a>
</li>
<li><span class="parameter">level</span>
if truthy then one level up is added, including the tree
</li>
</ul>
<h3>Returns:</h3>
<ol>
the 2 patterns as added to the list (file and tree), or nil + error
</ol>
</dd>
<dt>
<a name = "includetree"></a>
<strong>includetree (name, level)</strong>
</dt>
<dd>
Adds a tree to the include list (see <a href="../modules/luacov.defaults.html#">luacov.defaults</a>).
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">name</span>
see <a href="../modules/luacov.runner.html#excludefile">excludefile</a>
</li>
<li><span class="parameter">level</span>
see <a href="../modules/luacov.runner.html#includetree">includetree</a>
</li>
</ul>
<h3>Returns:</h3>
<ol>
the 2 patterns as added to the list (file and tree), or nil + error
</ol>
</dd>
</dl>
<h2 class="section-header "><a name="Fields"></a>Fields</h2>
<dl class="function">
<dt>
<a name = "version"></a>
<strong>version</strong>
</dt>
<dd>
LuaCov version in <code>MAJOR.MINOR.PATCH</code> format.
</dd>
</dl>
</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
<i style="float:right;">Last updated 2016-04-18 11:50:47 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
|
