diff options
Diffstat (limited to '')
| -rw-r--r-- | quarg.1 | 359 | ||||
| -rw-r--r-- | setup.py | 4 |
2 files changed, 363 insertions, 0 deletions
@@ -0,0 +1,359 @@ +.Dd May 5, 2021 +.Dt QUARG 1 +.Os +.Sh NAME +.Nm quarg +.Nd search Quassel logs for matching messages and print them +.Sh SYNOPSIS +.Nm +.Op Fl de +.Op Fl l Ar num +.Op Fl o Ar order +.Op Fl b Ar buffer +.Op Fl B Ar buftype +.Op Fl f Ar msgflag +.Op Fl m Ar prefix +.Op Fl n Ar nick +.Op Fl N Ar network +.Op Fl Q Ar user +.Op Fl t Ar msgtype +.Op Fl -after Ar date +.Op Fl -around Ar date Ns Op / Ns Ar range +.Op Fl -before Ar date +.Op Fl -joined | -no-joined +.Op Ar keyword Op Ar keyword ... +.Nm +.Fl h | -help +.Sh DESCRIPTION +.Nm +searches Quassel logs for messages matching a set of conditions and +prints the results. +See +.Sx CONNECTING TO QUASSEL +for more information on how to set up the database connection. +.Pp +A condition is any option from the +.Sx CONDITIONS +section. +At least one condition needs to be specified. +If multiple different types of conditions are given, all of them must +match. +The same condition can be specified multiple times with different +arguments, in which case it matches any of the arguments. +.Pp +If there are any results, +.Nm +prints each match using Quassel's message format, prefixed with the +timestamp in local time and the origin buffer of the message separated +by the tab +character. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl d +Prints additional debug information. +This includes the +.Em SELECT +statements executed by SQL as well as an internal representation of the +conditions passed to +.Nm . +.It Fl e +Interprets any +.Ar keyword +as a +.Em LIKE +expression. +This allows the use of the +.Sq % +placeholder. +If no placeholders are given, matches the +.Ar keyword +exactly. +.It Fl l Ar num +Limits the number of matches to +.Ar num . +.It Fl o Ar order +Specifies in which order to sort the messages. +Matches are always sorted by timestamp. +.Ar order +can be +.Sy asc +for ascending order or +.Sy desc +for descending order. +The default is +.Sy asc . +.Pp +This option is useful in conjunction with +.Fl l Ar num , +as it may be used to have +.Nm +limit output to the oldest +.Pq Sy asc +or most recent +.Pq Sy desc +.Ar num +matches. +.It Fl h | -help +Shows the integrated help page and exits. +.El +.Sh CONDITIONS +The conditions are as follows: +.Bl -tag -width Ds +.It Ar keyword +Matches messages containing +.Ar keyword . +.It Fl b Ar buffer +Matches messages in a specific buffer, given by its name as displayed in +the Quassel client. +.It Fl B Ar buftype +Matches messages in buffers of a specific type. +.Pp +.Ar buftype +can be one of +.Sy channel , +.Sy query , +or +.Sy status , +for channels, queries, and the status (or +.Dq network ) +buffers respectively. +.It Fl f Ar msgflag +Matches messages of a specific context, given by a flag name. +.Pp +The flag names are as follows: +.Bl -tag -width Ds +.It Sy highlight +Messages that triggered Quassel's +.Dq Remote Highlight +rules. +By default this includes messages containing the current nickname. +.It Sy none +Messages that do not have any flag set. +.It Sy self +Messages that were sent by Quassel users themselves. +.El +.It Fl m Ar prefix +Matches messages sent by nicknames that have a specific channel +membership prefix as defined in the +.Sy Channel Membership Prefix section Ns No [1] +of the Modern IRC Client Protocol specification. +.Pp +Common prefixes include +.Sq @ +for operators, +.Sq % +for half-ops, and +.Sq + +for voiced users. +.Pp +Note that multiple prefixes may be set at the same time (for example a +voiced operator). +In this case, any prefix will match, but the printed message will only +show the +.Dq highest +one. +.It Fl n Ar nick +Matches messages sent by a specific user, given by nickname. +.It Fl N Ar network +Matches messages in a specific network, given by its name as displayed +in the Quassel client. +.It Fl Q Ar user +Matches messages relating to a specific Quassel user, given by their +user name. +.Pp +This condition is only useful if the Quassel database contains logs +for multiple Quassel users. +Without this condition, +.Nm +matches messages from any Quassel user. +.It Fl t Ar msgtype +Matches messages of a specific type. +.Pp +.Ar msgtype +can be one of the following, corresponding to IRC messages as defined +in +.Sy RFC 1459 Ns No [2] : +.Sy invite , +.Sy join , +.Sy kick , +.Sy kill , +.Sy mode , +.Sy nick , +.Sy notice , +.Sy part , +.Sy privmsg , +.Sy quit , +.Sy topic . +.Pp +In addition, +.Nm +supports the following message types: +.Bl -tag -width Ds +.It Sy action +The CTCP ACTION message. +.It Sy error +Error messages as reported to the user by Quassel. +.It Sy netsplit_join +Messages indicating the end of a netsplit, along with the users who +rejoined. +.It Sy netsplit_quit +Messages indicating an ongoing netsplit, along with the users who quit. +.It Sy server +Server messages as reported to the user by Quassel. +.El +.It Fl -joined +Matches messages in channels that are currently joined. +.It Fl -no-joined +Matches messages in channels that are currently not joined. +.Pp +Note that as a result of the implementation in Quassel, this condition +matches all query buffers. +If this is undesirable, combine this condition with +.Fl B No channel . +.El +.Pp +In addition, +.Nm +supports matching on message timestamps. +Wherever a date is passed as an argument to a condition, +.Nm +parses it according to the +.Sy ISO-8601 +standard. +.Pp +A date may include a time element and a time zone offset. +If no time zone offset is given, the date is assumed to be in local +time. +Refer to +.Sy dateutil's isoparse documentation Ns No [3] +for detailed information. +.Pp +The conditions that match on message timestamps are as follows: +.Bl -tag -width Ds +.It Fl -after Ar date +Matches messages that were sent after +.Ar date . +.It Fl -around Ar date Ns Op / Ns Ar range +Matches messages sent after +.Ar date - +.Ar range +and before +.Ar date + +.Ar range . +If +.Ar range +is not given, defaults to 12 hours. +.Pp +.Ar range +consists of a number and an optional suffix +.Sq h +for hours or +.Sq m +for minutes. +If no suffix is given, defaults to hours. +.Pp +For example, +.Dq 2021-02-18 20:55Z/10m +matches messages sent between 20:45 and 21:05. +This is equivalent to the following: +.Bd -literal -offset indent +quarg --after '2021-02-18 20:45Z' --before '2021-02-18 21:05Z' +.Ed +.Pp +This option cannot be used with +.Fl -after +or +.Fl -before . +.It Fl -before Ar date +Matches messages that were sent before +.Ar date . +.El +.Sh CONNECTING TO QUASSEL +In order to access Quassel's logs, +.Nm +needs access to the Quassel database. +The easiest way to achieve this is to have it running on the database +host and remotely invoke it using +.Xr ssh 1 . +Alternatively, the database port (or socket) may be forwarded to a local +machine +via +.Xr ssh 1 +and used with a local +.Nm +instance. +.Pp +.Nm +uses SQLAlchemy which supports both SQLite and PostgreSQL backends. +The psycopg2 backend is recommended for the latter. +.Pp +If Quassel uses the PostgreSQL backend, +it is highly recommended to set up a read-only database role +specifically for +.Nm . +Furthermore, consider using the +.Sy Peer Authentication Ns No [4] +method with a dedicated user. +This type of authentication removes the need for a password and +also works over a forwarded connection. +.Pp +.Nm +reads the database URL from an INI-style configuration file. +See +.Sx FILES +for the location of this file. +The URL is specified in the +.Em Database +section using the +.Em url +key. +See +.Sy Database URLs Ns No [5] +for details on the URL format. +.Pp +The following is a valid configuration file specifying a connection to a +local PostgreSQL instance via its default socket: +.Bd -literal -offset indent +[Database] +url = postgresql+psycopg2://quarg@/quassel?host=/run/postgresql +.Ed +.Sh FILES +.Bl -tag -width Ds +.It Em $XDG_CONFIG_HOME/quarg/config +The configuration file for +.Nm . +.El +.Pp +.Nm +adheres to the XDG Base Directory Specification. +If $XDG_CONFIG_HOME is unset or empty, it will default to +.Em ~/.config +.Sh NOTES +.Bl -enum +.It +.Sy Channel Membership Prefixes +.Pp +https://modern.ircdocs.horse/#channel-membership-prefixes +.It +.Sy RFC 1459 +.Pp +https://tools.ietf.org/html/rfc1459 +.It +.Sy dateutil isoparse +.Pp +https://dateutil.readthedocs.io/en/stable/parser.html#dateutil.parser.isoparse +.It +.Sy Peer Authentication +.Pp +https://www.postgresql.org/docs/13/auth-peer.html +.It +.Sy Database URLs +.Pp +https://docs.sqlalchemy.org/en/14/core/engines.html#database-urls +.El +.Sh AUTHORS +.An -nosplit +.Nm +was written by +.An Wolfgang Müller Aq Mt wolf@oriole.systems @@ -9,6 +9,10 @@ setuptools.setup( packages=setuptools.find_packages(), python_requires=">=3.8", + data_files = [ + ('man/man1', ['quarg.1']) + ], + entry_points = { 'console_scripts': [ 'quarg = quarg.main:main', |