From d38a022654548d44122428f71dc8f0ebd7b34167 Mon Sep 17 00:00:00 2001 From: Peter Melnichenko Date: Wed, 29 Jun 2016 19:18:02 +0300 Subject: 0.12.0 release --- README.md | 64 +++++++---- doc/doc/index.html | 16 ++- doc/doc/ldoc.css | 2 +- doc/doc/modules/luacov.defaults.html | 44 ++++++-- doc/doc/modules/luacov.hook.html | 114 +++++++++++++++++++ doc/doc/modules/luacov.html | 9 +- doc/doc/modules/luacov.reporter.html | 53 +++++++-- doc/doc/modules/luacov.runner.html | 15 +-- doc/doc/modules/luacov.stats.html | 6 +- doc/doc/modules/luacov.tick.html | 6 +- doc/doc/modules/luacov.util.html | 213 +++++++++++++++++++++++++++++++++++ doc/index.html | 52 ++++++++- src/luacov/defaults.lua | 8 +- src/luacov/runner.lua | 2 +- 14 files changed, 531 insertions(+), 73 deletions(-) create mode 100644 doc/doc/modules/luacov.hook.html create mode 100644 doc/doc/modules/luacov.util.html diff --git a/README.md b/README.md index ce45ba3..8910e25 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,17 @@ page](https://github.com/keplerproject/luacov/releases). It can also be installed using Luarocks: - luarocks install luacov +``` +luarocks install luacov +``` + +In order to additionally install experimental C extensions that improve +performance and analysis accuracy install [CLuaCov] +(https://github.com/mpeterv/cluacov) package instead: + +``` +luarocks install cluacov +``` LuaCov is written in pure Lua and has no external dependencies. @@ -51,9 +61,9 @@ file named `luacov.report.out`. The script takes the following parameters: luacov [-c=configfile] [filename...] For the `-c` option see below at [configuration](#configuration). The filenames -(actually Lua patterns) indicate the files to include in the report, specifying them here -equals to adding them to the `include` list in the configuration file, with `.lua` -extension stripped. +(actually Lua patterns) indicate the files to include in the report, specifying +them here equals to adding them to the `include` list in the configuration +file, with `.lua` extension stripped. This is an example output of the report file: @@ -75,35 +85,44 @@ themselves). LuaCov saves its stats upon normal program termination. If your program is a daemon -- in other words, if it does not terminate normally -- you can use the -`luacov.tick` module, which periodically saves the stats file. For example, to -run (on Unix systems) LuaCov on -[Xavante](http://keplerproject.github.io/xavante/), just modify the first line of -`xavante_start.lua` so it reads: +`luacov.tick` module or `tick` configuration option, which periodically saves +the stats file. For example, to run (on Unix systems) LuaCov on +[Xavante](http://keplerproject.github.io/xavante/), just modify the first line +of `xavante_start.lua` so it reads: + +``` +#!/usr/bin/env lua -lluacov.tick +``` + +or add + +```lua +tick = true +``` - #!/usr/bin/env lua -lluacov.tick +to `.luacov` config file. ## Configuration LuaCov includes several configuration options, which have their defaults stored in `src/luacov/defaults.lua`. These are the global defaults. To use -project specific configuration, create a Lua script returning a table -with some options and store it as `.luacov` in the project directory from -where `luacov` is being run. For example, this config informs LuaCov that -only `foo` module and its submodules should be covered and that they are -located inside `src` directory: +project specific configuration, create a Lua script setting options as globals +or returning a table with some options and store it as `.luacov` in the project +directory from where `luacov` is being run. For example, this config informs +LuaCov that only `foo` module and its submodules should be covered and that +they are located inside `src` directory: ```lua -return { - modules = { - ["foo"] = "src/foo/init.lua", - ["foo.*"] = "src" - } +modules = { + ["foo"] = "src/foo/init.lua", + ["foo.*"] = "src" } ``` For a full list of options, see -[`luacov.defaults` documentation](http://keplerproject.github.io/luacov/doc/modules/luacov.defaults.html). +[`luacov.defaults` documentation] +(http://keplerproject.github.io/luacov/doc/modules/luacov.defaults.html). ## Custom reporter engines @@ -119,10 +138,11 @@ After cloning this repo, these commands may be useful: * `luarocks make` to install LuaCov from local sources; * `make test` to run tests (does not require installing beforehand); -* `ldoc .` to regenerate documentation using [LDoc](https://github.com/stevedonovan/LDoc). +* `ldoc .` to regenerate documentation using [LDoc] + (https://github.com/stevedonovan/LDoc). * `luacheck .` to lint using [Luacheck](https://github.com/mpeterv/luacheck). ## Credits LuaCov was designed and implemented by Hisham Muhammad as a tool for testing -[LuaRocks](http://www.luarocks.org). +[LuaRocks](https://luarocks.org/). diff --git a/doc/doc/index.html b/doc/doc/index.html index 26c4d57..7871d24 100644 --- a/doc/doc/index.html +++ b/doc/doc/index.html @@ -33,10 +33,12 @@ @@ -54,7 +56,11 @@ luacov.defaults - Default configuration file. + Default values for configuration options. + + + luacov.hook + Hook module, creates debug hook used by LuaCov. luacov.reporter @@ -73,13 +79,17 @@ Load luacov using this if you want it to periodically save the stats file. + + luacov.util + Utility module. +
-generated by LDoc 1.4.3 -Last updated 2016-04-18 11:50:47 +generated by LDoc 1.4.4 +Last updated 2016-06-29 18:46:30
diff --git a/doc/doc/ldoc.css b/doc/doc/ldoc.css index 7a954f4..269f328 100644 --- a/doc/doc/ldoc.css +++ b/doc/doc/ldoc.css @@ -28,7 +28,7 @@ del,ins { text-decoration: none; } li { - list-style: disc; +// list-style: disc; margin-left: 20px; } caption,th { diff --git a/doc/doc/modules/luacov.defaults.html b/doc/doc/modules/luacov.defaults.html index 52bdc0e..c512c18 100644 --- a/doc/doc/modules/luacov.defaults.html +++ b/doc/doc/modules/luacov.defaults.html @@ -41,10 +41,12 @@ @@ -52,11 +54,10 @@

Module luacov.defaults

-

Default configuration file.

-

Copy, customize and store in your - project folder as '.luacov' for project specific configuration. - If some options are missing, their default values from this file - will be used.

+

Default values for configuration options.

+

For project specific configuration create '.luacov' file in your project + folder. It should be a Lua script setting various options as globals + or returning table of options.

Tables

@@ -85,6 +86,10 @@ Filename to store report. + tick + Enable saving coverage data after every savestepsize lines? + + savestepsize Stats file updating frequency for luacov.tick. @@ -163,11 +168,10 @@

Usage:

@@ -202,6 +206,22 @@ + +
+ + tick +
+
+ Enable saving coverage data after every savestepsize lines? + Setting this flag to true in config is equivalent to running LuaCov + using luacov.tick module. Default: false. + + + + + + +
@@ -271,8 +291,8 @@
-generated by LDoc 1.4.3 -Last updated 2016-04-18 11:50:47 +generated by LDoc 1.4.4 +Last updated 2016-06-29 18:46:30
diff --git a/doc/doc/modules/luacov.hook.html b/doc/doc/modules/luacov.hook.html new file mode 100644 index 0000000..2c8ce8a --- /dev/null +++ b/doc/doc/modules/luacov.hook.html @@ -0,0 +1,114 @@ + + + + + LuaCov Reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module luacov.hook

+

Hook module, creates debug hook used by LuaCov.

+

+ +

+ + +

Functions

+ + + + + +
new (runner)Creates a new debug hook.
+ +
+
+ + +

Functions

+ +
+
+ + new (runner) +
+
+ Creates a new debug hook. + + +

Parameters:

+
    +
  • runner + runner module. +
    • +
+ +

Returns:

+
    + + debug hook function that uses runner fields and functions + and sets runner.data. +
+ + + + +
+
+ + +
+
+
+generated by LDoc 1.4.4 +Last updated 2016-06-29 18:46:30 +
+
+ + diff --git a/doc/doc/modules/luacov.html b/doc/doc/modules/luacov.html index d599026..ae4f40a 100644 --- a/doc/doc/modules/luacov.html +++ b/doc/doc/modules/luacov.html @@ -36,10 +36,12 @@ @@ -51,7 +53,8 @@

Useful for launching scripts from the command-line. Returns the luacov.runner module.

Usage:

@@ -65,8 +68,8 @@
-generated by LDoc 1.4.3 -Last updated 2016-04-18 11:50:47 +generated by LDoc 1.4.4 +Last updated 2016-06-29 18:46:30
diff --git a/doc/doc/modules/luacov.reporter.html b/doc/doc/modules/luacov.reporter.html index d1884b5..a2bd1cb 100644 --- a/doc/doc/modules/luacov.reporter.html +++ b/doc/doc/modules/luacov.reporter.html @@ -33,7 +33,7 @@

Contents

@@ -41,10 +41,12 @@ @@ -65,7 +67,7 @@ Runs the report generator. -

Class ReporterBase

+

Class ReporterBase

@@ -96,6 +98,10 @@ + + + + @@ -155,7 +161,7 @@ -

Class ReporterBase

+

Class ReporterBase

Basic reporter class stub. @@ -163,12 +169,11 @@ Provides some helper methods and stubs to be overridden by child classes.

Usage:

- 
- local MyReporter = setmetatable({}, ReporterBase)
- MyReporter.__index = MyReporter
- function MyReporter:on_hit_line(...)
-    self:write(("File %s: hit line %s %d times"):format(...))
- end
+ 
local MyReporter = setmetatable({}, ReporterBase)
+MyReporter.__index = MyReporter
+function MyReporter:on_hit_line(...)
+   self:write(("File %s: hit line %s %d times"):format(...))
+end
@@ -293,6 +298,32 @@ + +
+ + ReporterBase:on_file_error (filename, error_type, message) +
+
+ Stub method called if a file couldn't be processed due to an error. + + +

Parameters:

+
    +
  • filename + name of the file. +
    • +
  • error_type + "open", "read" or "load". +
    • +
  • message + error message. +
    • +
+ + + + +
@@ -422,8 +453,8 @@
-generated by LDoc 1.4.3 -Last updated 2016-04-18 11:50:47 +generated by LDoc 1.4.4 +Last updated 2016-06-29 18:46:30
diff --git a/doc/doc/modules/luacov.runner.html b/doc/doc/modules/luacov.runner.html index 74ee7f9..5e0cfd6 100644 --- a/doc/doc/modules/luacov.runner.html +++ b/doc/doc/modules/luacov.runner.html @@ -41,10 +41,12 @@ @@ -216,11 +218,10 @@

Usage:

    - 
    - local function custom_hook(_, line)
-    runner.debug_hook(_, line, 3)
-    extra_processing(line)
- end
    + 
    local function custom_hook(_, line)
+   runner.debug_hook(_, line, 3)
+   extra_processing(line)
+end
@@ -550,8 +551,8 @@
-generated by LDoc 1.4.3 -Last updated 2016-04-18 11:50:47 +generated by LDoc 1.4.4 +Last updated 2016-06-29 18:46:30
diff --git a/doc/doc/modules/luacov.stats.html b/doc/doc/modules/luacov.stats.html index c1f5a74..646e06c 100644 --- a/doc/doc/modules/luacov.stats.html +++ b/doc/doc/modules/luacov.stats.html @@ -40,10 +40,12 @@ @@ -134,8 +136,8 @@
-generated by LDoc 1.4.3 -Last updated 2016-04-18 11:50:47 +generated by LDoc 1.4.4 +Last updated 2016-06-29 18:46:30
diff --git a/doc/doc/modules/luacov.tick.html b/doc/doc/modules/luacov.tick.html index 45241ab..df7176d 100644 --- a/doc/doc/modules/luacov.tick.html +++ b/doc/doc/modules/luacov.tick.html @@ -36,10 +36,12 @@ @@ -67,8 +69,8 @@
-generated by LDoc 1.4.3 -Last updated 2016-04-18 11:50:47 +generated by LDoc 1.4.4 +Last updated 2016-06-29 18:46:30
diff --git a/doc/doc/modules/luacov.util.html b/doc/doc/modules/luacov.util.html new file mode 100644 index 0000000..b269ba3 --- /dev/null +++ b/doc/doc/modules/luacov.util.html @@ -0,0 +1,213 @@ + + + + + LuaCov Reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module luacov.util

+

Utility module.

+

+ +

+ + +

Functions

+
ReporterBase:config ()Stub method called before processing a file.
ReporterBase:on_file_error (filename, error_type, message)Stub method called if a file couldn't be processed due to an error.
ReporterBase:on_empty_line (filename, lineno, line) Stub method called for each empty source line and other lines that can't be hit.
+ + + + + + + + + + + + + + + + +
unprefix (str, prefix)Removes a prefix from a string if it's present.
load_string (str[, env[, chunkname]])Loads a string.
load_config (name, env)Load a config file.
file_exists (name)Checks if a file exists.
+ +
+
+ + +

Functions

+ +
+
+ + unprefix (str, prefix) +
+
+ Removes a prefix from a string if it's present. + + +

Parameters:

+
    +
  • str + a string. +
    • +
  • prefix + a prefix string. +
    • +
+ +

Returns:

+
    + + original string if does not start with prefix + or string without prefix. +
+ + + + +
+
+ + load_string (str[, env[, chunkname]]) +
+
+ Loads a string. + + +

Parameters:

+
    +
  • str + a string. +
    • +
  • env + environment table. + (optional) +
    • +
  • chunkname + chunk name. + (optional) +
    • +
+ + + + + +
+
+ + load_config (name, env) +
+
+ Load a config file. + Reads, loads and runs a Lua file in an environment. + + +

Parameters:

+
    +
  • name + file name. +
    • +
  • env + environment table. +
    • +
+ +

Returns:

+
    + + true and the first return value of config on success, + nil + error type + error message on failure, where error type + can be "read", "load" or "run". +
+ + + + +
+
+ + file_exists (name) +
+
+ Checks if a file exists. + + +

Parameters:

+
    +
  • name + file name. +
    • +
+ +

Returns:

+
    + + true if file can be opened, false otherwise. +
+ + + + +
+
+ + + + +
+generated by LDoc 1.4.4 +Last updated 2016-06-29 18:46:30 +
+ + + diff --git a/doc/index.html b/doc/index.html index 565e46c..a9a4d5c 100644 --- a/doc/index.html +++ b/doc/index.html @@ -89,11 +89,21 @@ luarocks install luacov

-LuaCov is written in pure Lua and has no external dependencies. +There are some C extensions LuaCov can use (if they are available) to improve performance +and analysis accuracy. To install LuaCov with these extensions install +CLuaCov package instead: +

+ +
+luarocks install cluacov +
+ +

+LuaCov itself is written in pure Lua and has no external dependencies.

-Alternatively, you can get the code directly from the git repo. +You can also get the code directly from the git repo.

Instructions

@@ -163,9 +173,9 @@ not the sources themselves).

LuaCov saves its stats upon normal program termination. If your program is a daemon -- in other words, if it does not terminate normally -- you -can use the luacov.tick module, which periodically saves the -stats file. For example, to run (on Unix systems) LuaCov on -Xavante, +can use the luacov.tick module or the tick configuration option, +which periodically saves the stats file. For example, to run (on Unix systems) +LuaCov on Xavante, just modify the first line of xavante_start.lua so it reads:

@@ -173,9 +183,41 @@ just modify the first line of xavante_start.lua so it reads: #!/usr/bin/env lua -lluacov.tick +or add this to .luacov config file: + +
+tick = true +
+ +LuaCov includes several configuration options, which have their defaults +stored in luacov.defaults module. +These are the global defaults. To use project specific configuration, create a Lua script +setting options as globals or returning a table with some options and store it as +.luacov in the project directory from where luacov is being run. +For example, this config informs LuaCov that only foo module and its submodules +should be covered and that they are located inside src directory: + +
+modules = {
+   ["foo"] = "src/foo/init.lua",
+   ["foo.*"] = "src"
+}
+
+

History

+
0.12.0 [June 29, 2016]
+
+
    +
  • Added support for experimental C extensions (CLuaCov).
    • +
  • Changed config format: options are now set by assigning to globals, old format (returning a table) is still supported.
    • +
  • Added tickconfig option, equivalent to using luacov.tick module.
    • +
  • Fixed coverage data being saved to wrong file when using relative statsfile path and the program running LuaCov changes directories.
    • +
  • Improved config loading error handling.
    • +
  • Added :on_file_error() stub method to base reporter class, used for reporting problems when analyzing coverage data related to a file.
    • +
+
0.11.0 [April 18, 2016]
    diff --git a/src/luacov/defaults.lua b/src/luacov/defaults.lua index 4986109..4343b4a 100644 --- a/src/luacov/defaults.lua +++ b/src/luacov/defaults.lua @@ -1,7 +1,7 @@ ---- Default configuration file. Copy, customize and store in your --- project folder as '.luacov' for project specific configuration. --- If some options are missing, their default values from this file --- will be used. +--- Default values for configuration options. +-- For project specific configuration create '.luacov' file in your project +-- folder. It should be a Lua script setting various options as globals +-- or returning table of options. -- @class module -- @name luacov.defaults return { diff --git a/src/luacov/runner.lua b/src/luacov/runner.lua index c5a2a00..9016ac8 100644 --- a/src/luacov/runner.lua +++ b/src/luacov/runner.lua @@ -6,7 +6,7 @@ local runner = {} --- LuaCov version in `MAJOR.MINOR.PATCH` format. -runner.version = "0.11.0" +runner.version = "0.12.0" local stats = require("luacov.stats") local util = require("luacov.util") -- cgit v1.2.1