net-pop 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3ef035bbd20a58700e4815d4bf06f46a9691fc357a720bb74d7fc56f23347f85
+  data.tar.gz: 9acb213cdb2f86913441a16f214528748f7c84724772ad3ff35be8808ea32ce2
+SHA512:
+  metadata.gz: fd1a187335df8a35903493beb209d872fb49ec59f65088d095209786a51493ee3f80619bd53e2d831329fa85afd70e9e3fb23847603dd3b755fa120001288def
+  data.tar.gz: db328d1b8b66fa497f2ed18b5831b4d08537c7f70ea4672ef62d701ab843bd05fb6e55056bd15e1c71aa74648d0d04f17a9b6f06a3af873d76a356d440c0d46e

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+Gemfile.lock

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.6.3
+before_install: gem install bundler -v 2.0.2

data/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+group :development do
+  gem "bundler"
+  gem "rake"
+  gem "test-unit"
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (C) 1993-2013 Yukihiro Matsumoto. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.

data/README.md

@@ -0,0 +1,66 @@
+# Net::POP3
+
+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).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'net-pop'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install net-pop
+
+## Usage
+
+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.
+
+```ruby
+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') do |f|
+      f.write m.pop
+    end
+    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.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/net-pop.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test/lib"
+  t.ruby_opts << "-rhelper"
+  t.test_files = FileList['test/**/test_*.rb']
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "net/pop"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/net/pop.rb

@@ -0,0 +1,1023 @@
+# frozen_string_literal: true
+# = net/pop.rb
+#
+# Copyright (c) 1999-2007 Yukihiro Matsumoto.
+#
+# Copyright (c) 1999-2007 Minero Aoki.
+#
+# Written & maintained by Minero Aoki <aamine@loveruby.net>.
+#
+# Documented by William Webber and Minero Aoki.
+#
+# This program is free software. You can re-distribute and/or
+# modify this program under the same terms as Ruby itself,
+# Ruby Distribute License.
+#
+# NOTE: You can find Japanese version of this document at:
+# http://docs.ruby-lang.org/ja/latest/library/net=2fpop.html
+#
+#   $Id$
+#
+# See Net::POP3 for documentation.
+#
+
+require 'net/protocol'
+require 'digest/md5'
+require 'timeout'
+
+begin
+  require "openssl"
+rescue LoadError
+end
+
+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
+
+  #
+  # == 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') do |f|
+  #           f.write m.pop
+  #         end
+  #         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') do |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') do |f|
+  #             f.write m.pop
+  #           end
+  #           m.delete
+  #           i += 1
+  #         end
+  #         puts "#{pop.mails.size} mails popped."
+  #       end
+  #     end
+  #
+  # POP3#delete_all is an alternative for #each_mail and #delete.
+  #
+  #     require 'net/pop'
+  #
+  #     Net::POP3.start('pop.example.com', 110,
+  #                     'YourAccount', 'YourPassword') do |pop|
+  #       if pop.mails.empty?
+  #         puts 'No mail.'
+  #       else
+  #         i = 1
+  #         pop.delete_all do |m|
+  #           File.open("inbox/#{i}", 'w') do |f|
+  #             f.write m.pop
+  #           end
+  #           i += 1
+  #         end
+  #       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') do |f|
+  #         f.write m.pop
+  #       end
+  #       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') do |f|
+  #         m.pop do |chunk|    # get a message little by little.
+  #           f.write chunk
+  #         end
+  #         i += 1
+  #       end
+  #     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($isapop).new('apop.example.com', 110)
+  #     pop.start('YourAccount', 'YourPassword') do |pop|
+  #       # Rest of the code is the same.
+  #     end
+  #
+  # === 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') do |pop|
+  #       pop.mails.select { |m| need_pop?(m.unique_id) }.each do |m|
+  #         do_something(m.pop)
+  #       end
+  #     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.
+  #
+  class POP3 < Protocol
+
+    # svn revision of this library
+    Revision = %q$Revision$.split[1]
+
+    #
+    # Class Parameters
+    #
+
+    # returns the port for POP3
+    def POP3.default_port
+      default_pop3_port()
+    end
+
+    # The default port for POP3 connections, port 110
+    def POP3.default_pop3_port
+      110
+    end
+
+    # The default port for POP3S connections, port 995
+    def POP3.default_pop3s_port
+      995
+    end
+
+    def POP3.socket_type   #:nodoc: obsolete
+      Net::InternetMessageIO
+    end
+
+    #
+    # 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) do |pop|
+    #       ....
+    #     end
+    #
+    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) do |pop|
+    #       pop.each_mail do |m|
+    #         yield m
+    #       end
+    #     end
+    #
+    # This method raises a POPAuthenticationError if authentication fails.
+    #
+    # === Example
+    #
+    #     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)  # :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)
+      start(address, port, account, password, isapop) {|pop|
+        pop.delete_all(&block)
+      }
+    end
+
+    # Opens a POP3 session, attempts authentication, and quits.
+    #
+    # This method raises POPAuthenticationError if authentication fails.
+    #
+    # === Example: normal POP3
+    #
+    #     Net::POP3.auth_only('pop.example.com', 110,
+    #                         'YourAccount', 'YourPassword')
+    #
+    # === Example: 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 previously opened POP session' if started?
+      start(account, password) {
+        ;
+      }
+    end
+
+    #
+    # SSL
+    #
+
+    @ssl_params = nil
+
+    # :call-seq:
+    #    Net::POP.enable_ssl(params = {})
+    #
+    # Enable SSL for all new instances.
+    # +params+ is passed to OpenSSL::SSLContext#set_params.
+    def POP3.enable_ssl(*args)
+      @ssl_params = create_ssl_params(*args)
+    end
+
+    # Constructs proper parameters from arguments
+    def POP3.create_ssl_params(verify_or_params = {}, certs = nil)
+      begin
+        params = verify_or_params.to_hash
+      rescue NoMethodError
+        params = {}
+        params[:verify_mode] = verify_or_params
+        if certs
+          if File.file?(certs)
+            params[:ca_file] = certs
+          elsif File.directory?(certs)
+            params[:ca_path] = certs
+          end
+        end
+      end
+      return params
+    end
+
+    # Disable SSL for all new instances.
+    def POP3.disable_ssl
+      @ssl_params = nil
+    end
+
+    # returns the SSL Parameters
+    #
+    # see also POP3.enable_ssl
+    def POP3.ssl_params
+      return @ssl_params
+    end
+
+    # returns +true+ if POP3.ssl_params is set
+    def POP3.use_ssl?
+      return !@ssl_params.nil?
+    end
+
+    # returns whether verify_mode is enable from POP3.ssl_params
+    def POP3.verify
+      return @ssl_params[:verify_mode]
+    end
+
+    # returns the :ca_file or :ca_path from POP3.ssl_params
+    def POP3.certs
+      return @ssl_params[:ca_file] || @ssl_params[:ca_path]
+    end
+
+    #
+    # 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.
+    #
+    # === Example
+    #
+    #    Net::POP3.start(addr, port, account, password) do |pop|
+    #      pop.each_mail do |m|
+    #        file.write m.pop
+    #        m.delete
+    #      end
+    #    end
+    #
+    def POP3.start(address, port = nil,
+                   account = nil, password = nil,
+                   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.
+    #
+    # 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
+      @ssl_params = POP3.ssl_params
+      @port = port
+      @apop = isapop
+
+      @command = nil
+      @socket = nil
+      @started = false
+      @open_timeout = 30
+      @read_timeout = 60
+      @debug_output = nil
+
+      @mails = nil
+      @n_mails = nil
+      @n_bytes = nil
+    end
+
+    # Does this instance use APOP authentication?
+    def apop?
+      @apop
+    end
+
+    # does this instance use SSL?
+    def use_ssl?
+      return !@ssl_params.nil?
+    end
+
+    # :call-seq:
+    #    Net::POP#enable_ssl(params = {})
+    #
+    # Enables SSL for this instance.  Must be called before the connection is
+    # established to have any effect.
+    # +params[:port]+ is port to establish the SSL connection on; Defaults to 995.
+    # +params+ (except :port) is passed to OpenSSL::SSLContext#set_params.
+    def enable_ssl(verify_or_params = {}, certs = nil, port = nil)
+      begin
+        @ssl_params = verify_or_params.to_hash.dup
+        @port = @ssl_params.delete(:port) || @port
+      rescue NoMethodError
+        @ssl_params = POP3.create_ssl_params(verify_or_params, certs)
+        @port = port || @port
+      end
+    end
+
+    # Disable SSL for all new instances.
+    def disable_ssl
+      @ssl_params = nil
+    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) do |pop|
+    #     ....
+    #   end
+    #
+    def set_debug_output(arg)
+      @debug_output = arg
+    end
+
+    # The address to connect to.
+    attr_reader :address
+
+    # The port number to connect to.
+    def port
+      return @port || (use_ssl? ? POP3.default_pop3s_port : POP3.default_pop3_port)
+    end
+
+    # Seconds to wait until a connection is opened.
+    # If the POP3 object cannot open a connection within this time,
+    # it raises a Net::OpenTimeout exception. The default value is 30 seconds.
+    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 Net::ReadTimeout exception. The default value is 60 seconds.
+    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?   #:nodoc: obsolete
+
+    # 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?
+        begin
+          do_start account, password
+          return yield(self)
+        ensure
+          do_finish
+        end
+      else
+        do_start account, password
+        return self
+      end
+    end
+
+    # internal method for Net::POP3.start
+    def do_start(account, password) # :nodoc:
+      s = Timeout.timeout(@open_timeout, Net::OpenTimeout) do
+        TCPSocket.open(@address, port)
+      end
+      if use_ssl?
+        raise 'openssl library not installed' unless defined?(OpenSSL)
+        context = OpenSSL::SSL::SSLContext.new
+        context.set_params(@ssl_params)
+        s = OpenSSL::SSL::SSLSocket.new(s, context)
+        s.hostname = @address
+        s.sync_close = true
+        ssl_socket_connect(s, @open_timeout)
+        if context.verify_mode != OpenSSL::SSL::VERIFY_NONE
+          s.post_connection_check(@address)
+        end
+      end
+      @socket = InternetMessageIO.new(s,
+                                      read_timeout: @read_timeout,
+                                      debug_output: @debug_output)
+      logging "POP session started: #{@address}:#{@port} (#{@apop ? 'APOP' : 'POP'})"
+      on_connect
+      @command = POP3Command.new(@socket)
+      if apop?
+        @command.apop account, password
+      else
+        @command.auth account, password
+      end
+      @started = true
+    ensure
+      # Authentication failed, clean up connection.
+      unless @started
+        s.close if s
+        @socket = nil
+        @command = nil
+      end
+    end
+    private :do_start
+
+    # Does nothing
+    def on_connect # :nodoc:
+    end
+    private :on_connect
+
+    # Finishes a POP3 session and closes TCP connection.
+    def finish
+      raise IOError, 'POP session not yet started' unless started?
+      do_finish
+    end
+
+    # nil's out the:
+    # - mails
+    # - number counter for mails
+    # - number counter for bytes
+    # - quits the current command, if any
+    def do_finish # :nodoc:
+      @mails = nil
+      @n_mails = nil
+      @n_bytes = nil
+      @command.quit if @command
+    ensure
+      @started = false
+      @command = nil
+      @socket.close if @socket
+      @socket = nil
+    end
+    private :do_finish
+
+    # Returns the current command.
+    #
+    # Raises IOError if there is no active socket
+    def command # :nodoc:
+      raise IOError, 'POP session not opened yet' \
+                                      if not @socket or @socket.closed?
+      @command
+    end
+    private :command
+
+    #
+    # 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
+        # some popd raises error for LIST on the empty mailbox.
+        @mails = []
+        return []
+      end
+
+      @mails = command().list.map {|num, size|
+        POPMail.new(num, size, self, command())
+      }
+      @mails.dup
+    end
+
+    # 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
+
+    # 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}") do |f|
+    #         f.write m.pop
+    #       end
+    #       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|
+        m.instance_eval {
+          @deleted = false
+        }
+      end
+    end
+
+    def set_all_uids   #:nodoc: internal use only (called from POPMail#uidl)
+      uidl = command().uidl
+      @mails.each {|m| m.uid = uidl[m.number] }
+    end
+
+    # debugging output for +msg+
+    def logging(msg)
+      @debug_output << msg + "\n" if @debug_output
+    end
+
+  end   # class POP3
+
+  # class aliases
+  POP = POP3 # :nodoc:
+  POPSession  = POP3 # :nodoc:
+  POP3Session = POP3 # :nodoc:
+
+  #
+  # This class is equivalent to POP3, except that it uses APOP authentication.
+  #
+  class APOP < POP3
+    # Always returns true.
+    def apop?
+      true
+    end
+  end
+
+  # class aliases
+  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)   #:nodoc:
+      @number = num
+      @length = len
+      @pop = pop
+      @command = cmd
+      @deleted = false
+      @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
+
+    #
+    # 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') do |pop|
+    #       n = 1
+    #       pop.mails.each do |popmail|
+    #         File.open("inbox/#{n}", 'w') do |f|
+    #           f.write popmail.pop
+    #         end
+    #         popmail.delete
+    #         n += 1
+    #       end
+    #     end
+    #
+    # === Example with block
+    #
+    #     POP3.start('pop.example.com', 110,
+    #                'YourAccount', 'YourPassword') do |pop|
+    #       n = 1
+    #       pop.mails.each do |popmail|
+    #         File.open("inbox/#{n}", 'w') do |f|
+    #           popmail.pop do |chunk|            ####
+    #             f.write chunk
+    #           end
+    #         end
+    #         n += 1
+    #       end
+    #     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
+      else
+        @command.retr(@number) do |chunk|
+          dest << chunk
+        end
+        dest
+      end
+    end
+
+    alias all pop    #:nodoc: obsolete
+    alias mail pop   #:nodoc: 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
+      end
+      dest
+    end
+
+    # 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') do |pop|
+    #       n = 1
+    #       pop.mails.each do |popmail|
+    #         File.open("inbox/#{n}", 'w') do |f|
+    #           f.write popmail.pop
+    #         end
+    #         popmail.delete         ####
+    #         n += 1
+    #       end
+    #     end
+    #
+    def delete
+      @command.dele @number
+      @deleted = true
+    end
+
+    alias delete! delete    #:nodoc: obsolete
+
+    # 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
+      @uid
+    end
+
+    alias uidl unique_id
+
+    def uid=(uid)   #:nodoc: internal use only
+      @uid = uid
+    end
+
+  end   # class POPMail
+
+
+  class POP3Command   #:nodoc: internal use only
+
+    def initialize(sock)
+      @socket = sock
+      @error_occurred = false
+      res = check_response(critical { recv_response() })
+      @apop_stamp = res.slice(/<[!-~]+@[!-~]+>/)
+    end
+
+    attr_reader :socket
+
+    def inspect
+      +"#<#{self.class} socket=#{@socket}>"
+    end
+
+    def auth(account, password)
+      check_response_auth(critical {
+        check_response_auth(get_response('USER %s', account))
+        get_response('PASS %s', password)
+      })
+    end
+
+    def apop(account, password)
+      raise POPAuthenticationError, 'not APOP server; cannot login' \
+                                                      unless @apop_stamp
+      check_response_auth(critical {
+        get_response('APOP %s %s',
+                     account,
+                     Digest::MD5.hexdigest(@apop_stamp + password))
+      })
+    end
+
+    def list
+      critical {
+        getok 'LIST'
+        list = []
+        @socket.each_list_item do |line|
+          m = /\A(\d+)[ \t]+(\d+)/.match(line) or
+                  raise POPBadResponse, "bad response: #{line}"
+          list.push  [m[1].to_i, m[2].to_i]
+        end
+        return list
+      }
+    end
+
+    def stat
+      res = check_response(critical { get_response('STAT') })
+      m = /\A\+OK\s+(\d+)\s+(\d+)/.match(res) or
+              raise POPBadResponse, "wrong response format: #{res}"
+      [m[1].to_i, m[2].to_i]
+    end
+
+    def rset
+      check_response(critical { get_response('RSET') })
+    end
+
+    def top(num, lines = 0, &block)
+      critical {
+        getok('TOP %d %d', num, lines)
+        @socket.each_message_chunk(&block)
+      }
+    end
+
+    def retr(num, &block)
+      critical {
+        getok('RETR %d', num)
+        @socket.each_message_chunk(&block)
+      }
+    end
+
+    def dele(num)
+      check_response(critical { get_response('DELE %d', num) })
+    end
+
+    def uidl(num = nil)
+      if num
+        res = check_response(critical { get_response('UIDL %d', num) })
+        return res.split(/ /)[1]
+      else
+        critical {
+          getok('UIDL')
+          table = {}
+          @socket.each_list_item do |line|
+            num, uid = line.split
+            table[num.to_i] = uid
+          end
+          return table
+        }
+      end
+    end
+
+    def quit
+      check_response(critical { get_response('QUIT') })
+    end
+
+    private
+
+    def getok(fmt, *fargs)
+      @socket.writeline sprintf(fmt, *fargs)
+      check_response(recv_response())
+    end
+
+    def get_response(fmt, *fargs)
+      @socket.writeline sprintf(fmt, *fargs)
+      recv_response()
+    end
+
+    def recv_response
+      @socket.readline
+    end
+
+    def check_response(res)
+      raise POPError, res unless /\A\+OK/i =~ res
+      res
+    end
+
+    def check_response_auth(res)
+      raise POPAuthenticationError, res unless /\A\+OK/i =~ res
+      res
+    end
+
+    def critical
+      return '+OK dummy ok response' if @error_occurred
+      begin
+        return yield()
+      rescue Exception
+        @error_occurred = true
+        raise
+      end
+    end
+
+  end   # class POP3Command
+
+end   # module Net

data/lib/net/pop/version.rb

@@ -0,0 +1,5 @@
+module Net
+  class POP3
+    VERSION = "0.1.0"
+  end
+end

data/net-pop.gemspec

@@ -0,0 +1,25 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "net/pop/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "net-pop"
+  spec.version       = Net::POP3::VERSION
+  spec.authors       = ["Hiroshi SHIBATA"]
+  spec.email         = ["hsbt@ruby-lang.org"]
+
+  spec.summary       = %q{Ruby client library for POP3.}
+  spec.description   = %q{Ruby client library for POP3.}
+  spec.homepage      = "https://github.com/ruby/net-pop"
+  spec.license       = "BSD-2-Clause"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: net-pop
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Hiroshi SHIBATA
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2019-11-06 00:00:00.000000000 Z
+dependencies: []
+description: Ruby client library for POP3.
+email:
+- hsbt@ruby-lang.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/net/pop.rb
+- lib/net/pop/version.rb
+- net-pop.gemspec
+homepage: https://github.com/ruby/net-pop
+licenses:
+- BSD-2-Clause
+metadata:
+  homepage_uri: https://github.com/ruby/net-pop
+  source_code_uri: https://github.com/ruby/net-pop
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Ruby client library for POP3.
+test_files: []