Add Functions for Handling Route WebEvent Data and Serialization in Pode

[mdaneri]

Recovered from #1353

Summary

This pull request adds several new functions to the Pode project for handling web event data and for serializing/deserializing hashtables. The new functions are:

• Get-PodeBodyData
• Get-PodeQueryParameter
• Get-PodePathParameter
• ConvertTo-PodeSerializedString
• ConvertFrom-PodeSerializedString

New Functions

Get-PodeBodyData

Retrieves the body data from the current Pode web event. This function is useful for accessing the main content sent in a web request, including PUT, POST, or any other methods that support a body.

Example:

Get-PodeBodyData

# This command returns the body data of the current web route. Equivalent to `$WebEvent.Data`

Get-PodeBodyData -Deserialize -Style 'Matrix'
# Retrieves and deserializes the body data using the 'Matrix' style.

Get-PodeBodyData -Deserialize -NoExplode
# Deserializes the body data without exploding arrays.

Get-PodeQueryParameter

Retrieves a specific query parameter value from the current Pode web event. This function is useful for accessing query parameters passed in the URL of a web request.

Example:

Get-PodeQueryParameter -Name 'userId'

# This command returns the value of the 'userId' query parameter from the current web route. Equivalent to `$WebEvent.Query['userId']`

Get-PodeQueryParameter -Name 'filter' -Deserialize -Style 'SpaceDelimited'
# Retrieves and deserializes the value of the 'filter' query parameter, using the 'SpaceDelimited' style.

Get-PodeQueryParameter -Name 'data' -Deserialize -NoExplode
# Deserializes the 'data' query parameter value without exploding arrays.

Get-PodePathParameter

Retrieves a specific parameter value from the current Pode web event. This function is useful for accessing parameters passed in the body or URL of a web request.

Example:

Get-PodePathParameter -Name 'action'

# This command returns the value of the 'action' parameter from the current web route. Equivalent to `$WebEvent.Parameters['action']`

ConvertTo-PodeSerializedString

Converts a hashtable to a serialized string using a specified serialization style. It supports various serialization styles such as 'Simple', 'Label', 'Matrix', 'Query', 'Form', 'SpaceDelimited', 'PipeDelimited', and 'DeepObject'. An optional 'Explode' switch can be used to modify the serialization format for certain styles.

This function is useful for example for callback scenarios.

Examples:

$hashtable = @{
    name = 'value'
    anotherName = 'anotherValue'
}
$serialized = ConvertTo-PodeSerializedString -Hashtable $hashtable -Style 'Query'
Write-Output $serialized

# This command serializes the hashtable using the 'Query' style.

$hashtable = @{
    name = 'value'
    anotherName = 'anotherValue'
}
$serializedExplode = ConvertTo-PodeSerializedString -Hashtable $hashtable -Style 'DeepObject' -Explode
Write-Output $serializedExplode

# This command serializes the hashtable using the 'DeepObject' style with the 'Explode' switch.

ConvertFrom-PodeSerializedString

Converts a serialized string back into a hashtable, automatically detecting the serialization style based on common delimiters and formats.

This function is useful when receiving complex data as a parameter without using JSON, YAML, or XML encoding.

Examples:

    # Simple style, explode = true
    $serialized = "name=value,anotherName=anotherValue"
    $hashtable = ConvertFrom-PodeSerializedString -SerializedString $serialized -Style 'Simple' -Explode
    Write-Output $hashtable

    # Simple style, explode = false
    $serialized = "name,value,anotherName,anotherValue"
    $hashtable = ConvertFrom-PodeSerializedString -SerializedString $serialized -Style 'Simple'
    Write-Output $hashtable

    # Label style, explode = true
    $serialized = ".name.value.anotherName.anotherValue"
    $hashtable = ConvertFrom-PodeSerializedString -SerializedString $serialized -Style 'Label' -Explode
    Write-Output $hashtable

    # Label style, explode = false
    $serialized = ".name,value,anotherName,anotherValue"
    $hashtable = ConvertFrom-PodeSerializedString -SerializedString $serialized -Style 'Label'
    Write-Output $hashtable

    # Matrix style, explode = true
    $serialized = ";name=value;anotherName=anotherValue"
    $hashtable = ConvertFrom-PodeSerializedString -SerializedString $serialized -Style 'Matrix' -Explode
    Write-Output $hashtable

    # Matrix style, explode = false
    $serialized = ";id=3;id=4;id=5"
    $hashtable = ConvertFrom-PodeSerializedString -SerializedString $serialized -Style 'Matrix'
    Write-Output $hashtable

    # Query style, explode = true
    $serialized = "name=value&anotherName=anotherValue"
    $hashtable = ConvertFrom-PodeSerializedString -SerializedString $serialized -Style 'Query' -Explode
    Write-Output $hashtable

    # Query style, explode = false
    $serialized = "name=value,anotherName=anotherValue"
    $hashtable = ConvertFrom-PodeSerializedString -SerializedString $serialized -Style 'Query'
    Write-Output $hashtable

    # Form style, explode = true
    $serialized = "name=value&anotherName=anotherValue"
    $hashtable = ConvertFrom-PodeSerializedString -SerializedString $serialized -Style 'Form' -Explode
    Write-Output $hashtable

    # Form style, explode = false
    $serialized = "name=value,anotherName=anotherValue"
    $hashtable = ConvertFrom-PodeSerializedString -SerializedString $serialized -Style 'Form'
    Write-Output $hashtable

    # SpaceDelimited style, explode = true
    $serialized = "id=3&id=4&id=5"
    $hashtable = ConvertFrom-PodeSerializedString -SerializedString $serialized -Style 'SpaceDelimited' -Explode
    Write-Output $hashtable

    # SpaceDelimited style, explode = false
    $serialized = "id=3%204%205"
    $hashtable = ConvertFrom-PodeSerializedString -SerializedString $serialized -Style 'SpaceDelimited'
    Write-Output $hashtable

    # PipeDelimited style, explode = true
    $serialized = "id=3&id=4&id=5"
    $hashtable = ConvertFrom-PodeSerializedString -SerializedString $serialized -Style 'PipeDelimited' -Explode
    Write-Output $hashtable

    # PipeDelimited style, explode = false
    $serialized = "id=3|4|5"
    $hashtable = ConvertFrom-PodeSerializedString -SerializedString $serialized -Style 'PipeDelimited'
    Write-Output $hashtable

    # DeepObject style, explode = true
    $serialized = "myId[role]=admin&myId[firstName]=Alex"
    $hashtable = ConvertFrom-PodeSerializedString -SerializedString $serialized -Style 'DeepObject' -Explode -KeyName 'myId'
    Write-Output $hashtable