NaviServer Built-in Commands – 5.0.0a
ns_percentencode - Encoding and Decoding Percent-Encoded Strings
This group of commands lets you safely encode and decode strings by escaping unsafe characters as percent‑escape sequences (“%xx”) per RFC 3986 (or RFC 1738 when in legacy mode). You can choose from several encoding schemes (query, path, cookie, oauth1) to control which characters remain unescaped and how spaces are handled. Hex digits default to lowercase but can be forced uppercase.
Percent‑encodes a single string. All characters not in the selected scheme’s unreserved set are replaced by “%” and two hex digits.
Reverses the percent‑encoding in a string. Under query scheme only, “+” is converted back to space. If decoding to UTF‑8 fails and -fallbackcharset is given (and -charset is not), a second decode attempt uses the fallback charset instead of raising an exception.
Alias for ns_percentencode, using -part in place of -scheme. Accepts multiple components. With the query scheme, components are joined by "&", in otherwise by "/".
Alias for ns_percentdecode, using -part in place of -scheme.
query (default): Encoding scheme for URL query strings and form data (application/x-www-form-urlencoded). Spaces are encoded as "+". Unsafe characters from query components from RFC 3986 are percent encoded. 76 characters remain unescapted:
! $ ' ( ) * + - . / 0 1 2 3 4 5 6 7 8 9 : ? @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z _ a b c d e f g h i j k l m n o p q r s t u v w x y z ~
path: Encoding scheme per RFC 3986 for path‐segment rules. Spaces are encoded as "%20"; slashes embedded in path segments are encoded as "%2F". 76 characters remain unescapted:
! $ & ' ( ) * + , - . 0 1 2 3 4 5 6 7 8 9 : @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z _ a b c d e f g h i j k l m n o p q r s t u v w x y z ~
cookie: Encode cookie‐value segments per RFC 6265. 89 characters remain unescaped:
! # $ & ' ( ) * + - . / 0 1 2 3 4 5 6 7 8 9 : < = > ? @
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ ] ^ _ `
a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~
oauth1: Encoding scheme for OAuth 1.0 signature base strings (RFC 5849 §3.6). Spaces are encoded as "%20"; only unreserved chars per RFC 3986 remain literal. 66 characters remain unescaped:
- . 0 1 2 3 4 5 6 7 8 9 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z _ a b c d e f g h i j k l m n o p q r s t u v w x y z ~
This scheme is also used for AWS signature encoding..
Encode form data as an application/x-www-form-urlencoded POST body (https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4):
set data {
first_name John
second_name Doe
data "Hello World"
}
set post_data {}
foreach {key value} $data {
lappend post_data "[ns_urlencode -part query $key]=[ns_urlencode $value]"
}
set post_data [join $post_data &]
Encode path segments per W3C URI recommendations (examples 1 and 2 of URI Recommendation):
% set e1 {albert bertram marie-claude}
% ns_urlencode -part path {*}$e1
albert/bertram/marie-claude
% set e2 {albert bertram/marie-claude}
% ns_urlencode -part path {*}$e2
albert/bertram%2fmarie-claude
By default escapes use lowercase, but you can request uppercase:
% ns_percentencode -scheme path -uppercase "a/b c" A%2FB%20C
Use the cookie scheme to percent‑encode only those bytes unsafe in cookie segments:
% ns_percentencode -scheme cookie "key=value; path=/" key%3Dvalue%3B%20path%3D%2F
Construct an OAuth 1.0 signature base string
% ns_percentencode -scheme oauth1 -uppercase "Ladies + Gentlemen" Ladies%20%2B%20Gentlemen
If your percent‐encoded input isn’t valid UTF‑8, you can retry with a different charset:
% ns_percentdecode "%C3%A9t%C3%A9" été % ns_percentdecode "%E9" input string '%E9' cannot be converted to UTF-8 % ns_percentdecode -charset iso8859-1 "%E9" é
With the fallback charset, a valid UTF-8 string and a latin-1 string can be decoded.
% ns_percentdecode -fallbackcharset iso8859-1 "%C3%A9t%C3%A9" été % ns_percentdecode -fallbackcharset iso8859-1 "%E9" é