Create a new params object

The params object is initialized with an HTTP::Request and a hash of params. The request object has many optional parameters. See Crystal's HTTP::Request class for more details.

request = HTTP::Request.new("GET", "/")
route_params = {"token" => "123"}

Lucky::Params.new(request, route_params)

Returns cached value

Returns uncached value

Returns x-www-form-urlencoded body params as HTTP::Params

Returns an HTTP::Params object for the request body. This method is rarely helpful since you can get query params with #get, but if you do need raw access to the body params this is the way to get them.

params.from_form_data["name"]

See the docs on HTTP::Params for more information.

Parses the request body as JSON::Any or raises Lucky::ParamParsingError if JSON is invalid.

# {"page": 1}
params.from_json["page"].as_i # 1
# {"users": [{"name": "Skyler"}]}
params.from_json["users"][0]["name"].as_s # "Skyler"

See the crystal docs on JSON::Any for more on using JSON in Crystal.

You can also get JSON params with Lucky::Params#get/nested. Sometimes Lucky::Params are not flexible enough. In those cases this method opens the possiblity to do just about anything with JSON.

Returns multipart params and files.

Return a Tuple with a hash of params and a hash of Lucky::UploadedFile. This method is rarely helpful since you can get params with #get and files with #get_file, but if you need something more custom you can use this method to get better access to the raw params.

form_params = params.from_multipart.last # Hash(String, String)
form_params["name"]                      # "Kyle"

files = params.from_multipart.last # Hash(String, Lucky::UploadedFile)
files["avatar"]                    # Lucky::UploadedFile

Returns just the query params as HTTP::Params

Returns an HTTP::Params object for only the query params. This method is rarely helpful since you can get query params with #get, but if you do need raw access to the query params this is the way to get them.

params.from_query["search"] # Will return the "search" query param

See the docs on HTTP::Params for more information.

Retrieve a value from the params hash, raise if key is absent

If no key is found a Lucky::MissingParamError will be raised:

params.get("page")    # 1 : String
params.get("missing") # Missing parameter: missing

Retrieve a value from the params hash, return nil if key is absent

params.get?("missing") # nil : (String | Nil)
params.get?("page")    # 1 : (String | Nil)

Retrieve a file from the params hash, raise if key is absent

If no key is found a Lucky::MissingParamError will be raised:

params.get_file("missing") # Raise: Missing parameter: missing

file = params.get_file("avatar_file") # Lucky::UploadedFile
file.name                             # avatar.png
file.metadata                         # HTTP::FormData::FileMetadata
file.tempfile.read                    # Get the file contents

Retrieve a file from the params hash, return nil if key is absent

params.get_file?("missing") # nil

file = params.get_file?("avatar_file") # Lucky::UploadedFile
file.not_nil!.name                     # avatar.png
file.not_nil!.metadata                 # HTTP::FormData::FileMetadata
file.not_nil!.tempfile.read            # Get the file contents

Retrieve nested values from the params

Nested params often appear in JSON requests or Form submissions. If no key is found a Lucky::MissingParamError will be raised:

body = "users[0]:name=Alesia&users[0]:age=35&users[1]:name=Bob&users[1]:age=40&page=1"
request = HTTP::Request.new("POST", "/", body: body)
params = Lucky::Params.new(request)

params.many_nested("users")
# [{"name" => "Alesia", "age" => "35"}, { "name" => "Bob", "age" => "40" }]
params.many_nested("missing") # Missing parameter: missing

Retrieve nested values from the params

Nested params often appear in JSON requests or Form submissions. If no key is found an empty array will be returned:

body = "users[0]:name=Alesia&users[0]:age=35&users[1]:name=Bob&users[1]:age=40&page=1"
request = HTTP::Request.new("POST", "/", body: body)
params = Lucky::Params.new(request)

params.nested("users")
# [{"name" => "Alesia", "age" => "35"}, { "name" => "Bob", "age" => "40" }]
params.nested("missing") # []

Retrieve a nested value from the params

Nested params often appear in JSON requests or Form submissions. If no key is found a Lucky::MissingParamError will be raised:

body = "user:name=Alesia&user:age=35&page=1"
request = HTTP::Request.new("POST", "/", body: body)
params = Lucky::Params.new(request)

params.nested("user")    # {"name" => "Alesia", "age" => "35"}
params.nested("missing") # Missing parameter: missing

Retrieve a nested value from the params

Nested params often appear in JSON requests or Form submissions. If no key is found an empty hash will be returned:

body = "user:name=Alesia&user:age=35&page=1"
request = HTTP::Request.new("POST", "/", body: body)
params = Lucky::Params.new(request)

params.nested("user")    # {"name" => "Alesia", "age" => "35"}
params.nested("missing") # {}

Retrieve a nested file from the params

Nested params often appear in JSON requests or Form submissions. If no key is found a Lucky::MissingParamError will be raised:

params.nested_file?("file")    # Lucky::UploadedFile
params.nested_file?("missing") # {}

Retrieve a nested file from the params

Nested params often appear in JSON requests or Form submissions. If no key is found an empty hash will be returned:

params.nested_file("file")    # Lucky::UploadedFile
params.nested_file("missing") # Missing parameter: missing

Converts the params in to a Hash(String, String)

request.query = "filter:name=trombone&page=1&per=50"
params = Lucky::Params.new(request)
params.to_h # {"filter" => {"name" => "trombone"}, "page" => "1", "per" => "50"}