# class Mail::Field

Provides a single class to call to create a new structured or unstructured field. Works out per RFC what field of field it is being given and returns the correct field of class back on new.

### Per RFC 2822¶ ↑

    2.2. Header Fields

       Header fields are lines composed of a field name, followed by a colon
       (":"), followed by a field body, and terminated by CRLF.  A field
       name MUST be composed of printable US-ASCII characters (i.e.,
       characters that have values between 33 and 126, inclusive), except
       colon.  A field body may be composed of any US-ASCII characters,
       except for CR and LF.  However, a field body may contain CRLF when
       used in header "folding" and  "unfolding" as described in section
       2.2.3.  All field bodies MUST conform to the syntax described in
       sections 3 and 4 of this standard.

### Constants

FIELDS_MAP
FIELD_NAME_MAP
FIELD_ORDER
FIELD_ORDER_LOOKUP
KNOWN_FIELDS
STRUCTURED_FIELDS

### Public Class Methods

new(name, value = nil, charset = 'utf-8') click to toggle source

Accepts a string:

    Field.new("field-name: field data")

Or name, value pair:

    Field.new("field-name", "value")

Or a name by itself:

    Field.new("field-name")

Note, does not want a terminating carriage return. Returns self appropriately parsed. If value is not a string, then it will be passed through as is, for example, content-type field can accept an array with the type and a hash of parameters:

    Field.new('content-type', ['text', 'plain', {:charset => 'UTF-8'}])

    # File lib/mail/field.rb, line 114
    def initialize(name, value = nil, charset = 'utf-8')
      case
      when name.index(COLON)            # Field.new("field-name: field data")
        @charset = Utilities.blank?(value) ? charset : value
        @name = name[FIELD_PREFIX]
        @raw_value = name
        @value = nil
      when Utilities.blank?(value)   # Field.new("field-name")
        @name = name
        @value = nil
        @raw_value = nil
        @charset = charset
      else                              # Field.new("field-name", "value")
        @name = name
        @value = value
        @raw_value = nil
        @charset = charset
      end
      @name = FIELD_NAME_MAP[@name.to_s.downcase] || @name
    end

### Public Instance Methods

<=>( other ) click to toggle source

    # File lib/mail/field.rb, line 184
    def <=>( other )
      self.field_order_id <=> other.field_order_id
    end

==( other ) click to toggle source

    # File lib/mail/field.rb, line 175
    def ==( other )
      return false unless other.kind_of?(self.class)
      match_to_s(other.name, self.name) && match_to_s(other.value, self.value)
    end

field() click to toggle source

    # File lib/mail/field.rb, line 139
    def field
      _, @value = split(@raw_value) if @raw_value && !@value
      @field ||= create_field(@name, @value, @charset)
    end

field=(value) click to toggle source

    # File lib/mail/field.rb, line 135
    def field=(value)
      @field = value
    end

field_order_id() click to toggle source

    # File lib/mail/field.rb, line 188
    def field_order_id
      @field_order_id ||= (FIELD_ORDER_LOOKUP[self.name.to_s.downcase] || 100)
    end

inspect() click to toggle source

    # File lib/mail/field.rb, line 160
    def inspect
      "#<#{self.class.name} 0x#{(object_id * 2).to_s(16)} #{instance_variables.map do |ivar|
        "#{ivar}=#{instance_variable_get(ivar).inspect}"
      end.join(" ")}>"
    end

method_missing(name, *args, &block) click to toggle source

    # File lib/mail/field.rb, line 192
    def method_missing(name, *args, &block)
      field.send(name, *args, &block)
    end

name() click to toggle source

    # File lib/mail/field.rb, line 144
    def name
      @name
    end

respond_to?(method_name, include_private = false) click to toggle source
Calls superclass method

    # File lib/mail/field.rb, line 201
    def respond_to?(method_name, include_private = false)
      field.respond_to?(method_name, include_private) || super
    end

respond_to_missing?(method_name, include_private) click to toggle source
Calls superclass method

    # File lib/mail/field.rb, line 197
    def respond_to_missing?(method_name, include_private)
      field.respond_to?(method_name, include_private) || super
    end

responsible_for?( val ) click to toggle source

    # File lib/mail/field.rb, line 180
    def responsible_for?( val )
      name.to_s.casecmp(val.to_s) == 0
    end

same( other ) click to toggle source

    # File lib/mail/field.rb, line 170
    def same( other )
      return false unless other.kind_of?(self.class)
      match_to_s(other.name, self.name)
    end

to_s() click to toggle source

    # File lib/mail/field.rb, line 156
    def to_s
      field.to_s
    end

update(name, value) click to toggle source

    # File lib/mail/field.rb, line 166
    def update(name, value)
      @field = create_field(name, value, @charset)
    end

value() click to toggle source

    # File lib/mail/field.rb, line 148
    def value
      field.value
    end

value=(val) click to toggle source

    # File lib/mail/field.rb, line 152
    def value=(val)
      @field = create_field(name, val, @charset)
    end

### Private Instance Methods

create_field(name, value, charset) click to toggle source

    # File lib/mail/field.rb, line 238
    def create_field(name, value, charset)
      value = unfold(value) if value.is_a?(String)

      begin
        new_field(name, value, charset)
      rescue Mail::Field::ParseError => e
        field = Mail::UnstructuredField.new(name, value)
        field.errors << [name, value, e]
        field
      end
    end

new_field(name, value, charset) click to toggle source

    # File lib/mail/field.rb, line 250
    def new_field(name, value, charset)
      lower_case_name = name.to_s.downcase
      if field_klass = FIELDS_MAP[lower_case_name]
        field_klass.new(value, charset)
      else
        OptionalField.new(name, value, charset)
      end
    end

split(raw_field) click to toggle source

    # File lib/mail/field.rb, line 219
    def split(raw_field)
      match_data = raw_field.mb_chars.match(FIELD_SPLIT)
      [match_data[1].to_s.mb_chars.strip, match_data[2].to_s.mb_chars.strip.to_s]
    rescue
      STDERR.puts "WARNING: Could not parse (and so ignoring) '#{raw_field}'"
    end

unfold(string) click to toggle source

2.2.3. Long Header Fields

    The process of moving from this folded multiple-line representation
    of a header field to its single line representation is called
    "unfolding". Unfolding is accomplished by simply removing any CRLF
    that is immediately followed by WSP.  Each header field should be
    treated in its unfolded form for further syntactic and semantic
    evaluation.

    # File lib/mail/field.rb, line 234
    def unfold(string)
      string.gsub(/[\r\n \t]+/m, ' ')
    end