padrino-mailer 0.10.2 → 0.10.3

data/.document

@@ -1,5 +1,5 @@
-README.rdoc
 lib/**/*.rb
 bin/*
-features/**/*.feature
-LICENSE
+-
+README.rdoc
+LICENSE.txt

data/.yardopts

@@ -0,0 +1 @@
+--title 'Padrino Mailer Documentation' --protected

data/README.rdoc

@@ -91,7 +91,7 @@ is invoking the render function passing the <tt>name</tt> attribute to the body
 
 Once the mailer definition has been completed and the template has been defined, the email can be sent using:
 
-  deliver(:sample, :registration_email, "Bob", "21")
+  deliver(:sample, :registration, "Bob", "21")
 
 And that will then deliver the email according the the configured options. This is all you need to send basic emails.
 

data/lib/padrino-mailer/base.rb

@@ -5,28 +5,58 @@ module Padrino
     #
     # You can set the default delivery settings from your app through:
     #
-    #   set :delivery_method, :smtp => {
-    #     :address         => 'smtp.yourserver.com',
-    #     :port            => '25',
-    #     :user_name       => 'user',
-    #     :password        => 'pass',
-    #     :authentication  => :plain # :plain, :login, :cram_md5, no auth by default
-    #     :domain          => "localhost.localdomain" # the HELO domain provided by the client to the server
-    #   }
+    #  set :delivery_method, :smtp => {
+    #    :address         => 'smtp.yourserver.com',
+    #    :port            => '25',
+    #    :user_name       => 'user',
+    #    :password        => 'pass',
+    #    :authentication  => :plain
+    #  }
     #
     # or sendmail:
     #
-    #   set :delivery_method, :sendmail
+    #  set :delivery_method, :sendmail
     #
     # or for tests:
     #
-    #   set :delivery_method, :test
+    #  set :delivery_method, :test
     #
-    # and then all delivered mail will use these settings unless otherwise specified.
+    # and all delivered mail will use these settings unless otherwise specified.
+    #
+    # Define a mailer in your application:
+    #
+    #   # app/mailers/sample_mailer.rb
+    #   MyAppName.mailers :sample do
+    #     defaults :content_type => 'html'
+    #     email :registration do |name, age|
+    #       to      'user@domain.com'
+    #       from    'admin@site.com'
+    #       subject 'Welcome to the site!'
+    #       locals  :name => name
+    #       render  'registration'
+    #     end
+    #   end
+    #
+    # Use the mailer to deliver messages:
+    #
+    #  deliver(:sample, :registration, "Bob", "21")
+    #
+    # For a more detailed guide, please read the {Padrino Mailer}[http://www.padrinorb.com/guides/padrino-mailer] guide.
     #
     class Base
       attr_accessor :delivery_settings, :app, :mailer_name, :messages
 
+      # Constructs a +Mailer+ base object with specified options.
+      #
+      # @param [Sinatra::Application] app
+      #   The application tied to this mailer.
+      # @param [Symbol] name
+      #   The name of this mailer.
+      # @param [Proc] block
+      #   The +email+ definitions block.
+      #
+      # @see Padrino::Mailer::Helpers::ClassMethods#mailer
+      # @api private
       def initialize(app, name, &block) # @private
         @mailer_name = name
         @messages    = {}
@@ -38,8 +68,12 @@ module Padrino
       ##
       # Defines a mailer object allowing the definition of various email messages that can be delivered
       #
-      # ==== Examples
+      # @param [Symbol] name
+      #   The name of this email message.
+      # @param [Proc] block
+      #   The message definition (i.e subject, to, from, locals).
       #
+      # @example
       #   email :birthday do |name, age|
       #     subject "Happy Birthday!"
       #     to   'john@fake.com'
@@ -48,6 +82,7 @@ module Padrino
       #     render 'birthday'
       #   end
       #
