# module URI::Params::Serializable

##
Overview

The `URI::Params::Serializable` module automatically generates methods for `x-www-form-urlencoded` serialization when included.

NOTE To use this module, you must explicitly import it with `require "uri/params/serializable"`.

###
Example

    require "uri/params/serializable"

    struct Applicant
      include URI::Params::Serializable

      getter first_name : String
      getter last_name : String
      getter qualities : Array(String)
    end

    applicant = Applicant.from_www_form "first_name=John&last_name=Doe&qualities=kind&qualities=smart"
    applicant.first_name  # => "John"
    applicant.last_name   # => "Doe"
    applicant.qualities   # => ["kind", "smart"]
    applicant.to_www_form # => "first_name=John&last_name=Doe&qualities=kind&qualities=smart"

###
Usage

Including `URI::Params::Serializable` will create `#to_www_form` and `self.from_www_form` methods on the current class. By default, these methods serialize into a www form encoded string containing the value of every instance variable, the keys being the instance variable name. Union types are also supported, including unions with nil. If multiple types in a union parse correctly, it is undefined which one will be chosen.

To change how individual instance variables are parsed, the annotation `URI::Params::Field` can be placed on the instance variable. Annotating property, getter and setter macros is also allowed.

`URI::Params::Field` properties:

- converter: specify an alternate type for parsing. The converter must define `.from_www_form(params : URI::Params, name : String)`. An example use case would be customizing the format when parsing `Time` instances, or supporting a type not natively supported.

Deserialization also respects default values of variables:

    require "uri/params/serializable"

    struct A
      include URI::Params::Serializable

      @a : Int32
      @b : Float64 = 1.0
    end

    A.from_www_form("a=1") # => A(@a=1, @b=1.0)

NOTE `URI::Params::Serializable` defines an internal constructor on any including type, which means the default constructor (`def initialize; end`) is absent unless explicitly defined by the user, even when all instance variables have a default initializer.

##
Defined in:

uri/params/serializable.cr

##
Instance Method Summary

- #to_www_form(*, space_to_plus : Bool = true) : String

##
Instance Method Detail

def to_www_form(*, space_to_plus : Bool = true) : String #