
** Logs Filter v0.1
** by Gamall Wednesday Ida
** email : gamall.ida@gmail.com
** web   : gamall-ida.com


usage: sis [options]
 -p  <str>     : validation predicate
 -t  <str>     : validation transform
 -rp <str>     : rejection predicate
 -rt <str>     : rejection transform
 -o  <str>     : select an opacity. Values are
                 Opaque/Residues/Transparent
 --no-blank    : don't print blank lines
 --help        : print this help and exit
 --help <str>  : print the documentation for a function
 --predicates  : print the list of all valid predicates
 --transforms  : print the list of all valid transforms
 --funs        : print the list of all valid functions
 --docu        : print the whole documentation of all functions
   


** Logs Filter v0.1
** by Gamall Wednesday Ida
** email : gamall.ida@gmail.com
** web   : gamall-ida.com

DOCUMENTATION OF ALL FUNCTIONS
================================================================================



PREDICATES:
================================================================================



  jk_adlgs : In Jedi Knight, keep all dialogues (say and tell)
--------------------------------------------------------------------------------
In Jedi Knight servers, lines such as
  tell: from_name to to_name: private message
indicate private messages, and lines such as
  say: name: message
indicate public messages.
    
This predicate only keeps those lines.
    
Note that there are other predicates about dialogues:
See jk_pdlgs and jk_dlgs.
  
There is an associated transform: jk_dlgs.
--------------------------------------------------------------------------------



      none : Block all lines. Closed filter
--------------------------------------------------------------------------------
This predicate always yields false, which means it keeps no line.
  
It is there only for the sake of completeness, but I doubt it has
any practical use besides debugging.
--------------------------------------------------------------------------------



   q3_uiip : In Q3 logs, keep lines with userinfo string & ip
--------------------------------------------------------------------------------
In games based on the Quake3 Engine, a string called the userinfo string stores
valuable information such as player name and IP address.
  
For instance, "\ip\12.234.22.11:5656\name\Gamall\etc..." looks like a userinfo 
string.
  
This predicate keeps only the lines where a userinfo strings containing an IP
address appears.
  
Not that this predicate has an homonym transform.
--------------------------------------------------------------------------------



  jk_event : In Jedi Knight, keep localised game events
--------------------------------------------------------------------------------
In Jedi Knight servers, some log lines read that way:
-> "broadcast: print "Gamall Wednesday Ida @@@PLRENAME Padawan\n""
The symbol prefixed by @@@ is replaced by localised strings in the game clients.
  
So these lines indicate lots of game events, connections, disconnections, 
kicks and bans, timelimits and much more.
  
This predicate only keeps lines of this form.
  
It has an homonym transform which removes the broadcast instructions from
the actual message.
--------------------------------------------------------------------------------



  jk_sinit : In Jedi Knight, keep server initialisation (maps)
--------------------------------------------------------------------------------
In Jedi Knight servers, lines such as 
  
  ------ Server Initialization ------
  Server: mp/ffa1
  
indicate the map loaded on the server.
  
This predicate keeps only those lines, yielding the list of the maps loaded 
on the server.
--------------------------------------------------------------------------------



  jk_pdlgs : In Jedi Knight, keep private dialogues (tell)
--------------------------------------------------------------------------------
In Jedi Knight servers, lines such as
  tell: from_name to to_name: private message
indicate private messages.
    
This predicate only keeps those lines.
    
Note that there are other predicates about dialogues:
See jk_adlgs and jk_dlgs.
  
There is an associated transform: jk_dlgs.
--------------------------------------------------------------------------------



       all : Accept all lines. Transparent filter (DEFAULT)
--------------------------------------------------------------------------------
This predicate always yields true, which means it keeps all lines.

This is the default predicate, which means that it will be used if you don't 
select another. Then you can use a transform alone.
--------------------------------------------------------------------------------



   jk_dlgs : In Jedi Knight, keep only public dialogues (say)
--------------------------------------------------------------------------------
In Jedi Knight servers, lines such as
  say: name: message
