mmmail 1.0.0

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2009 Loren Segal
+ 
+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.markdown

@@ -0,0 +1,81 @@
+MmMail
+======
+
+Mmmm, a Minimalist mail library for Ruby. Works with SMTP or sendmail.
+One method call to send out emails. You're done. Easy tastes good. Oh,
+and it works with Ruby 1.9.
+
+Join the discussion: #mmmail on freenode
+
+Install
+-------
+
+    $ git clone git://github.com/lsegal/mmmail
+    $ cd mmmail
+    $ rake install
+
+or use GitHub gems:
+
+    $ sudo gem install lsegal-mmmail --source http://gems.github.com
+    
+Use
+---
+
+**An easy example**:
+
+    require 'mmmail'
+    MmMail.send(to: 'me@gmail.com', from: 'me@yahoo.com', 
+                subject: 'hello joe', body: <<-eof)
+      Hey Joe,
+      
+      You left the kitchen light on.
+      It started a fire and burned down your house.
+      Have fun in Hawaii.
+      
+      Jake.
+    eof
+    
+Yes, that's Ruby 1.9 syntax, get used to it. It should work out
+with the inferior 1.8 hash syntax too.
+
+**More complex stuff, like using sendmail instead of Net::SMTP:**
+
+    require 'mmmail'
+    MmMail::Transport::DefaultConfig.method = :sendmail
+    MmMail.send(...)
+    
+Okay it wasn't that hard. You can also specify the path to sendmail with
+
+    MmMail::Transport::DefaultConfig.sendmail_binary = '/bin/sendmail'
+
+**Dealing with SMTP auth and separate hosts:**
+
+My ISP makes me do this:
+
+    require 'mmmail'
+    config = MmMail::Transport::DefaultConfig
+    config.host = 'smtp.myisp.com'
+    config.port = 587
+    config.auth_type = :plain # or :md5cram or :login
+    config.auth_user = 'myuser'
+    config.auth_pass = 'mypass'
+
+Yours might too. Okay, it doesn't make me do *all* of that, but these are
+just examples, right?
+
+You can also create a `MmMail::Transport::Config` object to pass to `#mail`
+if you need multiple configurations:
+
+    config = MmMail::Transport::Config.new
+    config.host = 'mail.someOtherIspHost.com'
+    
+    MmMail.send({options: here}, config)
+    # or 
+    msg = MmMail::Message.new(to: '...', from: '...', subject: '...', body: '...')
+    transport = MmMail::Transport.new(config)
+    transport.send(msg, config)
+    
+Documentation
+-------------
+
+[http://lsegal.github.com/mmmail/doc](http://lsegal.github.com/mmmail/doc)

data/Rakefile

@@ -0,0 +1,42 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+
+begin
+require 'spec'
+require 'spec/rake/spectask'
+rescue LoadError; end
+
+begin
+require 'yard'
+rescue LoadError; end
+ 
+WINDOWS = (PLATFORM =~ /win32|cygwin/ ? true : false) rescue false
+SUDO = WINDOWS ? '' : 'sudo'
+ 
+task :default => :specs
+ 
+load 'mmmail.gemspec'
+Rake::GemPackageTask.new(SPEC) do |pkg|
+  pkg.gem_spec = SPEC
+  pkg.need_zip = true
+  pkg.need_tar = true
+end
+ 
+desc "Install the gem locally"
+task :install => :package do
+  sh "#{SUDO} gem install pkg/#{SPEC.name}-#{SPEC.version}.gem --local"
+  sh "#{SUDO} rm -rf pkg/#{SPEC.name}-#{SPEC.version}" unless ENV['KEEP_FILES']
+end
+ 
+begin 
+desc "Run all specs"
+Spec::Rake::SpecTask.new("specs") do |t|
+  $DEBUG = true if ENV['DEBUG']
+  t.spec_opts = ["--format", "specdoc", "--colour"]
+  t.spec_files = Dir["spec/**/*_spec.rb"].sort
+end
+rescue LoadError; end
+ 
+begin
+YARD::Rake::YardocTask.new
+rescue LoadError; end

data/lib/mmmail.rb

@@ -0,0 +1,283 @@
+require 'net/smtp'
+
+module MmMail
+  # General exception class when something goes wrong in MmMail
+  class TransportError < Exception; end
+  
+  # Handles the transportation of a {Message} to its destination.
+  # Basic support for SMTP (through +Net::SMTP+) or +sendmail+.
+  # 
+  # You can either pass a new {Transport::Config} object during transport or use 
+  # the system wide {Transport::DefaultConfig} object. 
+  # 
+  # @example [To set transport to use sendmail]
+  #   MmMail::Transport::DefaultConfig.method = :sendmail
+  #   # Note you might need to point to sendmail if it's not in your PATH:
+  #   MmMail::Transport::DefaultConfig.sendmail_binary = '/path/to/sendmail'
+  # 
+  # @example [To connect to your ISP SMTP server on 587]
+  #   MmMail::Transport::DefaultConfig.host = 'smtp.myisp.com'
+  #   MmMail::Transport::DefaultConfig.port = 587
+  # 
+  # @see Transport::Config
+  # @see Transport::mail
+  class Transport
+    # Configuration class for a {Transport}
+    class Config
+      # Set/get the SMTP host/port information
+      attr_accessor :host, :port
+      
+      # Set/get the authentication type (nil for none, :plain, :login or :cram_md5)
+      attr_accessor :auth_type
+      
+      # Set/get the AUTH user/password when using SMTP transport.
+      attr_accessor :auth_user, :auth_pass
+      
+      # Set/get the email method. Allowed values are +:smtp+ or +:sendmail+.
+      attr_accessor :method
+      
+      # Set/get the location of the sendmail binary on the system
+      attr_accessor :sendmail_binary
+
+      # Creates a new Config object set to send via SMTP on
+      # localhost:25 with no authentication.
+      def initialize
+        @method = :smtp # :sendmail
+        @host = 'localhost'
+        @port = 25
+        @auth_type = nil # :plain, :login, :cram_md5
+        @auth_user = nil
+        @auth_pass = nil
+        @sendmail_binary = 'sendmail'
+      end
+    end
+    
+    # The default system wide configuration used when no custom config
+    # object is provided to a Transport object. If you want to make global
+    # configuration changes, change the settings here.
+    DefaultConfig = Config.new
+
+    # Creates a new {Transport} object and sends an email.
+    # 
+    # @see #mail
+    def self.mail(message, config = nil)
+      new(config).mail(message)
+    end
+    
+    # Sets a {Config} object to use when sending mail
+    attr_accessor :config
+    
+    # Creates a new Transport object to send emails with. To change
+    # settings to sendmail or use SMTP auth, set these in the {Config}
+    # object.
+    #  
+    # @param [Config] a configuration to use
+    # @raise [ArgumentError] if config is not a {Config} object.
+    def initialize(config = nil)
+      if config && !config.is_a?(Config)
+        raise ArgumentError, "expected #{self.class}::Config"
+      end
+      
+      @config = config || DefaultConfig
+    end
+    
+    # Sends a {Message} object out as an email using the configuration
+    # set during initialization.
+    # 
+    # @param [Message] an email to send
+    # @raise [ArgumentError] if message is not a {Message} object
+    # @raise [TransportError] if message is not {Message#valid? valid}.
+    def mail(message)
+      unless Message === message
+        raise ArgumentError, "expected MmMail::Message, got #{message.class}"
+      end
+      
+      raise TransportError, "invalid message" unless message.valid?
+      
+      send("mail_#{config.method}", message)
+    end
+    
+    # Sends a mail through Net::SMTP using the {#config} if
+    # any SMTP or hostname information is set.
+    # 
+    # @param [#to_s] message the message to send
+    def mail_smtp(message)
+      Net::SMTP.start(config.host, config.port, 'localhost.localdomain', 
+          config.auth_user, config.auth_pass, config.auth_type) do |smtp|
+        smtp.send_message(message.to_s, message.from, message.recipients_list)
+      end
+    end
+    
+    # Sends a mail through sendmail using the {Config#sendmail_binary} as the
+    # location of the file.
+    # 
+    # @param [#to_s] message the message to send
+    # @raise [TransportError] if a problem during execution occured
+    def mail_sendmail(message)
+      bin, err = config.sendmail_binary, ''
+      result = IO.popen("#{bin} -t 2>&1", "w+") do |io|
+        io.write(message.to_s)
+        io.close_write
+        err = io.read.chomp
+      end
+      
+      raise TransportError, err if $? != 0
+    end
+  end
+
+  # A Message object representing an Email to be passed to a {Transport}.
+  class Message
+    # Creates a new message with associated fields.
+    # 
+    # @example
+    #   MmMail::Message.new(:to => 'test@example.com', :body => 'hi')
+    # 
+    # @param [Hash] opts the options to create a message with.
+    # @option opts [String] :from ('nobody@localhost') The email's From field
+    # @option opts [String] :subject ('') The email's Subject field
+    # @option opts [String] :body ('') The email's body (not a header)
+    # @option opts [String] :to (nil) The email's To field. List multiple recipients as
+    #   'a@b.c, b@c.d', not an array.
+    def initialize(opts = {})
+      defaults = {
+        :from => 'nobody@localhost',
+        :subject => '',
+        :body => ''
+      }
+      @headers = defaults.merge(opts)
+    end
+    
+    # Allow access of fields by header name or symbolic representation
+    # 
+    # @example
+    #   m[:x_message_id] = '1234'
+    #   m['X-Message-Id'] == '1234' # => true
+    # 
+    # @param [String, Symbol] k the header or symbolic header value to lookup.
+    # @return [String] the value associated with the field
+    def [](k)     @headers[translate_header_to_sym(k)]     end
+
+    # Allow access of fields by header name or symbolic representation
+    # 
+    # @example
+    #   m[:x_message_id] = '1234'
+    #   m['X-Message-Id'] == '1234' # => true
+    # 
+    def []=(k, v) @headers[translate_header_to_sym(k)] = v end
+    
+    # Override this method to allow any call to obj.meth or obj.meth= to
+    # set a header field on this object.
+    # 
+    # @example [To set the field 'X-Message-Id']
+    #   m.x_message_id = '1234'
+    #   m.x_message_id == '1234' # => true
+    # 
+    def method_missing(sym, *args)
+      if sym.to_s =~ /=$/
+        self[sym.to_s[0..-2].to_sym] = args.first
+      elsif @headers.has_key?(sym)
+        self[sym]
+      else
+        super
+      end
+    end
+    
+    # Override this method to verify if a field has been set.
+    # 
+    # @return [Boolean] whether the field was set (or if a regular method
+    #   is callable.)
+    def respond_to?(sym)
+      return true if super
+      @headers.has_key?(sym)
+    end
+    
+    # Returns the message in its full form as expected by an SMTP server.
+    # 
+    # @return [String] the email with headers followed by a body
+    def to_s
+      [headers, body].join("\n")
+    end
+    
+    # Returns all the recipients in the To field.
+    # 
+    # @example
+    #   m.to = 'a@b.c, b@c.d'
+    #   m.recipients_list # => ['a@b.c', 'b@c.d']
+    # 
+    # @return [Array<String>] the emails in the To field of the message.
+    def recipients_list
+      to.split(/\s*,\s*/)
+    end
+    
+    # Checks if the message is valid. Validity is based on
+    # having the From, To and Subject fields set. From and To
+    # must not be empty.
+    # 
+    # @return [Boolean] whether or not the message is a valid e-mail
+    def valid?
+      [:from, :to].each do |field|
+        return false if !self[field] || self[field].empty?
+      end
+      
+      self[:subject] ? true : false
+    end
+    
+    private
+    
+    # Returns the headers as the RFC822 string.
+    # 
+    # @return [String] the headers in RFC822 format
+    def headers
+      @headers.reject {|k, v| k == :body }.map do |k, v|
+        translate_header_name(k) + ': ' + v + "\n"
+      end.join
+    end
+
+    # Translates a header from its symbolic representation to its
+    # RFC822 header name or the other way around. If you give in
+    # a header name (String) you will get a Symbol, and a Symbol
+    # if you give a String.
+    # 
+    # @example
+    #   msg.translate_header_name(:x_message_id) # => 'X-Message-Id'
+    #   msg.translate_header_name('Content-Type') # => :content_type
+    # 
+    # @param [String,Symbol] key the header name to translate
+    # @return [Symbol,String] the symbolic or header representation of
+    #   the symbol or header name.
+    # @raise [ArgumentError] if key is neither a String or Symbol
+    def translate_header_name(key)
+      case key
+      when String
+        key.downcase.tr('-', '_').to_sym
+      when Symbol
+        key.to_s.capitalize.gsub(/_(.)/) {|m| '-' + m[1].upcase }
+      else
+        raise ArgumentError, "invalid key type #{key.class}"
+      end
+    end
+    
+    # Translates a header one-way to the symbolic representation.
+    # 
+    # @param [String, Symbol] key any header or symbolic key
+    # @return [Symbol] the symbolic representation of the header name
+    # @see #translate_header_name
+    def translate_header_to_sym(key)
+      return key if Symbol === key
+      translate_header_name(key)
+    end
+  end
+  
+  # Quickly send out an email.
+  # 
+  # @example
+  #   MmMail.mail(:to => 'me@gmail.com', :body => 'hi!')
+  # 
+  # @param [Hash] opts the hash used to construct the message
+  # @param [Transport::Config, nil] config the configuration object to use
+  #   during transport
+  # @see Transport#mail
+  def self.mail(opts = {}, config = nil)
+    Transport.mail(Message.new(opts), config)
+  end
+end

data/spec/basic_spec.rb

@@ -0,0 +1,193 @@
+require File.dirname(__FILE__) + '/../lib/mmmail.rb'
+require 'net/smtp'
+
+describe MmMail::Message, '#initialize' do
+  it "should always have from, subject and body" do
+    m = MmMail::Message.new
+    m.from.should == 'nobody@localhost'
+    m.body.should == ''
+    m.subject.should == ''
+  end
+end
+
+describe MmMail::Message, "accessor methods" do
+  it "should allow access from m.value/m.value=" do
+    m = MmMail::Message.new
+    m.some_field = 'hello'
+    m.some_field.should == 'hello'
+  end
+  
+  it "should allow access from m[:value]" do
+    m = MmMail::Message.new
+    m[:some_field] = 'hello'
+    m[:some_field].should == 'hello'
+  end
+  
+  it "should allow access from m['Value']" do
+    m = MmMail::Message.new
+    m['Some-Field'] = 'hello'
+    m['Some-Field'].should == 'hello'
+  end
+  
+  it "should allow mixing of any form of access" do
+    check = lambda do |m|
+      m.some_field.should == 'hello'
+      m[:some_field].should == 'hello'
+      m['Some-Field'].should == 'hello'
+    end
+    
+    m = MmMail::Message.new
+    m.some_field = 'hello'
+    check.call(m)
+    m[:some_field] = 'hello'
+    check.call(m)
+    m['Some-Field'] = 'hello'
+    check.call(m)
+  end
+  
+  it "should advertise that it responds to set fields (respond_to?)" do
+    m = MmMail::Message.new
+    m.some_field = 'hello'
+    m.respond_to?(:to_s).should == true # sanity check
+    m.respond_to?(:some_field).should == true
+    m.respond_to?(:FAIL).should == false
+  end
+end
+
+describe MmMail::Message, '#translate_header_name' do
+  def translate(val) MmMail::Message.new.send(:translate_header_name, val) end
+  
+  it "should translate header 'Some-Field' attribute name to :some_field" do
+    translate('Some-Field').should == :some_field
+    translate('Some-field').should == :some_field
+    translate('To').should == :to
+    translate('X-Message-Id').should == :x_message_id
+  end
+  
+  it "should translate header :some_field to 'Some-Field'" do
+    translate(:some_field).should == 'Some-Field'
+  end
+  
+  it "should raise ArgumentError if arg is not Symbol or String" do
+    lambda { translate({}) }.should raise_error(ArgumentError)
+  end
+end
+
+describe MmMail::Message, "#to_s" do
+  it "should show all headers before special value body" do
+    m = MmMail::Message.new
+    m.to = 'hello@email.com'
+    m.from = 'me@email.com'
+    m.x_message_id = '12345'
+    m.body = "Hello World"
+    m.subject = 'Subject Here'
+    
+    # Might not work in Ruby 1.8 (hashes are unordered)
+    m.to_s.should == 
+    "From: me@email.com\nSubject: Subject Here\nTo: hello@email.com\n" +
+    "X-Message-Id: 12345\n\nHello World"
+  end
+end
+
+describe MmMail::Message, '#valid?' do
+  it "should be valid only if message has from, to and subject" do
+    m = MmMail::Message.new
+    m.valid?.should == false # no to or subject
+    m.to = '' 
+    m.valid?.should == false # to is empty, not good enough
+    m.to = 'hello@test.com'
+    m.subject = ''
+    m.valid?.should == true # empty subject is legal
+    m.subject = nil
+    m.valid?.should == false
+  end
+end
+
+describe MmMail::Message, '#recipient_list' do
+  it "should list all emails in the To header" do
+    m = MmMail::Message.new
+    m.to = 'a@b.c ,     b@c.d'
+    m.recipients_list.should == ['a@b.c', 'b@c.d']
+  end
+end
+
+describe MmMail::Transport::Config, '#initialize' do
+  it "should initialize with sane defaults" do
+    config = MmMail::Transport::Config.new
+    config.host.should == 'localhost'
+    config.port.should == 25
+    config.auth_type.should be_nil
+    config.auth_user.should be_nil
+    config.auth_pass.should be_nil
+    config.method.should == :smtp
+    config.sendmail_binary.should == 'sendmail'
+  end
+end
+
+describe MmMail::Transport, '.mail' do
+  it "should create a Transport object and call #mail" do
+    Net::SMTP.should_receive(:start)
+    m = MmMail::Message.new(:to => 'test@test.com', :subject => 'hi')
+    MmMail::Transport.mail(m)
+  end
+end
+
+describe MmMail::Transport, '#initialize' do
+  it "should allow config object to be passed" do
+    lambda { MmMail::Transport.new(:symbol) }.should raise_error(ArgumentError)
+  end
+  
+  it "should allow valid config" do
+    conf = MmMail::Transport::Config.new
+    transport = MmMail::Transport.new(conf)
+    transport.config.should == conf
+  end
+end
+
+describe MmMail::Transport, '#mail' do
+  it "should raise ArgumentError if argument is not a message" do
+    lambda { MmMail::Transport.new.mail(:sym) }.should raise_error(ArgumentError)
+  end
+  
+  it "should raise TransportError if message is invalid" do
+    invalid_m = MmMail::Message.new
+    lambda { MmMail::Transport.new.mail(invalid_m) }.should raise_error(MmMail::TransportError)
+  end
+  
+  it "should pass to Net::SMTP if method is set to :smtp" do
+    Net::SMTP.should_receive(:start).with('localhost', 25, 'localhost.localdomain', nil, nil, nil)
+    m = MmMail::Message.new(:to => 'test@test.com', :subject => 'hi')
+    MmMail::Transport.new.mail(m)
+  end
+  
+  it "should pass changed config values to Net::SMTP" do
+    conf = MmMail::Transport::Config.new
+    conf.auth_type = :plain
+    conf.auth_user = 'foo'
+    conf.auth_pass = 'bar'
+    conf.host = 'foo.bar'
+    conf.port = 587
+    Net::SMTP.should_receive(:start).with(conf.host, conf.port, 
+      'localhost.localdomain', conf.auth_user, conf.auth_pass, conf.auth_type)
+    m = MmMail::Message.new(:to => 'test@test.com', :subject => 'hi')
+    MmMail::Transport.new(conf).mail(m)
+  end
+
+  it "should pass to sendmail if method is set to :sendmail" do
+    conf = MmMail::Transport::Config.new
+    conf.method = :sendmail
+    conf.sendmail_binary = '/path/to/sendmail'
+    IO.should_receive(:popen).with('/path/to/sendmail -t 2>&1', 'w+')
+    m = MmMail::Message.new(:to => 'test@test.com', :subject => 'hi')
+    lambda { MmMail::Transport.new(conf).mail(m) }.should raise_error
+  end
+  
+  # Fails in rake specs? works from TextMate
+  it "should fail if the sendmail binary is invalid" do
+    conf = MmMail::Transport::Config.new
+    conf.method = :sendmail
+    conf.sendmail_binary = '/FAIL'
+    m = MmMail::Message.new(:to => 'test@test.com', :subject => 'hi')
+    lambda { MmMail::Transport.new(conf).mail(m) }.should raise_error(MmMail::TransportError)
+  end
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification 
+name: mmmail
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Loren Segal
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-02-22 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: 
+email: lsegal@soen.ca
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/mmmail.rb
+- spec/basic_spec.rb
+- LICENSE
+- README.markdown
+- Rakefile
+has_rdoc: yard
+homepage: http://github.com/lsegal/mmmail
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+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: mmmail
+rubygems_version: 1.3.4
+signing_key: 
+specification_version: 3
+summary: Mmmm, a Minimalist mail library for Ruby. Works with SMTP or sendmail.
+test_files: []
+