Module: Net::HTTPHeader

Defined in:
lib/net/http.rb

Overview

Header module.

Provides access to @header in the mixed-into class as a hash-like object, except with case-insensitive keys. Also provides methods for accessing commonly-used header values in a more convenient format.

Instance Method Summary (collapse)

Instance Method Details

- (Object) [](key)

Returns the header field corresponding to the case-insensitive key. For example, a key of "Content-Type" might return "text/html"



1310
1311
1312
1313
 
# File 'lib/net/http.rb', line 1310

def [](key)
  a = @header[key.downcase] or return nil
  a.join(', ')
end

- (Object) []=(key, val)

Sets the header field corresponding to the case-insensitive key.



1316
1317
1318
1319
1320
1321
1322
 
# File 'lib/net/http.rb', line 1316

def []=(key, val)
  unless val
    @header.delete key.downcase
    return val
  end
  @header[key.downcase] = [val]
end

- (Object) add_field(key, val)

Ruby 1.8.3

Adds header field instead of replace. Second argument val must be a String. See also #[]=, #[] and #get_fields.

request.add_field 'X-My-Header', 'a'
p request['X-My-Header']              #=> "a"
p request.get_fields('X-My-Header')   #=> ["a"]
request.add_field 'X-My-Header', 'b'
p request['X-My-Header']              #=> "a, b"
p request.get_fields('X-My-Header')   #=> ["a", "b"]
request.add_field 'X-My-Header', 'c'
p request['X-My-Header']              #=> "a, b, c"
p request.get_fields('X-My-Header')   #=> ["a", "b", "c"]


1339
1340
1341
1342
1343
1344
1345
 
# File 'lib/net/http.rb', line 1339

def add_field(key, val)
  if @header.key?(key.downcase)
    @header[key.downcase].push val
  else
    @header[key.downcase] = [val]
  end
end

- (Object) basic_auth(account, password)

Set the Authorization: header for "Basic" authorization.



1612
1613
1614
 
# File 'lib/net/http.rb', line 1612

def basic_auth(, password)
  @header['authorization'] = [basic_encode(, password)]
end

- (Boolean) chunked?

Returns "true" if the "transfer-encoding" header is present and set to "chunked". This is an HTTP/1.1 feature, allowing the the content to be sent in "chunks" without at the outset stating the entire content length.

Returns:

  • (Boolean) 


1512
1513
1514
1515
1516
 
# File 'lib/net/http.rb', line 1512

def chunked?
  return false unless @header['transfer-encoding']
  field = self['Transfer-Encoding']
  (/(?:\A|[^\-\w])chunked(?![\-\w])/i =~ field) ? true : false
end

- (Boolean) connection_close?

Returns:

  • (Boolean) 


1626
1627
1628
1629
 
# File 'lib/net/http.rb', line 1626

def connection_close?
  tokens(@header['connection']).include?('close') or
  tokens(@header['proxy-connection']).include?('close')
end

- (Boolean) connection_keep_alive?

Returns:

  • (Boolean) 


1631
1632
1633
1634
 
# File 'lib/net/http.rb', line 1631

def connection_keep_alive?
  tokens(@header['connection']).include?('keep-alive') or
  tokens(@header['proxy-connection']).include?('keep-alive')
end

- (Object) content_length

Returns an Integer object which represents the Content-Length: header field or nil if that field is not provided.



1493
1494
1495
1496
1497
1498
 
# File 'lib/net/http.rb', line 1493

def content_length
  return nil unless key?('Content-Length')
  len = self['Content-Length'].slice(/\d+/) or
      raise HTTPHeaderSyntaxError, 'wrong Content-Length format'
  len.to_i
end

- (Object) content_length=(len) 



1500
1501
1502
1503
1504
1505
1506
 
# File 'lib/net/http.rb', line 1500

def content_length=(len)
  unless len
    @header.delete 'content-length'
    return nil
  end
  @header['content-length'] = [len.to_i.to_s]
end

- (Object) content_range

Returns a Range object which represents Content-Range: header field. This indicates, for a partial entity body, where this fragment fits inside the full entity body, as range of byte offsets.



1521
1522
1523
1524
1525
1526
 
# File 'lib/net/http.rb', line 1521

def content_range
  return nil unless @header['content-range']
  m = %r<bytes\s+(\d+)-(\d+)/(\d+|\*)>i.match(self['Content-Range']) or
      raise HTTPHeaderSyntaxError, 'wrong Content-Range format'
  m[1].to_i .. m[2].to_i
end

- (Object) content_type

