p:www-form-urldecode (3.1)

Decode a URL parameter string into a map.

Summary
Description
Examples
- Basic usage
- Parameters with the same name
Additional details
Errors raised
Reference information

Summary

<p:declare-step type="p:www-form-urldecode">
  <output port="result" primary="true" content-types="application/json" sequence="true"/>
  <option name="value" as="xs:string" required="true"/>
</p:declare-step>

The p:www-form-urldecode step decodes a URL parameter string (like a=b&c=d) into a map. The result appears on the result port as a JSON document.

Ports:

Type	Port	Primary?	Content types	Seq?	Description
`output`	`result`	`true`	`application/json`	`true`	The resulting map, as a JSON document.

Options:

Name	Type	Req?	Description
`value`	`xs:string`	`true`	The URL parameter string to decode.

Description

The p:www-form-urldecode step is one of the few steps that have no primary input port, its main input is the value of the value option. This value must be a valid URL parameter string: the part that usually comes after the ? in a URL, like a=b&c=d. Officially, this is called a x-www-form-urlencoded string. This format is also used for sending HTML form data over HTTP.

The p:www-form-urldecode step takes such a string in its value option and converts it into a map. Each name/value pair in the input string is represented as a key/value pair in the map. Percent encoded values (like %20 for space) are decoded. The + sign also acts as a space.

The resulting map appears on the result port as a JSON document.

There is also a step for encoding these kinds of strings, called p:www-form-urlencode.

Examples

Basic usage

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">
  
  <p:output port="result"/>

  <p:www-form-urldecode value="a=b&amp;b=a%20b&amp;c=d+e+f"/>

</p:declare-step>

Result document:

{"a":"b","b":"a b","c":"d e f"}

Now assume you’re interested in parameter c and want to turn its value into an XML element. This is how you can do this:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">
  
  <p:output port="result"/>

  <p:www-form-urldecode value="a=b&amp;b=a%20b&amp;c=d+e+f"/>
  <p:identity>
    <p:with-input>
      <result-c>{.?c}</result-c>
    </p:with-input>
  </p:identity>

</p:declare-step>

Result document:

<result-c>d e f</result-c>

The document coming out of the p:www-form-urldecode step is a map. This map flows through my pipeline. The p:identity step, since it directly follows p:www-form-urldecode, can address this map with the dot . operator. And .?c is syntactic sugar for: give me the value of the context item map with the key 'c'.

Parameters with the same name

When the string to decode contains multiple parameters with the same name, the result for that key will be a sequence of values. We cannot serialize such a result directly (since JSON doesn't allow map entries with multiple values), but we can access and work with it in our program.

In the following example, parameter a is duplicated. The p:identity step combines the values for a with a pipe character |, using the XPath string-join() function.

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:output port="result"/>

  <p:www-form-urldecode value="a=b&amp;b=a%20b&amp;a=d+e+f"/>
  <p:identity>
    <p:with-input>
      <result-a-sequence>{string-join(.?a, '|')}</result-a-sequence>
    </p:with-input>
  </p:identity>

</p:declare-step>

Result document:

<result-a-sequence>b|d e f</result-a-sequence>

Additional details

The document appearing on the result port only has a content-type property. It has no other document-properties (also no base-uri).
If any parameter name occurs more than once in the input string, a sequence will be associated with the respective key. The order in the sequence retains the order of name/value pairs in the encoded string. However, if this happens, you cannot serialize (write to, for instance, disk) the result because it is no longer valid JSON. You can however still use the map in your program and access its members. See also the Parameters with the same name example

Errors raised

Error code	Description
`XC0037`	It is a dynamic error if the `value` provided is not a properly `x-www-form-urlencoded` value.

Reference information

This description of the p:www-form-urldecode step is for XProc version: 3.1. This is a required step (an XProc 3.1 processor must support this).

The formal specification for the p:www-form-urldecode step can be found here.

The p:www-form-urldecode step is part of categories:

The p:www-form-urldecode step is also present in version: 3.0.