path: root/scoop.1

.Dd May 17, 2021
.Dt SCOOP 1
.Os
.
.Sh NAME
.Nm scoop
.Nd query IRC logs
.
.Sh SYNOPSIS
.Nm
.Op Fl Lgpqrsv
.Op Fl D Ar date
.Op Fl F Ar format
.Op Fl N Ar network
.Op Fl T Ar target
.Op Fl a Ar time
.Op Fl b Ar time
.Op Fl c Ar context
.Op Fl d Ar path
.Op Fl f Ar format
.Op Fl h Ar host
.Op Fl l Ar limit
.Op Fl m Ar regexp
.Op Fl n Ar nick
.Op Fl t Ar type
.Op Fl u Ar user
.Op Fl w Ar expr
.Op Ar search
.Nm
.Fl S
.
.Sh DESCRIPTION
The
.Nm
utility queries the
.Xr litterbox 1
IRC log database,
matching events on the intersection
of the criteria specified in arguments.
.
.Pp
If standard output is a terminal,
colored output is piped to
.Ev PAGER
with
.Ev LESS=FRX
if it is not already set.
.
.Pp
The arguments are as follows:
.Bl -tag -width Ds
.It Fl D Ar date
Match events which occurred on
.Ar date ,
of the format
.Ar YYYY-MM-DD .
.
.It Fl F Ar format
Format timestamps using the
.Ar format
string,
similar to
.Xr strftime 3 .
The default format is
.Qq %Y-%m-%dT%H:%M:%S .
.
.It Fl L
Output timestamps in local time
and interpret timestamps in
.Fl D ,
.Fl a
and
.Fl b
as local time.
.
.It Fl N Ar network
Match events from
.Ar network .
.
.It Fl S
Instead of performing a query,
launch the
.Xr sqlite3 1
shell for the database.
.
.It Fl T Ar target
Match events
.Po
of type
.Cm kick ,
.Cm nick ,
.Cm ban
or
.Cm unban
.Pc
with the target nickname or mask
.Ar target .
.
.It Fl a Ar time
Match events which occurred after
.Ar time ,
of the format
.Ar YYYY-MM-DD HH:MM:SS .
.
.It Fl b Ar time
Match events which occurred before
.Ar time ,
of the format
.Ar YYYY-MM-DD HH:MM:SS .
.
.It Fl c Ar context
Match events from
.Ar context ,
either a channel or query name.
.
.It Fl d Ar path
Set the database path.
The default path is as in
.Xr litterbox 1 .
.
.It Fl f Ar format
Set the output format to one of
.Cm plain ,
.Cm color
or
.Cm irc .
The default format is
.Cm color
if standard output is a terminal,
.Cm plain
otherwise.
The
.Cm irc
format outputs events
as IRC protocol with
.Sy server-time
tags.
.
.It Fl g
Group events by network and channel or query name.
Implies
.Fl s .
.
.It Fl h Ar host
Match events from users with the hostname
.Ar host .
.
.It Fl l Ar limit
Limit the number of events matched,
ordered by most recently inserted.
Implies
.Fl s .
.
.It Fl m Ar regexp
Match events with messages
matching the modern regular expression
.Ar regexp .
See
.Xr re_format 7 .
.
.It Fl n Ar nick
Match events from users with the nickname
.Ar nick .
.
.It Fl p
Match only events from channels.
.
.It Fl q
Match only events from queries.
.
.It Fl r
Output results in reverse order.
.
.It Fl s
Sort the results from oldest to newest.
By default events are output
in the order they appear in the database.
.
.It Fl t Ar types
Match events of
the comma-separated list of
.Ar types .
The types are
.Cm privmsg ,
.Cm notice ,
.Cm action ,
.Cm join ,
.Cm part ,
.Cm quit ,
.Cm kick ,
.Cm nick ,
.Cm topic ,
.Cm ban ,
.Cm unban .
.
.It Fl u Ar user
Match events from users with the username
.Ar user .
.
.It Fl v
Print the expanded SQL query being used to standard error.
.
.It Fl w Ar expr
Add the SQL expression
.Ar expr
to the
.Sy WHERE
clause of the query.
.
.It Ar search
Match events using full-text search.
The searchable columns are
.Li network ,
.Li channel ,
.Li query ,
.Li nick ,
.Li user ,
.Li target ,
.Li message .
.El
.
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev PAGER
The command to pipe terminal output to.
The default is
.Ev PAGER=less .
.El
.
.Sh SEE ALSO
.Xr litterbox 1
.Bl -item
.It
.Lk https://www.sqlite.org/lang_datefunc.html "Date and Time Functions"
.It
.Lk https://www.sqlite.org/fts5.html#full_text_query_syntax "Full-text Query Syntax"
.El
.
.Sh AUTHORS
.An June Bug Aq Mt june@causal.agency
.
.Sh BUGS
Send mail to
.Aq Mt list+litterbox@causal.agency
or join
.Li #ascii.town
on
.Li chat.freenode.net .