rhizmail 0.1.1 → 0.1.2

data/lib/rhizmail.rb

@@ -32,21 +32,23 @@
 #
 # == Dependencies
 #
-# RhizMail depends on two external libraries:
+# RhizMail depends on three external libraries:
 #
 # * ContextualService: http://contxtlservice.rubyforge.org
 # * MockFS: http://mockfs.rubyforge.org
+# * Text::Format: http://rubyforge.org/projects/text-format
 
 require 'contxtlservice'
 require 'mockfs'
 require 'net/smtp'
+require 'text/format'
 
 module RhizMail
-	Version = '0.1.1'
+	Version = '0.1.2'
 
 	# Returns a boolean value describing whether <tt>address</tt> is a plausible 
 	# email address format.
-	def self.valid_address(address); (address =~ /\w@\w*\./) != nil; end
+	def self.valid_address?(address); (address =~ /\w@\w*\./) != nil; end
 
 	# InvalidStateError is raised by SimpleTemplateMessage if you try to send it
 	# out without doing all the necessary template substitutions.
@@ -114,7 +116,7 @@ module RhizMail
 		# accessors, the following defaults apply:
 		# [to_name] nil
 		# [from_name] nil
-		# [content_type] nil
+		# [content_type] nil (possible values for content_type are :html and :multipart)
 		# [charset] 'iso-8859-1'
 		def initialize( *args )
 			@charset = 'iso-8859-1'
@@ -132,25 +134,23 @@ module RhizMail
 		# Sends the email.
 		def deliver; Mailer.get_mailer.send_email( self ); end
 		
-		# Returns an array of strings describing the headers for this email
-		# message.
-		def headers
-			headers = []
-			headers << "Subject: #{@subject}"
-			toHeader = "To: "
-			if @to_name
-				toHeader += " #{@to_name} <#{@to_address}>"
-			else
-				toHeader += " #{@to_address}"
-			end
-			headers << toHeader
+		def from_header # :nodoc:
 			fromHeader = "From: "
 			if @from_name
 				fromHeader += "#{@from_name} <#{@from_address}>"
 			else
 				fromHeader += "#{@from_address}"
 			end
-			headers << fromHeader
+			fromHeader
+		end
+			
+		# Returns an array of strings describing the headers for this email
+		# message.
+		def headers
+			headers = []
+			headers << "Subject: #{@subject}"
+			headers << to_header
+			headers << from_header
 			if content_type == :html
 				headers << "Content-Type: text/html; charset=\"#{@charset}\""
 				headers << "MIME-Version: 1.0"
@@ -160,6 +160,16 @@ module RhizMail
 			end
 			headers
 		end
+		
+		def to_header # :nodoc:
+			toHeader = "To: "
+			if @to_name
+				toHeader += " #{@to_name} <#{@to_address}>"
+			else
+				toHeader += " #{@to_address}"
+			end
+			toHeader
+		end
 	
 		# Mailer calls this before sending a message; subclasses can override this
 		# if they want to ensure that certain parts of the message are valid before 
@@ -224,8 +234,17 @@ module RhizMail
 	#
 	#   Thanks!
 	#
-	# Note that the first line needs to be in the format "Subject: [ SUBJECT ]", 
-	# and should be followed by a blank line.
+	# The Subject and From information can be set explicitly in the template,
+	# with lines like:
+	#
+	#   Subject: Thanks for joining Website.com!
+	#   From: "Bill Smith" <bill.smith@email.com>
+	#
+	# These header lines need to be at the top of the template, and they should
+	# be followed by a blank line dividing them from the template body. Header 
+	# lines are optional; you can leave them and set them explicitly using 
+	# SimpleTemplateMessage#subject=, SimpleTemplateMessage#from_name=, and 
+	# SimpleTemplateMessage#from_address= instead.
 	#
 	# Then you create an instance of SimpleTemplateMessage and use 
 	# SimpleTemplateMessage#substitute to change the contents:
@@ -285,7 +304,7 @@ module RhizMail
 	#
 	# If you call SimpleTemplateMessage#deliver without doing all the
 	# substitutions required by the template, it will raise an InvalidStateError. 
-	# (Getting an exception is probably better than sending a customer an email
+	# (Getting an exception is probably better than sending somebody an email
 	# with funny symbols in it.)
 	class SimpleTemplateMessage < Message
 		SubclassAttributes = Struct.new( :substitutions, :template, :from_address )
@@ -342,6 +361,11 @@ module RhizMail
 		# Defaults for :template_file and :from_address can be set with
 		# SimpleTemplateMessage.template and SimpleTemplateMessage.from_address.
 		#
