# $EPIC: lastlog_command.txt,v 1.10 2009/11/19 08:34:18 jak Exp $
======Synopsis:======
[[lastlog]] [-] [-<option>] [-<level>] [--<level>] [-mangle <descr>] [<pattern>] [<number of entries> [<start>]]

======Description:======
The client keeps a copy of everything displayed to your windows in the 
[[lastlog]] buffer.  The [[LASTLOG]] command allows you to grep through 
this buffer and have items re-displayed to your window.  The size of the 
lastlog buffer is per-window and controlled by [[set lastlog]] or 
[[window lastlog]].  The [[levels]] that are saved in the buffer are 
per-window and controlled by [[set lastlog_level]] or [[window lastlog_level]].

For backwards compatibility reasons, up to three non-option arguments are
acceptable:
  * If the first option specified is not a number, then it is treated as if it were the argument to the -LITERAL option.  This **MUST** be the first non-option argument.
  * The first number is the number of lines to look at.
  * The second number is the position in the lastlog to start at.

======Options:======
^ Option          ^ Behavior ^
|-                 | Do not display the "Lastlog:" and "End of Lastlog" lines. |
|-literal <string> | Show lines that contain this literal string.|
|-regex <string>   | Show lines that match this regular expression.|
|-target <#chan%%|%%nick> | Show lines that were sent to or came from the target. |
|-max <num>        | Show only the first <num> lines that match. |
|-mangle <types>   | Output is mangled by specified [[mangle types]]. |
|-skip <number>    | Skip this many leading lastlog entries |
|-number <number>  | Start at the <number>th recent entry |
|-context <B[,A]>  | Show <B> lines before and after (or B lines before and A lines after) each match |
|-file <filename>  | Write the results to a file instead of displaying to the window |
|-separator <str>  | When using -context, use this as the separator between matches instead of "---" |
|-reverse          | Show all lines in reverse order; from the END to the BEGINNING. |
|-<LEVEL>          | Only show lines for the given [[level]].  This is done cumulatively, so you can specify as many levels as you want.|
|--<LEVEL>	   | Do not show lines for the given [[level]].  This is done cumulatively. |
|-rewrite <string> | Rewrite each line before it is displayed (see below) |
|-window <windesc> | Search the lastlog of <windesc> instead of the current window |

======Examples:======
The simplest use of the command just redisplays everything:
	/lastlog

But that's not terribly useful.  Usually you do it because you want to see
only references to a string, such as your nickname:
	/lastlog hop

You can double quote the string if it has spaces:
	/lastlog "help me"

You can filter a string based on the "target", which is a channel or nickname
that the output was caused by.
	/lastlog -target #epic "help me"
or to just see [[msg]]s sent to or from hop,
	/lastlog -target hop

You can use regexes instead of a string (you can double quote it):
	/lastlog -regex hi.*there
Regexes are compiled as REG_EXTENDED (modern regexes), REG_ICASE (case 
insensitive), and REG_NOSUB (no back-references).  See the man 3 regex
if you are curious about this.  Modern Regexes are what egrep(1) takes,
which are subtly different from basic regexes, which is what grep(2) uses.

You can use both a literal string and regexes together, and it must match
BOTH of them:
	/lastlog -target #epic "help me" -regex "pl\(ease|z\)"

Normally the lastlog buffer is searched OLDEST to NEWEST, and redisplayed
so everything appears in the same order as originally presented.  You may
want to see the NEWEST entries first, which you can do with -reverse.
	/lastlog -reverse -target #epic
Please note that this DOES display things in reverse order, newest to oldest!

You might not want to see everything that matches, so you can numerically
limit the number of matches displayed.  This is usually used with -reverse
	/lastlog -reverse -max 5 -target #epic "help me"
(to show the 5 most recent times that someone has said "help me" on #epic)

You might not want to have the first few lines considered for matching.
You can tell the client to skip the most oldest lines (or the most recent
lines if you use -reverse):
	/lastlog -reverse -skip 25 -max 3 hop
shows the most recent 3 times "hop" appeared in your window, but not currently
visible in your window, assuming your window is 25 lines.

-number

-context

-mangle
-rewrite
	$0  - lastlog refnum
	$1  - timestamp
	$2  - window refnum
	$3  - level
	$4  - reserved
	$5  - reserved
	$6  - reserved
	$7  - "target"
	$8- - the line of text
        All of this is limited to 10k, so super long lines are trunc'd.

-separator
-	(turns off header/footer)

-window

-file

-levels
-ALL
--ALL


Bare arguments
-literal is the same as bare argument

If -skip is > the size of the lastlog, it no-ops.
If -skip is >= 0 but -number is 0, it no-ops
If -max is 0, it no-ops.
-literal acts as a pmatch against "*%s*"
/xdebug lastlog will show you the gory details
-file will "append" to the given file.  NO TILDE SUPPORT, but it should.


======Examples:======
To list all private messages from JoeBob:
      /lastlog -msg joebob

To list all public messages from JoeBob in the last 100 lines
      /lastlog -public joebob 100

To list all occurrences of the phrase "ircII-EPIC is cool" from 100
to 600 lines ago:
      /lastlog "ircII-EPIC is cool" 100 500

To list everything *except* messages:
      /lastlog -all --msgs

To write everything containing "foo" to "lastlog.out":
      /lastlog -file lastlog.out foo

To list only public messages to #epic:
      /lastlog -target #epic -public

To list everything containing a specific number
      /lastlog -literal "1234"

======Rewriting the output:======
The -REWRITE flag rewrites each line by expanding the <string> argument using
the following values for $*

|$0|The lastlog item's unique refnum|
|$1|Timestamp (suitable for use with $strftime())|
|$2|Window refnum|
|$3|Output level|
|$4|Reserved for future use|
|$5|Reserved for future use|
|$6|Reserved for future use|
|$7|Output target|
|$8-| The logical line of output|

Remember that the <string> may be subject to quoting hell.

Example:
	/lastlog -rewrite "$$strftime($1 %T) $$8-"

======History:======
The [[lastlog]] command first appeared in ircII.
The -REWRITE flag first appeared in EPIC5-0.3.5