Loglite:

- README.md with documentation on usage and creating filter sets (implements #54).
- small improvements to default filter set.

src/script/README-loglite.md

@@ -0,0 +1,60 @@
+## Loglite
+
+The loglite script allows coloring and filtering of log files by specifying certain patterns and associating directives to them. These mainly specify colors but additionally, (non-)matched lines can be deleted from output and also all output lines can be numbered.
+
+
+### Usage
+
+The script can follow an existing log file (comparable to `tail -f`), or it can follow its standard input. A file to follow is always specified as the first argument and a filter set name as the second (use '-' as file name to read from standard input). Details on filter sets can be found below. If no filter set is mentioned on the command-line, the script will attempt to use one named 'default'.
+
+* Example following an existing log file using a filter set named 'example': `./loglite.lua print3d.log example`.
+* Example using standard input, to capture both output streams from `print3d`, with a filter set named 'example' (note the '-' as file name): `./print3d -V 2>&1 | ./loglite.lua - example`.
+
+
+### Filter sets
+
+The script looks for filter sets in the file '$HOME/loglite-filters.lua'. It looks like this:
+
+	local M = {}
+
+	M.default = {
+		['options'] = { mode = 'keep', count = 'none' },
+		['patterns'] = {
+			['%(error%)'] = 'red',
+			['%(warning%)'] = 'yellow',
+			['%(bulk%)'] = 'gray'
+		}
+	}
+
+	M.specialization = {
+		['parent'] = 'default',
+		['options'] = { mode = 'delete' }
+		['patterns'] = {
+			['setState%(%)'] = 'bblue,_nodelete'
+		}
+	}
+
+	return M
+
+Here, the declaration and returning of `M` is required for the loglite script to be able to cleanly import the file. In `M.default`, 'default' is the name of a filter set being defined (similar for 'specialization'). Definitions can contain three so-called keys: 'parent' specifies a filter set to inherit from in order to reduce code duplication, 'options' and 'patterns' are described below.
+
+Inheritance can be used to set new keys or to override keys from the parent set. Previously set keys cannot be removed, but they can be set to a non-existing directive (e.g., Lua's 'false' keyword) to achieve the same effect. Note that directives in inheriting sets are currently not combined with previous ones, so for instance overriding `['test'] = 'red, _delete'` with `['test'] = 'blue'` will result in only the directive 'blue' to be applied.
+
+#### Options
+
+Two options are currently available:
+
+* `mode`, which specifies whether to keep log lines (`keep`, the default) or to drop them (`delete`). For specific lines this can then be overriden, see 'Patterns' below.
+* `count`, which can be set to `all` to prefix log lines with a counter, or `none` (default) to leave them as is.
+
+#### Patterns
+
+Pattern specifications are patterns as used in Lua: [Lua documentation on patterns](http://www.lua.org/pil/20.2.html).
+The following directives can be associated with a pattern:
+
+* A foreground color, one of: black, red, green, yellow, blue, magenta, cyan or white.
+* A background color, like foreground colors but prefixed with 'b'.
+* `_delete` or `_nodelete` to override the active mode specified in the 'options' above.
+* Also available are `blink` and `underline` but they do currently not work in all terminal programs.
+
+Directives can be combined with ',' (e.g.: `'red,_nodelete'`). Finally, in any filter set, pattern rules are matched from top to bottom, the last one encountered overriding any previous conflicting directive.

src/script/loglite-filters.lua

@@ -1,7 +1,7 @@
 local M = {}
 
 M.default = {
-	['options'] = { ['mode'] = 'keep', count = 'none' },
+	['options'] = { mode = 'keep', count = 'none' },
 	['patterns'] = {
 		['%(error%)'] = 'red',
 		['%(warning%)'] = 'yellow',
@@ -26,14 +26,14 @@ M.print3d = {
 
 
 M.test = {  -- TEST set
-	['options'] = { ['mode'] = 'keep', count = 'all' },
+	['options'] = { mode = 'keep', count = 'all' },
 	['patterns'] = {
 		['%(info%)'] = 'yellow'
 	}
 }
 
 M.printstart = {
-	['options'] = { ['mode'] = 'delete' },
+	['options'] = { mode = 'delete' },
 	['patterns'] = {
 		['print started'] = '_uppercase,bwhite'
 	}

src/script/loglite.lua

@@ -1,32 +1,22 @@
 #!/usr/bin/env lua
 
--- EXAMPLE USAGE:
--- To be able to run print3d and at the same time color the logging you can use
--- the pipe (|) operator. Use 2>&1 to redirect the stderr to stdout, e.g.:
--- ./print3d -S -V -F -p marlin_generic 2>&1 | ./loglite.lua 
--- 
--- Notes
--- * directives: either a color, a color prefixed by 'b' or one of: _delete, _nodelete, [_matchonly]
--- * pattern rules are matched top to bottom, the last one encountered overriding any previous conflicting directive
---
--- TODO:
--- * pre-split keyword lists for efficiency?
--- * keep formats separate and only concat in the end, so things like uppercasing can work properly
--- * add more directives like uppercase, prefix/suffix?
--- * options: en/dis total count, en/dis match count (how to deal with multiple matches?), en/dis keep_mode / delete_mode/
--- * add specialized patterns for levels/modules?
---
--- FIXME:
--- * with deleteMode enabled, multiple matches and _nodelete in a later match, previous directives are ignored
-
 --[[
--- * https://stackoverflow.com/questions/17363973/how-can-i-tail-f-a-log-filetruncate-aware-in-lua
--- * http://pueblo.sourceforge.net/doc/manual/ansi_color_codes.html
+For documentation on this script, see README-loglite.md.
+
+Ideas for improvement:
+* add more directives like uppercase, prefix/suffix?
+* create separate package for this script: a) since it is useful for any log file, b) this file is getting somewhat long 
+* for broader terminal support: detect `tput` and use it if available (http://wiki.bash-hackers.org/scripting/terminalcodes)
+* pre-split keyword lists for efficiency instead of redoing this at every new line?
+
+FIXME:
+* with deleteMode enabled, multiple matches and _nodelete in a later match, previous directives are ignored
 ]]--
 
 
 --[[========================================================================]]--
 
+--Note: overview of ANSI escape codes: http://ascii-table.com/ansi-escape-sequences.php (support varies per terminal/termtype)
 local ANSI_COLORS = {
 	['blink'] = 5, -- no dice on osx/iterm2
 	['underline'] = 24, -- no dice on osx/iterm2
@@ -272,6 +262,7 @@ local function main()
 
 	--print("[DEBUG] following file: '" .. (followFile and followFile or "<stdin>") .. "', with filter set '" .. filterSetName .. "'.")
 
+	--Info on tailing a file: https://stackoverflow.com/questions/17363973/how-can-i-tail-f-a-log-filetruncate-aware-in-lua
 	--local tailin = io.popen('tail -F '..(...)..' 2>&1', 'r')
 	local tailin = followFile and io.popen('tail -f ' .. followFile, 'r') or io.stdin