+		# By default, SimpleTemplateMessage#body wraps to 72 columns. You can
+		# change this behavior by passing :body_wrap in through the hash; pass 
+		# +false+ to turn off wrapping, any other number to set the number of
+		# columns to wrap to.
+		#
 		# An older, deprecated style of creation is to take specific parameters:
 		#
 		#   msg = SimpleTemplateMessage.new(
@@ -350,21 +374,8 @@ module RhizMail
 		#   )
 		def initialize( *args )
 			if args.first.is_a? Hash
-				h = args.first
-				verboten_keys = [ :body, :charset, :content_type, :subject ]
-				raise InvalidStateError unless ( h.keys & verboten_keys ).empty?
-				template_file = nil
-				if h[:template_file]
-					template_file = h[:template_file]
-					h.delete :template_file
-				else
-					template_file = class_attributes.template
-				end
-				raise InvalidStateError if template_file.nil?
-				read_template template_file
-				if class_attributes.from_address and !h[:from_address]
-					h[:from_address] = class_attributes.from_address
-				end
+				h = args.first.clone
+				initialize_from_hash h
 				super h
 			else
 				to_address, from_address, template_file = args
@@ -373,15 +384,29 @@ module RhizMail
 			end
 			generate_body @template
 		end
+		
+		def body
+			if @body_wrap or @body_wrap.nil?
+				format = Text::Format.new
+				format.columns = @body_wrap if @body_wrap
+				format.first_indent = 0
+				@body = format.paragraphs @body
+			end
+			@body
+		end
 	
 		def body_template( template ) # :nodoc:
 			body = ''
 			blank_line_found = false
+			headers_included = true
 			template.each { |line|
-				if blank_line_found
+				if blank_line_found or !headers_included
 					body += line
-				else
+				elsif line =~ /: /
 					blank_line_found = true if line =~ /^\n/
+				else
+					headers_included = false
+					body += line
 				end
 			}
 			body
@@ -403,14 +428,31 @@ module RhizMail
 					substitute( token, proc )
 				end
 			}
-			body
+		end
+		
+		def initialize_from_hash( h ) # :nodoc:
+			verboten_keys = [ :body, :charset, :content_type, :subject ]
+			raise InvalidStateError unless ( h.keys & verboten_keys ).empty?
+			template_file = template_file_from_hash h
+			raise InvalidStateError if template_file.nil?
+			read_template template_file
+			if class_attributes.from_address and !h[:from_address]
+				h[:from_address] = class_attributes.from_address
+			end
+			unless h[:body_wrap].nil?
+				@body_wrap = h.delete :body_wrap
+			end
 		end
 		
 		def read_template( template_file ) # :nodoc:
 			@template = ''
 			MockFS.file.open( template_file ) { |file| @template = file.gets nil }
 			@template =~ /Subject: (.*)/
-			@subject = $1
+			@subject = ( $1 or '' )
+			if @template =~ /^From: "(.*?)" \<(.*?)\>$/m
+				self.from_name = $1
+				self.from_address = $2
+			end
 		end
 	
 		# Substitute a token with a value in the email body.
@@ -434,6 +476,14 @@ module RhizMail
 		# to make when you create a new instance. +substitutions+ should always 
 		# return a hash of tokens to either values or Procs.
 		def substitutions; {}; end
+			
+		def template_file_from_hash( h ) # :nodoc:
+			if h[:template_file]
+				h.delete :template_file
+			else
+				template_file = class_attributes.template
+			end
+		end
 		
 		# Mailer will call this before sending this message; this will fail if any
 		# tokens are left unsubstituted.

data/lib/rhizmail.rb~

@@ -40,13 +40,14 @@
 require 'contxtlservice'
 require 'mockfs'
 require 'net/smtp'
+require 'text/format'
 
 module RhizMail
-	Version = '0.1.0'
+	Version = '0.1.1'
 
 	# Returns a boolean value describing whether <tt>address</tt> is a plausible 
 	# email address format.
-	def self.valid_address(address); (address =~ /\w@\w*\./) != nil; end
+	def self.valid_address?(address); (address =~ /\w@\w*\./) != nil; end
 
 	# InvalidStateError is raised by SimpleTemplateMessage if you try to send it
 	# out without doing all the necessary template substitutions.
@@ -68,9 +69,8 @@ module RhizMail
 			@@smtpClass = smtpClass; 
 		end
 	
-		# Sends an email message. Will call +email+ needs to respond to
-		# +verify_sendable+; Mailer##send_email will call +verify_sendable+ before 
-		# sending the email.
+		# Sends an email message. +email+ needs to respond to +verify_sendable+;
+		# Mailer##send_email will call +verify_sendable+ before sending the email.
 		def send_email(email)
 			email.verify_sendable
 			msg = []
@@ -96,11 +96,26 @@ module RhizMail
 		attr_accessor :body, :charset, :content_type, :from_address, :from_name,
 		              :subject, :to_address, :to_name
 	