indicate public messages.
    
This predicate only keeps those lines.
    
Note that there are other predicates about dialogues:
See jk_adlgs and jk_pdlgs.
  
There is an associated transform: jk_dlgs.
--------------------------------------------------------------------------------


TRANSFORMS:
================================================================================



     cut80 : Truncate to the first 80 characters
--------------------------------------------------------------------------------
This transform only keeps the FIRST 80 characters of each line, which allows
the resulting text to be printed on any terminal without any line break.
  
Information can be lost, though.
  
This transform has a sister: see rcut80
--------------------------------------------------------------------------------



      mark : Debug mark. Prepends a mark
--------------------------------------------------------------------------------
This basic transform will just add 'MARKED: ' at the beginning of its input.
  
It has no practical use except for debugging the program.
--------------------------------------------------------------------------------



     lcase : To lowercase
--------------------------------------------------------------------------------
This transform turns its input to lowercase.
  
Since I has included uppercase (see upcase), I couldn't possibly omit 
lowercase...
--------------------------------------------------------------------------------



   q3_uiip : Separate IP from q3 userinfo string
--------------------------------------------------------------------------------
This transform is meant to be used in conjunction with its homonym predicate.
It isolates the IP from a userinfo string, and displays it clearly.
  
The original string is also entirely displayed after the IP.
  
There is another transform which prints the IP alone: q3_uioip
--------------------------------------------------------------------------------



  noq3cols : Remove Quake3 colour escapes
--------------------------------------------------------------------------------
In Quake3-based games, the character ^ is the 'colour escape' which, combined
with a number, changes the current colour. 
    
Of course, since the colours won't be displayed in text logs, these can
become an annoyance.
  
These transform removes any colour escape it finds. For instance
  ^5G^7amall ^5W^7ednesday ^5I^7da^7
becomes
  Gamall Wednesday Ida.
--------------------------------------------------------------------------------



  jk_event : Jedi Knight localised event trim
--------------------------------------------------------------------------------
This transform removes the "broadcast: print" instruction
and the quotes from lines containing a localised game event.
  
See the homonym predicate for more information.
--------------------------------------------------------------------------------



        id : Identity. lines are unaltered (DEFAULT)
--------------------------------------------------------------------------------
This transform is the identity: its input is unaltered.
  
This is the default transform, which means it will be used unless you select
another one.
  
This allows you to use the filter with a predicate alone.
--------------------------------------------------------------------------------



    rcut80 : Truncate to the last  80 characters
--------------------------------------------------------------------------------
This transform only keeps the LAST 80 characters of each line, which allows
the resulting text to be printed on any terminal without any line break.
  
Information can be lost, though.
  
This transform has a sister: see cut80
--------------------------------------------------------------------------------



   jk_dlgs : Jedi Knight dialogue line pretty-print
--------------------------------------------------------------------------------
This transform is to be used with the jk_dlgs, jk_adlgs and jk_pdlgs 
predicates.
  
It separates the names and the dialogues very clearly, using different templates
for public and private messages.
  
Tip: rather than use 
  -t jk_dlgs -p jk_adlgs
, you can use
  -t jk_dlgs --no-blank
  
Since this transform will yield a blank line if it fails, those two commands
are identical, except the second one only matches the regular expressions
one time, while the first does it twice. So the second command is a tad faster
than the first.
--------------------------------------------------------------------------------



    upcase : To uppercase
--------------------------------------------------------------------------------
This transform turns its input to uppercase.
  
I don't think it is of much use, but I put it here for the sake of example, to 
show how easy it is to add a transform to the program.
  
Besides, this was one of the example filters I shipped with SIS.
--------------------------------------------------------------------------------



  q3_uioip : Extracts IP from q3 userinfo string
--------------------------------------------------------------------------------
This transform only retains the IP from lines with a 
userinfo string.
  
See q3_uiip if you want to retain a copy of the original line.
--------------------------------------------------------------------------------
