* rcirc-sqlite: rcirc logging in SQLite

Find here the source for ~rcirc-sqlite.el~, that stores the logging from
~rcirc~ into a SQLite database.

~rcirc~ is a default, simple IRC client in Emacs. rcirc can be enabled
to log the IRC chats, it logs to files.

This minor mode, when activated, diverts the rcirc logs to a SQLite
database.

* Installation and activation
** Installation

** Install from GNU ELPA
The GNU ELPA package name is: ~rcirc-sqlite~

To install the package:

- ~M-x package-refresh-contents~
- ~M-x package-install~

and search for ~rcirc-sqlite~.

Or use ~use-package~

#+begin_src emacs-lisp
(use-package rcirc-sqlite
    :ensure t
    :config
    (add-hook 'rcirc-mode-hook #'rcirc-sqlite-log-mode))
#+end_src

** Manual installation
Create a directory for the package.

#+begin_src sh
mkdir ~/.emacs.d/manualpackages
#+end_src

At this directory as a load path to your init file:

#+begin_src emacs-lisp
(add-to-list 'load-path "~/.emacs.d/manualpackages")
(require 'rcirc-sqlite)
#+end_src

Re-evaluate your init file or restart Emacs, whatever you prefer.

** Activation
The command ~rcirc-sqlite-log-mode~  toggles between activation
and deactivation of ~rcirc-sqlite~.

To start ~rcirc-sqlite~ automatically when ~rcirc~ is started, add the
following to your init file:

#+begin_src emacs-lisp
(require 'rcirc-sqlite)
(add-hook 'rcirc-mode-hook #'rcirc-sqlite-log-mode)
#+end_src

* Usage
Use the following commands to query the database.

- ~M-x rcirc-sqlite-view-log~: display the logs.
- ~M-x rcirc-sqlite-text-search~ perform full text search in the logs.
- ~M-x rcirc-sqlite-logs-from-nick~ display the logs from a specific nick.
- ~M-x rcirc-sqlite-stats~ displays some stats.
- ~M-x rcirc-sqlite-stats-per-month~ displays counts per month.

** ~rcirc-sqlite-view-log~
Default this commands shows the last 200 messages, optionally narrowed
to a specific channel, or month.

** ~rcirc-sqlite-logs-from-nick~
Display the logs from a specific nick.

Prompts:

- for a nick
- for a time range

Completion is used to choose a nick and a time range.

When a time range is chosen, only show the messages that were send in
that specific range.  Choose ~All channels~ to display everything.

** ~rcirc-sqlite-text-search~
Perform full text searches in the database.

Prompts:

- for a search string
- for a channel
- for a time range
- for a nick

Completion is used to choose a channel, a time range, or nick.

When a channel is chosen, the search is performed within the
chat logs of that specific channel.  Choose ~All channels~ to
search everywhere.

When a time range is chosen, the search is performed within the
messages that were send in that specific range. Choose ~Anytime~
to search everywhere.

When a nick is chosen, the search is performed within the
chats of that specific nick.  Choose ~All nicks~ to search
independent of the sender.

The search string is used to do a full text search in the SQLite
database. When the search string is ~foo~, chat messages
containing the word ~foo~ will be found, but chat messages
containing the word ~foobar~ will not be found.

To search for both ~foo~ and ~foobar~, use the search
string ~foo*~.

Likewise, to search for URLs, use something like ~"http://*"~ or
~"https://*"~ as search string, or for example
~"gopher://*"~. Because of the colon (~:~), the double
quotes (~"~) here are required.

** ~rcirc-sqlite-stats~
This command gives an overview of the number of messages in the database.

The user is prompted for a nick. Choose a nick through completion.

When a nick is chosen, the buffer ~*rcirc log*~ is opened where
each channel with one or more chat messages from that nick is listed,
together with the number of chat messages from that nick.

When ~All nicks~ is chosen, the buffer shows the row count
for each channel in the database.

When ~Nicks per channel~ is chosen, the buffer shows for
each channel the number of uniq nicks.

When ~Channels per nick~ is chosen, the buffer shows for
each nick the number of channels with messages from this nick.

Use drill-down in the stats buffer to get more details, either by the
"RET" key, or the left mouse button.

** ~rcirc-sqlite-stats-per-month~
This command gives an overview of the number of messages per month.

** Key bindings in the buffer ~*rcirc log*~
In the log buffer showing the channel, time, nick, and message
a number of functions are available with the press of a single key.

First, select a message by moving point up or down. Next, use one of the
following keys.

| Key   | Action                                                          |
|-------+-----------------------------------------------------------------|
| ~RET~ | Show logs of the channel and date of the selected message       |
| ~>~   | Same, but also include the next day                             |
| ~^~   | Same, but also include the previous day                         |
| ~a~   | Same, but also include all following days                       |
| ~b~   | Browse URL in the message                                       |
| ~<~   | Show logs of the channel,date, and nick of the selected message |
| ~c~   | Copy the selected message, nicely formatted, to the kill-ring   |
| ~R~   | Insert the selected message, nicely formatted, into a register  |
| ~r~   | Same, but append to the register                                |
| ~(~   | Suppress display of server in channel name                      |
| ~)~   | Activate display of server in channel name                      |

The register to insert or append messages is default register ~r~. A different
register can be set as user option, with ~customize-group RET rcicq-sqlite~.

* Contribute
A copyright assignment to the FSF is required for all non-trivial code
contributions.

* Source code
~rcirc-sqlite~ is developed at [[https://codeberg.org/mattof/rcirc-sqlite][Codeberg]].

* Bugs and patches
Please use the "Issues" option in the Codeberg repository.

* Distribution
~rcirc-sqlite.el~ and all other source files in this directory are
distributed under the GNU Public License, Version 3, or any later
version.