Class: IMAPProcessor
- Inherits:
-
Object
- Object
- IMAPProcessor
- Defined in:
- lib/imap_processor.rb
Overview
IMAPProcessor is a client for processing messages on an IMAP server.
Subclasses need to provide:
-
A process_args class method that adds any extra options to the default IMAPProcessor options.
-
An initialize method that connects to an IMAP server and sets the @imap instance variable
-
A run method that uses the IMAP connection to process messages.
Defined Under Namespace
Classes: Archive, Connection, Error, IDLE, Keywords
Constant Summary collapse
- VERSION =
The version of IMAPProcessor you are using
'1.3'
- @@options =
{}
- @@extra_options =
[]
Instance Attribute Summary collapse
-
#imap ⇒ Object
readonly
Net::IMAP connection, set this via #initialize.
-
#options ⇒ Object
readonly
Options Hash from process_args.
Class Method Summary collapse
-
.add_move ⇒ Object
Adds a –move option to the option parser which stores the destination mailbox in the MoveTo option.
-
.process_args(processor_file, args, required_options = {}) ⇒ Object
Handles processing of
args
loading defaults from a file in ~ based onprocessor_file
. -
.run(args = ARGV, &block) ⇒ Object
Sets up an IMAP processor’s options then calls its #run method.
Instance Method Summary collapse
-
#connect(host = , port = , ssl = , username = , password = , auth = ) ⇒ Object
Connects to IMAP server
host
atport
using ssl ifssl
is true then logs in asusername
withpassword
. -
#create_mailbox(name) ⇒ Object
Create the mailbox
name
if it doesn’t exist. -
#delete_messages(uids, expunge = true) ⇒ Object
Delete and
expunge
the specifieduids
. -
#each_message(uids, type) ⇒ Object
Yields each uid and message as a TMail::Message for
uids
of MIME typetype
. -
#each_part(parts, header = false) ⇒ Object
Yields each message part from
parts
. -
#initialize(options) ⇒ IMAPProcessor
constructor
Handles the basic settings from
options
including verbosity, mailboxes to process, and Net::IMAP::debug. -
#log(message) ⇒ Object
Logs
message
to $stderr if verbose. -
#mime_parts(uids, mime_type) ⇒ Object
Retrieves the BODY data item name for the
mime_type
part from messagesuids
. -
#move_messages(uids, destination, expunge = true) ⇒ Object
Move the specified
uids
to a newdestination
then delete andexpunge
them. -
#show_messages(uids) ⇒ Object
Displays Date, Subject and Message-Id from messages in
uids
. -
#verbose? ⇒ Boolean
Did the user set –verbose?.
Constructor Details
#initialize(options) ⇒ IMAPProcessor
Handles the basic settings from options
including verbosity, mailboxes to process, and Net::IMAP::debug
308 309 310 311 312 313 |
# File 'lib/imap_processor.rb', line 308 def initialize() @options = @verbose = [:Verbose] @boxes = [:Boxes] Net::IMAP.debug = [:Debug] end |
Instance Attribute Details
#imap ⇒ Object (readonly)
Net::IMAP connection, set this via #initialize
56 57 58 |
# File 'lib/imap_processor.rb', line 56 def imap @imap end |
#options ⇒ Object (readonly)
Options Hash from process_args
61 62 63 |
# File 'lib/imap_processor.rb', line 61 def @options end |
Class Method Details
.add_move ⇒ Object
Adds a –move option to the option parser which stores the destination mailbox in the MoveTo option. Call this from a subclass’ process_args method.
71 72 73 74 75 76 77 78 79 80 81 82 |
# File 'lib/imap_processor.rb', line 71 def self.add_move @@options[:MoveTo] = nil @@extra_options << proc do |opts, | opts.on( "--move=MAILBOX", "Mailbox to move message to", "Default: #{[:MoveTo].inspect}", "Options file name: :MoveTo") do |mailbox| [:MoveTo] = mailbox end end end |
.process_args(processor_file, args, required_options = {}) ⇒ Object
Handles processing of args
loading defaults from a file in ~ based on processor_file
. Extra option defaults can be specified by required_options
. Yields an option parser instance to add new OptionParser options to:
class MyProcessor < IMAPProcessor
def self.process_args(args)
required_options = {
:MoveTo => [nil, "MoveTo not set"],
}
super __FILE__, args, required_options do |opts, options|
opts.banner << "Explain my_processor's executable"
opts.on( "--move=MAILBOX",
"Mailbox to move message to",
"Default: #{options[:MoveTo].inspect}",
"Options file name: :MoveTo") do |mailbox|
options[:MoveTo] = mailbox
end
end
end
NOTE: You can add a –move option using ::add_move
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 |
# File 'lib/imap_processor.rb', line 110 def self.process_args(processor_file, args, = {}) # :yield: OptionParser opts_file_name = File.basename processor_file, '.rb' opts_file_name = "imap_#{opts_file_name}" unless opts_file_name =~ /^imap_/ opts_file = File. "~/.#{opts_file_name}" = @@options.dup if then .each do |option, (default, )| raise ArgumentError, "required_options message is missing for #{option}" if default.nil? and .nil? end end if File.exist? opts_file then unless File.stat(opts_file).mode & 077 == 0 then $stderr.puts "WARNING! #{opts_file} is group/other readable or writable!" $stderr.puts "WARNING! I'm not doing a thing until you fix it!" exit 1 end .merge! YAML.load_file(opts_file) end [:SSL] = true unless .key? :SSL [:Username] ||= ENV['USER'] [:Root] ||= nil [:Verbose] ||= false [:Debug] ||= false .each do |k,(v,m)| [k] ||= v end op = OptionParser.new do |opts| opts.program_name = File.basename $0 opts. = "Usage: #{opts.program_name} [options]\n\n" opts.separator '' opts.separator 'Connection options:' opts.on("-H", "--host HOST", "IMAP server host", "Default: #{[:Host].inspect}", "Options file name: :Host") do |host| [:Host] = host end opts.on("-P", "--port PORT", "IMAP server port", "Default: The correct port SSL/non-SSL mode", "Options file name: :Port") do |port| [:Port] = port end opts.on("-s", "--[no-]ssl", "Use SSL for IMAP connection", "Default: #{[:SSL].inspect}", "Options file name: :SSL") do |ssl| [:SSL] = ssl end opts.on( "--[no-]debug", "Display Net::IMAP debugging info", "Default: #{[:Debug].inspect}", "Options file name: :Debug") do |debug| [:Debug] = debug end opts.separator '' opts.separator 'Login options:' opts.on("-u", "--username USERNAME", "IMAP username", "Default: #{[:Username].inspect}", "Options file name: :Username") do |username| [:Username] = username end opts.on("-p", "--password PASSWORD", "IMAP password", "Default: Read from ~/.#{opts_file_name}", "Options file name: :Password") do |password| [:Password] = password end authenticators = Net::IMAP.send :class_variable_get, :@@authenticators auth_types = authenticators.keys.sort.join ', ' opts.on("-a", "--auth AUTH", auth_types, "IMAP authentication type override", "Authentication type will be auto-", "discovered", "Default: #{[:Auth].inspect}", "Options file name: :Auth") do |auth| [:Auth] = auth end opts.separator '' opts.separator "IMAP options:" opts.on("-r", "--root ROOT", "Root of mailbox hierarchy", "Default: #{[:Root].inspect}", "Options file name: :Root") do |root| [:Root] = root end opts.on("-b", "--boxes BOXES", Array, "Comma-separated list of mailbox names", "to search", "Default: #{[:Boxes].inspect}", "Options file name: :Boxes") do |boxes| [:Boxes] = boxes end opts.on("-v", "--[no-]verbose", "Be verbose", "Default: #{[:Verbose].inspect}", "Options file name: :Verbose") do |verbose| [:Verbose] = verbose end opts.on("-q", "--quiet", "Be quiet") do [:Verbose] = false end if block_given? then opts.separator '' opts.separator "#{self} options:" yield opts, if block_given? end @@extra_options.each do |block| block.call opts, end opts.separator '' opts. << <<-EOF Options may also be set in the options file ~/.#{opts_file_name} Example ~/.#{opts_file_name}: \tHost=mail.example.com \tPassword=my password EOF end op.parse! args [:Port] ||= [:SSL] ? 993 : 143 if [:Host].nil? or [:Password].nil? or [:Boxes].nil? or .any? { |k,(v,m)| [k].nil? } then $stderr.puts op $stderr.puts $stderr.puts "Host name not set" if [:Host].nil? $stderr.puts "Password not set" if [:Password].nil? $stderr.puts "Boxes not set" if [:Boxes].nil? .each do |option_name, (option_value, )| $stderr.puts if [option_name].nil? end exit 1 end return end |
.run(args = ARGV, &block) ⇒ Object
Sets up an IMAP processor’s options then calls its #run method.
287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 |
# File 'lib/imap_processor.rb', line 287 def self.run(args = ARGV, &block) = process_args args client = new(, &block) client.run rescue Interrupt exit rescue SystemExit raise rescue Exception => e $stderr.puts "Failed to finish with exception: #{e.class}:#{e.}" $stderr.puts "\t#{e.backtrace.join "\n\t"}" exit 1 ensure client.imap.logout if client and client.imap end |
Instance Method Details
#connect(host = , port = , ssl = , username = , password = , auth = ) ⇒ Object
Connects to IMAP server host
at port
using ssl if ssl
is true then logs in as username
with password
. IMAPProcessor is only known to work with PLAIN auth on SSL sockets.
Returns a Connection object.
322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 |
# File 'lib/imap_processor.rb', line 322 def connect(host = @options[:Host], port = @options[:Port], ssl = @options[:SSL], username = @options[:Username], password = @options[:Password], auth = @options[:Auth]) # :yields: Connection imap = Net::IMAP.new host, port, ssl, nil, false log "Connected to imap://#{host}:#{port}/" capability = imap.capability log "Capabilities: #{capability.join ', '}" auth_caps = capability.select { |c| c =~ /^AUTH/ } if auth.nil? then raise "Couldn't find a supported auth type" if auth_caps.empty? auth = auth_caps.first.sub(/AUTH=/, '') end auth = auth.upcase log "Trying #{auth} authentication" imap.authenticate auth, username, password log "Logged in as #{username}" connection = Connection.new imap, capability if block_given? then begin yield connection ensure connection.imap.logout end else return connection end end |
#create_mailbox(name) ⇒ Object
Create the mailbox name
if it doesn’t exist. Note that this will SELECT the mailbox if it exists.
364 365 366 367 368 369 370 |
# File 'lib/imap_processor.rb', line 364 def create_mailbox name log "LIST #{name}" list = imap.list '', name return if list log "CREATE #{name}" imap.create name end |
#delete_messages(uids, expunge = true) ⇒ Object
Delete and expunge
the specified uids
.
375 376 377 378 379 380 381 382 |
# File 'lib/imap_processor.rb', line 375 def uids, expunge = true log "DELETING [...#{uids.size} uids]" imap.store uids, '+FLAGS.SILENT', [:Deleted] if expunge then log "EXPUNGE" imap.expunge end end |
#each_message(uids, type) ⇒ Object
Yields each uid and message as a TMail::Message for uids
of MIME type type
.
If there’s an exception raised during handling a message the subject, message-id and inspected body are logged.
If the block returns nil or false, the message is considered skipped and its uid is not returned in the uid list. (Hint: next false unless …)
Returns the uids of successfully handled messages.
396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 |
# File 'lib/imap_processor.rb', line 396 def (uids, type) # :yields: TMail::Mail parts = mime_parts uids, type uids = [] each_part parts, true do |uid, | skip = false mail = TMail::Mail.parse begin success = yield uid, mail uids << uid if success rescue => e log e. puts "\t#{e.backtrace.join "\n\t"}" unless $DEBUG # backtrace at bottom log "Subject: #{mail.subject}" log "Message-Id: #{mail.}" p mail.body if verbose? raise if $DEBUG end end uids end |
#each_part(parts, header = false) ⇒ Object
Yields each message part from parts
. If header
is true, a complete message is yielded, appropriately joined for use with TMail::Mail.
428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 |
# File 'lib/imap_processor.rb', line 428 def each_part(parts, header = false) # :yields: uid, message parts.each do |uid, section| sequence = ["BODY[#{section}]"] sequence.unshift "BODY[#{section}.MIME]" unless section == 'TEXT' sequence.unshift 'BODY[HEADER]' if header body = imap.fetch(uid, sequence).first sequence = sequence.map { |item| body.attr[item] } unless section == 'TEXT' and header then sequence[0].sub!(/\r\n\z/, '') end yield uid, sequence.join end end |
#log(message) ⇒ Object
Logs message
to $stderr if verbose
449 450 451 452 |
# File 'lib/imap_processor.rb', line 449 def log() return unless @verbose $stderr.puts "# #{}" end |
#mime_parts(uids, mime_type) ⇒ Object
Retrieves the BODY data item name for the mime_type
part from messages uids
. Returns an array of uid/part pairs. If no matching part with mime_type
is found the uid is omitted.
Returns an Array of uid, section pairs.
Use a subsequent Net::IMAP#fetch to retrieve the selected part.
463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 |
# File 'lib/imap_processor.rb', line 463 def mime_parts(uids, mime_type) media_type, subtype = mime_type.upcase.split('/', 2) structures = imap.fetch uids, 'BODYSTRUCTURE' structures.zip(uids).map do |body, uid| section = nil structure = body.attr['BODYSTRUCTURE'] case structure when Net::IMAP::BodyTypeMultipart then parts = structure.parts section = parts.each_with_index do |part, index| break index if part.media_type == media_type and part.subtype == subtype end next unless Integer === section when Net::IMAP::BodyTypeText, Net::IMAP::BodyTypeBasic then section = 'TEXT' if structure.media_type == media_type and structure.subtype == subtype end [uid, section] end.compact end |
#move_messages(uids, destination, expunge = true) ⇒ Object
Move the specified uids
to a new destination
then delete and expunge
them. Creates the destination mailbox if it doesn’t exist.
495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 |
# File 'lib/imap_processor.rb', line 495 def uids, destination, expunge = true return if uids.empty? log "COPY [...#{uids.size} uids]" begin imap.copy uids, destination rescue Net::IMAP::NoResponseError => e # ruby-lang bug #1713 #raise unless e.response.data.code.name == 'TRYCREATE' create_mailbox destination imap.copy uids, destination end uids, expunge end |
#show_messages(uids) ⇒ Object
Displays Date, Subject and Message-Id from messages in uids
514 515 516 517 518 519 520 521 522 523 524 |
# File 'lib/imap_processor.rb', line 514 def (uids) return if uids.nil? or (Array === uids and uids.empty?) fetch_data = 'BODY.PEEK[HEADER.FIELDS (DATE SUBJECT MESSAGE-ID)]' = imap.fetch uids, fetch_data fetch_data.sub! '.PEEK', '' # stripped by server .each do |res| puts res.attr[fetch_data].delete("\r") end end |
#verbose? ⇒ Boolean
Did the user set –verbose?
529 530 531 |
# File 'lib/imap_processor.rb', line 529 def verbose? @verbose end |