mailparser 0.5.0.beta1 → 0.5.0.beta2

data/README.md

@@ -0,0 +1,30 @@
+MailParser
+==========
+
+MailParser is a parser for mail message.
+
+Installation
+------------
+
+    % gem install --pre mailparser
+
+Usage
+-----
+
+    require 'mailparser'
+    f = File.open('hoge.eml')
+    m = MailParser::Message.new(f, :output_charset=>'utf-8')
+    m.subject  #=> String
+    m.body     #=> String
+    m.part     #=> Array of Mailparser::Message
+
+License
+-------
+
+Ruby's
+
+
+Copyright
+---------
+
+Copyright (C) 2009 TOMITA Masahiro <tommy@tmtm.org>

data/lib/mailparser.rb

@@ -15,14 +15,6 @@ require "mmapscanner"
 require "stringio"
 require "tempfile"
 
-# メールをパースする。
-#
-#   m = MailParser.new
-#   m.parse(src)
-#   m.header => #<MailParser::Header>
-#   m.body => パースされた本文文字列
-#   m.part => [#<Mailparser>, ...]
-#
 module MailParser
   include RFC2045, RFC2183, RFC2822
 
@@ -57,14 +49,14 @@ module MailParser
     "content-disposition"       => RFC2183,
   }
 
-  # 単一のヘッダ
+  # Header field
   class HeaderItem
-    # name:: ヘッダ名(String)
-    # raw:: ヘッダ値(String)
-    # opt:: オプション(Hash)
-    #  :decode_mime_header::   MIMEヘッダをデコードする
-    #  :output_charset::       デコード出力文字コード(デフォルト: UTF-8)
-    #  :strict::               RFC違反時に ParseError 例外を発生する
+    # @param [String] name header field name
+    # @param [String] raw header field value
+    # @param [Hash] opt options
+    # @option opt [Boolean] :decode_mime_header (false) decode MIME header
+    # @option opt [String] :output_charset (nil) output encoding name
+    # @option opt [Boolean] :strict (false) raise ParseError exception when message is invalid
     def initialize(name, raw, opt={})
       @name = name
       @raw = raw
@@ -72,9 +64,10 @@ module MailParser
       @opt = opt
     end
 
+    # @return [String] raw field value
     attr_reader :raw
 
-    # パースした結果オブジェクトを返す
+    # @return [header field value] parsed header object
     def parse()
       return @parsed if @parsed
       if HEADER_PARSER.key? @name then
@@ -107,8 +100,12 @@ module MailParser
     end
   end
 
-  # 同じ名前を持つヘッダの集まり
+  # Header part
   class Header
+    # @param [Hash] opt options
+    # @option opt [Boolean] :decode_mime_header decode MIME header
+    # @option opt [String] :output_charset output encoding name
+    # @option opt [Boolean] :strict raise ParseError exception when message is invalid
     def initialize(opt={})
       @hash = {}
       @parsed = {}
@@ -116,17 +113,19 @@ module MailParser
       @opt = opt
     end
 
-    # name ヘッダに body を追加する
-    # name:: ヘッダ名(String)
-    # body:: ヘッダ値(String)
+    # add header field
+    # @param [String] name header field name
+    # @param [String] body header field value
+    # @return [void]
     def add(name, body)
       name = name.downcase
       @hash[name] = [] unless @hash.key? name
       @hash[name] << HeaderItem.new(name, body, @opt)
     end
 
-    # パースした結果オブジェクトの配列を返す
-    # name:: ヘッダ名(String)
+    # header field value
+    # @param [String] name header field name
+    # @return [Array<header field value>]
     def [](name)
       return nil unless @hash.key? name
       return @parsed[name] if @parsed.key? name
@@ -134,8 +133,8 @@ module MailParser
       return @parsed[name]
     end
 
-    # 生ヘッダ値文字列の配列を返す
-    # name:: ヘッダ名(String)
+    # @param [String] name header field name
+    # @return [Array<String>] raw header value
     def raw(name)
       return nil unless @hash.key? name
       return @raw[name] if @raw.key? name
@@ -143,18 +142,22 @@ module MailParser
       return @raw[name]
     end
 
-    # ヘッダ名の配列を返す
+    # @return [Array<String>] header names
     def keys()
       return @hash.keys
     end
 
-    # ヘッダが存在するか？
+    # @param [String] name header field name
+    # @return [Boolean] true if header field exists
     def key?(name)
       return @hash.key?(name)
     end
 
-    # 各ヘッダについてブロックを繰り返す
-    # ブロック引数は、[ヘッダ名, パース結果オブジェクト,...]]
+    # repeat block for each header field
+    # @yield [key, value]
+    # @yieldparam [String] key header field name
+    # @yieldparam [header field value] value header field value
+    # @return [void]
     def each()
       @hash.each do |k, v|
         yield k, self[k]
@@ -162,17 +165,22 @@ module MailParser
     end
   end
 
-  # メール全体またはひとつのパートを表すクラス
+  # Mail message
+  # @example
+  #  require 'mailparser'
+  #  f = File.open('hoge.eml')
+  #  m = MailParser::Message.new(f, :output_charset=>'utf-8')
+  #  m.subject  #=> String
+  #  m.body     #=> String
+  #  m.part     #=> Array of Mailparser::Message
   class Message
