NAME
CatalystX::QueryModel::QueryParser - Parse URL query parameters
SYNOPSIS
TBDDESCRIPTION
Given a flat list of query parameters will attempt to convert it to a hash of values, with nested and arrays of nested values as needed. For example you can convert something like:
.-------------------------------------+--------------------------------------.
| Parameter | Value |
+-------------------------------------+--------------------------------------+
| person.username | jjn |
| person.first_name [multiple] | 2, John |
| person.last_name | Napiorkowski |
| person.password | abc123 |
| person.password_confirmation | abc123 |
'-------------------------------------+--------------------------------------'Into:
{
first_name => "John",
last_name => "Napiorkowski",
username => "jjn",
}Or:
.-------------------------------------+--------------------------------------.
| Parameter | Value |
+-------------------------------------+--------------------------------------+
| person.first_name [multiple] | 2, John |
| person.last_name | Napiorkowski |
| person.person_roles[0]._nop | 1 |
| person.person_roles[1].role_id | 1 |
| person.person_roles[2].role_id | 2 |
| person.username | jjn |
'-------------------------------------+--------------------------------------'Into:
{
first_name => "John",
last_name => "Napiorkowski",
username => "jjn",
person_roles => [
{
role_id => 1,
},
{
role_id => 2,
},
],
}We define some settings described below to help you deal with some of the issues you find when trying to parse HTML form posted body content. For now please see the test cases for more examples.
VALUE PARSER CONFIGURATION
This parser defines the following attribute properties which effect how a value is parsed.
flatten
If the value associated with a field is an array, flatten it to a single value. Its really a hack to deal with HTML form POST and Query parameters since the way those formats work you can't be sure if a value is flat or an array.
always_array
Similar to flatten but opposite, it forces a value into an array even if there's just one value.
NOTE: The attribute property settings flatten and always_array are currently exclusive (only one of the two will apply if you supply both. The always_array property always takes precedence. At some point in the future supplying both might generate an exception so its best not to do that. I'm only leaving it allowed for now since I'm not sure there's a use case for both.
INDEXING
When using deeply nested parameters with repeated elements you can use a naming convention to indicate ordering:
param[index]...For example:
.-------------------------------------+--------------------------------------.
| Parameter | Value |
+-------------------------------------+--------------------------------------+
| person.person_roles[0]._nop | 1 |
| person.person_roles[1].role_id | 1 |
| person.person_roles[2].role_id | 2 |
| person.person_roles[].role_id | 3 |
'-------------------------------------+--------------------------------------'Could convert to:
[
{
role_id => 1,
},
{
role_id => 2,
},
]Please note the the index value is just used for ordering purposed, the actual value is tossed after its used to do the sorting. Also if you just need to add a new item to the end of the indexed list you can use an empty index '[]' as in the example above. You might find this useful if you are building HTML forms and need to tack on an extra value but don't know the last index.
EXCEPTIONS
See CatalystX::RequestModel::ContentBodyParser for exceptions.