Returns a content type string such as "text/html". This method returns nil if Content-Type: header field does not exist.



1536
1537
1538
1539
1540
1541
1542
 
# File 'lib/net/http.rb', line 1536

def content_type
  return nil unless main_type()
  if sub_type()
  then "#{main_type()}/#{sub_type()}"
  else main_type()
  end
end

- (Object) delete(key)

Removes a header field.



1407
1408
1409
 
# File 'lib/net/http.rb', line 1407

def delete(key)
  @header.delete(key.downcase)
end

- (Object) each_capitalized Also known as: canonical_each

As for #each_header, except the keys are provided in capitalized form.



1422
1423
1424
1425
1426
1427
 
# File 'lib/net/http.rb', line 1422

def each_capitalized
  block_given? or return enum_for(__method__)
  @header.each do |k,v|
    yield capitalize(k), v.join(', ')
  end
end

- (Object) each_capitalized_name

Iterates for each capitalized header names.



1391
1392
1393
1394
1395
1396
 
# File 'lib/net/http.rb', line 1391

def each_capitalized_name  #:yield: +key+
  block_given? or return enum_for(__method__)
  @header.each_key do |k|
    yield capitalize(k)
  end
end

- (Object) each_header Also known as: each

Iterates for each header names and values.



1373
1374
1375
1376
1377
1378
 
# File 'lib/net/http.rb', line 1373

def each_header   #:yield: +key+, +value+
  block_given? or return enum_for(__method__)
  @header.each do |k,va|
    yield k, va.join(', ')
  end
end

- (Object) each_name(&block) Also known as: each_key

Iterates for each header names.



1383
1384
1385
1386
 
# File 'lib/net/http.rb', line 1383

def each_name(&block)   #:yield: +key+
  block_given? or return enum_for(__method__)
  @header.each_key(&block)
end

- (Object) each_value

Iterates for each header values.



1399
1400
1401
1402
1403
1404
 
# File 'lib/net/http.rb', line 1399

def each_value   #:yield: +value+
  block_given? or return enum_for(__method__)
  @header.each_value do |va|
    yield va.join(', ')
  end
end

- (Object) fetch(key, *args, &block)

Returns the header field corresponding to the case-insensitive key. Returns the default value args, or the result of the block, or raises an IndexErrror if there's no header field named key See Hash#fetch



1367
1368
1369
1370
 
# File 'lib/net/http.rb', line 1367

def fetch(key, *args, &block)   #:yield: +key+
  a = @header.fetch(key.downcase, *args, &block)
  a.kind_of?(Array) ? a.join(', ') : a
end

- (Object) get_fields(key)

Ruby 1.8.3

Returns an array of header field strings corresponding to the case-insensitive key. This method allows you to get duplicated header fields without any processing. See also #[].

p response.get_fields('Set-Cookie')
  #=> ["session=al98axx; expires=Fri, 31-Dec-1999 23:58:23",
       "query=rubyscript; expires=Fri, 31-Dec-1999 23:58:23"]
p response['Set-Cookie']
  #=> "session=al98axx; expires=Fri, 31-Dec-1999 23:58:23, query=rubyscript; expires=Fri, 31-Dec-1999 23:58:23"


1358
1359
1360
1361
 
# File 'lib/net/http.rb', line 1358

def get_fields(key)
  return nil unless @header[key.downcase]
  @header[key.downcase].dup
end

- (Object) initialize_http_header(initheader) 



1293
1294
1295
1296
1297
1298
1299
1300
 
# File 'lib/net/http.rb', line 1293

def initialize_http_header(initheader)
  @header = {}
  return unless initheader
  initheader.each do |key, value|
    warn "net/http: warning: duplicated HTTP header: #{key}" if key?(key) and $VERBOSE
    @header[key.downcase] = [value.strip]
  end
end

- (Boolean) key?(key)

true if key header exists.

Returns:

  • (Boolean) 


1412
1413
1414
 
# File 'lib/net/http.rb', line 1412

def key?(key)
  @header.key?(key.downcase)
end

- (Object) main_type

Returns a content type string such as "text". This method returns nil if Content-Type: header field does not exist.



1546
1547
1548
1549
 
# File 'lib/net/http.rb', line 1546

def main_type
  return nil unless @header['content-type']
  self['Content-Type'].split(';').first.to_s.split('/')[0].to_s.strip
end

- (Object) proxy_basic_auth(account, password)

Set Proxy-Authorization: header for "Basic" authorization.



1617
1618
1619
 
# File 'lib/net/http.rb', line 1617

