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

Parameters:

  • britta (GmailBritta::Britta)

    the filterset object

  • options (Hash) (defaults to: {})

    a customizable set of options

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

Returns:


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.

Parameters:

  • options (Hash) (defaults to: {})

    a customizable set of options

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.

Returns:

  • (Filter)

    self (not the newly-constructed filter)


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.

Parameters:

  • email (String)

    an email address to forward the message to


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.

Returns:

  • (String)

    the Atom XML representation of this filter


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.

    Parameters:

    • conditions (Array<conditions>)

      a list of gmail search terms, all of which must match

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

    Conditions ORed together for the filter to match

    Parameters:

    • conditions ({:or => conditions})

      a hash of the form {:or => [condition1, condition2]} - either of these conditions must match to match the filter.


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

Parameters:

  • label (String)

    the label to assign 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

Returns:


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.

Returns:

  • (Filter)

    the filter that


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

Parameters:

  • category (String)

    the smart label to assign 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.

    Parameters:

    • conditions (Array<conditions>)

      a list of gmail search terms, all of which must match

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

    Conditions ORed together for the filter to match

    Parameters:

    • conditions ({:or => conditions})

      a hash of the form {:or => [condition1, condition2]} - either of these conditions must match to match the filter.


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