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

Checks the passed arguments against the memoized args and runs the method body if it is the very first call or the arguments do not match

Returns uncached value

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

Returns a URI::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 URI::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 URI::Params

Returns a URI::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 trimmed value from the params hash, raise if key is absent

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

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

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

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

Retrieve values for a given key

Checks in places that could provide multiple values and returns first with values:

• JSON body
• multipart params
• form encoded params
• query params

For all params locations it appends square brackets so searching for "emails" in query params will look for values with a key of "emails[]"

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

params.get_all(:names)    # ["Paul", "Johnny"] : Array(String)
params.get_all("missing") # Missing parameter: missing

Retrieve values for a given key, return nil if key is absent

params.get_all(:names)    # ["Paul", "Johnny"] : (Array(String) | Nil)
params.get_all("missing") # nil : (Array(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 a raw, untrimmed value from the params hash, raise if key is absent

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

params.get_raw("name")    # " Paul " : String
params.get_raw("page")    # "1" : String
params.get_raw("missing") # Missing parameter: missing

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

params.get_raw?("missing") # nil : (String | Nil)
params.get_raw?("page")    # "1" : (String | Nil)
params.get_raw?("name")    # " Paul " : (String | Nil)

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 array 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_array("tags")    # {"tags" => ["Lucky", "Crystal"]}
params.nested_array("missing") # Missing parameter: 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"}