-    # src からヘッダ部を読み込み Header オブジェクトに保持する
-    # src:: String / File / MmapScanner / read メソッドを持つオブジェクト
-    # opt:: オプション(Hash)
-    #  :extract_message_type:: message/* type を展開する
-    #  :decode_mime_header::   MIMEヘッダをデコードする
-    #  :decode_mime_filename:: ファイル名を MIME デコードする
-    #  :output_charset::       デコード出力文字コード(デフォルト: 変換しない)
-    #  :strict::               RFC違反時に ParseError 例外を発生する
-    #  :charset_converter::    文字コード変換用 Proc または Method
+    # @param [String, File, MmapScanner, #read] src source object
+    # @param [Hash] opt options
+    # @option opt [Boolean] :decode_mime_header (false) decode MIME header
+    # @option opt [Boolean] :decode_mime_filename (false) decode MIME encoded filename
+    # @option opt [Boolean] :output_charset (nil) output encoding
+    # @option opt [Boolean] :strict (false) raise ParseError exception when message is invalid
+    # @option opt [Proc, Method, #call] :charset_converter (nil) charset converter. default is MailParser::ConvCharset.conv_charset
     def initialize(src, opt={})
       if src.is_a? String
         @src = MmapScanner.new src
@@ -206,8 +214,12 @@ module MailParser
     end
 
     attr_reader :header, :part
+    # @!attribute [r] header
+    #   @return [MailParser::Header]
+    # @!attribute [r] part
+    #   @return [Array<MailParser::Message>]
 
-    # charset 変換後の本文を返す
+    # @return [String] message body decoded and converted charset
     def body
       body = body_preconv
       if type == 'text' and charset and @opt[:output_charset]
@@ -220,9 +232,8 @@ module MailParser
       body
     end
 
-    # charset 変換前の本文を返す
+    # @return [String] message body decoded and not converted charset
     def body_preconv
-      return '' if type == 'multipart' or type == 'message'
       body = @rawbody.to_s
       ret = case content_transfer_encoding
             when "quoted-printable" then RFC2045.qp_decode(body)
@@ -236,11 +247,10 @@ module MailParser
       ret
     end
 
-    # Content-Type が message の時 Message を返す。そうでなければ nil を返す。
+    # @return [MailParser::Message] body type is message/*
+    # @return [nil] when type is not message/*
     def message
-      unless @opt[:extract_message_type] and type == "message"
-        return nil
-      end
+      return nil unless type == "message"
       if ['7bit', '8bit'].include? content_transfer_encoding
         @rawbody.pos = 0
         return Message.new(@rawbody, @opt)
@@ -248,8 +258,8 @@ module MailParser
       return Message.new(body_preconv, @opt)
     end
 
-    # From ヘッダがあれば Mailbox を返す。
-    # なければ nil
+    # @return [MailParser::RFC2822::Mailbox] From field
+    # @return [nil] when From field don't exist
     def from()
       return @from if @from
       if @header.key? "from" then
@@ -260,8 +270,8 @@ module MailParser
       return @from
     end
 
-    # To ヘッダがあれば Mailbox の配列を返す
-    # なければ空配列
+    # @return [Array<MailParser::RFC2822::Mailbox>] To field
+    # @return [nil] when To field don't exist
     def to()
       return @to if @to
       if @header.key? "to" then
@@ -272,8 +282,8 @@ module MailParser
       return @to
     end
 
-    # Cc ヘッダがあれば Mailbox の配列を返す
-    # なければ空配列
+    # @return [Array<MailParser::RFC2822::Mailbox>] Cc field
+    # @return [nil] when Cc field don't exist
     def cc()
       return @cc if @cc
       if @header.key? "cc" then
@@ -284,8 +294,7 @@ module MailParser
       return @cc
     end
 
-    # Subject ヘッダがあれば文字列を返す
-    # なければ空文字
+    # @return [String] Subject field
     def subject()
       return @subject if @subject
       if @header.key? "subject" then
@@ -296,8 +305,7 @@ module MailParser
       return @subject
     end
 
-    # Content-Type の type を返す。
-    # Content-Type がない場合は "text"
+    # @return [String] Content-Type main type as lower-case
     def type()
       return @type if @type
       if @header.key? "content-type" then
@@ -308,8 +316,7 @@ module MailParser
       return @type
     end
 
-    # Content-Type の subtype を返す。
-    # Content-Type がない場合は "plain"
+    # @return [String] Content-Type sub type as lower-case
     def subtype()
       return @subtype if @subtype
       if @header.key? "content-type" then
@@ -320,8 +327,8 @@ module MailParser
       return @subtype
     end
 
-    # Content-Type の charset 属性の値(小文字)を返す。
-    # charset 属性がない場合は nil
+    # @return [String] Content-Type charset attribute as lower-case
+    # @return [nil] when charset attribute don't exist
     def charset()
       return @charset if @charset
       if @header.key? "content-type" then
@@ -333,13 +340,12 @@ module MailParser
       return @charset
     end
 
-    # マルチパートメッセージかどうかを返す
+    # @return [Boolean] true if multipart type
     def multipart?()
       return type == "multipart"
     end
 
