#+TITLE: Chotto
#+VERSION: 0.0.1

Chotto is an initial tagging script for Notmuch
- http://notmuchmail.org/
- http://notmuchmail.org/initial_tagging/

Chotto is written in Ruby and had a (quite) nice DSL for configuration.

* Naming & Afew
Notmuch ecosystem already has a great script for initial tagging - afew.
However it is written in Python and therefore it's always a gamble if it will consider the user worthy or running.

Chotto, =a few= in Japanese.
Because afew refused to work on my system.
And because I love Ruby!

* Prerequisites
Chotto expects:
- ruby 3x
- notmuch
- notmuch ruby bindings.

While the first 2 are obvious, getting ruby bindings to work may be an adventure on its own.

*FreeBSD* provides a ready package =ruby-notmuch=.

*MacOS* requires compiling from source, which will be problematic due to linking difficulties.
It's not an OS designed for technical folks.

Some *Linux* distros provide the bindings in their package managers, but otherwise compiling should be easy.

If you use *Windows*, you have my sympathy.

* Configuration
Chotto expects the configuration file to be present in

=~/.config/chotto/config.rb=

The user needs to add (at least) two blocks to the file: config & rule sets

* Config
Presently, the only option Config expects is the absolute path to the Notmuch database:

Chotto.configure do
  config.database_path = =/home/<user>/mail=
end

Please, adjust the path to the valid location

* Rule sets
The actual magic happens in =Rule Sets= which are sets of filters & tag modifications.
A very simple rule set can look like:

#+BEGIN_SRC ruby
Chotto.rule_set "notes" do
  messages.filter(from: "<my email>").each do |msg|
     msg.tags << "note" 
     msg.save!
  end
end
#+END_SRC

Let's break it down.

First, we define a named =rule_set=.
The name can be a string or a hash and is currently not used anywhere.
It makes it easier to manager bigger rule sets.

Then we search for messages.
In this case, we want all messages sent from =<my email>= .

After, we loop over each found message.

msg.tags returns a mutable array, and we can mutate is as such.

Lastly, we save! the message in the database.

* Filter language

We can quite easily filter messages based. Chotto accepts filters as:
- Strings (from(=Subject:Hired!=)).
  The string will not be modified.
- Hash with string values (from(subject: =Hired=)).
  The key of each hash element is a modified header value - it's down cased, and =-= becomes =_=, therefore:
  - =X-Spam-Id= becomes =x_spam_id=
  - =X-Thread-Id= becomes =x_thread_id=

  The values on the other hand can be:
  - String.
    Kind of obvious.
  - Array.
    Arrays here are treated as the current conjunctions.
    The default conjunction here is =OR=, so =k: [1,2]= will become =key:1 OR key:2=

  User can add multiple elements to the hash, and they will be join in the current conjunction mode.
  By default the mode is =AND=, therefore:

  {key: 'val1', key2: 'val2'} are treated as =key:val1 AND key2:val2=.

  =filter= returns self, therefore we can combine multiple filters =filter(key1: 'val').filter(key2: 'val2')=.
  Filters will be joined in the current conjunction mode.

  Conjunction mode can be changed using the =or= and =and= methods: filter(key1: =val1=).or.filter(key2: =val2=).

  The language is simple, but gives huge chances to go wrong.
  You can test what is produced by calling =#to_query_string= on messages instance.