email_address_validator 0.0.1

data/.gitignore

@@ -0,0 +1,3 @@
+*.swp
+pkg/*
+*.rbc

data/LICENSE

@@ -0,0 +1 @@
+

data/README.md

@@ -0,0 +1,87 @@
+# EmailAddressValidator #
+
+Implementation of RFCs 2822 and 822 for email address validation, and 1123 for domain validation.
+
+## Description ##
+
+Parsing email addresses is not easy, and most regex based approaches deviate from the RFCs. This library is based off the actual grammars in the RFCs, allowing it to achieve greater accuracy.
+
+This may mean that this library is more permissive than you desire, as the RFCs support syntax that many will find undesirable. To accomodate this, there are a few options users can set to achieve more practical results.
+
+The two man things to know are that:
+
+1. What most people desire from a validator is to match only the addr_spec portion of the grammars, as this keeps certain weird addresses, such as RFC groups excluded.
+2. RFCs 822/2822 do not require valid domains, essentially requiring little more than dotted strings. This library provides additional RFC-1123 Parsing to ensure that a valid domain has been passed in.
+
+## Examples ##
+
+Validate only the addr_spec portion of an address as per RFC-2822. Additionally, validate the domain of the address as per RFC-1123. This is what most people probably want:
+
+    EmailAddressValidator.validate_addr('example@example.net',true)
+
+Validate against the full grammar for RFC-2822, without checking the domain.
+
+    EmailAddressValidator.validate('example@example.net', false)
+
+Validate against the addr_spec portion of RFC-822
+
+    EmailAddressValidator.validate_822_addr('example@example.net')
+
+Validate against the full grammar for RFC-822
+
+    EmailAddressValidator.validate_822('example@example.net')
+
+Validate a domain per RFC-1123
+    
+    EmailAddressValidator.validate_domain('example.net')
+
+## Additional notes on the RFCs ##
+
+RFC 2822 removes a lot of the cruft that 822 carries with it, unless you have a good reason, you likely want to stay away from RFC 822.
+
+A few fun things came up researching this library: 
+
+* RFCs 2822/822 do not validate domains properly.
+* RFCs 2822/822 support groups, multiple labeled lists of addresses such as `MyGroup: "John Higgins" <john@example.net>, mark mark@example.net;`
+* RFC 822 supports routes, a sequence of mailservers the message is supposed to travel, such as `test@mymailserver@othermailserver.com`
+* RFCs 2822/822 support double quoted strings as the local part of an address, with crazy chars in them, such as `"my@funky$address"@example.net`
+* RFCs 2822/822 support phrases before angle bracketed addresses so the entirety of the string `"Test" <test@example.net>` is valid. This is why you probably only want to validate the addr_spec portion.
+
+## Further Reading ##
+
+[RFC-2822](http://www.ietf.org/rfc/rfc2822.txt)
+ 
+[RFC-822](http://www.ietf.org/rfc/rfc0822.txt)
+ 
+[RFC-1123](http://www.ietf.org/rfc/rfc1123.txt)
+
+## Authors ##
+
+Evan Phoenix / [evanphx](http://github.com/evanphx)
+
+Andrew Cholakian / [andrewvc](http://github.com/andrewvc)
+
+## License ##
+ 
+(The MIT License) FIXME (different license?)
+
+Copyright (c) 2011 FIXME (author's name)
+
+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/Rakefile

@@ -0,0 +1,15 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake/rdoctask'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) 
+task :default => :spec
+
+desc "Rebuild the parsers"
+task "parser" do
+  sh "kpeg -s -o lib/email_address_validator/rfc822-parser.rb  -f grammars/rfc822.kpeg"
+  sh "kpeg -s -o lib/email_address_validator/rfc2822-parser.rb -f grammars/rfc2822.kpeg"
+  sh "kpeg -s -o lib/email_address_validator/domain-parser.rb  -f grammars/domain.kpeg"
+end

data/email_address_validator.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "email_address_validator/version"
+
+Gem::Specification.new do |s|
+  s.name        = "email_address_validator"
+  s.version     = EmailAddressValidator::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Evan Phoenix", "Andrew Cholakian"]
+  s.email       = ["andrew@andrewvc.com"]
+  s.homepage    = "https://github.com/andrewvc/rfc-822"
+  s.summary     = %q{RFC 2822/822 Email Address Parsing.}
+  s.description = %q{RFC Compliant Email Address Parsing using the KPEG grammars.}
+  s.extra_rdoc_files = [
+    "LICENSE",
+    "README.md"
+  ]
+
+  s.rubyforge_project = "email_address_validator"
+
+  s.add_development_dependency "rspec", ">= 2.4.0"
+  s.add_development_dependency "kpeg",  ">= 0.7.0"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end
+

data/grammars/domain.kpeg

@@ -0,0 +1,28 @@
+%% name = EmailAddressValidator::DomainParser
+
+domain = < subdomain > &{ text.size < 255 }
+
+subdomain = subdomain "." label
+          | label
+
+# See http://tools.ietf.org/html/rfc1123#section-2.1.
+# It allows for a digit to start a label.
+
+label = let-dig < let-dig-hyp* >
+          &{ text.size < 63 && (text.size == 0 || text[-1] != ?-) }
+
+let-dig-hyp = let-dig | "-"
+
+let-dig = letter | digit
+
+# <letter> ::= any one of the 52 alphabetic characters A through Z in
+#              upper case and a through z in lower case
+
+letter = /[A-Za-z]/
+
+# <digit> ::= any one of the ten digits 0 through 9
+
+digit = /[0-9]/
+
+root = domain !.
+

data/grammars/rfc2822.kpeg

@@ -0,0 +1,152 @@
+%% name = EmailAddressValidator::RFC2822Parser
+
+%% { attr_accessor :validate_domain }
+
+d(num) = <.> &{ text[0] == num }
+d_btw(start,fin) = <.> &{ t = text[0]; t >= start && t <= fin }
+
+WSP = " " | d(9)
+
+LF   = /\x0A/
+CR   = /\x0D/
+
+CRLF = CR LF
+
+ALPHA = /[A-Za-z]/
+
+DIGIT = /[0-9]/
+
+NO-WS-CTL = d_btw(1,8)
+          | d(11)
+          | d(12)
+          | d_btw(14,31)
+          | d(127)
+
+text = d_btw(1,9)
+     | d(11)
+     | d(12)
+     | d_btw(14,127)
+     | obs-text
+
+quoted-pair = "\\" text
+            | obs-qp
+
+FWS = (WSP* CRLF)? WSP+
+    | obs-FWS
+
+ctext = NO-WS-CTL
+      | d_btw(33,39)
+      | d_btw(42,91)
+      | d_btw(93,126)
+
+ccontent = ctext | quoted-pair | comment
+
+comment = "(" (FWS? ccontent)* FWS? ")"
+
+CFWS = (FWS? comment)* ((FWS? comment) | FWS)
+
+atext = ALPHA | DIGIT
+      | "!" | "#"
+      | "$" | "%"
+      | "&" | "'"
+      | "*" | "+"
+      | "-" | "/"
+      | "=" | "?"
+      | "^" | "_"
+      | "`" | "{"
+      | "|" | "}"
+      | "~"
+
+atom = CFWS? atext+ CFWS?
+
+dot-atom = CFWS? dot-atom-text CFWS?
+
+dot-atom-text = atext+ ("." atext+)*
+
+qtext = NO-WS-CTL
+      | d(33)
+      | d_btw(35,91)
+      | d_btw(93,126)
+
+qcontent = qtext | quoted-pair
+
+quoted-string = CFWS? "\"" (FWS? qcontent)* FWS? "\"" CFWS?
+
+word = atom | quoted-string
+
+phrase = word+ | obs-phrase
+
+utext = NO-WS-CTL
+      | d_btw(33,126)
+      | obs-utext
+
+unstructured = (FWS? utext)* FWS?
+
+address = mailbox | group
+
+mailbox = name-addr | addr-spec
+
+name-addr = display-name? angle-addr
+
+angle-addr = CFWS? "<" addr-spec ">" CFWS?
+           | obs-angle-addr
+
+group = display-name ":" (mailbox-list | CFWS)? ";" CFWS?
+
+display-name = phrase
+
+mailbox-list = mailbox ("," mailbox)*
+             | obs-mbox-list
+
+address-list = address ("," address)*
+             | obs-addr-list
+
+addr-spec = local-part "@" domain
+
+local-part = dot-atom | quoted-string | obs-local-part
+
+domain = < dot-atom >
+            &{ @validate_domain ? EmailAddressValidator::DomainParser.new(text).parse : true }
+       | domain-literal
+       | < obs-domain >
+            &{ @validate_domain ? EmailAddressValidator::DomainParser.new(text).parse : true }
+
+domain-literal = CFWS? "[" (FWS? dcontent)* FWS? "]" CFWS?
+
+dcontent = dtext | quoted-pair
+
+dtext = NO-WS-CTL
+      | d_btw(33,90)
+      | d_btw(94,126)
+
+obs-qp = "\\" d_btw(0,127)
+
+obs-text = LF* CR* (obs-char LF* CR*)*
+
+obs-char = d_btw(0,9) | d(11)
+         | d(12) | d_btw(14,127)
+
+obs-utext = obs-text
+
+obs-phrase = word (word | "." | CFWS)*
+
+obs-phrase-list = phrase
+                | (phrase? CFWS? "," CFWS?)+ phrase?
+
+obs-FWS = WSP+ (CRLF WSP+)*
+
+obs-angle-addr = CFWS? "<" obs-route? addr-spec ">" CFWS?
+
+obs-route = CFWS? obs-domain-list ":" CFWS?
+
+obs-domain-list = "@" domain ((CFWS | ",")* CFWS? "@" domain)*
+
+obs-local-part = word ("." word)*
+
+obs-domain = atom ("." atom)*
+
+obs-mbox-list = (address? CFWS? "," CFWS?)+ address?
+
+root = address !.
+
+only_addr_spec = addr-spec !.

data/grammars/rfc822.kpeg

@@ -0,0 +1,76 @@
+%% name = EmailAddressValidator::RFC822Parser
+
+%% { attr_accessor :validate_domain }
+
+HTAB = /\x09/
+LF   = /\x0A/
+CR   = /\x0D/
+SPACE = " "
+- = SPACE*
+AT    = "@"
+
+LWSP_char = SPACE | HTAB
+CHAR = /[\x00-\x7f]/
+CTL  = /[\x00-\x1f\x7f]/
+
+special = /[\]()<>@,;:\\".\[]/
+
+CRLF = CR LF
+
+linear_white_space = (CRLF? LWSP_char)+
+
+atom = /[^\]\x00-\x20 \x7F\x80-\xFF()<>@,;:\\".\[]+/
+
+ctext = /[^)\\\x0D\x80-\xFF(]+/
+      | linear_white_space
+
+
+dtext = /[^\]\\\x0D\x80-\xFF\[]+/
+      | linear_white_space
+
+qtext = /[^"\\\x0D\x80-\xFF]+/
+      | linear_white_space
+
+
+quoted_pair = "\\" CHAR
+
+quoted_string = "\"" (qtext | quoted_pair)* "\""
+
+domain_literal = "[" (dtext | quoted_pair)* "]"
+
+comment = "(" (ctext | quoted_pair | comment)* ")"
+
+ocms = comment*
+
+word = atom | quoted_string
+
+phrase = (word -)+
+
+valid = ocms address ocms
+
+address = mailbox | group
+
+group = phrase ocms ":" ocms mailbox (ocms "," ocms mailbox)* ocms ";"
+
+mailbox = addr_spec
+        | phrase - ocms - angle_addr
+
+angle_addr = "<" ocms route? ocms addr_spec ">"
+
+route = (AT ocms domain)+ ":"
+
+addr_spec = local_part ocms "@" ocms domain
+
+local_part = word ocms ("." ocms word)*
+
+domain = domain_literal
+       | < sub_domain ocms ("." ocms sub_domain)* >
+           &{ @validate_domain ? EmailAddressValidator::DomainParser.new(text).parse : true }
+
+sub_domain = domain_ref | domain_literal
+
+domain_ref = atom
+
+root = valid !.
+
+only_addr_spec = addr_spec !.

data/lib/email_address_validator.rb

@@ -0,0 +1,103 @@
+module EmailAddressValidator
+  # :stopdoc:
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  VERSION = ::File.read(PATH + 'version.txt').strip
+  # :startdoc:
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    rv =  args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+    if block_given?
+      begin
+        $LOAD_PATH.unshift LIBPATH
+        rv = yield
+      ensure
+        $LOAD_PATH.shift
+      end
+    end
+    return rv
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    rv = args.empty? ? PATH : ::File.join(PATH, args.flatten)
+    if block_given?
+      begin
+        $LOAD_PATH.unshift PATH
+        rv = yield
+      ensure
+        $LOAD_PATH.shift
+      end
+    end
+    return rv
+  end
+
+  # Utility method used to require all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+  
+  # Shorthand for +EmailAddressParser.validate_2822_addr
+  def self.validate_addr(addr, validate_domain=false); self.validate_2822; end
+
+  # Validates +addr+ against the addr_spec portion of RFC 2822.
+  # This is what most people actually want out of an email validator
+  # You very well may want to set validate_domain to true as well,
+  # as RFC2822 doesn't explicitly require valid domains
+  def self.validate_2822_addr(addr, validate_domain=false)
+    parser = RFC2822Parser.new(addr, "only_addr_spec")
+    parser.validate_domain = validate_domain
+    parser.parse
+  end
+
+  # Shorthand for +EmailAddressParser.validate_2822
+  def self.validate(addr, validate_domain=false); self.validate_2822; end
+
+  # Validates an email address according to RFC 2822
+  # This validates addresses against the full spec, which
+  # may not be what you want. 
+  def self.validate_2822(addr, validate_domain=false)
+    parser = RFC2822Parser.new(addr)
+    parser.validate_domain = validate_domain
+    parser.parse
+  end
+
+  # Validates legacy address according to RFC 822, the original
+  # email grammar.
+  def self.validate_822(addr, validate_domain=false)
+    parser = RFC822Parser.new(addr)
+    parser.validate_domain = validate_domain
+    parser.parse
+  end
+
+  # Validates only the addr_spec portion an address according to RFC 822
+  def self.validate_822_addr(addr, validate_domain=false)
+    parser = RFC822Parser.new(addr, "only_addr_spec")
+    parser.validate_domain = validate_domain
+    parser.parse
+  end
+
+  # Validates a domain name
+  def self.validate_domain(domain)
+    parser = DomainParser.new(addr)
+    parser.parse
+  end
+
+end
+
+EmailAddressValidator.require_all_libs_relative_to(__FILE__)