Class: GmailBritta::Filter

Inherits:
Object
  • Object
show all
Includes:
SingleWriteAccessors
Defined in:
lib/gmail-britta/filter.rb

Overview

TODO:

this probably needs some explanatory docs to make it understandable.

This class specifies the behavior of a single filter definition. Create a filter object in the DSL via FilterSet::Delegator#filter or use #also, #otherwise or #archive_unless_directed to make a new filter based on another one.

Direct Known Subclasses

ChainingFilter

Methods for use in a filter definition block collapse

Filter chaining collapse

Instance Method Summary collapse

Constructor Details

#initialize(britta, options = {}) ⇒ Filter

Note:

Over the lifetime of GmailBritta, new GmailBritta::Filters usually get created only by the GmailBritta::FilterSet::Delegate.

Create a new filter object

Options Hash (options):

  • :log (Logger)

    a logger for debug messages


187
188
189
190
191
192
193
194
# File 'lib/gmail-britta/filter.rb', line 187

def initialize(britta, options={})
  @britta = britta
  @log = options[:log]
  @from = []
  @to = []
  @has = []
  @has_not = []
end

Instance Method Details

#also { ... } ⇒ Filter

Register and return a new filter that matches a message only if this filter's conditions and the previous filter's condition match.

Yields:

  • The filter definition block


153
154
155
# File 'lib/gmail-britta/filter.rb', line 153

def also(&block)
  chain(PositiveChainingFilter, &block)
end

#archivevoid

This method returns an undefined value.

Archive the message.


17
# File 'lib/gmail-britta/filter.rb', line 17

single_write_boolean_accessor :archive, 'shouldArchive'

#archive_unless_directed(options = {}) ⇒ Filter

Note:

This method returns the previous filter to make it easier to construct filter chains with #otherwise and #also with #archive_unless_directed in the middle.

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.

Options Hash (options):

  • :mark_read (true, false)

    If true, mark the message as read

  • :to (Array<String>)

    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.


168
169
170
171
172
173
174
175
176
177
178
179
180
# File 'lib/gmail-britta/filter.rb', line 168

def archive_unless_directed(options={})
  mark_as_read=options[:mark_read]
  tos=Array(options[:to] || me)
  filter = PositiveChainingFilter.new(self).perform do
    has_not [{:or => tos.map {|to| "to:#{to}"}}]
    archive
    if mark_as_read
      mark_read
    end
  end
  filter.log_definition
  self
end

#chain(type, &block) ⇒ Object


133
134
135
136
137
# File 'lib/gmail-britta/filter.rb', line 133

def chain(type, &block)
  filter = type.new(self).perform(&block)
  filter.log_definition
  filter
end

#delete_itvoid

This method returns an undefined value.

Move the message to the trash.


21
# File 'lib/gmail-britta/filter.rb', line 21

single_write_boolean_accessor :delete_it, 'shouldTrash'

#forward_to(email) ⇒ void

This method returns an undefined value.

Forward the message to the given label.


74
# File 'lib/gmail-britta/filter.rb', line 74

single_write_accessor :forward_to, 'forwardTo'

#from(conditions) ⇒ void

This method returns an undefined value.

Defines the positive conditions for the filter to match. Uses: /apps:property Instead of: /apps:property


94
95
96
# File 'lib/gmail-britta/filter.rb', line 94

single_write_accessor :from, 'from' do |list|
  emit_filter_spec(list)
end

#generate_xmlString

Return the filter's value as XML text.


198
199
200
201
202
203
204
205
206
207
208
# File 'lib/gmail-britta/filter.rb', line 198

