From 22560fbfbe2214f260c71c0ae5c928f81a431b76 Mon Sep 17 00:00:00 2001 From: mms Date: Tue, 12 Nov 2024 22:50:10 +0100 Subject: feat: README --- README.html | 419 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 3 - README.org | 114 +++++++++++++ README.txt | 143 +++++++++++++++++ lib/osugiru.rb | 5 +- lib/osugiru/database.rb | 2 +- lib/osugiru/message.rb | 17 +- 7 files changed, 695 insertions(+), 8 deletions(-) create mode 100644 README.html delete mode 100644 README.md create mode 100644 README.org create mode 100644 README.txt diff --git a/README.html b/README.html new file mode 100644 index 0000000..a4c1b26 --- /dev/null +++ b/README.html @@ -0,0 +1,419 @@ + + + + + + + +Chotto + + + + + +
+

Chotto

+ +

+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.databasepath = /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. +

    • +
+
+
+
+
+

Author: User Mms

+

Created: 2024-11-12 Tue 23:12

+

Validate

+
+ + diff --git a/README.md b/README.md deleted file mode 100644 index ed201df..0000000 --- a/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# some - -An inititial tagger for Notmucn \ No newline at end of file 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//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: "").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 == . + +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. + + + + + + diff --git a/README.txt b/README.txt new file mode 100644 index 0000000..aabe8a7 --- /dev/null +++ b/README.txt @@ -0,0 +1,143 @@ + __________ + + 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 +- +- + +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//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: "").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 `' . + + 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. diff --git a/lib/osugiru.rb b/lib/osugiru.rb index 91a2c06..4e99212 100644 --- a/lib/osugiru.rb +++ b/lib/osugiru.rb @@ -3,12 +3,13 @@ require 'notmuch' require 'pry' -require_relative 'osugiru/database' require_relative 'osugiru/config' +require_relative 'osugiru/database' +require_relative 'osugiru/helpers' require_relative 'osugiru/message' require_relative 'osugiru/messages' -require_relative 'osugiru/helpers' require_relative 'osugiru/ruleset' +require_relative 'osugiru/tags' module Osugiru class << self diff --git a/lib/osugiru/database.rb b/lib/osugiru/database.rb index d014c94..0d33a24 100644 --- a/lib/osugiru/database.rb +++ b/lib/osugiru/database.rb @@ -5,7 +5,7 @@ module Osugiru attr_reader :db def initialize(path:) - @db = ::Notmuch::Database.new(path) + @db = ::Notmuch::Database.new(path, mode: Notmuch::MODE_READ_WRITE) end def query(query) diff --git a/lib/osugiru/message.rb b/lib/osugiru/message.rb index 3446f17..0555724 100644 --- a/lib/osugiru/message.rb +++ b/lib/osugiru/message.rb @@ -6,9 +6,10 @@ module Osugiru def initialize(msg:) @message = msg + @tags = @message.tags end - def method_missing(method_name, *_args) + def method_missing(method_name, *_args) handle_get(Osugiru::Helpers.header_name_from_dsl(method_name)) end @@ -17,7 +18,19 @@ module Osugiru end def tags - @message.tags + @tags + end + + def tags=(new_tags) + @tags = new_tags + end + + def save! + message.remove_all_tags + tags.each do |tag| + message.add_tag(tag) + end + binding.pry end end end -- cgit v1.2.3