Preview Ruby 4.1 is a preview. It can change before the final release. Switch to Ruby 4.0 →

instance method

Net::HTTPHeader#set_form

(::Hash[untyped, untyped] params, ?::String enctype, ?::Hash[untyped, untyped] formopt) -> void

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

# File tmp/rubies/ruby-4.1.0-preview1/lib/net/http/header.rb, line 969
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

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:

Example

_uri = uri.dup
_uri.path ='/posts'
req = 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:

Example

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

Two strings:

Example

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:
  
  Example
```
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:

Example

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:

Example

# 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.

See also #set_content_type #set_form_data #range_length #set_range also in 4.0 · 3.4 · 3.3 · 3.2 · 3.1 · 3.0

‹ prev#set_content_type next ›#set_form_data