-		# Unless they are explicitly set using accessors, the following defaults 
-		# apply:
+		# Pass a hash to Message.new to create it:
+		#
+		#   Message.new(
+		#     :body => 'body', :subject => "subject here",
+		#     :from_address => 'from@email.com', :to_address => 'to@email.com'
+		#   )
+		#
+		# Any of the attributes listed above (under "Attributes") are valid for
+		# this hash.
+		#
+		# The older, deprecated style of instantiation is to take specific
+		# parameters:
+		#
+		#   Message.new( subject, to_address, from_address, body )
+		#
+		# Unless they are explicitly set, during creation or afterwards using
+		# accessors, the following defaults apply:
 		# [to_name] nil
 		# [from_name] nil
-		# [content_type] nil
+		# [content_type] nil (possible values for content_type are :html and :multipart)
 		# [charset] 'iso-8859-1'
 		def initialize( *args )
 			@charset = 'iso-8859-1'
@@ -216,13 +231,17 @@ module RhizMail
 	# Then you create an instance of SimpleTemplateMessage and use 
 	# SimpleTemplateMessage#substitute to change the contents:
 	#
-	#   irb> msg = RhizMail::SimpleTemplateMessage.new(
-	#     'john.doe@email.com', 'webmaster@website.com',
-	#     '/Users/francis/Desktop/template.txt'
+	#   msg = RhizMail::SimpleTemplateMessage.new(
+	#     :to_address => 'john.doe@email.com',
+	#     :from_address => 'webmaster@website.com',
+	#     :template_file => '/Users/francis/Desktop/template.txt'
 	#   )
-	#   irb> msg.substitute( 'email', 'john.doe@email.com' )
-	#   irb> msg.substitute( 'password', 'p4ssw0rd' )
-	#   irb> puts msg.body
+	#   msg.substitute( 'email', 'john.doe@email.com' )
+	#   msg.substitute( 'password', 'p4ssw0rd' )
+	#   puts msg.body
+	#
+	# Which prints this:
+	#
 	#   Hi! Thanks for joining Website.com. For your reference, here's your signup
 	#   information:
 	#
@@ -230,7 +249,40 @@ module RhizMail
 	#   Password: p4ssw0rd
 	#
 	#   Thanks!
-	#   irb> msg.deliver
+	#
+	# This is the sort of email you're likely to send out a lot, so you can
+	# encapsulate a lot of specific information when you define a subclass:
+	#
+	#   class IntroEmail < RhizMail::SimpleTemplateMessage
+	#     from_address 'webmaster@website.com'
+	#     template     '/Users/francis/Desktop/template.txt'
+	#     substitute   'email', Proc.new { |msg| msg.user.email }
+	#     substitute   'password', Proc.new { |msg| msg.user.password }
+	#     
+	#     attr_reader :user
+	#
+	#     def initialize( user )
+	#       @user = user
+	#       super( :to_address => user.email )
+	#     end
+	#   end
+	#
+	#   User = Struct.new( :email, :password )
+	#
+	#   u = User.new( 'john.doe@email.com', 'p4ssw0rd' )
+	#   email = IntroEmail.new u
+	#
+	# This accomplishes the same thing.
+	#
+	# Note that a Proc passed to SimpleTemplateMessage.substitute needs to take
+	# the message itself as a parameter; this is because the Proc belongs to the
+	# class, and doesn't know which instance to use unless it's specified. Don't 
+	# forget to use +attr_reader+ to give the Proc access to the message
+	# variables it needs.
+	#
+	# A child of SimpleTemplateMessage should call +super+ at the end of its
+	# +initialize+ method; this will automatically take care of the defined
+	# substitutions.
 	#
 	# If you call SimpleTemplateMessage#deliver without doing all the
 	# substitutions required by the template, it will raise an InvalidStateError. 
@@ -243,23 +295,68 @@ module RhizMail
 			hash[key] = SubclassAttributes.new( {} )
 		}
 		
-		def self.attributes; @@subclass_attributes[self]; end
+		def self.attributes # :nodoc:
+			@@subclass_attributes[self]
+		end
 		
+		# Sets the +from_address+ of every message of this class; use this to
+		# parameterize children of SimpleTemplateMessage.
 		def self.from_address( from_address )
 			attributes.from_address = from_address
 		end
 			
+		# Sets the +template+ for every message of this class; use this to
+		# parameterize children of SimpleTemplateMessage.
 		def self.template( template_file )
 			attributes.template = template_file
 		end
 		
