# $EPIC: urlencode.txt,v 1.5 2009/08/29 23:21:45 jnelson Exp $
======Synopsis:======
$__urlencode__(<text>)

======Technical:======
This function performs a rfc3986 transformation on <text>.
The rfc3986 transformation converts all bytes into percent format,
except bytes with the value 0x41-0x5A ("A" - "Z"), 0x61-0x7A ("a" - "z"),
0x2D ("-"), or 0x5F ("_").

The percent format substitutes three bytes of output for each byte of 
input.  The first byte is 0x25 ("%"), the last two bytes are the character
equivalent of the hexadecimal value of the input.

For example, a space is converted into the three bytes 0x25 0x32 0x30,
("%20").

This conversion is popularly used to protect strange characters from 
mishandling in http requests.

Unfortunately, because everything in the client is done as a C string, you
cannot convert binary data using this method, since the convesion will stop
at the first nul (ascii 0).

The [[urldecode]] function does the reverse transformation.

This function has been superceded by [[xform]] which has a URL transform.

======Practical:======
This can be used to mangle text passed to the /[[exec command|exec]]
command so that it does not contain dangerous meta-characters.  You
could also rename files sent via dcc.

======Returns:======
The input <text> with many punctuation marks substituted with
"url encoded" equivalents.