simple_mailer 1.1.0

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2009 Jeremy Evans <code@jeremyevans.net>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README

@@ -0,0 +1,59 @@
+= simple_mailer
+
+simple_mailer is a very simple email library for ruby, with testing
+support.  It just uses ruby's standard net/smtp library to send out
+the emails.  Configuration is limited to setting the server that
+the email is sent to (defaults to localhost).  Testing support is
+limited to appending the emails that would have been sent to an
+array.
+
+simple_mailer can be installed with:
+
+    sudo gem install jeremyevans-simple_mailer \
+      --source=http://gems.github.com
+
+Source is available at github:
+http://github.com/jeremyevans/simple_mailer
+
+RDoc is available at: http://code.jeremyevans.net/doc/simple_mailer/
+
+== Usage
+
+There is no required configuration, you can use simple_mailer
+immediately:
+
+  require 'simple_mailer'
+  SimpleMailer.send_email('from@from.com', 'to@to.com', 'Subject',
+    'Body', 'HeaderKey'=>'HeaderValue')
+  
+SimpleMailer is a module that can be included in other classes:
+
+  class Mailer
+    include SimpleMailer
+
+    def initialize(subject, body)
+      @subject = subject
+      @body = body
+      self.smtp_server = 'smtp.example.com'
+    end
+
+    def email(from, to)
+      send_email(from, to, @subject, @body)
+    end
+  end
+  Mailer.new('Subject', 'Body').email('from@from.com', 'to@to.com')
+
+== Testing
+
+Testing support is probably the main reason to use simple_mailer over
+using net/smtp directly.  After you enter test mode, emails you send
+are available via the emails_sent option:
+
+  SimpleMailer.test_mode!
+  SimpleMailer.emails_sent # []
+  SimpleMailer.send_email('from@from.com', 'to@to.com', 'S, 'B')
+  SimpleMailer.emails_sent # [[message, 'from@from.com', 'to@to.com']]
+
+== Author
+
+Jeremy Evans (code@jeremyevans.net)

data/lib/simple_mailer.rb

@@ -0,0 +1,93 @@
+require 'net/smtp'
+
+# SimpleMailer is a very small class that uses net/smtp to sent email messages
+# to a given smtp server (localhost by default).  Like the name implies, it
+# is very simple, you provide a from address, to address, subject, body and
+# an optional hash of headers.
+#
+# The main advantage of this over just using Net::SMTP directly is that
+# it handles headers and it has a test mode that just records the number of
+# emails sent instead of actually sending the messages.
+module SimpleMailer
+  @test_mode = false
+  @emails_sent = []
+
+  extend self
+
+  DEFAULT_SMTP_HOST = 'localhost'.freeze
+
+  # The array of emails sent
+  def self.emails_sent
+    @emails_sent
+  end
+
+  # Turn on the test mode.  There is no method given to turn it off.
+  # While in test mode, messages will not be sent, but the messages
+  # that would have been sent are available via emails_sent.
+  # This method also resets the emails_sent variable to the empty array.
+  def self.test_mode!
+    @emails_sent.clear
+    @test_mode = true
+  end
+  
+  # Whether we are in simple mailer's test mode
+  def self.test_mode?
+    @test_mode
+  end
+
+  # The smtp server to sent email to
+  attr_accessor :smtp_server
+  
+  # The emails sent in test mode.  Is an array of arrays.  Each
+  # element array is a array of three elements, the message, from address,
+  # and to address.
+  def emails_sent
+    SimpleMailer.emails_sent
+  end
+
+  # Formats email message using from address, to address, subject, message,
+  # and header hash.  Arguments:
+  # * from - From address for the message
+  # * to - To address for the message
+  # * subject - Subject of the message
+  # * message - Body of the message
+  # * headers - Headers for the message. Also, handles the following keys
+  #   specially:
+  #   * :smtp_from - the SMTP MAIL FROM address to use.  Uses the value of
+  #     of the from argument by default.
+  #   * :smtp_to - the SMTP RCPT TO address to use.  Uses the value of the
+  #     to argument by default.
+  #
+  # The caller is responsible for ensuring that the from, to, subject, and
+  # headers do not have an carriage returns or line endings.  Otherwise,
+  # it's possible to inject arbitrary headers or body content.
+  def send_email(from, to, subject, message, headers={})
+    smtp_from = headers.delete(:smtp_from) || from
+    smtp_to = headers.delete(:smtp_to) || to
+    _send_email(<<END_OF_MESSAGE, smtp_from, smtp_to)
+From: #{from}
+To: #{to}
+Subject: #{subject}
+#{headers.sort.map{|k,v| "#{k}: #{v}"}.join("\n")}#{"\n" unless headers.empty?}
+#{message}
+END_OF_MESSAGE
+  end
+  
+  private
+
+  # If in test mode, call test_mode_send_email with the arguments.
+  # Otherwise, use net/smtp to send the message to the smtp server.
+  def _send_email(msg, from, to)
+    if SimpleMailer.test_mode?
+      test_mode_send_email(msg, from, to)
+    else
+      Net::SMTP.start(smtp_server || DEFAULT_SMTP_HOST){|s| s.send_message(msg, from, to)}
+    end
+  end
+
+  # Handle the message in test mode. By default just adds it to the emails_sent
+  # array.  
+  def test_mode_send_email(msg, from, to)
+    emails_sent << [msg, from, to]
+  end
+end

data/spec/simple_mailer.rb

@@ -0,0 +1,103 @@
+#!/usr/bin/env spec
+require File.join(File.dirname(File.dirname(__FILE__)), '/lib/simple_mailer')
+Object.send(:remove_const, :Net)
+
+$message = [nil, nil, nil]
+module Net
+  class SMTP
+    class Mock
+      def initialize(host)
+        @host = host
+      end
+      def send_message(msg, from, to)
+        $message = [msg, from, to, @host]
+      end
+    end
+    def self.start(host, *args)
+      yield(Mock.new(host))
+    end
+  end
+end
+
+shared_examples_for "simple_mailer" do
+  before do
+    $message = [nil, nil, nil]
+  end
+
+  it "should sent email" do
+    @mailer.send_email('from1@from.com', 'to1@to.com', 'Test Subject 1', 'Test Body 1')
+    $message.should == [<<END_MESSAGE, 'from1@from.com', 'to1@to.com', 'localhost']
+From: from1@from.com
+To: to1@to.com
+Subject: Test Subject 1
+
+Test Body 1
+END_MESSAGE
+  end
+
+  it "should allow the setting of headers" do
+    @mailer.send_email('from2@from.com', 'to2@to.com', 'Test Subject 2', 'Test Body 2', 'HeaderKey2'=>'HeaderValue2')
+    $message.should == [<<END_MESSAGE, 'from2@from.com', 'to2@to.com', 'localhost']
+From: from2@from.com
+To: to2@to.com
+Subject: Test Subject 2
+HeaderKey2: HeaderValue2
+
+Test Body 2
+END_MESSAGE
+  end
+
+  it "should recognize the special :smtp_from and :smtp_to headers" do
+    @mailer.send_email('from3@from.com', 'to3@to.com', 'Test Subject 3', 'Test Body 3', 'HeaderKey3'=>'HeaderValue3', :smtp_from=>'from@to.com', :smtp_to=>'to@from.com')
+    $message.should == [<<END_MESSAGE, 'from@to.com', 'to@from.com', 'localhost']
+From: from3@from.com
+To: to3@to.com
+Subject: Test Subject 3
+HeaderKey3: HeaderValue3
+
+Test Body 3
+END_MESSAGE
+  end
+
+  it "should allow the setting of smtp server" do
+    @mailer.smtp_server = 'blah.com'
+    @mailer.send_email('from1@from.com', 'to1@to.com', 'Test Subject 1', 'Test Body 1')
+    $message.should == [<<END_MESSAGE, 'from1@from.com', 'to1@to.com', 'blah.com']
+From: from1@from.com
+To: to1@to.com
+Subject: Test Subject 1
+
+Test Body 1
+END_MESSAGE
+  end
+
+  it "should not send emails in test mode" do
+    SimpleMailer.test_mode!
+    @mailer.send_email('from3@from.com', 'to3@to.com', 'Test Subject 3', 'Test Body 3', 'HeaderKey3'=>'HeaderValue3', :smtp_from=>'from@to.com', :smtp_to=>'to@from.com')
+    $message.should == [nil, nil, nil]
+  end
+
+  it "should record emails sent to emails_sent in test mode" do
+    SimpleMailer.test_mode!
+    @mailer.send_email('from3@from.com', 'to3@to.com', 'Test Subject 3', 'Test Body 3', 'HeaderKey3'=>'HeaderValue3', :smtp_from=>'from@to.com', :smtp_to=>'to@from.com')
+    @mailer.emails_sent.should == [[<<END_MESSAGE, 'from@to.com', 'to@from.com']]
+From: from3@from.com
+To: to3@to.com
+Subject: Test Subject 3
+HeaderKey3: HeaderValue3
+
+Test Body 3
+END_MESSAGE
+    SimpleMailer.instance_variable_set(:@test_mode, false)
+  end
+end
+
+describe "SimpleMailer module itself" do
+  before{@mailer = SimpleMailer}
+  it_should_behave_like "simple_mailer"
+end
+
+describe "Class including SimpleMailer" do
+  before{@mailer = Class.new{include SimpleMailer}.new}
+  it_should_behave_like "simple_mailer"
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification 
+name: simple_mailer
+version: !ruby/object:Gem::Version 
+  version: 1.1.0
+platform: ruby
+authors: 
+- Jeremy Evans
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-08 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: 
+email: code@jeremyevans.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+files: 
+- README
+- LICENSE
+- lib/simple_mailer.rb
+- spec/simple_mailer.rb
+has_rdoc: true
+homepage: 
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --line-numbers
+- README
+- lib
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: Simple email library with testing support
+test_files: []
+