Difference between revisions of "LlEscapeURL"

From Second Life Wiki
Jump to: navigation, search
(another more practical option)
 
(32 intermediate revisions by 13 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
+
|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=is the escaped/encoded version of '''url''', replacing spaces with %20 etc.
+
|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
|caveats=*The return is limited to 255 characters, this means this function can only safely escape 14 character string.
+
|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]}}
**UTF-8 characters requiring up to 6 bytes to express; though there are no characters defined in the Unicode standard as of yet that use more then 4 bytes. This has the effect that if a string containing all 6-byte characters, this function could only encode 14 characters. See: {{LSLG|string#Caveats|String:Caveats}}
+
|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.
 +
 
 +
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
 
|constants
|examples
+
|examples=<source lang="lsl2">
 +
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"
 +
    }
 +
}
 +
</source>
 
|helpers
 
|helpers
|also_functions=*{{LSLG|llUnescapeURL}}
+
|also_functions={{LSL DefineRow|[[llUnescapeURL]]}}
 
|also_events
 
|also_events
 
|also_tests
 
|also_tests
|also_articles=*{{LSLG|UTF-8}}
+
|also_articles={{LSL DefineRow|[[UTF-8]]}}
*{{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
|negative_index
+
|history=*Prior to SL versions 1.19.1.81992, this function was limited to returning a maximum of 254 characters. {{Jira|SVC-470}}
 
|cat1=Encoding
 
|cat1=Encoding
|cat2
+
|cat2=String
|cat3
+
|cat3=Encoding/URL
|cat4=Stub
+
|cat4
 
}}
 
}}

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 );