__________

                                 CHOTTO

                                User Mms
                               __________


Table of Contents
_________________

1. Naming & Afew
2. Prerequisites
3. Configuration
4. Config
5. Rule sets


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.


1 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!


2 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.


3 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


4 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


5 Rule sets
===========

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

  ,----
  | Chotto.rule_set "notes" do
  |   messages.filter(from: "<my email>").each do |msg|
  |      msg.tags << "note" 
  |      msg.save!
  |   end
  | end
  `----

  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.