+		# Adds a substitution to use on every message of this class. Use this to
+		# parameterize children of SimpleTemplateMessage, like so:
+		#
+		#   class IntroEmail < RhizMail::SimpleTemplateMessage
+		#     substitute   'email', Proc.new { |msg| msg.user.email }
+		#     substitute   'password', Proc.new { |msg| msg.user.password }
+		#     ...
+		#   end
+		#
+		# Note that a Proc passed to SimpleTemplateMessage.substitute needs to take
+		# the message itself as a parameter; this is because the Proc belongs to
+		# the class, and doesn't know which instance to use unless it's specified.
+		# Don't forget to use +attr_reader+ to give the Proc access to the message
+		# variables it needs.
 		def self.substitute( token, proc )
 			attributes.substitutions[token] = proc
 		end
 		
+		# Pass a hash to SimpleTemplateMessage.new to create it:
+		#
+		#   msg = SimpleTemplateMessage.new(
+		#     :to_address => 'john.doe@email.com',
+		#     :from_address => 'webmaster@website.com',
+		#     :template_file => '/Users/francis/Desktop/template.txt'
+		#   )
+		#
+		# :template_file is a required key. Other valid keys are :from_address,
+		# :from_name, :to_address, :to_name.
+		#
+		# Defaults for :template_file and :from_address can be set with
+		# SimpleTemplateMessage.template and SimpleTemplateMessage.from_address.
+		#
+		# By default, SimpleTemplateMessage#body wraps to 72 columns. You can
+		# change this behavior by passing :body_wrap in through the hash; pass 
+		# +false+ to turn off wrapping, any other number to set the number of
+		# columns to wrap to.
+		#
+		# An older, deprecated style of creation is to take specific parameters:
+		#
+		#   msg = SimpleTemplateMessage.new(
+		#     'john.doe@email.com', 'webmaster@website.com',
+		#     '/Users/francis/Desktop/template.txt'
+		#   )
 		def initialize( *args )
 			if args.first.is_a? Hash
-				h = args.first
+				h = args.first.clone
 				verboten_keys = [ :body, :charset, :content_type, :subject ]
 				raise InvalidStateError unless ( h.keys & verboten_keys ).empty?
 				template_file = nil
@@ -274,6 +371,9 @@ module RhizMail
 				if class_attributes.from_address and !h[:from_address]
 					h[:from_address] = class_attributes.from_address
 				end
+				unless h[:body_wrap].nil?
+					@body_wrap = h.delete :body_wrap
+				end
 				super h
 			else
 				to_address, from_address, template_file = args
@@ -282,6 +382,16 @@ module RhizMail
 			end
 			generate_body @template
 		end
+		
+		def body
+			if @body_wrap or @body_wrap.nil?
+				format = Text::Format.new
+				format.columns = @body_wrap if @body_wrap
+				format.first_indent = 0
+				@body = format.paragraphs @body
+			end
+			@body
+		end
 	
 		def body_template( template ) # :nodoc:
 			body = ''
@@ -296,7 +406,9 @@ module RhizMail
 			body
 		end
 		
-		def class_attributes; self.class.attributes; end
+		def class_attributes # :nodoc:
+			self.class.attributes
+		end
 		
 		def generate_body( template ) # :nodoc:
 			@body = body_template( template )
@@ -310,16 +422,16 @@ module RhizMail
 					substitute( token, proc )
 				end
 			}
-			body
 		end
 		
-		def read_template( template_file )
+		def read_template( template_file ) # :nodoc:
 			@template = ''
 			MockFS.file.open( template_file ) { |file| @template = file.gets nil }
 			@template =~ /Subject: (.*)/
 			@subject = $1
 		end
 	
+		# Substitute a token with a value in the email body.
 		def substitute(token, value_or_proc )
 			regexp = Regexp.new( "<%\s*#{ token }\s*%>", true )
 			@body.gsub!( regexp ){ |match|
@@ -341,6 +453,8 @@ module RhizMail
 		# return a hash of tokens to either values or Procs.
 		def substitutions; {}; end
 		
+		# Mailer will call this before sending this message; this will fail if any
+		# tokens are left unsubstituted.
 		def verify_sendable
 			super
 			if @body =~ /<%/ || @body =~ /%>/

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.6
 specification_version: 1
 name: rhizmail
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
-date: 2005-08-14
+  version: 0.1.2
+date: 2005-09-16
 summary: RhizMail is a test-friendly library for sending out customized emails.
 require_paths: 
   - lib
@@ -51,6 +51,16 @@ dependencies:
   - !ruby/object:Gem::Dependency 
     name: mockfs
     version_requirement: 
+    version_requirements: !ruby/object:Gem::Version::Requirement 
+      requirements: 
+        - 
+          - ">"
+          - !ruby/object:Gem::Version 
+            version: 0.0.0
+      version: 
+  - !ruby/object:Gem::Dependency 
+    name: text-format
+    version_requirement: 
     version_requirements: !ruby/object:Gem::Version::Requirement 
       requirements: 
         -