Method: Gem::Net::HTTPHeader#set_form

Defined in:

lib/rubygems/net-http/lib/net/http/header.rb

#set_form(params, enctype = 'application/x-www-form-urlencoded', formopt = {}) ⇒ Object

Stores form data to be used in a POST or PUT request.

The form data given in params consists of zero or more fields; each field is:

• A scalar value.

• A name/value pair.

• An IO stream opened for reading.

Argument params should be an Enumerable (method params.map will be called), and is often an array or hash.

First, we set up a request:

_uri = uri.dup
_uri.path ='/posts'
req = Gem::Net::HTTP::Post.new(_uri)

Argument params As an Array

When params is an array, each of its elements is a subarray that defines a field; the subarray may contain:

• One string:

  req.set_form([['foo'], ['bar'], ['baz']])
  

• Two strings:

  req.set_form([%w[foo 0], %w[bar 1], %w[baz 2]])
  

• When argument enctype (see below) is given as 'multipart/form-data':

  • A string name and an IO stream opened for reading:

    require 'stringio'
    req.set_form([['file', StringIO.new('Ruby is cool.')]])
    

  • A string name, an IO stream opened for reading, and an options hash, which may contain these entries:

    • :filename: The name of the file to use.

    • :content_type: The content type of the uploaded file.

    Example:

    req.set_form([['file', file, {filename: "other-filename.foo"}]]
    

The various forms may be mixed:

req.set_form(['foo', %w[bar 1], ['file', file]])

Argument params As a Hash

When params is a hash, each of its entries is a name/value pair that defines a field:

• The name is a string.

• The value may be:

  • nil.

  • Another string.

  • An IO stream opened for reading (only when argument enctype – see below – is given as 'multipart/form-data').

Examples:

# Nil-valued fields.
req.set_form({'foo' => nil, 'bar' => nil, 'baz' => nil})

# String-valued fields.
req.set_form({'foo' => 0, 'bar' => 1, 'baz' => 2})

# IO-valued field.
require 'stringio'
req.set_form({'file' => StringIO.new('Ruby is cool.')})

# Mixture of fields.
req.set_form({'foo' => nil, 'bar' => 1, 'file' => file})

Optional argument enctype specifies the value to be given to field 'Content-Type', and must be one of:

• 'application/x-www-form-urlencoded' (the default).

• 'multipart/form-data'; see RFC 7578.

Optional argument formopt is a hash of options (applicable only when argument enctype is 'multipart/form-data') that may include the following entries:

• :boundary: The value is the boundary string for the multipart message. If not given, the boundary is a random string. See Boundary.

• :charset: Value is the character set for the form submission. Field names and values of non-file fields should be encoded with this charset.

# File 'lib/rubygems/net-http/lib/net/http/header.rb', line 924

def set_form(params, enctype='application/x-www-form-urlencoded', formopt={})
  @body_data = params
  @body = nil
  @body_stream = nil
  @form_option = formopt
  case enctype
  when /\Aapplication\/x-www-form-urlencoded\z/i,
    /\Amultipart\/form-data\z/i
    self.content_type = enctype
  else
    raise ArgumentError, "invalid enctype: #{enctype}"
  end
end