-    # Content-Transfer-Encoding の mechanism を返す
-    # Content-Transfer-Encoding がない場合は "7bit"
+    # @return [String] Content-Transfer-Encoding mechanism. default is "7bit"
     def content_transfer_encoding()
       return @content_transfer_encoding if @content_transfer_encoding
       if @header.key? "content-transfer-encoding" then
@@ -350,10 +356,8 @@ module MailParser
       return @content_transfer_encoding
     end
 
-    # ファイル名を返す。
-    # Content-Disposition の filename パラメータ
-    # または Content-Type の name パラメータ。
-    # デフォルトは nil。
+    # @return [String] Content-Disposition filename attribute or Content-Type name attribute
+    # @return [nil] when filename attribute don't exist
     def filename()
       return @filename if @filename
       if @header.key? "content-disposition" and @header["content-disposition"][0].params.key? "filename" then
@@ -365,19 +369,23 @@ module MailParser
       return @filename
     end
 
-    # 生メッセージを返す
+    # @return [String] raw message
     def raw
       return @src.to_s
     end
 
-    # 生ヘッダを返す
+    # @return [String] raw header
     def rawheader
       @rawheader.to_s
     end
 
+    # @return [String] raw body
+    def rawbody
+      @rawbody.to_s
+    end
+
     private
 
-    # ヘッダ部をパースする
     def read_header()
       @rawheader = @src.scan_until(/^(?=\r?\n)|\z/)
       @header = Header.new(@opt)
@@ -390,11 +398,10 @@ module MailParser
           @rawheader.skip(/.*\n/) or break
         end
       end
-      @src.scan(/\r?\n/)        # 空行スキップ
+      @src.scan(/\r?\n/)        # skip delimiter line
       @rawbody = @src.rest
     end
 
-    # 各パートの Message オブジェクトの配列を作成
     def read_part()
       return if type != "multipart" or @src.eos?
       b = @header["content-type"][0].params["boundary"]
@@ -410,7 +417,6 @@ module MailParser
       end
     end
 
-    # uuencode のデコード
     def decode_uuencode(str)
       ret = ""
       str.each_line do |line|
@@ -423,7 +429,6 @@ module MailParser
       ret
     end
 
-    # str をそのまま返す
     def decode_plain(str)
       str
     end

data/lib/mailparser/loose.rb

@@ -40,10 +40,10 @@ module MailParser
     }
 
     module_function
-    # ヘッダをパースした結果のオブジェクトを返す
-    # hname:: ヘッダ名(String)
-    # hbody:: ヘッダ本文(String)
-    # opt:: オプション(Hash)
+    # @param [String] hname
+    # @param [String] hbody
+    # @param [Hash] opt options
+    # @return [header field value]
     def parse(hname, hbody, opt={})
       if HEADER_PARSER.key? hname then
         return method(HEADER_PARSER[hname]).call(hbody, opt)
@@ -57,7 +57,10 @@ module MailParser
       end
     end
 
-    # Date ヘッダをパースして、RFC2822::DateTime を返す
+    # parse Date field
+    # @param [String] str
+    # @param [Hash] opt options
+    # @return [MailParser::RFC2822::DateTime]
     def parse_date(str, opt={})
       begin
         t = Time.rfc2822(str) rescue Time.parse(str)
@@ -67,27 +70,42 @@ module MailParser
       return RFC2822::DateTime.new(t.year, t.month, t.day, t.hour, t.min, t.sec, t.zone)
     end
 
-    # From,To,Cc 等のヘッダをパースして RFC2822::Mailbox の配列を返す
+    # parse From, To,Cc field
+    # @param [String] str
+    # @param [Hash] opt options
+    # @return [Array<MailParser::RFC2822::Mailbox>]
     def parse_mailbox_list(str, opt={})
       mailbox_list(str, opt)
     end
 
-    # Sender,Resent-Sender ヘッダをパースして RFC2822::Mailbox を返す
+    # parse Sender,Resent-Sender field
+    # @param [String] str
+    # @param [Hash] opt options
+    # @return [MailParser::RFC2822::Mailbox]
     def parse_mailbox(str, opt={})
       mailbox_list(str, opt)[0]
     end
 
-    # Message-Id,Resent-Message-Id ヘッダをパースして RFC2822::MsgId を返す
+    # parse Message-Id, Resent-Message-Id field
+    # @param [String] str
+    # @param [Hash] opt options
+    # @return [MailParser::RFC2822::MsgId]
     def parse_msg_id(str, opt={})
       msg_id_list(str)[0]
     end
 
-    # In-Reply-To,References 等のヘッダを RFC2822::MsgIdList を返す
+    # parse In-Reply-To, References field
+    # @param [String] str
+    # @param [Hash] opt options
+    # @return [MailParser::RFC2822::MsgIdList]
     def parse_msg_id_list(str, opt={})
       msg_id_list(str)
     end
 
-    # Keywords ヘッダをパースして文字列の配列を返す
+    # parse Keywords field
+    # @param [String] str
+    # @param [Hash] opt options
+    # @return [Array<String>]
     def parse_phrase_list(str, opt={})
       s = split_by(Tokenizer.token(str), ",")
       s.map!{|i| i.join(" ")}
