feat: README

1 files changed, 114 insertions, 0 deletions

diff --git a/README.org b/README.org
new file mode 100644
index 0000000..5a8b406
--- /dev/null
+++ b/README.org
@@ -0,0 +1,114 @@
+#+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.
+
+
+
+
+
+