struct HTTP::Params

Returns an empty HTTP::Params.

Parses an HTTP query string into a HTTP::Params

require "http/params"

HTTP::Params.parse("foo=bar&foo=baz&qux=zoo")
# => #<HTTP::Params @raw_params = {"foo" => ["bar", "baz"], "qux" => ["zoo"]}>

Builds an url-encoded HTTP form/query.

The yielded object has an #add method that accepts two arguments, a key (String) and a value (String or Nil). Keys and values are escaped using URI.encode_www_form.

require "http/params"

params = HTTP::Params.build do |form|
  form.add "color", "black"
  form.add "name", "crystal"
  form.add "year", "2012 - today"
end
params # => "color=black&name=crystal&year=2012+-+today"

Returns the given key value pairs as a url-encoded HTTP form/query.

require "http/params"

HTTP::Params.encode({"foo" => "bar", "baz" => ["quux", "quuz"]}) # => "foo=bar&baz=quux&baz=quuz"

Returns the given key value pairs as a url-encoded HTTP form/query.

require "http/params"

HTTP::Params.encode({foo: "bar", baz: ["quux", "quuz"]}) # => "foo=bar&baz=quux&baz=quuz"

Parses an HTTP query and yields each key-value pair.

require "http/params"

query = "foo=bar&foo=baz&qux=zoo"
HTTP::Params.parse(query) do |key, value|
  # ...
end

Returns true if this struct is equal to other.

Both structs's instance vars are compared to each other. Thus, two structs are considered equal if each of their instance variables are equal. Subclasses should override this method to provide specific equality semantics.

struct Point
  def initialize(@x : Int32, @y : Int32)
  end
end

p1 = Point.new 1, 2
p2 = Point.new 1, 2
p3 = Point.new 3, 4

p1 == p2 # => true
p1 == p3 # => false

Returns first value for specified param name.

require "http/params"

params = HTTP::Params.parse("email=john@example.org")
params["email"]              # => "john@example.org"
params["non_existent_param"] # KeyError

Sets first value for specified param name.

params["item"] = "pencil"

Returns first value or nil for specified param name.

params["email"]?              # => "john@example.org"
params["non_existent_param"]? # nil

Appends new value for specified param name. Creates param when there was no such param.

params.add("item", "keychain")
params.fetch_all("item") # => ["pencil", "book", "workbook", "keychain"]

Deletes first value for provided param name. If there are no values left, deletes param itself. Returns deleted value.

params.delete("item")    # => "keychain"
params.fetch_all("item") # => ["keynote"]

params.delete("item") # => "keynote"
params["item"]        # KeyError

params.delete("non_existent_param") # KeyError

Deletes all values for provided param name. Returns array of deleted values.

params.set_all("comments", ["hello, world!", ":+1:"])
params.delete_all("comments") # => ["hello, world!", ":+1:"]
params.has_key?("comments")   # => false

Allows to iterate over all name-value pairs.

params.each do |name, value|
  puts "#{name} => #{value}"
end

# Outputs:
# email => john@example.org
# item => keychain
# item => keynote

Returns true if params is empty.

HTTP::Params.new.empty?                              # => true
HTTP::Params.parse("foo=bar&foo=baz&qux=zoo").empty? # => false

Returns true if params is empty.

HTTP::Params.new.empty?                              # => true
HTTP::Params.parse("foo=bar&foo=baz&qux=zoo").empty? # => false

Returns first value for specified param name. Fallbacks to provided default value when there is no such param.

params.fetch("email", "none@example.org")           # => "john@example.org"
params.fetch("non_existent_param", "default value") # => "default value"

Returns first value for specified param name. Fallbacks to return value of provided block when there is no such param.

params.fetch("email") { raise "Email is missing" }              # raises "Email is missing"
params.fetch("non_existent_param") { "default computed value" } # => "default computed value"

Returns all values for specified param name.

params.set_all("item", ["pencil", "book", "workbook"])
params.fetch_all("item") # => ["pencil", "book", "workbook"]

Returns true if param with provided name exists.

params.has_key?("email")   # => true
params.has_key?("garbage") # => false

Returns true if param with provided name exists.

params.has_key?("email")   # => true
params.has_key?("garbage") # => false

Sets all values for specified param name at once.

params.set_all("item", ["keychain", "keynote"])
params.fetch_all("item") # => ["keychain", "keynote"]

Serializes to string representation as http url-encoded form.

require "http/params"

params = HTTP::Params.parse("item=keychain&item=keynote&email=john@example.org")
params.to_s # => "item=keychain&item=keynote&email=john%40example.org"