class Lucky::Params

Included Modules

Defined in:

lucky/params.cr
lucky_avram/ext/lucky/params.cr

Constructors

Instance Method Summary

Constructor Detail

def self.new(request : HTTP::Request, route_params : Hash(String, String) = empty_params) #

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)

[View source]

Instance Method Detail

def body : String #

Returns cached value


[View source]
def body__tuple_cached : Tuple(String) #

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


[View source]
def body__uncached : String #

Returns uncached value


[View source]
def from_form_data : URI::Params #

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.


[View source]
def from_json : JSON::Any #

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.

[View source]
def from_multipart : Tuple(Hash(String, String), Hash(String, Lucky::UploadedFile)) #

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

[View source]
def from_query : URI::Params #

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.


[View source]
def get(key) : String #

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

[View source]
def get?(key : String | Symbol) : String? #

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)

[View source]
def get_all(key : String | Symbol) : Array(String) #

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

[View source]
def get_all?(key : String | Symbol) : Array(String)? #

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)

[View source]
def get_all_files(key : String | Symbol) : Array(Lucky::UploadedFile) #

[View source]
def get_all_files?(key : String | Symbol) : Array(Lucky::UploadedFile) #

[View source]
def get_file(key) : Lucky::UploadedFile #

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

[View source]
def get_file?(key : String | Symbol) : Lucky::UploadedFile? #

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

[View source]
def get_raw(key) : String #

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

[View source]
def get_raw?(key : String | Symbol) : String? #

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)

[View source]
def many_nested(nested_key : String | Symbol) : Array(Hash(String, String)) #

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

[View source]
def many_nested?(nested_key : String | Symbol) : Array(Hash(String, String)) #

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") # []

[View source]
def nested(nested_key : String | Symbol) : Hash(String, String) #

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

[View source]
def nested?(nested_key : String | Symbol) : Hash(String, String) #

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") # {}

[View source]
def nested_array_files(nested_key : String | Symbol) : Hash(String, Array(Lucky::UploadedFile)) #

[View source]
def nested_array_files?(nested_key : String | Symbol) : Hash(String, Array(Lucky::UploadedFile))? #

[View source]
def nested_arrays(nested_key : String | Symbol) : Hash(String, Array(String)) #

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

[View source]
def nested_arrays?(nested_key : String | Symbol) : Hash(String, Array(String)) #

[View source]
def nested_file(nested_key : String | Symbol) : Hash(String, Lucky::UploadedFile) #

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") # {}

[View source]
def nested_file?(nested_key : String | Symbol) : Hash(String, Lucky::UploadedFile)? #

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

[View source]
def route_params=(route_params) #

[View source]
def to_h #

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

[View source]