Module luacov.runner
Statistics collecting module.
Calling the module table is a shortcut to calling the init function.
Functions
| file_included (filename) | Uses LuaCov's configuration to check if a file is included for coverage data collection. | 
| update_stats (old_stats, extra_stats) | Adds stats to an existing file stats table. | 
| debug_hook (_, line_nr[, level]) | Debug hook set by LuaCov. | 
| run_report ([configuration]) | Runs the reporter specified in configuration. | 
| real_name (filename) | Returns real name for a source file name using luacov.defaults.modules option. | 
| load_config ([configuration]) | Loads a valid configuration. | 
| pause () | Pauses saving data collected by LuaCov's runner. | 
| resume () | Resumes saving data collected by LuaCov's runner. | 
| with_luacov (f) | Wraps a function, enabling coverage gathering in it explicitly. | 
| init ([configuration]) | Initializes LuaCov runner to start collecting data. | 
| shutdown () | Shuts down LuaCov's runner. | 
| excludefile (name) | Adds a file to the exclude list (see luacov.defaults). | 
| includefile (name) | Adds a file to the include list (see luacov.defaults). | 
| excludetree (name, level) | Adds a tree to the exclude list (see luacov.defaults). | 
| includetree (name, level) | Adds a tree to the include list (see luacov.defaults). | 
Fields
| version | LuaCov version in MAJOR.MINOR.PATCHformat. | 
Functions
- file_included (filename)
- 
    Uses LuaCov's configuration to check if a file is included for
 coverage data collection.
    Parameters:- filename name of the file.
 Returns:- 
        true if file is included, false otherwise.
    
 
- update_stats (old_stats, extra_stats)
- 
    Adds stats to an existing file stats table.
    Parameters:- old_stats stats to be updated.
- extra_stats another stats table, will be broken during update.
 
- debug_hook (_, line_nr[, level])
- 
    Debug hook set by LuaCov.
 Acknowledges that a line is executed, but does nothing
 if called manually before coverage gathering is started.
    Parameters:- _ event type, should always be "line".
- line_nr line number.
- level 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. (optional)
 Usage:local function custom_hook(_, line) runner.debug_hook(_, line, 3) extra_processing(line) end 
- run_report ([configuration])
- 
    Runs the reporter specified in configuration.
    Parameters:- configuration
         if string, filename of config file (used to call load_config).
 If table then config table (see file luacov.default.luafor an example). Ifconfiguration.reporteris 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. (optional)
 
- configuration
         if string, filename of config file (used to call load_config).
 If table then config table (see file 
- real_name (filename)
- 
    Returns real name for a source file name
 using luacov.defaults.modules option.
    Parameters:- filename name of the file.
 
- load_config ([configuration])
- 
    Loads a valid configuration.
    Parameters:- configuration user provided config (config-table or filename) (optional)
 Returns:- 
         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 luacov.defaults are used instead.
    
 
- pause ()
- Pauses saving data collected by LuaCov's runner. Allows other processes to write to the same stats file. Data is still collected during pause.
- resume ()
- Resumes saving data collected by LuaCov's runner.
- with_luacov (f)
- 
    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.
    Parameters:- f a function
 Returns:- 
        a function that enables coverage gathering and calls the original function.
    
 Usage:local coro = coroutine.create(runner.with_luacov(func)) 
- init ([configuration])
- 
    Initializes LuaCov runner to start collecting data.
    Parameters:- configuration
         if string, filename of config file (used to call load_config).
 If table then config table (see file luacov.default.luafor an example) (optional)
 
- configuration
         if string, filename of config file (used to call load_config).
 If table then config table (see file 
- shutdown ()
- 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.
- excludefile (name)
- 
    Adds a file to the exclude list (see luacov.defaults).
 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 require(name)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.Parameters:- name
- string; literal filename,
- string; modulename as passed to require(),
- function; where containing file is looked up,
- table; module table where containing file is looked up
 
 Returns:- 
        the pattern as added to the list, or nil + error
    
 
- name
- includefile (name)
- 
    Adds a file to the include list (see luacov.defaults).
    Parameters:- name see excludefile
 Returns:- 
        the pattern as added to the list, or nil + error
    
 
- excludetree (name, level)
- 
    Adds a tree to the exclude list (see luacov.defaults).
 If name = 'luacov'andlevel = nilthen module 'luacov' (luacov.lua) and the tree 'luacov' (containingluacov/runner.luaetc.) is excluded. Ifname = 'pl.path'andlevel = truethen module 'pl' (pl.lua) and the tree 'pl' (containingpl/path.luaetc.) is excluded. NOTE: in case of an 'init.lua' file, the 'level' parameter will always be setParameters:- name see excludefile
- level if truthy then one level up is added, including the tree
 Returns:- 
        the 2 patterns as added to the list (file and tree), or nil + error
    
 
- includetree (name, level)
- 
    Adds a tree to the include list (see luacov.defaults).
    Parameters:- name see excludefile
- level see includetree
 Returns:- 
        the 2 patterns as added to the list (file and tree), or nil + error