diff options
author | gsinclair <gsinclair@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2003-08-05 13:22:20 +0000 |
---|---|---|
committer | gsinclair <gsinclair@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2003-08-05 13:22:20 +0000 |
commit | 717848493c02584d1a7ae379766a01860ad548ee (patch) | |
tree | 519518e72ebb94b361db9551be48ed4ca9350344 | |
parent | f2c49270e75313b9438bfb80bd99925dbe9ca1b2 (diff) | |
download | ruby-717848493c02584d1a7ae379766a01860ad548ee.tar.gz |
RDoc comments provided by William Webber <wew@williamwebber.com>
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@4331 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
-rw-r--r-- | lib/net/pop.rb | 872 |
1 files changed, 405 insertions, 467 deletions
diff --git a/lib/net/pop.rb b/lib/net/pop.rb index 09d172df06..5b4ad69c73 100644 --- a/lib/net/pop.rb +++ b/lib/net/pop.rb @@ -1,468 +1,191 @@ -=begin - -= net/pop.rb - -Copyright (c) 1999-2003 Yukihiro Matsumoto -Copyright (c) 1999-2003 Minero Aoki - -written & maintained by Minero Aoki <aamine@loveruby.net> - -This program is free software. You can re-distribute and/or -modify this program under the same terms as Ruby itself, -Ruby Distribute License or GNU General Public License. - -NOTE: You can find Japanese version of this document in -the doc/net directory of the standard ruby interpreter package. - -$Id$ - -== What is This Module? - -This module provides your program the function to retrieve -mails via POP3, Post Office Protocol version 3. For details -of POP3, refer [RFC1939] ((<URL:http://www.ietf.org/rfc/rfc1939.txt>)). - -== Examples - -=== Retrieving Mails - -This example retrieves mails from server and delete it (on server). -Mails are written in file named 'inbox/1', 'inbox/2', .... -Replace 'pop3.server.address' your POP3 server address. - - require 'net/pop' - - pop = Net::POP3.new('pop.example.com', 110) - pop.start('YourAccount', 'YourPassword') # (1) - if pop.mails.empty? - puts 'no mail.' - else - i = 0 - pop.each_mail do |m| # or "pop.mails.each ..." # (2) - File.open("inbox/#{i}", 'w') {|f| - f.write m.pop - } - m.delete - i += 1 - end - puts "#{pop.mails.size} mails popped." - end - pop.finish # (3) - -(1) call Net::POP3#start and start POP session -(2) access mails by using POP3#each_mail and/or POP3#mails -(3) close POP session by calling POP3#finish or use block form #start. - -This example is using block form #start to close the session. - -=== Enshort Code - -The example above is very verbose. You can enshort code by using -some utility methods. At first, block form of Net::POP3.start can -alternates POP3.new, POP3#start and POP3#finish. - - require 'net/pop' - - Net::POP3.start('pop.example.com', 110, - 'YourAccount', 'YourPassword') {|pop| - if pop.mails.empty? - puts 'no mail.' - else - i = 0 - pop.each_mail do |m| # or "pop.mails.each ..." - File.open("inbox/#{i}", 'w') {|f| - f.write m.pop - } - m.delete - i += 1 - end - puts "#{pop.mails.size} mails popped." - end - } - -POP3#delete_all alternates #each_mail and m.delete. - - require 'net/pop' - - Net::POP3.start('pop.example.com', 110, - 'YourAccount', 'YourPassword') {|pop| - if pop.mails.empty? - puts 'no mail.' - else - i = 1 - pop.delete_all do |m| - File.open("inbox/#{i}", 'w') {|f| - f.write m.pop - } - i += 1 - end - end - } - -And here is more shorter example. - - require 'net/pop' - - i = 0 - Net::POP3.delete_all('pop.example.com', 110, - 'YourAccount', 'YourPassword') do |m| - File.open("inbox/#{i}", 'w') {|f| - f.write m.pop - } - i += 1 - end - -=== Memory Space Issue - -All examples above get mail as one big string. -This example does not create such one. - - require 'net/pop' - - i = 1 - Net::POP3.delete_all('pop.example.com', 110, - 'YourAccount', 'YourPassword') do |m| - File.open("inbox/#{i}", 'w') {|f| - m.pop do |chunk| # get a message little by little. - f.write chunk - end - i += 1 - } - end - -=== Using APOP - -The net/pop library supports APOP authentication. -To use APOP, use Net::APOP class instead of Net::POP3 class. -You can use utility method, Net::POP3.APOP(). Example: - - require 'net/pop' - - # Use APOP authentication if $isapop == true - pop = Net::POP3.APOP($is_apop).new('apop.example.com', 110) - pop.start(YourAccount', 'YourPassword') {|pop| - # Rest code is same. - } - -=== Fetch Only Selected Mail Using `UIDL' POP Command - -If your POP server provides UIDL function, -you can pop only selected mails from POP server. -e.g. - - def need_pop?( id ) - # determine if we need pop this mail... - end - - Net::POP3.start('pop.example.com', 110, - 'Your account', 'Your password') {|pop| - pop.mails.select {|m| need_pop?(m.unique_id) }.each do |m| - do_something(m.pop) - end - } - -POPMail#unique_id method returns the unique-id of the message (String). -Normally unique-id is a hash of the message. - - -== class Net::POP3 - -=== Class Methods - -: new( address, port = 110, isapop = false ) - creates a new Net::POP3 object. - This method does NOT open TCP connection yet. - -: start( address, port = 110, account, password, isapop = false ) -: start( address, port = 110, account, password, isapop = false ) {|pop| .... } - equals to Net::POP3.new(address, port, isapop).start(account, password). - This method raises POPAuthenticationError if authentication is failed. - - # Typical usage - Net::POP3.start(addr, port, account, password) {|pop| - pop.each_mail do |m| - file.write m.pop - m.delete - end - } - -: APOP( is_apop ) - returns Net::APOP class object if IS_APOP. - Else, IS_APOP. Use this method like: - - # Example 1 - pop = Net::POP3::APOP($is_apop).new(addr, port) - - # Example 2 - Net::POP3::APOP($is_apop).start(addr, port) {|pop| - .... - } - -: foreach( address, port = 110, account, password, isapop = false ) {|popmail| .... } - starts POP3 protocol and iterates for each POPMail object. - This method equals to: - - Net::POP3.start(address, port, account, password) {|pop| - pop.each_mail do |m| - yield m - end - } - - This method raises POPAuthenticationError if authentication is failed. - - # Typical usage - Net::POP3.foreach('pop.example.com', 110, - 'YourAccount', 'YourPassword') do |m| - file.write m.pop - m.delete if $DELETE - end - -: delete_all( address, port = 110, account, password, isapop = false ) -: delete_all( address, port = 110, account, password, isapop = false ) {|popmail| .... } - starts POP3 session and delete all mails. - If block is given, iterates for each POPMail object before delete. - This method raises POPAuthenticationError if authentication is failed. - - # Example - Net::POP3.delete_all('pop.example.com', 110, - 'YourAccount', 'YourPassword') do |m| - file.write m.pop - end - -: auth_only( address, port = 110, account, password, isapop = false ) - (just for POP-before-SMTP) - - opens POP3 session and does autholize and quit. - This method must not be called while POP3 session is opened. - This method raises POPAuthenticationError if authentication is failed. - - # Example 1: normal POP3 - Net::POP3.auth_only('pop.example.com', 110, - 'YourAccount', 'YourPassword') - - # Example 2: APOP - Net::POP3.auth_only('pop.example.com', 110, - 'YourAccount', 'YourPassword', true) - -=== Instance Methods - -: start( account, password ) -: start( account, password ) {|pop| .... } - starts POP3 session. - - When called with block, gives a POP3 object to block and - closes the session after block call finish. - - This method raises POPAuthenticationError if authentication is failed. - -: started? -: active? OBSOLETE - true if POP3 session is started. - -: address - the address to connect - -: port - the port number to connect - -: open_timeout -: open_timeout=(n) - seconds to wait until connection is opened. - If POP3 object cannot open a conection in this seconds, - it raises TimeoutError exception. - -: read_timeout -: read_timeout=(n) - seconds to wait until reading one block (by one read(1) call). - If POP3 object cannot open a conection in this seconds, - it raises TimeoutError exception. - -: finish - finishes POP3 session. - If POP3 session had not be started, raises an IOError. - -: n_mails - returns the number of mails on the POP server. - -: n_bytes - returns the bytes of all mails on the POP server. - -: mails - an array of Net::POPMail objects. - This array is renewed when session restarts. - - This method raises POPError if any problem happened. - -: each_mail {|popmail| .... } -: each {|popmail| .... } - is equals to: - - pop3.mails.each do |popmail| - .... - end - - This method raises POPError if any problem happened. - -: delete_all -: delete_all {|popmail| .... } - deletes all mails on server. - If called with block, gives mails to the block before deleting. - - # Example - n = 1 - pop.delete_all do |m| - File.open("inbox/#{n}") {|f| - f.write m.pop - } - n += 1 - end - - This method raises POPError if any problem happened. - -: reset - reset the session. All "deleted mark" are removed. - - This method raises POPError if any problem happened. - -: set_debug_output( output ) - WARNING: This method causes serious security hole. - Use this method for only debugging. - - set output stream for debugging. - - # Example - pop = Net::POP.new(addr, port) - pop.set_debug_output $stderr - pop.start(account, passwd) { - .... - } - - -== class Net::APOP - -This class defines no new methods. -Only difference from POP3 is using APOP authentification. - -=== Super Class - -Net::POP3 - - -== class Net::POPMail - -A class of mail which exists on POP server. - -=== Instance Methods - -: pop - This method fetches a message as a String. - - This method may raise POPError. - - # Example - POP3.start('pop.example.com', 110, - 'YourAccount, 'YourPassword') {|pop| - n = 1 - pop.mails.each do |popmail| - File.open("inbox/#{n}", 'w') {|f| - f.write popmail.pop #### - } - popmail.delete - n += 1 - end - } - -: pop {|chunk| .... } - gives the block parts of the message. - - This method may raise POPError. - - # Example - POP3.start('pop.example.com', 110, - 'YourAccount, 'YourPassword') {|pop| - n = 1 - pop.mails.each do |popmail| - File.open("inbox/#{n}", 'w') {|f| - popmail.pop do |chunk| #### - f.write chunk - end - } - n += 1 - end - } - -: header - fetches the message header. - - This method may raise POPError. - -: top( lines ) - fetches the message header and LINES lines of body. - - This method may raise POPError. - -: delete - deletes the message on the POP server. - - This method may raise POPError. - - # Example - POP3.start('pop.example.com', 110, - 'YourAccount, 'YourPassword') {|pop| - n = 1 - pop.mails.each do |popmail| - File.open("inbox/#{n}", 'w') {|f| - f.write popmail.pop - } - popmail.delete #### - n += 1 - end - } - -: length -: size - the length of the message (in octets). - -: deleted? - true if mail was deleted. - -: unique_id - returns the unique-id of the message. - Normally unique-id is a hash string of the message. - - This method may raise POPError. - - -== POP3 Related Exception Classes - -: POPError - POP3 protocol error (reply code "-ERR", except authentication). - - ancestors: ProtocolError (obsolete) - -: POPAuthenticationError - POP3 authentication error. - - ancestors: POPError, ProtoAuthError (obsolete), ProtocolError (obsolete) - -: POPBadResponse - Unexpected response got from server. - - ancestors: POPError - -=end - +# = net/pop.rb +# +#-- +# Copyright (c) 1999-2003 Yukihiro Matsumoto +# Copyright (c) 1999-2003 Minero Aoki +# +# written & maintained by Minero Aoki <aamine@loveruby.net> +# +# This program is free software. You can re-distribute and/or +# modify this program under the same terms as Ruby itself, +# Ruby Distribute License or GNU General Public License. +# +# NOTE: You can find Japanese version of this document in +# the doc/net directory of the standard ruby interpreter package. +# +# $Id$ +#++ +# +# == What is This Library? +# +# This library provides functionality for retrieving +# email via POP3, the Post Office Protocol version 3. For details +# of POP3, see [RFC1939] (http://www.ietf.org/rfc/rfc1939.txt). +# +# == Examples +# +# === Retrieving Messages +# +# This example retrieves messages from the server and deletes them +# on the server. +# Messages are written to files named 'inbox/1', 'inbox/2', .... +# Replace 'pop.example.com' with your POP3 server address, and +# 'YourAccount' and 'YourPassword' with the appropriate account +# details. +# +# require 'net/pop' +# +# pop = Net::POP3.new('pop.example.com') +# pop.start('YourAccount', 'YourPassword') # (1) +# if pop.mails.empty? +# puts 'no mail.' +# else +# i = 0 +# pop.each_mail do |m| # or "pop.mails.each ..." # (2) +# File.open("inbox/#{i}", 'w') {|f| +# f.write m.pop +# } +# m.delete +# i += 1 +# end +# puts "#{pop.mails.size} mails popped." +# end +# pop.finish # (3) +# +# 1. call Net::POP3#start and start POP session +# 2. access messages by using POP3#each_mail and/or POP3#mails +# 3. close POP session by calling POP3#finish or use the block form of #start. +# +# === Shortened Code +# +# The example above is very verbose. You can shorten the code by using +# some utility methods. First, the block form of Net::POP3.start can +# be used instead of POP3.new, POP3#start and POP3#finish. +# +# require 'net/pop' +# +# Net::POP3.start('pop.example.com', 110, +# 'YourAccount', 'YourPassword') {|pop| +# if pop.mails.empty? +# puts 'no mail.' +# else +# i = 0 +# pop.each_mail do |m| # or "pop.mails.each ..." +# File.open("inbox/#{i}", 'w') {|f| +# f.write m.pop +# } +# m.delete +# i += 1 +# end +# puts "#{pop.mails.size} mails popped." +# end +# } +# +# POP3#delete_all alternates #each_mail and m.delete. +# +# require 'net/pop' +# +# Net::POP3.start('pop.example.com', 110, +# 'YourAccount', 'YourPassword') {|pop| +# if pop.mails.empty? +# puts 'no mail.' +# else +# i = 1 +# pop.delete_all do |m| +# File.open("inbox/#{i}", 'w') {|f| +# f.write m.pop +# } +# i += 1 +# end +# end +# } +# +# And here is an even shorter example. +# +# require 'net/pop' +# +# i = 0 +# Net::POP3.delete_all('pop.example.com', 110, +# 'YourAccount', 'YourPassword') do |m| +# File.open("inbox/#{i}", 'w') {|f| +# f.write m.pop +# } +# i += 1 +# end +# +# === Memory Space Issues +# +# All the examples above get each message as one big string. +# This example avoids this. +# +# require 'net/pop' +# +# i = 1 +# Net::POP3.delete_all('pop.example.com', 110, +# 'YourAccount', 'YourPassword') do |m| +# File.open("inbox/#{i}", 'w') {|f| +# m.pop do |chunk| # get a message little by little. +# f.write chunk +# end +# i += 1 +# } +# end +# +# === Using APOP +# +# The net/pop library supports APOP authentication. +# To use APOP, use the Net::APOP class instead of the Net::POP3 class. +# You can use the utility method, Net::POP3.APOP(). For example: +# +# require 'net/pop' +# +# # Use APOP authentication if $isapop == true +# pop = Net::POP3.APOP($is_apop).new('apop.example.com', 110) +# pop.start(YourAccount', 'YourPassword') {|pop| +# # Rest code is same. +# } +# +# === Fetch Only Selected Mail Using `UIDL' POP Command +# +# If your POP server provides UIDL functionality, +# you can grab only selected mails from the POP server. +# e.g. +# +# def need_pop?( id ) +# # determine if we need pop this mail... +# end +# +# Net::POP3.start('pop.example.com', 110, +# 'Your account', 'Your password') {|pop| +# pop.mails.select {|m| need_pop?(m.unique_id) }.each do |m| +# do_something(m.pop) +# end +# } +# +# The POPMail#unique_id() method returns the unique-id of the message as a +# String. Normally the unique-id is a hash of the message. +# require 'net/protocol' require 'digest/md5' - module Net + # Non-authentication POP3 protocol error (reply code "-ERR", except + # authentication. class POPError < ProtocolError; end + + # POP3 authentication error. class POPAuthenticationError < ProtoAuthError; end + + # Unexpected response from the server. class POPBadResponse < POPError; end + # + # Class providing POP3 client functionality. + # + # See documentation for the file pop.rb for examples of usage. + # class POP3 < Protocol Revision = %q$Revision$.split[1] @@ -471,12 +194,13 @@ module Net # Class Parameters # + # The default port for POP3 connections, port 110 def POP3.default_port 110 end # obsolete - def POP3.socket_type + def POP3.socket_type # :nodoc: Net::InternetMessageIO end @@ -484,18 +208,57 @@ module Net # Utilities # + # Returns the APOP class if +isapop+ is true; otherwise, returns + # the POP class. For example: + # + # # Example 1 + # pop = Net::POP3::APOP($is_apop).new(addr, port) + # + # # Example 2 + # Net::POP3::APOP($is_apop).start(addr, port) {|pop| + # .... + # } def POP3.APOP( isapop ) isapop ? APOP : POP3 end + # Starts a POP3 session and iterates over each POPMail object, + # yielding it to the +block+. + # This method is equivalent to: + # + # Net::POP3.start(address, port, account, password) {|pop| + # pop.each_mail do |m| + # yield m + # end + # } + # + # This method raises a POPAuthenticationError if authentication fails. + # + # # Typical usage + # Net::POP3.foreach('pop.example.com', 110, + # 'YourAccount', 'YourPassword') do |m| + # file.write m.pop + # m.delete if $DELETE + # end def POP3.foreach( address, port = nil, account = nil, password = nil, - isapop = false, &block ) + isapop = false, &block ) # :yields: message start(address, port, account, password, isapop) {|pop| pop.each_mail(&block) } end + # Starts a POP3 session and deletes all messages on the server. + # If a block is given, each POPMail object is yielded to it before + # being deleted. + # + # This method raises a POPAuthenticationError if authentication fails. + # + # # Example + # Net::POP3.delete_all('pop.example.com', 110, + # 'YourAccount', 'YourPassword') do |m| + # file.write m.pop + # end def POP3.delete_all( address, port = nil, account = nil, password = nil, isapop = false, &block ) @@ -504,12 +267,26 @@ module Net } end + # Opens a POP3 session, attempts authentication, and quits. + # + # This method raises POPAuthenticationError if authentication fails. + # + # # Example 1: normal POP3 + # Net::POP3.auth_only('pop.example.com', 110, + # 'YourAccount', 'YourPassword') + # + # # Example 2: APOP + # Net::POP3.auth_only('pop.example.com', 110, + # 'YourAccount', 'YourPassword', true) def POP3.auth_only( address, port = nil, account = nil, password = nil, isapop = false ) new(address, port, isapop).auth_only account, password end + # Starts a pop3 session, attempts authentication, and quits. + # This method must not be called while POP3 session is opened. + # This method raises POPAuthenticationError if authentication fails. def auth_only( account, password ) raise IOError, 'opening already opened POP session' if started? start(account, password) { @@ -521,12 +298,33 @@ module Net # Session management # + # Creates a new POP3 object and open the connection. Equivalent to + # Net::POP3.new(address, port, isapop).start(account, password) + # + # If +block+ is provided, yields the newly-opened POP3 object to it, + # and automatically closes it at the end of the session. + # + # Typical usage: + # + # Net::POP3.start(addr, port, account, password) {|pop| + # pop.each_mail do |m| + # file.write m.pop + # m.delete + # end + # } + # def POP3.start( address, port = nil, account = nil, password = nil, - isapop = false, &block ) + isapop = false, &block ) # :yield: pop new(address, port, isapop).start(account, password, &block) end + # Creates a new POP3 object. + # +address+ is the hostname or ip address of your POP3 server. + # The optional +port+ is the port to connect to; it defaults to 110. + # The optional +isapop+ specifies whether this connection is going + # to use APOP authentication; it defaults to +false+. + # This method does *not* open the TCP connection. def initialize( addr, port = nil, isapop = false ) @address = addr @port = port || self.class.default_port @@ -544,36 +342,67 @@ module Net @n_bytes = nil end + # Does this instance use APOP authentication? def apop? @apop end + # Provide human-readable stringification of class state. def inspect "#<#{self.class} #{@address}:#{@port} open=#{@started}>" end + # *WARNING*: This method causes a serious security hole. + # Use this method only for debugging. + # + # Set an output stream for debugging. + # + # # Example + # pop = Net::POP.new(addr, port) + # pop.set_debug_output $stderr + # pop.start(account, passwd) { + # .... + # } def set_debug_output( arg ) @debug_output = arg end + # The address to connect to. attr_reader :address + + # The port number to connect to. attr_reader :port + # Seconds to wait until a connection is opened. + # If the POP3 object cannot open a connection within this time, + # it raises a TimeoutError exception. attr_accessor :open_timeout + + # Seconds to wait until reading one block (by one read(1) call). + # If the POP3 object cannot complete a read() within this time, + # it raises a TimeoutError exception. attr_reader :read_timeout + # Set the read timeout. def read_timeout=( sec ) @command.socket.read_timeout = sec if @command @read_timeout = sec end + # +true+ if the POP3 session has started. def started? @started end alias active? started? # obsolete - def start( account, password ) + # Starts a POP3 session. + # + # When called with block, gives a POP3 object to the block and + # closes the session after block call finishes. + # + # This method raises a POPAuthenticationError if authentication fails. + def start( account, password ) # :yield: pop raise IOError, 'POP session already started' if @started if block_given? @@ -607,6 +436,8 @@ module Net end private :on_connect + # Finishes a POP3 session. + # If a POP3 session has not been started, raises an IOError. def finish raise IOError, 'already closed POP session' unless @started @mails = nil @@ -628,18 +459,26 @@ module Net # POP protocol wrapper # + # Returns the number of messages on the POP server. def n_mails return @n_mails if @n_mails @n_mails, @n_bytes = command().stat @n_mails end + # Returns the total size in bytes of all the messages on the POP server. def n_bytes return @n_bytes if @n_bytes @n_mails, @n_bytes = command().stat @n_bytes end + # Returns an array of Net::POPMail objects, representing all the + # messages on the server. This array is renewed when the session + # restarts; otherwise, it is fetched from the server the first time + # this method is called (directly or indirectly) and cached. + # + # This method raises a POPError if an error occurs. def mails return @mails.dup if @mails if n_mails() == 0 @@ -654,19 +493,44 @@ module Net @mails.dup end - def each_mail( &block ) + # Yields each message to the passed-in block in turn. + # Equivalent to: + # + # pop3.mails.each do |popmail| + # .... + # end + # + # This method raises a POPError if an error occurs. + def each_mail( &block ) # :yield: message mails().each(&block) end alias each each_mail - def delete_all + # Deletes all messages on the server. + # + # If called with a block, yields each message in turn before deleting it. + # + # # Example + # n = 1 + # pop.delete_all do |m| + # File.open("inbox/#{n}") {|f| + # f.write m.pop + # } + # n += 1 + # end + # + # This method raises a POPError if an error occurs. + def delete_all # :yield: message mails().each do |m| yield m if block_given? m.delete unless m.deleted? end end + # Resets the session. This clears all "deleted" marks from messages. + # + # This method raises a POPError if an error occurs. def reset command().rset mails().each do |m| @@ -690,7 +554,10 @@ module Net POPSession = POP3 POP3Session = POP3 + # This class is equivalent to POP3, except that it uses APOP authentication. class APOP < POP3 + + # Always returns true. def apop? true end @@ -698,10 +565,12 @@ module Net APOPSession = APOP - + # This class represents a message which exists on the POP server. + # Instances of this class are created by the POP3 class; they should + # not be directly created by the user. class POPMail - def initialize( num, len, pop, cmd ) + def initialize( num, len, pop, cmd ) # :nodoc: @number = num @length = len @pop = pop @@ -710,15 +579,53 @@ module Net @uid = nil end + # The sequence number of the message on the server. attr_reader :number + + # The length of the message in octets. attr_reader :length alias size length + # Provide human-readable stringification of class state. def inspect "#<#{self.class} #{@number}#{@deleted ? ' deleted' : ''}>" end - def pop( dest = '', &block ) + # This method fetches the message. If called with a block, the + # message is yielded to the block one chunk at a time. If called + # without a block, the message is returned as a String. The optional + # +dest+ argument will be prepended to the returned String; this + # argument is essentially obsolete. + # + # # Example without block + # POP3.start('pop.example.com', 110, + # 'YourAccount, 'YourPassword') {|pop| + # n = 1 + # pop.mails.each do |popmail| + # File.open("inbox/#{n}", 'w') {|f| + # f.write popmail.pop + # } + # popmail.delete + # n += 1 + # end + # } + # + # # Example with block + # POP3.start('pop.example.com', 110, + # 'YourAccount, 'YourPassword') {|pop| + # n = 1 + # pop.mails.each do |popmail| + # File.open("inbox/#{n}", 'w') {|f| + # popmail.pop do |chunk| #### + # f.write chunk + # end + # } + # n += 1 + # end + # } + # + # This method raises a POPError if an error occurs. + def pop( dest = '', &block ) # :yield: message_chunk if block_given? @command.retr(@number, &block) nil @@ -733,7 +640,10 @@ module Net alias all pop # backward compatibility alias mail pop # backward compatibility - # `dest' argument is obsolete + # Fetches the message header and +lines+ lines of body. + # The optional +dest+ argument is obsolete. + # + # This method raises a POPError if an error occurs. def top( lines, dest = '' ) @command.top(@number, lines) do |chunk| dest << chunk @@ -741,11 +651,32 @@ module Net dest end - # `dest' argument is obsolete + # Fetches the message header. + # The optional +dest+ argument is obsolete. + # + # This method raises a POPError if an error occurs. def header( dest = '' ) top(0, dest) end + # Marks a message for deletion on the server. Deletion does not + # actually occur until the end of the session; deletion may be + # cancelled for _all_ marked messages by calling POP3#reset(). + # + # This method raises a POPError if an error occurs. + # + # # Example + # POP3.start('pop.example.com', 110, + # 'YourAccount, 'YourPassword') {|pop| + # n = 1 + # pop.mails.each do |popmail| + # File.open("inbox/#{n}", 'w') {|f| + # f.write popmail.pop + # } + # popmail.delete #### + # n += 1 + # end + # } def delete @command.dele @number @deleted = true @@ -753,10 +684,15 @@ module Net alias delete! delete # backward compatibility + # True if the mail has been deleted. def deleted? @deleted end + # Returns the unique-id of the message. + # Normally the unique-id is a hash string of the message. + # + # This method raises a POPError if an error occurs. def unique_id return @uid if @uid @pop.set_all_uids @@ -773,7 +709,7 @@ module Net end # class POPMail - class POP3Command + class POP3Command # :nodoc: def initialize( sock ) @socket = sock @@ -782,6 +718,7 @@ module Net @apop_stamp = res.slice(/<.+>/) end + # Provide human-readable stringification of class state. def inspect "#<#{self.class} socket=#{@socket}>" end @@ -905,3 +842,4 @@ module Net end # class POP3Command end # module Net + |