@@ -97,12 +115,18 @@ module MailParser
       s
     end
 
-    # Return-Path ヘッダをパースして RFC2822:ReturnPath を返す
+    # parse Return-Path field
+    # @param [String] str
+    # @param [Hash] opt options
+    # @return [Array<MailParser::RFC2822::ReturnPath>]
     def parse_return_path(str, opt={})
       mailbox_list(str, opt)[0]
     end
 
-    # Received ヘッダをパースして RFC2822::Received を返す
+    # parse Received field
+    # @param [String] str
+    # @param [Hash] opt options
+    # @return [MailParser::RFC2822::Received]
     def parse_received(str, opt={})
       a = split_by(Tokenizer.token_received(str), ";")
       date = a.length > 1 ? parse_date(a.last.join(" ")) : RFC2822::DateTime.now
@@ -124,7 +148,10 @@ module MailParser
       RFC2822::Received.new(name_val, date)
     end
 
-    # Content-Type ヘッダをパースして RFC2045::ContentType を返す
+    # parse Content-Type field
+    # @param [String] str
+    # @param [Hash] opt options
+    # @return [MailParser::RFC2045::ContentType]
     def parse_content_type(str, opt={})
       token = split_by(Tokenizer.token(str), ";")
       type, subtype = token.empty? ? nil : token.shift.join.split("/", 2)
@@ -140,17 +167,26 @@ module MailParser
       RFC2045::ContentType.new(type, subtype, params)
     end
 
-    # Content-Transfer-Encoding ヘッダをパースして RFC2045::ContentTransferEncoding を返す
+    # parse Content-Transfer-Encoding field
+    # @param [String] str
+    # @param [Hash] opt options
+    # @return [MailParser::RFC2045::ContentTransferEncoding]
     def parse_content_transfer_encoding(str, opt={})
       RFC2045::ContentTransferEncoding.new(Tokenizer.token(str).first.to_s)
     end
 
-    # Mime-Version ヘッダをパースして文字列を返す
+    # parse Mime-Version field
+    # @param [String] str
+    # @param [Hash] opt options
+    # @return [String]
     def parse_mime_version(str, opt={})
       Tokenizer.token(str).join
     end
 
-    # Content-Disposition ヘッダをパースして RFC2183::ContentDisposition を返す
+    # parse Content-Disposition field
+    # @param [String] str
+    # @param [Hash] opt options
+    # @return [MailParser::RFC2183::ContentDispositoin]
     def parse_content_disposition(str, opt={})
       token = split_by(Tokenizer.token(str), ";")
       type = token.empty? ? '' : token.shift.join
@@ -162,7 +198,10 @@ module MailParser
       RFC2183::ContentDisposition.new(type, params)
     end
 
-    # array を delim で分割した配列(要素は配列)を返す
+    # split arry by delim
+    # @param [Array] array
+    # @param [Object] delim
+    # @return [Array<Array>]
     def split_by(array, delim)
       ret = []
       a = []
@@ -178,7 +217,10 @@ module MailParser
       return ret
     end
 
-    # Mailbox のリストを返す
+    # parse Mailbox type field
+    # @param [String] str
+    # @param [Hash] opt options
+    # @return [Array<MailParser::RFC2822::Mailbox>]
     def mailbox_list(str, opt)
       ret = []
       split_by(Tokenizer.token(str), ",").each do |m|
@@ -198,7 +240,9 @@ module MailParser
       return ret
     end
 
-    # MsgId のリストを返す
+    # parse MsgId type field
+    # @param [String] str
+    # @return [Array<MailParser::RFC2822::MsgId>]
     def msg_id_list(str)
       ret = []
       flag = false
@@ -226,12 +270,14 @@ module MailParser
     end
 
     class Tokenizer < RFC2822::Scanner
+      # @return [String] str source string
       def initialize(str)
         @comments = []
         @ss = StringScanner.new(str)
       end
 
-      # トークンに分割(コメント部は削除)
+      # tokenize
+      # @return [Array<String>] tokens
       def token()
         token = []
         while @ss.rest? do
@@ -256,7 +302,8 @@ module MailParser
         return token
       end
 
-      # Received 用に分割
+      # tokenize for Received field
+      # @return [Array<String>] tokens
       def token_received()
         ret = []
         while @ss.rest? do

data/lib/mailparser/rfc2822/scanner.rb

@@ -68,7 +68,8 @@ class MailParser::RFC2822::Scanner
     @ss.rest
   end
 
-  # 「(」の直後からコメント部の終わりまでスキャン
+  # scan from after "(" to end of comment part
+  # @return [String] comment
   def cfws(ss)
     comments = []
     while true
@@ -81,17 +82,17 @@ class MailParser::RFC2822::Scanner
     return comments.join
   end
 
