HTTP::Params - Crystal 0.35.1

# struct HTTP::Params

- HTTP::Params
- Struct
- Value
- Object

##
Overview

Represents a collection of http parameters and their respective values.

##
Included Modules

- Enumerable({String, String})

##
Defined in:

##
Constructors

- .new(raw_params : Hash(String, Array(String)))
- .new

  Returns an empty `HTTP::Params`.

- .parse(query : String) : self

  Parses an HTTP query string into a `HTTP::Params`

##
Class Method Summary

- .build(&block : Builder -> ) : String

  Builds an url-encoded HTTP form/query.

- .encode(hash : Hash(String, String | Array(String)))

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

- .encode(named_tuple : NamedTuple)

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

- .parse(query : String, &)

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

##
Instance Method Summary

- #==(other : self)
- #==(other)

  Returns `true` if this struct is equal to other.

- #[](name)

  Returns first value for specified param name.

- #[]=(name, value)

  Sets first value for specified param name.

- #[]?(name)

  Returns first value or `nil` for specified param name.

- #add(name, value)

  Appends new value for specified param name.

- #delete(name)

  Deletes first value for provided param name.

- #delete_all(name)

  Deletes all values for provided param name.

- #each(&)

  Allows to iterate over all name-value pairs.

- #empty?(*args, **options)

  Returns `true` if params is empty.

- #empty?(*args, **options, &)

  Returns `true` if params is empty.

- #fetch(name, default)

  Returns first value for specified param name.

- #fetch(name, &)

  Returns first value for specified param name.

- #fetch_all(name)

  Returns all values for specified param name.

- #has_key?(*args, **options, &)

  Returns `true` if param with provided name exists.

- #has_key?(*args, **options)

  Returns `true` if param with provided name exists.

- #set_all(name, values)

  Sets all values for specified param name at once.

- #to_s(io : IO) : Nil

  Serializes to string representation as http url-encoded form.

### Instance methods inherited from module `Enumerable({String, String})`

all?(&)
all?(pattern)
all? all?, any?(&)
any?(pattern)
any? any?, chunks(&block : {String, String} -> U) forall U chunks, compact_map(&) compact_map, count(&)
count(item) count, cycle(&)
cycle(n, &) cycle, each(&block : {String, String} -> _) each, each_cons(count : Int, reuse = false, &) each_cons, each_cons_pair(& : {String, String}, {String, String} -> _) : Nil each_cons_pair, each_slice(count : Int, reuse = false, &) each_slice, each_with_index(offset = 0, &) each_with_index, each_with_object(obj, &) each_with_object, empty? empty?, find(if_none = nil, &) find, first(&)
first(count : Int)
first first, first? first?, flat_map(&block : {String, String} -> Array(U) | Iterator(U) | U) forall U flat_map, grep(pattern) grep, group_by(&block : {String, String} -> U) forall U group_by, in_groups_of(size : Int, filled_up_with : U = nil) forall U
in_groups_of(size : Int, filled_up_with : U = nil, reuse = false, &) forall U in_groups_of, includes?(obj) includes?, index(&)
index(obj) index, index_by(&block : {String, String} -> U) forall U index_by, join(separator = "", & : {String, String} -> )
join(separator, io : IO, &)
join(io : IO, separator = "", & : {String, String}, IO -> )
join(separator = "")
join(separator, io : IO)
join(io : IO, separator = "") join, map(&block : {String, String} -> U) forall U map, map_with_index(offset = 0, &block : {String, String}, Int32 -> U) forall U map_with_index, max max, max? max?, max_by(&block : {String, String} -> U) forall U max_by, max_by?(&block : {String, String} -> U) forall U max_by?, max_of(&block : {String, String} -> U) forall U max_of, max_of?(&block : {String, String} -> U) forall U max_of?, min min, min? min?, min_by(&block : {String, String} -> U) forall U min_by, min_by?(&block : {String, String} -> U) forall U min_by?, min_of(&block : {String, String} -> U) forall U min_of, min_of?(&block : {String, String} -> U) forall U min_of?, minmax minmax, minmax? minmax?, minmax_by(&block : {String, String} -> U) forall U minmax_by, minmax_by?(&block : {String, String} -> U) forall U minmax_by?, minmax_of(&block : {String, String} -> U) forall U minmax_of, minmax_of?(&block : {String, String} -> U) forall U minmax_of?, none?
none?(pattern)
none?(&) none?, one?(&)
one?(pattern)
one? one?, partition(&) partition, product
product(initial : Number)
product(initial : Number, &)
product(&) product, reduce(memo, &)
reduce(&) reduce, reduce?(&) reduce?, reject(pattern)
reject(type : U.class) forall U
reject(&block : {String, String} -> ) reject, select(pattern)
select(type : U.class) forall U
select(&block : {String, String} -> ) select, size size, skip(count : Int) skip, skip_while(&) skip_while, sum(initial)
sum
sum(initial, &)
sum(&) sum, take_while(&) take_while, tally : Hash({String, String}, Int32) tally, to_a to_a, to_h
to_h(&block : {String, String} -> Tuple(K, V)) forall K, V to_h, to_set to_set, zip(*others : Indexable | Iterable | Iterator, &)
zip(*others : Indexable | Iterable | Iterator) zip, zip?(*others : Indexable | Iterable | Iterator, &)
zip?(*others : Indexable | Iterable | Iterator) zip?

### Instance methods inherited from struct `Struct`

==(other) : Bool ==, hash(hasher) hash, inspect(io : IO) : Nil inspect, pretty_print(pp) : Nil pretty_print, to_s(io : IO) : Nil to_s

### Instance methods inherited from struct `Value`

==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup

### Instance methods inherited from class `Object`

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(*values : Object) : Bool
in?(collection) : Bool in?, inspect : String
inspect(io : IO) : Nil inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO)
to_json to_json, to_pretty_json(io : IO, indent : String = " ")
to_pretty_json(indent : String = " ") to_pretty_json, to_s : String
to_s(io : IO) : Nil to_s, to_yaml(io : IO)
to_yaml to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

### Class methods inherited from class `Object`

from_json(string_or_io, root : String)
from_json(string_or_io) from_json, from_yaml(string_or_io : String | IO) from_yaml

##
Constructor Detail

def self.new(raw_params : Hash(String, Array(String))) #
def self.new #

Returns an empty `HTTP::Params`.

def self.parse(query : String) : self #

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"]}>

##
Class Method Detail

def self.build(&block : Builder -> ) : String #

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"

def self.encode(hash : Hash(String, String | Array(String))) #

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"

def self.encode(named_tuple : NamedTuple) #

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"

def self.parse(query : String, &) #

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

##
Instance Method Detail

def ==(other : self) #
def ==(other) #
Description copied from struct Struct

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

def [](name) #

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

def []=(name, value) #

Sets first value for specified param name.

    params["item"] = "pencil"

def []?(name) #

Returns first value or `nil` for specified param name.

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

def add(name, value) #

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"]

def delete(name) #

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

def delete_all(name) #

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

def each(&) #

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

def empty?(*args, **options) #

Returns `true` if params is empty.

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

def empty?(*args, **options, &) #

Returns `true` if params is empty.

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

def fetch(name, default) #

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"

def fetch(name, &) #

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"

def fetch_all(name) #

Returns all values for specified param name.

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

def has_key?(*args, **options, &) #

Returns `true` if param with provided name exists.

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

def has_key?(*args, **options) #

Returns `true` if param with provided name exists.

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

def set_all(name, values) #

Sets all values for specified param name at once.

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

def to_s(io : IO) : Nil #

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"