Chotto

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

+Chotto is an initial tagging script for Notmuch +

+ +

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