p:www-form-urldecode (3.0) 

Decode a URL parameter string into a map.

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:

Port

Type

Primary?

Content types

Seq?

Description

result

output

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'. You could also have written it as .('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.0. This is a required step (an XProc 3.0 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.1.