Difference between revisions of "LlEscapeURL"

From Second Life Wiki
Jump to: navigation, search
(another more practical option)
 
(7 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
{{LSL_Function
 
{{LSL_Function
 
|func_id=307|func_sleep=0.0|func_energy=10.0
 
|func_id=307|func_sleep=0.0|func_energy=10.0
|func=llEscapeURL|return_type=string|p1_type=string|p1_name=url
+
|func=llEscapeURL|return_type=string|p1_type=string|p1_name=url|p1_desc=A (preferably valid and unescaped URL) string.
|func_footnote=To clarify, numbers and ASCII7 alphabetical characters are NOT escaped. If a character requires more then one byte in UTF-8 byte form then it returns multiple %xx sequences chained together.
+
|func_footnote=To clarify, numbers and ASCII7 alphabetical characters are NOT escaped. If a character requires more then one byte in {{Wikipedia|UTF-8|UTF-8}} {{Wikipedia|Byte|byte}} form then it returns multiple <code>"%xx"</code> sequences chained together.
 
|func_desc
 
|func_desc
|return_text=that is the escaped/encoded version of '''url''', replacing spaces with ''%20'' etc. The function will escape any character not in {a-z, A-Z, 0-9} to ''%xx'' where "xx" is the hexadecimal value of the character in UTF-8 byte form.
+
|return_text=that is the escaped/encoded version of {{LSLPT|url}}, replacing spaces with <code>"%20"</code> etc. The function will escape any character not in {{HoverText|<nowiki>[a-zA-Z0-9]</nowiki>|a-z, A-Z, 0-9}} to <code>"%xx"</code> where <code>"xx"</code> is the {{Wikipedia|Hexadecimal|hexadecimal}} value of the character in {{Wikipedia|UTF-8|UTF-8}} {{Wikipedia|Byte|byte}} form.
 
|spec
 
|spec
 
|other_languages={{LSL OL|PHP|[http://php.net/manual/en/function.rawurlencode.php rawurlencode]}}{{LSL OL|{{HoverText|ECMAScript|JavaScript, ActionScript, etc}}|[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent encodeURIComponent]}}
 
|other_languages={{LSL OL|PHP|[http://php.net/manual/en/function.rawurlencode.php rawurlencode]}}{{LSL OL|{{HoverText|ECMAScript|JavaScript, ActionScript, etc}}|[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent encodeURIComponent]}}
|caveats=* The function is not appropriate for escaping a URL all at once, because the ':' after the protocol, and all of the '/' characters delimiting the various parts, will be escaped. Instead, build the URL in parts; escaping parts of the path and query string arguments as needed.
+
|caveats=The function is not appropriate for escaping a {{LSLP|url}} all at once, because the <code>":"</code> after the protocol, and all of the <code>"/"</code> characters delimiting the various parts, will be escaped. Instead, build the {{LSLP|url}} in parts; escaping parts of the path and query string arguments as needed.
|constants
+
|examples=<lsl>
+
//  Provides a clickable link to the LSL Portal by escaping the space in the title
+
//  "LSL Portal" here becomes "LSL%20Portal"
+
  
string title = "LSL Portal";
+
Sample URL: [https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322/foo/bar?arg=gra {{HoverTextStyle|style=color:green;|<nowiki>https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322</nowiki>|2={{String|x-script-url}} = {{String|https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322}}}}{{HoverTextStyle|style=color:blue;|/foo/bar|2={{String|x-path-info}} = {{String|/foo/bar}}}}?{{HoverTextStyle|style=color:red;|1=arg=gra|2={{String|x-query-string}} = {{String|1=arg=gra}}}}]
  
 +
{{{!}} class="lltable" style="font-size: 85%; text-align: center; width: auto; border=1px;"
 +
! URL part
 +
! example
 +
{{!}}-
 +
{{!}} base URL
 +
{{!}} <font color="green"><nowiki>https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322</nowiki></font>
 +
{{!}}-
 +
{{!}} trailing path
 +
{{!}} <font color="blue">/foo/bar</font>
 +
{{!}}-
 +
{{!}} query string past the first "?" in the URL
 +
{{!}} <font color="red">arg=gra</font>
 +
{{!}}}
 +
|constants
 +
|examples=<source lang="lsl2">
 +
string str = "http://wiki.secondlife.com/wiki/LSL Portal";
 +
 
default
 
default
 
{
 
{
 
     state_entry()
 
     state_entry()
 
     {
 
     {
         llOwnerSay("http://wiki.secondlife.com/wiki/" + llEscapeURL(title));
+
         llOwnerSay("Plain string:\n\t" + str);
 +
        // output: "http://wiki.secondlife.com/wiki/LSL Portal"
 +
 +
        llOwnerSay("Escaped string:\n\t" + llEscapeURL(str));
 +
        // output: "http%3A%2F%2Fwiki%2Esecondlife%2Ecom%2Fwiki%2FLSL%20Portal"
 +
 +
        llOwnerSay("Escaped string unescaped again:\n\t" + llUnescapeURL( llEscapeURL(str) ));
 +
        // output: "http://wiki.secondlife.com/wiki/LSL Portal"
 +
 +
        // because escaping and unescaping are exact opposite
 +
        // and unescaping an escaped string returns the original
 +
 +
 +
        //  For readability's sake it would make more sense to do:
 +
        llOwnerSay("For readability's sake:\n\t" + "http://wiki.secondlife.com/wiki/" + llEscapeURL("LSL Portal"));
 +
        // output: "http://wiki.secondlife.com/wiki/LSL%20Portal"
 
     }
 
     }
 
}
 
}
</lsl>
+
</source>
 
|helpers
 
|helpers
 
|also_functions={{LSL DefineRow|[[llUnescapeURL]]}}
 
|also_functions={{LSL DefineRow|[[llUnescapeURL]]}}
Line 29: Line 57:
 
|also_articles={{LSL DefineRow|[[UTF-8]]}}
 
|also_articles={{LSL DefineRow|[[UTF-8]]}}
 
{{LSL DefineRow|{{LSLGC|Base64}}}}
 
{{LSL DefineRow|{{LSLGC|Base64}}}}
|notes
+
|notes=*The SL viewer pretty prints URLs when converting them to clickable links in chat and dialogs. To confirm that a URL was escaped as intended, right-click the URL and copy, then paste to inspect it in the chat bar; or wrap it between "<nowiki><nolink>...</nolink></nowiki>"; or examine your chat log in an external editor; or display the string with an alternative function like [[llSetText]].
 
|permission
 
|permission
 
|history=*Prior to SL versions 1.19.1.81992, this function was limited to returning a maximum of 254 characters. {{Jira|SVC-470}}
 
|history=*Prior to SL versions 1.19.1.81992, this function was limited to returning a maximum of 254 characters. {{Jira|SVC-470}}

Latest revision as of 19:16, 6 February 2015

Summary

Function: string llEscapeURL( string url );

Returns a string that is the escaped/encoded version of url, replacing spaces with "%20" etc. The function will escape any character not in [a-zA-Z0-9] to "%xx" where "xx" is the hexadecimal value of the character in UTF-8 byte form.

• string url A (preferably valid and unescaped URL) string.

To clarify, numbers and ASCII7 alphabetical characters are NOT escaped. If a character requires more then one byte in UTF-8 byte form then it returns multiple "%xx" sequences chained together.

This function is similar to functions (e.g. rawurlencode, encodeURIComponent) found in many other languages: 
PHP
rawurlencode
ECMAScript
encodeURIComponent

Caveats

The function is not appropriate for escaping a url all at once, because the ":" after the protocol, and all of the "/" characters delimiting the various parts, will be escaped. Instead, build the url in parts; escaping parts of the path and query string arguments as needed.

Sample URL: https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322/foo/bar?arg=gra

URL part example
base URL https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322
trailing path /foo/bar
query string past the first "?" in the URL arg=gra
All Issues ~ Search JIRA for related Bugs

Examples

string str = "http://wiki.secondlife.com/wiki/LSL Portal";
 
default
{
    state_entry()
    {
        llOwnerSay("Plain string:\n\t" + str);
        // output: "http://wiki.secondlife.com/wiki/LSL Portal"
 
        llOwnerSay("Escaped string:\n\t" + llEscapeURL(str));
        // output: "http%3A%2F%2Fwiki%2Esecondlife%2Ecom%2Fwiki%2FLSL%20Portal"
 
        llOwnerSay("Escaped string unescaped again:\n\t" + llUnescapeURL( llEscapeURL(str) ));
        // output: "http://wiki.secondlife.com/wiki/LSL Portal"
 
        // because escaping and unescaping are exact opposite
        // and unescaping an escaped string returns the original
 
 
        //  For readability's sake it would make more sense to do:
        llOwnerSay("For readability's sake:\n\t" + "http://wiki.secondlife.com/wiki/" + llEscapeURL("LSL Portal"));
        // output: "http://wiki.secondlife.com/wiki/LSL%20Portal"
    }
}

Notes

  • The SL viewer pretty prints URLs when converting them to clickable links in chat and dialogs. To confirm that a URL was escaped as intended, right-click the URL and copy, then paste to inspect it in the chat bar; or wrap it between "<nolink>...</nolink>"; or examine your chat log in an external editor; or display the string with an alternative function like llSetText.

See Also

Functions

• llUnescapeURL

Articles

• UTF-8
• Base64

Deep Notes

History

  • Prior to SL versions 1.19.1.81992, this function was limited to returning a maximum of 254 characters. SVC-470

Search JIRA for related Issues

Signature

function string llEscapeURL( string url );