-  # コメント部の処理
-  # return: コメント部の文字列
+  # process comment part
+  # @return [String] comment part
   def cfws_sub(ss)
     ret = ""
     until ss.eos? do
       if ss.scan(/(\s*(\\[#{TEXT_RE}]|[#{CTEXT_RE}]))*\s*/o) then
         ret << ss.matched
       end
-      if ss.scan(/\)/) then      # 「)」が来たら復帰
+      if ss.scan(/\)/) then         # return when ")"
         return ret
-      elsif ss.scan(/\(/) then      # 「(」が来たら再帰
+      elsif ss.scan(/\(/) then      # recursive when "("
         c = cfws_sub(ss)
         break if c.nil?
         ret << "(" << c << ")"
@@ -99,17 +100,19 @@ class MailParser::RFC2822::Scanner
         raise MailParser::ParseError, ss.rest
       end
     end
-    # 「)」がなかったら例外
+    # error when ")" don't exist
     raise MailParser::ParseError, ss.rest
   end
 
-  # @token中の位置が s から e までの間のコメント文字列の配列を得る
+  # @param [Integer] s start index
+  # @param [Integer] e end index
   def get_comment(s, e)
     a = @token[s..e].select{|i| i =~ /^\s*\(/}.map{|i| i.strip}
     return a
   end
 
-  # @token中の object_id が s_id から e_id までの間のコメント文字列の配列を得る
+  # @param [Integer] s_id start object id
+  # @param [Integer] e_id end object id
   def get_comment_by_id(s_id, e_id)
     s = s_id ? @token_idx[s_id] : 0
     e = e_id ? @token_idx[e_id] : -1

data/test/test_mailparser.rb

@@ -604,7 +604,7 @@ EOS
     assert_equal("body2", m.part[1].body)
   end
 
-  def test_extract_message_type()
+  def test_message_type()
     msg = StringIO.new(<<EOS)
 From: from1@example.com
 Content-Type: multipart/mixed; boundary="xxxx"
@@ -623,7 +623,7 @@ Content-Type: text/plain
 body2
 --xxxx--
 EOS
-    m = MailParser::Message.new(msg, :extract_message_type=>true)
+    m = MailParser::Message.new(msg)
     assert_equal("<from1@example.com>", m.from.to_s)
     assert_equal(2, m.part.size)
     assert_equal("text", m.part[0].type)
@@ -631,9 +631,10 @@ EOS
     assert_equal("message", m.part[1].type)
     assert_equal("<from2@example.com>", m.part[1].message.from.to_s)
     assert_equal("body2", m.part[1].message.body)
+    assert_equal("From: from2@example.com\nContent-Type: text/plain\n\nbody2", m.part[1].body)
   end
 
-  def test_extract_message_type_header_only
+  def test_message_type_header_only
     msg = StringIO.new(<<EOS)
 From: from1@example.com
 Content-Type: multipart/mixed; boundary="xxxx"
@@ -650,7 +651,7 @@ From: from2@example.com
 Content-Type: text/plain
 --xxxx--
 EOS
-    m = MailParser::Message.new(msg, :extract_message_type=>true)
+    m = MailParser::Message.new(msg)
     assert_equal("<from1@example.com>", m.from.to_s)
     assert_equal(2, m.part.size)
     assert_equal("text", m.part[0].type)
@@ -710,7 +711,7 @@ hoge
 hoge
 EOS
     m = MailParser::Message.new(msg)
-    assert_equal("", m.body)
+    assert_equal("hoge\nhoge\n", m.body)
     assert_equal([], m.part)
   end
 
@@ -858,6 +859,17 @@ EOS
     assert_equal "From: from@example.com\r\nContent-Type: text/plain\r\n", m.rawheader
   end
 
+  def test_rawbody
+    msg = StringIO.new(<<EOS)
+From: from@example.com\r
+Content-Type: text/plain\r
+\r
+hogehoge\r
+EOS
+    m = MailParser::Message.new msg
+    assert_equal "hogehoge\r\n", m.rawbody
+  end
+
   def test_raw_single_part
     msg = StringIO.new(<<EOS)
 From: from@example.com

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailparser
 version: !ruby/object:Gem::Version
-  version: 0.5.0.beta1
+  version: 0.5.0.beta2
   prerelease: 6
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-17 00:00:00.000000000 Z
+date: 2012-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mmapscanner
@@ -33,7 +33,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- README.txt
+- README.md
 - lib/mailparser.rb
 - lib/mailparser/rfc2183/scanner.rb
 - lib/mailparser/rfc2183/parser.rb

data/README.txt

@@ -1,497 +0,0 @@
-= MailParser =
-
-メールメッセージを解析する。
-
-== 作者 ==
-
-とみたまさひろ <tommy@tmtm.org>
-
-== ライセンス ==
-
-Ruby ライセンス http://www.ruby-lang.org/ja/LICENSE.txt と同等。
-
-== 機能 ==
-
- * メールファイルをパースした結果を返す。
- * メール構造による例外は発生しない(例外を発生させることも可能)。
-   不正な構造のメッセージがあった場合は適当に処理する。
-
- * 0.4 でイチから作りなおしたので、0.3 とは互換がない。
-   require "mailparser/obsolete" すれば 0.3 と同じ機能が使用可能。
-
-== ダウンロード ==
-
- * http://github.com/tmtm/mailparser
-
-== インストール ==
-
-インストールには racc が必要。
-
-{{{
-$ make
-$ make test
-# make install
-}}}
-
-== 使用例 ==
-
-{{{
-require "mailparser"
-File.open("/tmp/hoge.eml") do |f|
-  m = MailParser::Message.new(f, :decode_mime_header=>true)
-  m.from                # => From ヘッダ (MailParser::RFC2822::Mailbox)
-  m.to                  # => To ヘッダ (MailParser::RFC2822::Mailbox の配列)
-  m.subject             # => Subject 文字列 (String)
-  m.body                # => 本文文字列 (String)
-  m.charset             # => 本文文字コード (String)
-  m.part                # => 添付ファイル (MailParser::Message の配列)
-  m.part[0].filename    # => １つめの添付ファイルのファイル名 (String)
-  m.part[0].body        # => １つめの添付ファイルの本文 (String)
-end
-}}}
-
-== MailParser::Message ==
-
-=== self.new(io, [opt]) ===
- 
-io から MailParser::Message オブジェクトを生成する。
-
-io には IO または StringIO オブジェクトを指定する。実際には１行毎の文
-字列を返す gets イテレータを持ち、処理した位置を覚えていて次回実
-行時に続きから実行できるオブジェクトであれば何でも良い。
-String オブジェクトも指定可能。内部で StringIO が生成されて使用される。
-
-opt は Hash オブジェクトで次の値を指定できる。
-
- :skip_body => true
-   本文をスキップする。デフォルトは false。
-
- :text_body_only => true
-   text/* type 以外の本文をスキップする。デフォルトは false。
-
- :extract_message_type => true
-   message/* type を展開する。デフォルトは false。
-
- :decode_mime_header => true
-   MIMEヘッダをデコードする。デフォルトは false。
-
- :decode_mime_filename => true
-   MIME エンコードされたファイル名をデコードする。デフォルトは false。
-   
- :output_charset => charsetname
-   出力文字コード。デフォルトは nil で無変換。
-
- :charset_converter => proc{|f,t,s| ...}
-   文字コード変換時に呼び出される Proc オブジェクト。引数は、元charset,新charset,元文字列。デフォルトは MailParser::ConvCharset.conv_charset が呼ばれる。
-
- :strict => true
-   RFC違反時に ParseError 例外を発生する。デフォルトは false。
-
- :use_file => bytes
-   raw が指定したサイズを超えたら、メモリではなくファイルを使う。nil 指定時は無制限にメモリを使う。デフォルトは nil。
-
-=== from ===
-
-From ヘッダのパース結果の最初のアドレスを MailParser::Mailbox オブジェクトで返す。
-{{{
-m = MailParser::Message.new(StringIO.new(<<EOS))
-From: TOMITA Masahiro <tommy@tmtm.org>
-EOS
-m.from.display_name   # => "TOMITA Masahiro"
-m.from.addr_spec.to_s # => "tommy@tmtm.org"
-}}}
-
-=== to ===
-
-To ヘッダのパース結果を MailParser::Mailbox オブジェクトの配列で返す。
-{{{
-m = MailParser::Message.new(StringIO.new(<<EOS))
-To: TOMITA Masahiro <tommy@tmtm.org>, foo@example.com
-EOS
-m.to[0].to_s   # => "TOMITA Masahiro <tommy@tmt.morg>"
-m.to[1].to_s   # => "<foo@example.com>"
-}}}
-
-=== cc ===
-
-Cc ヘッダのパース結果を MailParser::Mailbox オブジェクトの配列で返す。
-
-=== subject ===
-
-Subject ヘッダの値を文字列で返す。
-{{{
-m = MailParser::Message.new(StringIO.new(<<EOS), :decode_mime_header=>true, :output_charset=>"utf-8")
-Subject: =?iso-2022-jp?b?GyRCJEgkXyQ/JEckORsoQg==?=
-EOS
-m.subject    # => "とみたです"
-}}}
-
-=== type ===
-
-Content-Type ヘッダのタイプを小文字の文字列で返す。
-Content-Type がない場合は "text" を返す。
-{{{
-m = MailParser::Message.new(StringIO.new(<<EOS), :decode_mime_header=>true, :output_charset=>"utf-8")
-Content-Type: Text/Plain; charset=ISO-2022-JP
-EOS
-m.type     # => "text"
-m.subtype  # => "plain"
-m.charset  # => "iso-2022-jp"
-}}}
-
-=== subtype ===
-
-Content-Type ヘッダのサブタイプを小文字の文字列で返す。
-Content-Type がない場合またはサブタイプがない場合は "plain" を返す。
-
-=== charset ===
-
-Content-Type ヘッダの charset 属性を小文字の文字列で返す。
-Content-Type がない場合または charset がない場合は nil を返す。
-
-=== multipart? ===
-
-マルチパートメッセージの場合 true を返す。
-
-=== filename ===
-
-ファイル名を返す。
-ファイル名は、Content-Disposition ヘッダの filename 属性または Content-Type ヘッダの name 属性から取得する(Content-Disposition ヘッダが優先)。
-{{{
-m = MailParser::Message.new(StringIO.new(<<EOS))
-Content-Disposition: attachment; filename="hogehoge.txt"
-EOS
-m.filename  # => "hogehoge.txt"
-}}}
-
-{{{
-m = MailParser::Message.new(StringIO.new(<<EOS))
-Content-Disposition: attachment; filename*=utf-8''%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E5%90%8D.txt
-EOS
-m.filename # => "ファイル名.txt"
-}}}
-
-RFC的には正しくない(でも一般に使われている)ダブルクォートで括られてMIMEエンコードされた文字列を MIMEデコードしたい場合は、:decode_mime_filename=>true を指定する必要がある。
-
-{{{
-m = MailParser::Message.new(StringIO.new(<<EOS), :decode_mime_filename=>true)
-Content-Disposition: attachment; filename="=?utf-8?b?44OV44Kh44Kk44Or5ZCNLnR4dA==?="
-EOS
-m.filename # => "ファイル名"
-}}}
-
-=== header ===
-
-ヘッダを表す MailParser::Header オブジェクトを返す。
-MailParser::Header はハッシュのように使用できる。
-キーは小文字のヘッダ名文字列で、値はヘッダオブジェクトの配列(複数存在する場合があるので配列)。
-{{{
-m = MailParser::Message.new(StringIO.new(<<EOS))
-From: TOMITA Masahiro <tommy@tmtm.org>
-To: foo@example.com
-Subject: test subject
-EOS
-m.header["from"][0]      # => MailParser::Mailbox の配列
-m.header["to"][0]        # => MailParser::Mailbox の配列
-m.header["subject"][0]   # => String
-}}}
-
-ヘッダとパース結果のクラスの対応は次の通り。
-
-|| Date                      || MailParser::DateTime
-|| From                      || MailParser::Mailbox の配列
-|| Sender                    || MailParser::Mailbox
-|| Reply-To                  || MailParser::Mailbox または MailParser::Group の配列
-|| To                        || MailParser::Mailbox または MailParser::Group の配列
-|| Cc                        || MailParser::Mailbox または MailParser::Group の配列
-|| Bcc                       || MailParser::Mailbox または MailParser::Group の配列
-|| Message-Id                || MailParser::MsgId
-|| In-Reply-To               || 文字列または MailParser::MsgId の配列
-|| References                || 文字列または MailParser::MsgId の配列
-|| Keywords                  || 文字列の配列
-|| Resent-Date               || MailParser::DateTime
-|| Resent-From               || MailParser::Mailbox の配列
-|| Resent-To                 || MailParser::Mailbox または MailParser::Group の配列
-|| Resent-Cc                 || MailParser::Mailbox または MailParser::Group の配列
-|| Resent-Bcc                || MailParser::Mailbox または MailParser::Group の配列
-|| Resent-Message-Id         || MailParser::MsgId
-|| Return-Path               || MailParser::Mailbox または nil (<> の場合)
-|| Received                  || MailParser::Received
-|| Content-Type              || MailParser::ContentType
-|| Content-Transfer-Encoding || MailParser::ContentTransferEncoding
-|| Content-Id                || MailParser::MsgId
-|| Mime-Version              || 文字列
-|| Content-Disposition       || MailParser::ContentDisposition
-
-=== body ===
-
-本文文字列を返す。
-{{{
-m = MailParser::Message.new(StringIO.new(<<EOS))
-From: TOMITA Masahiro <tommy@tmtm.org>
-Content-Type: text/plain; charset=utf-8
-
-これは本文です。
-EOS
-m.body  # => "これは本文です。\n"
-}}}
-
-=== body_preconv ===
-
-本文の charset変換前文字列を返す。
-{{{
-m = MailParser::Message.new(<<EOS)
-From: TOMITA Masahiro <tommy@tmtm.org>
-Content-Type: text/plain; charset=iso-2022-jp
-
-\e$B$3$l$OK\\J8$G$9\e(B
-EOS
-m.body           # => "これは本文です\n"
-m.body_preconv   # => "\e$B$3$l$OK\\J8$G$9\e(B\n"
-}}}
-
-=== part ===
-
-マルチパートメッセージの場合、各パートを表す MailParser::Message オブジェクトの配列を返す。
-マルチパートメッセージでない場合は空配列を返す。
-{{{
-m = MailParser::Message.new(StringIO.new(<<EOS, :output_charset=>"utf8"))
-Content-Type: multipart/mixed; boundary="abcdefg"
-
---abcdefg
-Content-Type: text/plain
-
-first part.
---abcdefg
-Content-Type: text/plain
-
-second part.
---abcdefg--
-EOS
-m.part.size    # => 2
-m.part[0]      # => 最初のパートの MailParser::Message オブジェクト
-m.part[1]      # => ２番目のパートの MailParser::Message オブジェクト
-}}}
-
-=== message ===
-
-:extract_message_type=>true で message タイプのメッセージの場合、本文が示すメッセージの Mailparser::Message オブジェクトを返す。
-:extract_message_type=>false または message タイプでない場合は nil を返す。
-{{{
-m = MailParser::Message.new(StringIO.new(<<EOS), :extract_message_type=>true)
-Content-Type: message/rfc822
-
-Subject: message subject
-
-message body
-EOS
-m.message.subject  # => "message subject"
-}}}
-
-=== rawheader ===
-
-ヘッダ部文字列をパースせずにそのまま返す。
-{{{
-m = MailParser::Message.new(StringIO.new(<<EOS))
-From: TOMITA Masahiro <tommy@tmtm.org>
-To: foo@example.com
-Subject: subject
-
-body message
-EOS
-m.rawheader  # => "From: TOMITA Masahiro <tommy@tmtm.org>\nTo: foo@example.com\nSubject: subject\n"
-}}}
-
-=== raw ===
-
-生メッセージ文字列を返す。
-{{{
-m = MailParser::Message.new(StringIO.new(<<EOS))
-From: TOMITA Masahiro <tommy@tmtm.org>
-To: foo@example.com
-Subject: subject
-
-body message
-EOS
-m.rawheader  # => "From: TOMITA Masahiro <tommy@tmtm.org>\nTo: foo@example.com\nSubject: subject\n"
-}}}
-
-== MailParser::Header ==
-
-同じ名前を持つヘッダを表すクラス。
-
-=== add(name, body) ===
-name ヘッダの値として body を追加する。
-
-=== [](name) ===
-name ヘッダの値をパースした結果オブジェクトの配列を返す。
-パース結果オブジェクトは raw メソッドを持ち、パース前文字列を取り出すことができる。
-
-=== raw(name) ===
-name ヘッダの値のパース前の文字列の配列を返す。
-
-=== keys ===
-ヘッダ名文字列の一覧を返す。
-
-=== key?(name) ===
-name ヘッダがあれば真。
-
-=== each {|n,v| } ===
-各ヘッダについてブロックを繰り返す。
-ブロック引数は、１番目がヘッダ名文字列、２番目がパース結果オブジェクトの配列。
-
-== MailParser::DateTime ==
-
-Date ヘッダを表すクラス。
-
-=== year ===
-
-年を表す整数。
-
-=== month ===
-
-月を表す整数。
-
-=== day ===
-
-日を表す整数。
-
-=== hour ===
-
-時を表す整数。
-
-=== min ===
-
-分を表す整数。
-
-=== sec ===
-
-秒を表す整数。
-
-=== zone ===
-
-タイムゾーンを表す文字列。「+9999」または「-9999」の形式。
-
-=== time ===
-
-Time オブジェクトを返す。範囲外の日付の場合は :strict が false でも ArgumentError 例外が発生するので注意。
-
-== MailParser::Mailbox ==
-
-メールアドレスを表すクラス。
-
-=== addr_spec ===
-
-メールアドレスを表す MailParser::AddrSpec を返す。
-
-=== local_part ===
-
-ローカルパートを表す文字列。
-MailParser::Mailbox#addr_spec.local_part と同じ。
-
-=== domain ===
-
-ドメインを表す文字列。
-addr_spec.domain と同じ。
-
-=== display_name ===
-
-表示名を表す文字列。
-
-=== phrase ===
-
-display_name と同じ。
-
-== MailParser::Group ==
-
-グループアドレスを表すクラス。
-
-=== mailbox_list ===
-
-MailParser::Mailbox の配列。
-
-=== display_name ===
-
-表示名を表す文字列。
-
-=== phrase ===
-
-display_name と同じ。
-
-== MailParser::MsgId ==
-
-=== msg_id ===
-
-メッセージID文字列。先頭と末尾の < > は含まない。
-
-== MailParser::Received ==
-
-Received ヘッダを表すクラス。
-
-=== name_val ===
-
-Received ヘッダ中の名前(小文字の文字列)と値(文字列)の組を表す Hash を返す。
-{{{
-m = MailParser::Message.new(StringIO.new(<<EOS))
-Received: from mx1.tmtm.org (localhost [127.0.0.1])
-        by mx2.tmtm.org (Postfix) with ESMTP id 3ED69108383
-        for <tommy@tmtm.org>; Tue, 16 Jan 2007 14:20:23 +0900 (JST)
-EOS
-r = m.header["received"][0]
-r.name_val["from"]    # => "mx1.tmtm.org"
-r.name_val["by"]      # => "mx2.tmtm.org"
-r.name_val["with"]    # => "ESMTP"
-r.name_val["for"]     # => "tommy@tmtm.org"
-}}}
-
-=== date_time ===
-
-Received ヘッダ中の日時を表す MailParser::DateTime オブジェクトを返す。
-
-== MailParser::ContentType ==
-
-Content-Type ヘッダのパラメータを表すクラス。
-
-=== type ===
-
-Content-Type ヘッダのタイプを表す小文字の文字列を返す。
-
-=== subtype ===
-
-Content-Type ヘッダのサブタイプを表す小文字の文字列を返す。
-
-=== params ===
-
-Content-Type ヘッダのパラメータを表す Hash を返す。
-Hash のキーは小文字の文字列。値は文字列。
-
-== MailParser::ContentTransferEncoding ==
-
-Content-Transfer-Encoding ヘッダを表すクラス。
-
-=== mechanism ===
-
-Content-Transfer-Encoding ヘッダの値を小文字の文字列で返す。
-
-== MailParser::ContentDisposition ==
-
-=== type ===
-
-Content-Disposition ヘッダのタイプを表す小文字の文字列を返す。
-
-=== params ===
-
-Content-Disposition ヘッダのパラメータを表す Hash を返す。
-Hash のキーは小文字の文字列。値は文字列。
-
-== MailParser::AddrSpec ==
-
-メールアドレスを表すクラス。
-
-=== local_part ===
-
-メールアドレスのローカルパート文字列を返す。
-
-=== domain ===
-
-メールアドレスのドメイン部文字列を返す。