def proxy_basic_auth(, password)
  @header['proxy-authorization'] = [basic_encode(, password)]
end

- (Object) range

Returns an Array of Range objects which represents Range: header field, or nil if there is no such header.



1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
 
# File 'lib/net/http.rb', line 1438

def range
  return nil unless @header['range']
  self['Range'].split(/,/).map {|spec|
    m = /bytes\s*=\s*(\d+)?\s*-\s*(\d+)?/i.match(spec) or
            raise HTTPHeaderSyntaxError, "wrong Range: #{spec}"
    d1 = m[1].to_i
    d2 = m[2].to_i
    if    m[1] and m[2] then  d1..d2
    elsif m[1]          then  d1..-1
    elsif          m[2] then -d2..-1
    else
      raise HTTPHeaderSyntaxError, 'range is not specified'
    end
  }
end

- (Object) range_length

The length of the range represented in Content-Range: header.



1529
1530
1531
1532
 
# File 'lib/net/http.rb', line 1529

def range_length
  r = content_range() or return nil
  r.end - r.begin + 1
end

- (Object) set_content_type(type, params = {}) Also known as: content_type=

Set Content-Type: header field by type and params. type must be a String, params must be a Hash.



1576
1577
1578
 
# File 'lib/net/http.rb', line 1576

def set_content_type(type, params = {})
  @header['content-type'] = [type + params.map{|k,v|"; #{k}=#{v}"}.join('')]
end

- (Object) set_form_data(params, sep = '&') Also known as: form_data=

Set header fields and a body from HTML form data. params should be a Hash containing HTML form data. Optional argument sep means data record separator.

This method also set Content-Type: header field to application/x-www-form-urlencoded.

Example:

http.form_data = {"q" => "ruby", "lang" => "en"}
http.form_data = {"q" => ["ruby", "perl"], "lang" => "en"}
http.set_form_data({"q" => "ruby", "lang" => "en"}, ';')


1594
1595
1596
1597
 
# File 'lib/net/http.rb', line 1594

def set_form_data(params, sep = '&')
  self.body = params.map {|k, v| encode_kvpair(k, v) }.flatten.join(sep)
  self.content_type = 'application/x-www-form-urlencoded'
end

- (Object) set_range(r, e = nil) Also known as: range=

Set Range: header from Range (arg r) or beginning index and length from it (arg idx&len).

req.range = (0..1023)
req.set_range 0, 1023


1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
 
# File 'lib/net/http.rb', line 1460

def set_range(r, e = nil)
  unless r
    @header.delete 'range'
    return r
  end
  r = (r...r+e) if e
  case r
  when Numeric
    n = r.to_i
    rangestr = (n > 0 ? "0-#{n-1}" : "-#{-n}")
  when Range
    first = r.first
    last = r.last
    last -= 1 if r.exclude_end?
    if last == -1
      rangestr = (first > 0 ? "#{first}-" : "-#{-first}")
    else
      raise HTTPHeaderSyntaxError, 'range.first is negative' if first < 0
      raise HTTPHeaderSyntaxError, 'range.last is negative' if last < 0
      raise HTTPHeaderSyntaxError, 'must be .first < .last' if first > last
      rangestr = "#{first}-#{last}"
    end
  else
    raise TypeError, 'Range/Integer is required'
  end
  @header['range'] = ["bytes=#{rangestr}"]
  r
end

- (Object) size Also known as: length

:nodoc: obsolete



1302
1303
1304
 
# File 'lib/net/http.rb', line 1302

def size   #:nodoc: obsolete
  @header.size
end

- (Object) sub_type

Returns a content type string such as "html". This method returns nil if Content-Type: header field does not exist or sub-type is not given (e.g. "Content-Type: text").



1554
1555
1556
1557
1558
1559
 
# File 'lib/net/http.rb', line 1554

def sub_type
  return nil unless @header['content-type']
  main, sub = *self['Content-Type'].split(';').first.to_s.split('/')
  return nil unless sub
  sub.strip
end

- (Object) to_hash

Returns a Hash consist of header names and values.



1417
1418
1419
 
# File 'lib/net/http.rb', line 1417

def to_hash
  @header.dup
end

- (Object) type_params

Returns content type parameters as a Hash as like => "iso-2022-jp".



1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
 
# File 'lib/net/http.rb', line 1563

def type_params
  result = {}
  list = self['Content-Type'].to_s.split(';')
  list.shift
  list.each do |param|
    k, v = *param.split('=', 2)
    result[k.strip] = v.strip
  end
  result
end