def generate_xml
  generate_xml_properties
  engine = Haml::Engine.new("
%entry
  %category{:term => 'filter'}
  %title Mail Filter
  %content
#{generate_haml_properties 1}
", :attr_wrapper => '"')
  engine.render(self)
end

#generate_xml_propertiesObject


210
211
212
213
# File 'lib/gmail-britta/filter.rb', line 210

def generate_xml_properties
  engine = Haml::Engine.new(generate_haml_properties, :attr_wrapper => '"')
  engine.render(self)
end

#has([conditions]) ⇒ void #has({: or => [conditions]}) ⇒ void

This method returns an undefined value.

Defines the positive conditions for the filter to match.

Overloads:

  • #has([conditions]) ⇒ void

    Conditions ANDed together that an incoming email must match.

  • #has({: or => [conditions]}) ⇒ void

    Conditions ORed together for the filter to match


85
86
87
# File 'lib/gmail-britta/filter.rb', line 85

single_write_accessor :has, 'hasTheWord' do |list|
  emit_filter_spec(list)
end

#has_attachmentvoid

This method returns an undefined value.

Filter for messages that have an attachment


129
# File 'lib/gmail-britta/filter.rb', line 129

single_write_boolean_accessor :has_attachment, 'hasAttachment'

#has_not(conditions) ⇒ void

This method returns an undefined value.

Defines the negative conditions that must not match for the filter to be allowed to match.


123
124
125
# File 'lib/gmail-britta/filter.rb', line 123

single_write_accessor :has_not, 'doesNotHaveTheWord' do |list|
  emit_filter_spec(list)
end

#label(label) ⇒ void

This method returns an undefined value.

Assign the given label to the message


47
# File 'lib/gmail-britta/filter.rb', line 47

single_write_accessor :label, 'label'

#mark_importantvoid

This method returns an undefined value.

Mark the message as important.


29
# File 'lib/gmail-britta/filter.rb', line 29

single_write_boolean_accessor :mark_important, 'shouldAlwaysMarkAsImportant'

#mark_readvoid

This method returns an undefined value.

Mark the message as read.


25
# File 'lib/gmail-britta/filter.rb', line 25

single_write_boolean_accessor :mark_read, 'shouldMarkAsRead'

#mark_unimportantvoid

This method returns an undefined value.

Do not mark the message as important.


33
# File 'lib/gmail-britta/filter.rb', line 33

single_write_boolean_accessor :mark_unimportant, 'shouldNeverMarkAsImportant'

#never_spamvoid

This method returns an undefined value.

Never mark the message as spam


41
# File 'lib/gmail-britta/filter.rb', line 41

single_write_boolean_accessor :never_spam, 'shouldNeverSpam'

#otherwise { ... } ⇒ Filter

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.

Yields:

  • The filter definition block


144
145
146
# File 'lib/gmail-britta/filter.rb', line 144

def otherwise(&block)
  chain(NegatedChainingFilter, &block)
end

#perform { ... } ⇒ Filter

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Note:

this method gets called by Delegate#filter to create and register a new filter object

Evaluate block as a filter definition block and register self as a filter on the containing GmailBritta::FilterSet

Yields:

  • The filter definition. self in the block is the new filter object.


220
221
222
223
224
# File 'lib/gmail-britta/filter.rb', line 220

def perform(&block)
  instance_eval(&block)
  @britta.filters << self
  self
end

#smart_label(category) ⇒ void

This method returns an undefined value.

Assign the given smart label to the message


53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
# File 'lib/gmail-britta/filter.rb', line 53

single_write_accessor :smart_label, 'smartLabelToApply' do |category|
  case category
  when 'personal', 'Personal'
    '^smartlabel_personal'
  when 'forums', 'Forums'
    '^smartlabel_group'
  when 'notifications', 'Notifications', 'updates', 'Updates'
    '^smartlabel_notification'
  when 'promotions', 'Promotions'
    '^smartlabel_promo'
  when 'social', 'Social'
    '^smartlabel_social'
  else
    raise 'invalid category "' << category << '"'
  end
end

#starvoid

This method returns an undefined value.

Star the message


37
# File 'lib/gmail-britta/filter.rb', line 37

single_write_boolean_accessor :star, 'shouldStar'

#subject([conditions]) ⇒ void #subject({: or => [conditions]}) ⇒ void

This method returns an undefined value.

Defines the positive conditions for the filter to match.

Overloads:

  • #subject([conditions]) ⇒ void

    Conditions ANDed together that an incoming email must match.

  • #subject({: or => [conditions]}) ⇒ void

    Conditions ORed together for the filter to match


116
117
118
# File 'lib/gmail-britta/filter.rb', line 116

single_write_accessor :subject, 'subject' do |list|
  emit_filter_spec(list)
end

#to(conditions) ⇒ void

This method returns an undefined value.

Defines the positive conditions for the filter to match. Uses: /apps:property Instead of: /apps:property


103
104
105
# File 'lib/gmail-britta/filter.rb', line 103

single_write_accessor :to, 'to' do |list|
  emit_filter_spec(list)
end