+      # @api public
       def email(name, &block)
         raise "The email '#{name}' is already defined" if self.messages[name].present?
         self.messages[name] = Proc.new { |*attrs|
@@ -62,13 +97,16 @@ module Padrino
 
       # Defines the default attributes for a message in this mailer (including app-wide defaults)
       #
-      # ==== Examples
+      # @param [Hash] attributes
+      #   The hash of message options to use as default.
       #
+      # @example
       #   mailer :alternate do
-      #    defaults :from => 'padrino@from.com', :to => 'padrino@to.com'
-      #    email(:foo) do ... end
+      #     defaults :from => 'padrino@from.com', :to => 'padrino@to.com'
+      #     email(:foo) do; end
       #   end
       #
+      # @api public
       def defaults(attributes=nil)
         if attributes.nil? # Retrieve the default values
           @app.respond_to?(:mailer_defaults) ? @app.mailer_defaults.merge(@defaults) : @defaults

data/lib/padrino-mailer/ext.rb

@@ -16,7 +16,6 @@ module Mail # @private
         settings.views = File.expand_path("./mailers")
         settings.reload_templates = true
       end
-
       # Run the original initialize
       initialize_without_app(*args, &block)
     end
@@ -25,8 +24,7 @@ module Mail # @private
     ##
     # Setup like in Sinatra/Padrino apps content_type and template lookup.
     #
-    # ==== Examples
-    #
+    # @example
     #   # This add a email plain part if a template called bar.plain.* is found
     #   # and a html part if a template called bar.html.* is found
     #   email do
@@ -50,8 +48,7 @@ module Mail # @private
     # html_part are both defined in a message, then it will be a multipart/alternative
     # message and set itself that way.
     #
-    # ==== Examples
-    #
+    # @example
     #  text_part "Some text"
     #  text_part { render('multipart/basic.text') }
     #
@@ -69,8 +66,7 @@ module Mail # @private
     # text_part are both defined in a message, then it will be a multipart/alternative
     # message and set itself that way.
     #
-    # ==== Examples
-    #
+    # @example
     #  html_part "Some <b>Html</b> text"
     #  html_part { render('multipart/basic.html') }
     #
@@ -86,8 +82,7 @@ module Mail # @private
     ##
     # Allows you to add a part in block form to an existing mail message object
     #
-    # ==== Examples
-    #
+    # @example
     #  mail = Mail.new do
     #    part :content_type => "multipart/alternative", :content_disposition => "inline" do |p|
     #      p.part :content_type => "text/plain", :body => "test text\nline #2"
@@ -118,7 +113,6 @@ module Mail # @private
     def settings
       self.class
     end
-    alias :options :settings
 
     ##
     # Sets the message defined template path to the given view path
@@ -191,6 +185,17 @@ module Mail # @private
       @_defaults.each_pair { |k, v| default(k.to_sym, v) } if @_defaults.is_a?(Hash)
     end
 
+    ##
+    # Check if we can log
+    #
+    def self.logging?
+      @_logging
+    end
+
+    def self.logging=(value)
+      @_logging = value
+    end
+
     # Shortcut for delivery_method with smarter smtp overwrites
     def via(method = nil, settings = {})
       if method.nil?

data/lib/padrino-mailer/helpers.rb

@@ -6,30 +6,44 @@ module Padrino
       end
 
       ##
-      # Delivers an email with the given mail attributes (to, from, subject, cc, bcc, body, et.al)
+      # Delivers an email with the given mail attributes.
       #
-      # ==== Examples
+      # @param [Hash] mail_attributes
+      #   The attributes for this message (to, from, subject, cc, bcc, body, etc)
+      # @param [Proc] block
+      #   The block mail attributes for this message.
       #
+      # @example
       #   email do
       #     to      @user.email
-      #     from    "awesomeness@example.com",
+      #     from    "awesomeness@example.com"
       #     subject "Welcome to Awesomeness!"
       #     locals  :a => a, :b => b
       #     render  'path/to/my/template'
       #   end
       #
+      # @see ClassMethods#email
+      # @api public
       def email(mail_attributes={}, &block)
         settings.email(mail_attributes, &block)
       end
 
       ##
-      # Delivers a mailer message email with the given attributes
+      # Delivers a mailer message email with the given attributes.
       #
-      # ==== Examples
+      # @param [Symbol] mailer_name
+      #   The name of the mailer.
+      # @param [Symbol] message_name
+      #   The name of the message to deliver.
+      # @param attributes
+      #   The parameters to pass to the mailer.
       #
+      # @example
       #   deliver(:sample, :birthday, "Joey", 21)
       #   deliver(:example, :message, "John")
       #
+      # @see ClassMethods#deliver
+      # @api public
       def deliver(mailer_name, message_name, *attributes)
         settings.deliver(mailer_name, message_name, *attributes)
       end
@@ -42,16 +56,18 @@ module Padrino
 
         ##
         # Returns all registered mailers for this application
-        #
+        # @private
         def registered_mailers
           @_registered_mailers ||= {}
         end
 
         ##
-        # Defines a mailer object allowing the definition of various email messages that can be delivered
+        # Defines a mailer object allowing the definition of various email messages that can be delivered.
         #
-        # ==== Examples
+        # @param [Symbol] name
+        #   The name of the mailer to initialize.
         #
+        # @example
         #   mailer :sample do
         #     email :birthday do |name, age|
         #       subject 'Happy Birthday!'
@@ -62,6 +78,7 @@ module Padrino
         #     end
         #   end
         #
+        # @api public
         def mailer(name, &block)
           mailer                   = Padrino::Mailer::Base.new(self, name, &block)
           mailer.delivery_settings = delivery_settings
@@ -73,11 +90,18 @@ module Padrino
         ##
         # Delivers a mailer message email with the given attributes
         #
-        # ==== Examples
+        # @param [Symbol] mailer_name
+        #   The name of the mailer.
+        # @param [Symbol] message_name
+        #   The name of the message to deliver.
+        # @param attributes
+        #   The parameters to pass to the mailer.
         #
+        # @example
         #   deliver(:sample, :birthday, "Joey", 21)
         #   deliver(:example, :message, "John")
         #
+        # @api public
         def deliver(mailer_name, message_name, *attributes)
           message = registered_mailers[mailer_name].messages[message_name].call(*attributes)
           message.delivery_method(*delivery_settings)
@@ -85,22 +109,26 @@ module Padrino
         end
 
         ##
-        # Delivers an email with the given mail attributes (to, from, subject, cc, bcc, body, et.al) using settings of
-        # the given app.
+        # Delivers an email with the given mail attributes with specified and default settings.
         #
-        # ==== Examples
+        # @param [Hash] mail_attributes
+        #   The attributes for this message (to, from, subject, cc, bcc, body, etc)
+        # @param [Proc] block
+        #   The block mail attributes for this message.
         #
+        # @example
         #   MyApp.email(:to => 'to@ma.il', :from => 'from@ma.il', :subject => 'Welcome!', :body => 'Welcome Here!')
         #
         #   # or if you prefer blocks
         #
         #   MyApp.email do
         #     to @user.email
-        #     from "awesomeness@example.com",
+        #     from "awesomeness@example.com"
         #     subject "Welcome to Awesomeness!"
         #     body 'path/to/my/template', :locals => { :a => a, :b => b }
         #   end
         #
+        # @api public
         def email(mail_attributes={}, &block)
           message = Mail::Message.new(self)
           message.delivery_method(*delivery_settings)
@@ -111,10 +139,11 @@ module Padrino
 
         private
           ##
-          # Return the parsed delivery method
+          # Returns the parsed delivery method options
           #
           def delivery_settings
             @_delivery_setting ||= begin
+              raise "You must setup :delivery_method, see api for more details" if RUBY_PLATFORM =~ /win32/ && !respond_to?(:delivery_method)
               return [:sendmail, { :location => `which sendmail`.chomp }] unless respond_to?(:delivery_method)
               return [delivery_method.keys[0], delivery_method.values[0]] if delivery_method.is_a?(Hash)
               return [delivery_method, {}] if delivery_method.is_a?(Symbol)

data/lib/padrino-mailer/mime.rb

@@ -7,14 +7,18 @@ module Padrino
       # +mime+ should be the content type like "text/plain"
       # +fallback+ may be any symbol
       #
-      # Also see the documentation for MIME_TYPES
+      # Also see the documentation for {MIME_TYPES}.
       #
-      # ==== Examples
+      # @param [String] mime
+      #   The mime alias to fetch (i.e 'text/plain').
+      # @param [Symbol] fallback
+      #   The fallback mime to use if +mime+ doesn't exist.
       #
-      #   => :plain
+      # @example
       #   Padrino::Mailer::Mime.mime_type('text/plain')
-      #   => :html
+      #   # => :plain
       #   Padrino::Mailer::Mime.mime_type('text/html')
+      #   # => :html
       #
       # This is a shortcut for:
       #
@@ -24,9 +28,8 @@ module Padrino
         MIME_TYPES.fetch(mime.to_s.downcase, fallback)
       end
 
-      # List of most common mime-types, selected various sources
-      # according to their usefulness in a emailg scope for Ruby
-      # users.
+      # List of common mime-types, selected from various sources
+      # according to their usefulness for an email scope.
       #
       # You can add your own mime types like:
       #

data/lib/padrino-mailer.rb

@@ -1,4 +1,4 @@
-# require tilt if available; fall back on bundled version.
+# requires tilt if available; falls back on bundled version.
 begin
   require 'tilt'
 rescue LoadError
@@ -12,19 +12,38 @@ FileSet.glob_require('padrino-mailer/**/*.rb', __FILE__)
 
 module Padrino
   ##
-  # This component uses the 'mail' library to create a powerful but simple mailer system within Padrino (and Sinatra).
-  # There is full support for using plain or html content types as well as for attaching files.
-  # The MailerPlugin has many similarities to ActionMailer but is much lighterweight and (arguably) easier to use.
+  # This component uses the +mail+ library to create a powerful but simple mailer within Padrino (and Sinatra).
+  # There is full support for using plain or html content-types as well as for file attachments.
+  #
+  # Using the mailer in Padrino has two forms. The 'quick' method requires only use
+  # of the +email+ method directly in the controller:
+  #
+  #  # app/controllers/session.rb
+  #  post :create do
+  #    email do
+  #      from "tony@reyes.com"
+  #      to "john@smith.com"
+  #      subject "Welcome!"
+  #      body render('email/registered')
+  #    end
+  #  end
+  #
+  # For a more detailed guide, please read the {Padrino Mailer}[http://www.padrinorb.com/guides/padrino-mailer] guide.
   #
   module Mailer
-    ##
-    # Register
-    #
-    #   Padrino::Mailer::Helpers
-    #
-    # for Padrino::Application
-    #
     class << self
+      ##
+      # Registers the Padrino::Mailer helpers with the application.
+      #
+      # @param [Sinatra::Application] app The application that needs mailers.
+      #
+      # @example
+      #   require 'padrino-mailer'
+      #   class Demo < Padrino::Application
+      #     register Padrino::Mailer::Helpers
+      #   end
+      #
+      # @api public
       def registered(app)
         app.helpers Padrino::Mailer::Helpers
       end

data/test/helper.rb

@@ -2,15 +2,13 @@ ENV['PADRINO_ENV'] = 'test'
 PADRINO_ROOT = File.dirname(__FILE__) unless defined? PADRINO_ROOT
 
 require File.expand_path('../../../load_paths', __FILE__)
-require 'test/unit'
-require 'shoulda'
-require 'mocha'
+require File.join(File.dirname(__FILE__), '..', '..', 'padrino-core', 'test', 'mini_shoulda')
 require 'rack/test'
 require 'padrino-core'
 require 'padrino-helpers'
 require 'padrino-mailer'
 
-class Test::Unit::TestCase
+class MiniTest::Spec
   include Rack::Test::Methods
 
   # Sets up a Sinatra::Base subclass defined with the block
@@ -24,16 +22,6 @@ class Test::Unit::TestCase
     Rack::Lint.new(@app)
   end
 
-  # Silences the output by redirecting to stringIO
-  # silence_logger { ...commands... } => "...output..."
-  def silence_logger(&block)
-    orig_stdout = $stdout
-    $stdout = log_buffer = StringIO.new
-    block.call
-    $stdout = orig_stdout
-    log_buffer.rewind && log_buffer.read
-  end
-
   def pop_last_delivery
     Mail::TestMailer.deliveries.pop
   end

data/test/test_email.rb

@@ -1,6 +1,6 @@
 require File.expand_path(File.dirname(__FILE__) + '/helper')
 
-class TestEmail < Test::Unit::TestCase
+describe "Email" do
 
   context 'the mailer in a app' do
 
@@ -147,7 +147,7 @@ class TestEmail < Test::Unit::TestCase
     end
 
     should 'raise an error if there are two messages with the same name' do
-      assert_raise RuntimeError do
+      assert_raises RuntimeError do
         mock_app do
           register Padrino::Mailer
           mailer :foo do

data/test/test_message.rb

@@ -1,6 +1,6 @@
 require File.expand_path(File.dirname(__FILE__) + '/helper')
 
-class TestMessage < Test::Unit::TestCase
+describe "Message" do
 
   context 'the message' do
     should "accept headers and body" do
@@ -18,7 +18,7 @@ class TestMessage < Test::Unit::TestCase
     end
 
     should "raise an error if template was not found" do
-      assert_raise Padrino::Rendering::TemplateNotFound do
+      assert_raises Padrino::Rendering::TemplateNotFound do
         Mail::Message.new do
           from    'padrino@me.com'
           to      'padrino@you.com'

data/test/test_padrino_mailer.rb

@@ -2,7 +2,7 @@ require File.expand_path(File.dirname(__FILE__) + '/helper')
 require File.expand_path(File.dirname(__FILE__) + '/fixtures/sinatra_app/app')
 require File.expand_path(File.dirname(__FILE__) + '/fixtures/padrino_app/app')
 
-class TestPadrinoMailer < Test::Unit::TestCase
+describe "PadrinoMailer" do
 
   context 'for mail delivery in sample sinatra application' do
     setup { @app = SinatraApp }
@@ -82,7 +82,7 @@ class TestPadrinoMailer < Test::Unit::TestCase
       assert_email_sent(:to => 'john@apple.com', :from => 'joe@smith.com',
                         :subject => 'Test Email', :body => 'Test Body', :delivery_method => @app.delivery_method)
     end
-    
+
     should_eventually 'be able to deliver a basic email using Padrino::Helpers' do
       post '/deliver/helper'
       assert_equal 'mail delivered', body
@@ -90,6 +90,6 @@ class TestPadrinoMailer < Test::Unit::TestCase
                         :content_type => 'text/html', :delivery_method => @app.delivery_method,
                         :subject => "Welcome Helper!", :body => "<a href=\"#\">jim</a>")
     end
-    
+
   end
 end

data/test/test_part.rb

@@ -1,6 +1,6 @@
 require File.expand_path(File.dirname(__FILE__) + '/helper')
 
-class TestPart < Test::Unit::TestCase
+describe "Part" do
 
   context "the part" do
     should "use correctly parts" do

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: padrino-mailer
 version: !ruby/object:Gem::Version 
-  hash: 51
+  hash: 49
   prerelease: 
   segments: 
   - 0
   - 10
-  - 2
-  version: 0.10.2
+  - 3
+  version: 0.10.3
 platform: ruby
 authors: 
 - Padrino Team
@@ -18,7 +18,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-31 00:00:00 -07:00
+date: 2011-10-03 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -29,12 +29,12 @@ dependencies:
     requirements: 
     - - "="
       - !ruby/object:Gem::Version 
-        hash: 51
+        hash: 49
         segments: 
         - 0
         - 10
-        - 2
-        version: 0.10.2
+        - 3
+        version: 0.10.3
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
@@ -64,7 +64,8 @@ extra_rdoc_files:
 files: 
 - .document
 - .gitignore
-- LICENSE
+- .yardopts
+- LICENSE.txt
 - README.rdoc
 - Rakefile
 - lib/padrino-mailer.rb