gmail-britta 0.1.4 → 0.1.5

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/Gemfile

@@ -8,6 +8,8 @@ gem 'haml', '~> 3.1.6'
 group :development do
   gem "shoulda", ">= 0"
   gem "rdoc", "~> 3.12"
+  gem "yard", '~> 0.8.3'
+  gem 'redcarpet', '~> 2.2.2'
   gem "bundler", "~> 1.2.0"
   gem "jeweler", "~> 1.8.4"
   gem "rcov", ">= 0"

data/Gemfile.lock

@@ -20,12 +20,14 @@ GEM
     rcov (1.0.0)
     rdoc (3.12)
       json (~> 1.4)
+    redcarpet (2.2.2)
     shoulda (3.1.1)
       shoulda-context (~> 1.0)
       shoulda-matchers (~> 1.2)
     shoulda-context (1.0.0)
     shoulda-matchers (1.3.0)
       activesupport (>= 3.0.0)
+    yard (0.8.3)
 
 PLATFORMS
   ruby
@@ -38,4 +40,6 @@ DEPENDENCIES
   nokogiri
   rcov
   rdoc (~> 3.12)
+  redcarpet (~> 2.2.2)
   shoulda
+  yard (~> 0.8.3)

data/README.md

@@ -0,0 +1,186 @@
+# gmail-britta
+
+This library helps you generate XML that you can import into gmail's
+filter settings. It makes it more pleasant to write simple (and even
+complex) filter chains.
+
+## Motivation
+
+As a user of the internet, you probably use gmail, and you probably
+get a lot of Email - I do. Just like me, you're also likely to have a
+lot of filters that were once supposed to keep your inbox
+clean. But every time you click "Filter messages like this", you
+remember the enormous list of filters you have and how it is only ever
+going to make things worse in the long run.
+
+### But how do you make them better?
+
+As a programmer, I write code. As a metaprogrammer, I write code that
+writes code. If only gmail filters could be written by a program. Oh
+wait, [they
+can](http://gmailblog.blogspot.com/2009/03/new-in-labs-filter-importexport.html).
+There's an import & export function for gmail filters. These filters
+are exported as XML, and the import in turn takes XML files. What this
+library does is generate XML that you can import.
+
+## Examples
+
+Here are some very simple examples of how gmail-britta can make your
+life easier:
+
+### Archiving (or not) semi-important email
+
+Imagine you're on a discussion mailing list that you skim from time to
+time - so you want to label email to that list, and archive email from
+it so it doesn't clog up your inbox. Now, from time to time someone
+will Cc: you an important message, and you don't want to miss these -
+what to do?
+
+Naively, you define a filter like this:
+
+```
+list:discuss@lists.some-side-project.org !to:thisisme@mydomain.com
+     -> Archive, Label "some-side-project"
+```
+
+But this also means email addressed to you but also sent to that list
+will be missing the "some-side-project" label. This means you need two
+filters!
+
+```
+list:discuss@lists.some-side-project.org !to:thisisme@mydomain.com
+     -> Archive
+list:discuss@lists.some-side-project.org
+     -> Label "some-side-project"
+```
+
+Now this can get pretty hairy pretty quickly; and if you ever have to
+change the filter (e.g., the list changes email addresses), you have
+to change two filters! Ugh.
+
+With gmail-britta, it's just this:
+
+``` ruby
+GmailBritta.filterset do
+  filter {
+    has %w{list:discuss@lists.some-side-project.org}
+  }.archive_unless_directed
+end
+```
+
+That's it - this little piece of ruby code will generate these two
+filters; and if the list address changes, you just re-import these
+filters. Easy.
+
+### Better detection of your own email address
+
+If you have issued a search for `to:me` on gmail in the last few
+months (and you get Email from iCloud nee MobileMe users), you'll
+notice that `to:me` also matches the "me" in `example@me.com`. This is
+very frustrating mostly because any filter as above that matches on
+`to:me` will now also not archive email sent from a me.com
+account. With gmail-britta, you can define a set of emails that are
+yours, and `archive_unless_directed` will generate a filter that
+matches on those:
+
+``` ruby
+GmailBritta.filterset(:me => ['thisisme@my-private.org', 'this-is-me@bigco.example.com']) do
+  filter {
+    has %w{list:discuss@lists.some-side-project.org}
+  }.archive_unless_directed
+end
+```
+
+### If/else chains on filters
+
+There are instances where you can't only match on the mailing list -
+sometimes interesting stuff will be sent to one list (that you want to
+read), and lots of unnecessary silliness will be sent there too. So,
+to put email with a certain subject into one label, and to put all the
+rest into another, you have to make multiple filters. But gmail lacks
+if/else in filters - you have to duplicate and correctly negate each
+filter's condition in the next one. Luckily, you have gmail-britta to
+help you out there:
+
+``` ruby
+GmailBritta.filterset do
+  filter {
+    has %w{list:robots@bigco.com subject:Important}
+    label 'work/robots/important'
+    # Do not archive
+  }.otherwise {
+    has %w{list:robots@bigco.com subject:Chunder}
+    label 'work/robots/irrelevant'
+  }.archive_unless_directed(:mark_read => true).otherwise {
+    has %w{list:robots@bigco.com subject:Semirelevant}
+    label 'work/robots/meh'
+  }.archive_unless_directed
+end
+```
+
+A lot of things going on here! First, I hope you notice that this
+looks similar to an if/else-if statement. Second, you may notice the
+liberal application of `.archive_unless_directed`, with an optional
+`:mark_read` parameter. Third, do check out the XML generated by this,
+it's pretty horriffic - but the filters do exactly what the code says:
+
+1. If the email is sent to that list and has "Important" in the subject, it gets labeled with the work/robots/important label, and won't be archived (unless another filter further down does archive that email).
+2. If the email does not match all the above criteria, but is sent to that list and has "Chunder" in the subject, label it irrelevant, archive it and mark the email as read.
+3. If the email does not match all the above criteria, but is sent to that list and has "Semirelevant" in the subject, label it "meh" and archive it, but don't mark it as read.
+
+## Installation & usage
+
+Best to use gmail-britta from a ruby script; but install the gem first:
+
+     gem install gmail-britta
+
+Or include it in your Gemfile:
+
+     gem 'gmail-britta'
+
+This is a simple script that generates filters for you:
+
+``` ruby
+#!/bin/env ruby
+
+require 'rubygems'
+require 'gmail-britta'
+
+fs = GmailBritta.filterset(:me => ['thisisme@my-private.org']) do
+  filter {
+    has %w{from:asf@boinkor.net}
+    label 'from-the-author-of-gmail-britta'
+    never_spam
+  }
+end
+puts fs.generate
+```
+
+Running this script will write to stdout the filter XML that you
+need. Redirect that to a file and upload it on the bottom of your
+gmail filter settings, and you'll label email from me and archive it
+unless I email you specifically. Not that useful, but with your own
+filters and the recipes above, you should be able to make it work (-:
+
+## A short apology to you, dear code-diver
+
+A lot of this is a bit hacky (particularly the filter condition merge
+logic), as it started as a oneoff ruby script - very sorry for any
+amateurish code you may encounter. There are few tests, but so far, it
+does work for me. Let me know if this made your life harder or easier!
+(-:
+
+## Contributing to gmail-britta
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. (Note that are only very few tests yet. I would totally appreciate if you started fleshing out this suite, but I wouldn't expect you to add much of anything.)
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2012 Andreas Fuchs. See LICENSE.txt for
+further details.

data/Rakefile

@@ -42,12 +42,6 @@ end
 
 task :default => :test
 
-require 'rdoc/task'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+require 'yard'
 
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "gmail-britta #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+YARD::Rake::YardocTask.new

data/VERSION

@@ -1 +1 @@
-0.1.4
+0.1.5

data/gmail-britta.gemspec

@@ -5,29 +5,30 @@
 
 Gem::Specification.new do |s|
   s.name = "gmail-britta"
-  s.version = "0.1.4"
+  s.version = "0.1.5"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Andreas Fuchs"]
-  s.date = "2012-12-22"
+  s.date = "2012-12-23"
   s.description = "This gem helps create large (>50) gmail filter chains by writing xml compatible with gmail's \"import/export filters\" feature."
   s.email = "asf@boinkor.net"
   s.extra_rdoc_files = [
     "LICENSE.txt",
-    "README.rdoc"
+    "README.md"
   ]
   s.files = [
     ".document",
+    ".yardopts",
     "Gemfile",
     "Gemfile.lock",
     "LICENSE.txt",
-    "README.rdoc",
+    "README.md",
     "Rakefile",
     "VERSION",
     "gmail-britta.gemspec",
     "lib/gmail-britta.rb",
-    "lib/gmail-britta/delegate.rb",
     "lib/gmail-britta/filter.rb",
+    "lib/gmail-britta/filter_set.rb",
     "lib/gmail-britta/single_write_accessors.rb",
     "test/test_gmail-britta.rb"
   ]
@@ -44,6 +45,8 @@ Gem::Specification.new do |s|
       s.add_runtime_dependency(%q<haml>, ["~> 3.1.6"])
       s.add_development_dependency(%q<shoulda>, [">= 0"])
       s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_development_dependency(%q<yard>, ["~> 0.8.3"])
+      s.add_development_dependency(%q<redcarpet>, ["~> 2.2.2"])
       s.add_development_dependency(%q<bundler>, ["~> 1.2.0"])
       s.add_development_dependency(%q<jeweler>, ["~> 1.8.4"])
       s.add_development_dependency(%q<rcov>, [">= 0"])
@@ -53,6 +56,8 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<haml>, ["~> 3.1.6"])
       s.add_dependency(%q<shoulda>, [">= 0"])
       s.add_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_dependency(%q<yard>, ["~> 0.8.3"])
+      s.add_dependency(%q<redcarpet>, ["~> 2.2.2"])
       s.add_dependency(%q<bundler>, ["~> 1.2.0"])
       s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
       s.add_dependency(%q<rcov>, [">= 0"])
@@ -63,6 +68,8 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<haml>, ["~> 3.1.6"])
     s.add_dependency(%q<shoulda>, [">= 0"])
     s.add_dependency(%q<rdoc>, ["~> 3.12"])
+    s.add_dependency(%q<yard>, ["~> 0.8.3"])
+    s.add_dependency(%q<redcarpet>, ["~> 2.2.2"])
     s.add_dependency(%q<bundler>, ["~> 1.2.0"])
     s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
     s.add_dependency(%q<rcov>, [">= 0"])

data/lib/gmail-britta.rb

@@ -11,50 +11,22 @@ require 'haml'
 require 'logger'
 
 require 'gmail-britta/single_write_accessors'
-require 'gmail-britta/delegate'
+require 'gmail-britta/filter_set'
 require 'gmail-britta/filter'
 
+# # A generator DSL for importable gmail filter specifications.
+#
+# This is the main entry point for defining a filter set (multiple filters). See {.filterset} for details.
 module GmailBritta
-  class Britta
-    def initialize(opts={})
-      @filters = []
-      @me = opts[:me] || 'me'
-      @logger = opts[:logger] || allocate_logger
-    end
-
-    def allocate_logger
-      logger = Logger.new(STDERR)
-      logger.level = Logger::WARN
-      logger
-    end
-
-    attr_accessor :filters
-    attr_accessor :me
-    attr_accessor :logger
-
-    def rules(&block)
-      GmailBritta::Delegate.new(self, :logger => @logger).perform(&block)
-    end
-
-    def generate
-      engine = Haml::Engine.new(<<-ATOM)
-!!! XML
-%feed{:xmlns => 'http://www.w3.org/2005/Atom', 'xmlns:apps' => 'http://schemas.google.com/apps/2006'}
-  %title Mail Filters
-  %id tag:mail.google.com,2008:filters:
-  %updated #{Time.now.utc.iso8601}
-  %author
-    %name Andreas Fuchs
-    %email asf@boinkor.net
-  - filters.each do |filter|
-    != filter.generate_xml
-ATOM
-      engine.render(self)
-    end
-  end
 
+  # Create a {FilterSet} and run the filter set definition in the block.
+  # This is the main entry point for GmailBritta.
+  # @option opts :me [Array<String>] A list of email addresses that should be considered as belonging to "you", effectively those email addresses you would expect `to:me` to match.
+  # @option opts :logger [Logger] (Logger.new()) An initialized logger instance.
+  # @yield the filterset definition block. `self` inside the block is the {FilterSet} instance.
+  # @return [FilterSet] the constructed filterset
   def self.filterset(opts={}, &block)
-    (britta = Britta.new(opts)).rules(&block)
+    (britta = FilterSet.new(opts)).rules(&block)
     britta
   end
 end

data/lib/gmail-britta/filter.rb

@@ -1,27 +1,137 @@
 module GmailBritta
+  # This class specifies the behavior of a single filter
+  # definition. Create a filter object in the DSL via
+  # {FilterSet::Delegator#filter} or use {Filter#also},
+  # {Filter#otherwise} or {Filter#archive_unless_directed} to make a
+  # new filter based on another one.
+  # @todo this probably needs some explanatory docs to make it understandable.
+
   class Filter
     include SingleWriteAccessors
-    single_write_accessor :has, 'hasTheWord' do |list|
-      emit_filter_spec(list)
-    end
-    single_write_accessor :has_not, 'doesNotHaveTheWord' do |list|
-      emit_filter_spec(list)
-    end
+
+    # @!group Methods for use in a filter definition block
+    # Archive the message.
+    # @!macro [new] bool_dsl_method
+    #   @return [void]
+    #   @!method $1()
     single_write_boolean_accessor :archive, 'shouldArchive'
+
+    # Move the message to the trash.
+    # @macro bool_dsl_method
     single_write_boolean_accessor :delete_it, 'shouldTrash'
+
+    # Mark the message as read.
+    # @macro bool_dsl_method
     single_write_boolean_accessor :mark_read, 'shouldMarkAsRead'
+
+    # Mark the message as important.
+    # @macro bool_dsl_method
     single_write_boolean_accessor :mark_important, 'shouldAlwaysMarkAsImportant'
+
+    # Do not mark the message as important.
+    # @macro bool_dsl_method
     single_write_boolean_accessor :mark_unimportant, 'shouldNeverMarkAsImportant'
+
+    # Star the message
+    # @macro bool_dsl_method
     single_write_boolean_accessor :star, 'shouldStar'
+
+    # Never mark the message as spam
+    # @macro bool_dsl_method
     single_write_boolean_accessor :never_spam, 'shouldNeverSpam'
+
+    # Assign the given label to the message
+    # @return [void]
+    # @!method label(label)
+    # @param [String] label the label to assign the message
     single_write_accessor :label, 'label'
+
+    # Forward the message to the given label.
+    # @return [void]
+    # @!method forward_to(email)
+    # @param [String] email an email address to forward the message to
     single_write_accessor :forward_to, 'forwardTo'
 
+    # @!method has(conditions)
+    # @return [void]
+    # Defines the positive conditions for the filter to match.
+    # @overload has([conditions])
+    #   Conditions ANDed together that an incoming email must match.
+    #   @param [Array<conditions>] conditions a list of gmail search terms, all of which must match
+    # @overload has({:or => [conditions]})
+    #   Conditions ORed together for the filter to match
+    #   @param [{:or => conditions}] conditions a hash of the form `{:or => [condition1, condition2]}` - either of these conditions must match to match the filter.
+    single_write_accessor :has, 'hasTheWord' do |list|
+      emit_filter_spec(list)
+    end
+
+    # @!method has_not(conditions)
+    # @return [void]
+    # Defines the negative conditions that must not match for the filter to be allowed to match.
+    single_write_accessor :has_not, 'doesNotHaveTheWord' do |list|
+      emit_filter_spec(list)
+    end
+    # @!endgroup
+
+    # Register and return a new filter that matches only if this
+    # filter's conditions (those that are not duplicated on the new
+    # filter's `has` clause) do not match.
+    # @yield The filter definition block
+    # @return [Filter] the new filter
+    def otherwise(&block)
+      filter = Filter.new(@britta, :log => @log).perform(&block)
+      filter.merge_negated_criteria(self)
+      filter.log_definition
+      filter
+    end
+
+    # Register and return a new filter that matches a message only if
+    # this filter's conditions *and* the previous filter's condition
+    # match.
+    # @yield The filter definition block
+    # @return [Filter] the new filter
+    def also(&block)
+      filter = Filter.new(@britta, :log => @log).perform(&block)
+      filter.merge_positive_criteria(self)
+      filter.log_definition
+      filter
+    end
+
+    # Register (but don't return) a filter that archives the message
+    # unless it matches the `:to` email addresses. Optionally, mark
+    # the message as read if this filter matches.
+    #
+    # @note This method returns the previous filter to make it easier to construct filter chains with {#otherwise} and {#also}.
+    #
+    # @option options [true, false] :mark_read If true, mark the message as read
+    # @option options [Array<String>] :to a list of addresses that the message may be addressed to in order to prevent this filter from matching. Defaults to the value given to :me on {GmailBritta.filterset}.
+    # @return [Filter] the current (not the newly-constructed filter)
+    def archive_unless_directed(options={})
+      mark_as_read=options[:mark_read]
+      tos=(options[:to] || me).to_a
+      filter = Filter.new(@britta, :log => @log).perform do
+        has_not [{:or => tos.map {|to| "to:#{to}"}}]
+        archive
+        if mark_as_read
+          mark_read
+        end
+      end
+      filter.merge_positive_criteria(self)
+      filter.log_definition
+      self
+    end
+
+    # Create a new filter object
+    # @note Over the lifetime of {GmailBritta}, new {Filter}s usually get created only by the {Delegate}.
+    # @param [GmailBritta::Britta] britta the filterset object
+    # @option options :log [Logger] a logger for debug messages
     def initialize(britta, options={})
       @britta = britta
       @log = options[:log]
     end
 
+    # Return the filter's value as XML text.
+    # @return [String] the Atom XML representation of this filter
     def generate_xml
       engine = Haml::Engine.new(<<-ATOM)
 %entry
@@ -36,49 +146,19 @@ ATOM
       engine.render(self)
     end
 
-    def self.emit_filter_spec(filter, infix=' ')
-      str = ''
-      case filter
-      when String
-        str << filter
-      when Hash
-        filter.keys.each do |key|
-          case key
-          when :or
-              str << '('
-            str << emit_filter_spec(filter[key], ' OR ')
-            str << ')'
-          when :not
-              str << '-('
-            str << emit_filter_spec(filter[key], ' ')
-            str << ')'
-          end
-        end
-      when Array
-        str << filter.map {|elt| emit_filter_spec(elt, ' ')}.join(infix)
-      end
-      str
-    end
-
-    def me
-      @britta.me
-    end
-
-    def log_definition
-      @log.debug  "Filter: #{self}"
-      Filter.single_write_accessors.each do |name|
-        val = instance_variable_get(Filter.ivar_name(name))
-        @log.debug "  #{name}: #{val}" if val
-      end
-      self
-    end
-
+    # Evaluate block as a filter definition block and register `self` as a filter on the containing {FilterSet}
+    # @note this method gets called by {Delegate#filter} to create and register a new filter object
+    # @yield The filter definition. `self` in the block is the new filter object.
+    # @api private
+    # @return [Filter] the filter that
     def perform(&block)
       instance_eval(&block)
       @britta.filters << self
       self
     end
 
+    protected
+
     def merge_negated_criteria(filter)
       old_has_not = Marshal.load(Marshal.dump((filter.get_has_not || []).reject { |elt|
             @has.member?(elt)
@@ -103,13 +183,6 @@ ATOM
       @log.debug("  M: nhn #{@has_not.inspect}")
     end
 
-    def otherwise(&block)
-      filter = Filter.new(@britta, :log => @log).perform(&block)
-      filter.merge_negated_criteria(self)
-      filter.log_definition
-      filter
-    end
-
     def merge_positive_criteria(filter)
       new_has = (@has || []) + (filter.get_has || [])
       new_has_not = (@has_not || []) + (filter.get_has_not || [])
@@ -117,26 +190,44 @@ ATOM
       @has_not = new_has_not
     end
 
-    def also(&block)
-      filter = Filter.new(@britta, :log => @log).perform(&block)
-      filter.merge_positive_criteria(self)
-      filter.log_definition
-      filter
+    def self.emit_filter_spec(filter, infix=' ')
+      str = ''
+      case filter
+      when String
+        str << filter
+      when Hash
+        filter.keys.each do |key|
+          case key
+          when :or
+              str << '('
+            str << emit_filter_spec(filter[key], ' OR ')
+            str << ')'
+          when :not
+              str << '-('
+            str << emit_filter_spec(filter[key], ' ')
+            str << ')'
+          end
+        end
+      when Array
+        str << filter.map {|elt| emit_filter_spec(elt, ' ')}.join(infix)
+      end
+      str
     end
 
-    def archive_unless_directed(options={})
-      mark_as_read=options[:mark_read]
-      tos=(options[:to] || me).to_a
-      filter = Filter.new(@britta, :log => @log).perform do
-        has_not [{:or => tos.map {|to| "to:#{to}"}}]
-        archive
-        if mark_as_read
-          mark_read
-        end
+    # Note a filter definition on the logger.
+    # @note for debugging only.
+    def log_definition
+      @log.debug  "Filter: #{self}"
+      Filter.single_write_accessors.each do |name|
+        val = instance_variable_get(Filter.ivar_name(name))
+        @log.debug "  #{name}: #{val}" if val
       end
-      filter.merge_positive_criteria(self)
-      filter.log_definition
       self
     end
+
+    # Return the list of emails that the filterset has configured as "me".
+    def me
+      @britta.me
+    end
   end
 end

data/lib/gmail-britta/filter_set.rb

@@ -0,0 +1,82 @@
+module GmailBritta
+  class FilterSet
+    def initialize(opts={})
+      @filters = []
+      @me = opts[:me] || 'me'
+      @logger = opts[:logger] || allocate_logger
+    end
+
+    # Currently defined filters
+    # @see Delegate#filter
+    # @see GmailBritta::Filter#otherwise
+    # @see GmailBritta::Filter#also
+    # @see GmailBritta::Filter#archive_unless_directed
+    attr_accessor :filters
+
+    # The list of emails that belong to the user running this {FilterSet} definition
+    # @see GmailBritta.filterset
+    attr_accessor :me
+
+    # The logger currently being used for debug output
+    # @see GmailBritta.filterset
+    attr_accessor :logger
+
+    # Run the block that defines the filters in {Delegate}'s `instance_eval`. This method will typically only be called by {GmailBritta.filterset}.
+    # @api private
+    # @yield the filter definition block in {Delegate}'s instance_eval.
+    def rules(&block)
+      Delegate.new(self, :logger => @logger).perform(&block)
+    end
+
+    # Generate ATOM XML for the defined filter set and return it as a String.
+    # @return [String] the generated XML, ready for importing into Gmail.
+    def generate
+      engine = Haml::Engine.new(<<-ATOM)
+!!! XML
+%feed{:xmlns => 'http://www.w3.org/2005/Atom', 'xmlns:apps' => 'http://schemas.google.com/apps/2006'}
+  %title Mail Filters
+  %id tag:mail.google.com,2008:filters:
+  %updated #{Time.now.utc.iso8601}
+  %author
+    %name Andreas Fuchs
+    %email asf@boinkor.net
+  - filters.each do |filter|
+    != filter.generate_xml
+ATOM
+      engine.render(self)
+    end
+
+    # A class whose sole purpose it is to be the `self` in a {FilterSet} definition block.
+    class Delegate
+
+      # @api private
+      def initialize(britta, options={})
+        @britta = britta
+        @log = options[:logger]
+        @filter = nil
+      end
+
+      # Create, register and return a new {Filter} without any merged conditions
+      # @yield [] the {Filter} definition block, with the new {Filter} instance as `self`.
+      # @return [Filtere] the new filter.
+      def filter(&block)
+        GmailBritta::Filter.new(@britta, :log => @log).perform(&block)
+      end
+
+      # Evaluate the {FilterSet} definition block with the {Delegate} object as `self`
+      # @api private
+      # @note this method will typically only be called by {FilterSet#rules}
+      # @yield [ ] that filterset definition block
+      def perform(&block)
+        instance_eval(&block)
+      end
+    end
+
+    private
+    def allocate_logger
+      logger = Logger.new(STDERR)
+      logger.level = Logger::WARN
+      logger
+    end
+  end
+end

data/lib/gmail-britta/single_write_accessors.rb

@@ -51,6 +51,7 @@ module GmailBritta
       end
     end
 
+    # @!visibility private
     def self.included(base)
       base.extend(ClassMethods)
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: gmail-britta
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 17
   prerelease: 
   segments: 
   - 0
   - 1
-  - 4
-  version: 0.1.4
+  - 5
+  version: 0.1.5
 platform: ruby
 authors: 
 - Andreas Fuchs
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-12-22 00:00:00 Z
+date: 2012-12-23 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   version_requirements: &id001 !ruby/object:Gem::Requirement 
@@ -64,6 +64,38 @@ dependencies:
   requirement: *id003
 - !ruby/object:Gem::Dependency 
   version_requirements: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 57
+        segments: 
+        - 0
+        - 8
+        - 3
+        version: 0.8.3
+  prerelease: false
+  type: :development
+  name: yard
+  requirement: *id004
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 2
+        - 2
+        - 2
+        version: 2.2.2
+  prerelease: false
+  type: :development
+  name: redcarpet
+  requirement: *id005
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -77,9 +109,9 @@ dependencies:
   prerelease: false
   type: :development
   name: bundler
-  requirement: *id004
+  requirement: *id006
 - !ruby/object:Gem::Dependency 
-  version_requirements: &id005 !ruby/object:Gem::Requirement 
+  version_requirements: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -93,9 +125,9 @@ dependencies:
   prerelease: false
   type: :development
   name: jeweler
-  requirement: *id005
+  requirement: *id007
 - !ruby/object:Gem::Dependency 
-  version_requirements: &id006 !ruby/object:Gem::Requirement 
+  version_requirements: &id008 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -107,9 +139,9 @@ dependencies:
   prerelease: false
   type: :development
   name: rcov
-  requirement: *id006
+  requirement: *id008
 - !ruby/object:Gem::Dependency 
-  version_requirements: &id007 !ruby/object:Gem::Requirement 
+  version_requirements: &id009 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -121,9 +153,9 @@ dependencies:
   prerelease: false
   type: :development
   name: minitest
-  requirement: *id007
+  requirement: *id009
 - !ruby/object:Gem::Dependency 
-  version_requirements: &id008 !ruby/object:Gem::Requirement 
+  version_requirements: &id010 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -135,7 +167,7 @@ dependencies:
   prerelease: false
   type: :development
   name: nokogiri
-  requirement: *id008
+  requirement: *id010
 description: This gem helps create large (>50) gmail filter chains by writing xml compatible with gmail's "import/export filters" feature.
 email: asf@boinkor.net
 executables: []
@@ -144,19 +176,20 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE.txt
-- README.rdoc
+- README.md
 files: 
 - .document
+- .yardopts
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
-- README.rdoc
+- README.md
 - Rakefile
 - VERSION
 - gmail-britta.gemspec
 - lib/gmail-britta.rb
-- lib/gmail-britta/delegate.rb
 - lib/gmail-britta/filter.rb
+- lib/gmail-britta/filter_set.rb
 - lib/gmail-britta/single_write_accessors.rb
 - test/test_gmail-britta.rb
 homepage: http://github.com/antifuchs/gmail-britta

data/README.rdoc

@@ -1,24 +0,0 @@
-= gmail-britta
-
-This gem assists in writing complex gmail filters. You probably have a
-lot of questions, and I'm sorry this README currently answers so few
-of them )-:
-
-A lot of this is very hacky, as it started as a oneoff ruby script -
-very sorry for any amateurish code you may encounter. All I can say
-is, it works for me [-:
-
-== Contributing to gmail-britta
-
-* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
-* Fork the project.
-* Start a feature/bugfix branch.
-* Commit and push until you are happy with your contribution.
-* Make sure to add tests for it. (Note that are only very few tests yet. I would totally appreciate if you started fleshing out this suite, but I wouldn't expect you to add much of anything.)
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
-
-== Copyright
-
-Copyright (c) 2012 Andreas Fuchs. See LICENSE.txt for
-further details.

data/lib/gmail-britta/delegate.rb

@@ -1,17 +0,0 @@
-module GmailBritta
-  class Delegate
-    def initialize(britta, options={})
-      @britta = britta
-      @log = options[:logger]
-      @filter = nil
-    end
-
-    def filter(&block)
-      GmailBritta::Filter.new(@britta, :log => @log).perform(&block)
-    end
-
-    def perform(&block)
-      instance_eval(&block)
-    end
-  end
-end