Second Life Wiki - User contributions [en]

Talk:Json usage in LSL

2013-06-23T14:58:09Z

Gistya Eusebio: responding to enquotation badness

I am concerned because the JSON format specifies at json.org that you can use escape codes like \u0000 to represent Unicode byte values in strings. But LSL has the ugly habit of censoring and altering strings so that a character with byte value of 0x0000 is removed from the string, and some functions like llSHA1String are essentially broken since they also convert UTF-16 integers between \u0128–\u0255 into UTF-8 byte values starting with %c2 (which therefore have a different integer value due to the addition of the extraneous byte). Is LSL also going to mangle JSON strings' byte values when it renders them into LSL strings? Won't this corrupt attempts at efficiently verifying the signatures of any incoming messages, and thwart attempts to generate proper signatures for some outgoing JSON-formatted requests? Or do the Lindens have plans to finally give us a proper suite of escape codes in LSL (or some other solution)?
--[[User:Gistya Eusebio|Gistya Eusebio]] 09:41, 30 May 2013 (PDT)

Add to that the complete crash-and-burn if your string starts with a quote, generating invalid JSON. I really don't get why LL finds it advantageous to include magic switches which forces everybody to do workaround for normal use, and ensures that all future JSON implementations in SL must be hand-coded to keep backwards compatibility with the spec breaks currently implemented.
[[User:Tali Rosca|Tali Rosca]] 15:50, 19 June 2013 (PDT)

:This sounds like a bug, you should report it. -- '''[[User:Strife_Onizuka|Strife]]''' <sup><small>([[User talk:Strife_Onizuka|talk]]|[[Special:Contributions/Strife_Onizuka|contribs]])</small></sup> 21:49, 20 June 2013 (PDT)

::nm I see that you did. {{jira|BUG-2594}} -- '''[[User:Strife_Onizuka|Strife]]''' <sup><small>([[User talk:Strife_Onizuka|talk]]|[[Special:Contributions/Strife_Onizuka|contribs]])</small></sup> 21:50, 20 June 2013 (PDT)

:::I've been kicking and screaming about getting a robust JSON handling :-) 2594 got us some way, but we still have {{jira|BUG-2736}}, which I consider so exceedingly ill-advised as to be a bug, despite the insistence that it's a really awesome feature. [[User:Tali Rosca|Tali Rosca]] 16:39, 21 June 2013 (PDT)

::::     The trailing quotation mark is the real nasty problem, not the leading one :D But yeah.. if they do add the capability to handle enquoted* text, how would that break anyone's scripts? Is anyone really relying on enquotation to invalidate their JSON strings on purpose? Besides when has breaking people's scripts stopped them from doing anything? I have tens of thousands of L$ worth of vehicles that are now worthless due to the Havok 4 update, but hey, life goes on. My copy of Microsoft Word 1.0 for Mac won't run on Mountain Lion either. I like backwards compatibility but we developers would be out of a job if software never had to be rewritten to work with the ever-evolving platforms that are out there :D <br>     --[[User:Gistya Eusebio|Gistya Eusebio]] 07:58, 23 June 2013 (PDT) <br>* I know "enquoted" is not in the dictionary. However it is in the lexicon. :D

Json usage in LSL

2013-06-23T14:19:44Z

Gistya Eusebio: enhancing the warning about how multiple members with the same name are handled

{{LSL Header|lm=*}}{{LSLC|}}{{LSLC|JSON|*Json usage in LSL}}
==Type Conversions==

Json has native representation for:
* numbers - directly mappable to LSL Integer and Float (json numbers without a decimal point are assumed to be Integers, those with a decimal point are Floats)
* strings - identical to LSL [[String]]
* arrays - a list of values of any type: directly analogous to an LSL [[List]]
* objects - represented in LSL as a strided list of name/value pairs (see below re: values)
* the constants 'true' and 'false' - directly mapped to and from the LSL constants [[JSON_TRUE]] and [[JSON_FALSE]]
* the constant 'null' - directly mapped to and from the LSL constant [[JSON_NULL]]
* All other LSL types (Key, Rotation, and Vector) are implicitly converted to their string representation when converting to Json; when converting from Json to LSL, these values are returned as String values, so the script must explicitly convert using the existing conversion methods.

==New LSL Methods==
===Specifying Json Elements===

[[llJsonGetValue]], [[llJsonValueType]] and [[llJsonSetValue]] each take the same first two arguments:
1. a JSON value in the form of a [[String|string]], and
2. a set of specifiers in the form of a [[List|list]].
[[llJsonSetValue]] additionally takes a third an argument:
3. a JSON value in the form of a [[String|string]].

To understand specifiers one must generally understand that JSON data is structured in a [http://en.wikipedia.org/wiki/Nested_set_model nested set model]. LSL's built-in JSON parser uses the supplied "specifiers" list to perform [http://en.wikipedia.org/wiki/Tree_traversal tree traversal] on the nodes of the supplied JSON [http://en.wikipedia.org/wiki/Tree_(data_structure) tree data structure]. A JSON tree may be visualized as a set of hierarchical levels of parents and children. Each level is contained within '''curly braces {for objects, which are lists of members, that are defined as key-value pairs}''' or '''square braces [for arrays of elements, that are defined as single values]'''.

When JSON is presented in human-readable form, it is traditionally formatted such that the first parent level of organization is indented farthest to the left, and each more deeply-nested child level of organization is indented farther and farther to the right. The left-most level of nodes have no parents, only children. They begin with the very first member that appears after the initial "{" character of the JSON string (if it starts as an object), or the first element that appears after the initial "[" character (if it starts as an array). A node is considered as being a parent only if it has a non-null JSON object or array as its value.

With that parent-child tree data structure in mind, the specifiers list that you supply in the above functions tell LSL's JSON parser how to [http://en.wikipedia.org/wiki/Tree_(data_structure)#Traversal_methods walk the tree] of the JSON data that you have supplied with the first argument of the function. The first specifier in the list tells the LSL JSON parser which node to walk to first. The next specifier tells it which of that node's children to walk to. Once the LSL parser has "walked" to the last destination node specified by your list of specifiers, it will then perform the function on the JSON value that it finds there.

If, anywhere along the line, any of the specified nodes do not exist, [[llJsonGetValue]] and [[llJsonValueType]] will almost always return [[JSON_INVALID]]. However there is a rare exception: if any specifier in the list leads to a node that has no characters in its JSON string value, JSON_NULL will be returned instead of JSON_INVALID—no matter what might come after it in the specifiers list. For example in:

<lsl>
string parent = "{\"parent\":,}";
string test1 = llJsonGetValue(example,[parent]);
string test2 = llJsonGetValue(example,["parent","child that doesn't exist","etc."]);
</lsl>
test1 and test2 will both be JSON_NULL.

The same is true for arrays: a specifier pointing to any element of a valid array will return JSON_NULL anywhere there is no JSON value specified at given position in the array:

<lsl>
string "{\"parent\":[ , , , , ]}";
string test1 = llJsonGetValue(example,["parent",2]);
string test2 = llJsonGetValue(example,["parent",1,"child that does not exist","etc."]);
</lsl>
test1 and test2 will also both be JSON_NULL.

These types of scenarios may be useful in determining valid JSON paths for the setter: in all the scenarios where JSON_NULL is returned, the same set of specifiers is able to be successfully used for [[llJsonSetValue]]. However if [[JSON_INVALID]] is returned, there is no guarantee the setter won't return an error.

For [[llJsonGetValue]], if a JSON value is present at the specified node, it will be returned by the function. The value may an object that contains no valid JSON data, so be careful. Such an object will be deemed a [[JSON_OBJECT]] by [[llJsonValueType]], even if its contents are not valid JSON. Therefore it's always best to check the [[llJsonValueType]] of any specified value to make sure it's valid before using the information in your script.

{{LSL Tip|Counter-intuitiveness warning! If there exist multiple members with the same name in the same object at the same child-level, a specifier that points to that name will be interpreted by LSL as pointing to the member closest to the end of the string! This behavior is opposite from the behavior of [[llListFindList]] and [[llSubStringIndex]], which always find the match that is closest to the beginning of the list or string, respectively!}}

The specifiers list may only consist of strings/keys (for object member keys), and integers (for array element positions), which define a path to the desired value in a JSON compound object.

* An empty list specifies the entire Json value.
* If the list is not empty, each element of the list is used to select the element at the same level of nesting in the JSON value:
** if the specifier list element is a string, then the corresponding element in the json value must be an object and the list element selects the value whose JSON name exactly matches the string.
** if the specifier list element is an integer, then the corresponding element in the json value must be an array and the list element is used as a zero-based index into the Json array.
* Additionally llJsonSetValue accepts [[JSON_APPEND]] as a specifier to indicate appending the value to the end of the array at that level. Be careful because If the value at that level is not an array, it will be overwritten and replaced with the array you're setting!

For example, given the JSON value:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
"a": 3.2,
"b": true
}
}
</javascript>
the contents of the string returned would be:
<lsl>
llJsonGetValue ( value, [ "alpha" ] ) ⇒ 1
llJsonGetValue ( value, [ "beta" ] ) ⇒ [ "x", "y", "z" ]
llJsonGetValue ( value, [ "beta", 2 ] ) ⇒ z
llJsonGetValue ( value, [ "gamma", "a" ] ) ⇒ 3.2
</lsl>

llJsonSetValue(string json, list specifiers, string value_to_set) will force the resulting JSON to conform with the specifiers supplied, as long as the specified path is traversable.

==Json Interrogation and Validation==

To determine the type of a json value:

<lsl>string type = llJsonValueType( string json, list specifiers );</lsl>

:returns one of several following special constants (see table below). Each constant has a name, JSON_XXXX, which unlike most LSL constants is not an integer—instead, it's a single-character string. The single character is not printable but has a specific escape value (if run through llEscapeURL) in the range of %EF%B7%90–97. The below table shows each constant's invocation and escape code:

{{LSL Constants/JSON}}

==Json to LSL Conversion==

To directly extract a Json value to an LSL string:

string value = llJsonGetValue( string json, list specifiers );
* ''json'' is a string containing a valid json array or object value
* ''specifiers'' is a list of specifiers (see Specifying Json Elements)
* returns a json string
* if the specifiers do not indicate a value that exists in the input, [[JSON_INVALID]] is returned

To convert a json compound value (either an array or an object) to an LSL List:

list values = llJson2List( string json );
* ''json'' is a string containing a valid json array or object value
* If the string in json is not a valid json object or array a list with a single item matching the conversion above is returned.

==Recursive Parsing==

Since any value in a Json array or object may be any arbitrary type, including an array or object, the parsing methods must handle nested values. Nested arrays or objects are not converted, but remain LSL String values. If an LSL script needs to use the components in such a nested value, it must explicitly pass that string to the appropriate method. For example, the following json value is passed to llJson2List:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
a: 3.2,
b: true
}
}
</javascript>
The result would be an LSL list with a stride of 2: the first elements of the 3 strides would be "alpha", "beta", and "gamma". The second element of the first stride would be the integer 1, but the second elements of the other two strides would be LSL strings containing the json representation of the array '[ "x", "y", "z" ]' and object '{ a: 3.2, b: true }' respectively.

==LSL to Json==

To convert a list to json:
string json = llList2Json( string type, list values );
* ''type'' must be either [[JSON_ARRAY]] or [[JSON_OBJECT]]
* ''values'' is the list to be converted to json.

:Produces an LSL String containing a Json compound value, either an array or an object depending on type, containing the values in the input list.

:If type is [[JSON_ARRAY]], the list may contain values of any LSL type; they are converted as described in Type Conversions above.

:If type is [[JSON_OBJECT]], the list must have a stride of 2. The first value of each stride must be a string. The second value of each stride may be any LSL type, and are converted as described in Type Conversions above. [[JSON_INVALID]] is returned if the stride is not 2.

:[[JSON_INVALID]] is returned if any other string or json type is specified as the type.

To directly set a Json value within a string:

string jsonresult = llJsonSetValue( string json, list specifiers, string value );
* ''json'' is a string containing a valid json array or object value
* ''specifiers'' is a list of specifiers (see [[#Specifying Json Elements]])
* ''value'' the value to be inserted into the specified place in json
* Returns the newly modified json string

:The only failure mode for llJsonSetValue is if an array index is specified in specifiers that is negative (but not [[JSON_APPEND]]) or more greater than the list size. In all other cases the json is modified so that the set can succeed. For example if an integer is specified for a level that is an object, the object will be removed completely and replaced with an array. If the object key does not exist it will be added, and JSON_APPEND or an index one larger than the last item in an array can be used to append to an array. These features are to allow building a Json string with llJsonSetValue.

==Recursive Construction of Compound Json Values==

Since LSL does not support nested lists, the construction method may only be used to convert a single level; to create a Json array or object whose values are nested arrays or objects, the LSL script must first construct the nested values and then pass those values as strings to another construction method call. For example, to construct the Json value:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
a: 3.2,
b: true
}
}
</javascript>
The following sequence could be used:
<pre>
string gamma_value = llList2Json( JSON_OBJECT, [ "a", 3.2, "b", TRUE ] );
string beta_value = llList2Json( JSON_ARRAY, [ "x", "y", "z" ] );
string value = llList2Json( JSON_OBJECT,[ "alpha", 1, "beta", beta_value, "gamma", gamma_value ] );
</pre>
or the equivalent without the intermediate variables:
<lsl>
string value =
llList2Json( JSON_OBJECT,
["alpha", 1,
"beta", llList2Json( JSON_ARRAY, [ "x", "y", "z" ] ),
"gamma", llList2Json( JSON_OBJECT, [ "a", 3.2, "b", TRUE ] )]
);
</lsl>

Json usage in LSL

2013-06-23T14:10:02Z

Gistya Eusebio: adding note about how it picks from multiple members of the same name

{{LSL Header|lm=*}}{{LSLC|}}{{LSLC|JSON|*Json usage in LSL}}
==Type Conversions==

Json has native representation for:
* numbers - directly mappable to LSL Integer and Float (json numbers without a decimal point are assumed to be Integers, those with a decimal point are Floats)
* strings - identical to LSL [[String]]
* arrays - a list of values of any type: directly analogous to an LSL [[List]]
* objects - represented in LSL as a strided list of name/value pairs (see below re: values)
* the constants 'true' and 'false' - directly mapped to and from the LSL constants [[JSON_TRUE]] and [[JSON_FALSE]]
* the constant 'null' - directly mapped to and from the LSL constant [[JSON_NULL]]
* All other LSL types (Key, Rotation, and Vector) are implicitly converted to their string representation when converting to Json; when converting from Json to LSL, these values are returned as String values, so the script must explicitly convert using the existing conversion methods.

==New LSL Methods==
===Specifying Json Elements===

[[llJsonGetValue]], [[llJsonValueType]] and [[llJsonSetValue]] each take the same first two arguments:
1. a JSON value in the form of a [[String|string]], and
2. a set of specifiers in the form of a [[List|list]].
[[llJsonSetValue]] additionally takes a third an argument:
3. a JSON value in the form of a [[String|string]].

To understand specifiers one must generally understand that JSON data is structured in a [http://en.wikipedia.org/wiki/Nested_set_model nested set model]. LSL's built-in JSON parser uses the supplied "specifiers" list to perform [http://en.wikipedia.org/wiki/Tree_traversal tree traversal] on the nodes of the supplied JSON [http://en.wikipedia.org/wiki/Tree_(data_structure) tree data structure]. A JSON tree may be visualized as a set of hierarchical levels of parents and children. Each level is contained within '''curly braces {for objects, which are lists of members, that are defined as key-value pairs}''' or '''square braces [for arrays of elements, that are defined as single values]'''.

When JSON is presented in human-readable form, it is traditionally formatted such that the first parent level of organization is indented farthest to the left, and each more deeply-nested child level of organization is indented farther and farther to the right. The left-most level of nodes have no parents, only children. They begin with the very first member that appears after the initial "{" character of the JSON string (if it starts as an object), or the first element that appears after the initial "[" character (if it starts as an array). A node is considered as being a parent only if it has a non-null JSON object or array as its value.

With that parent-child tree data structure in mind, the specifiers list that you supply in the above functions tell LSL's JSON parser how to [http://en.wikipedia.org/wiki/Tree_(data_structure)#Traversal_methods walk the tree] of the JSON data that you have supplied with the first argument of the function. The first specifier in the list tells the LSL JSON parser which node to walk to first. The next specifier tells it which of that node's children to walk to. Once the LSL parser has "walked" to the last destination node specified by your list of specifiers, it will then perform the function on the JSON value that it finds there.

If, anywhere along the line, any of the specified nodes do not exist, [[llJsonGetValue]] and [[llJsonValueType]] will almost always return [[JSON_INVALID]]. However there is a rare exception: if any specifier in the list leads to a node that has no characters in its JSON string value, JSON_NULL will be returned instead of JSON_INVALID—no matter what might come after it in the specifiers list. For example in:

<lsl>
string parent = "{\"parent\":,}";
string test1 = llJsonGetValue(example,[parent]);
string test2 = llJsonGetValue(example,["parent","child that doesn't exist","etc."]);
</lsl>
test1 and test2 will both be JSON_NULL.

The same is true for arrays: a specifier pointing to any element of a valid array will return JSON_NULL anywhere there is no JSON value specified at given position in the array:

<lsl>
string "{\"parent\":[ , , , , ]}";
string test1 = llJsonGetValue(example,["parent",2]);
string test2 = llJsonGetValue(example,["parent",1,"child that does not exist","etc."]);
</lsl>
test1 and test2 will also both be JSON_NULL.

These types of scenarios may be useful in determining valid JSON paths for the setter: in all the scenarios where JSON_NULL is returned, the same set of specifiers is able to be successfully used for [[llJsonSetValue]]. However if [[JSON_INVALID]] is returned, there is no guarantee the setter won't return an error.

For [[llJsonGetValue]], if a JSON value is present at the specified node, it will be returned by the function. The value may an object that contains no valid JSON data, so be careful. Such an object will be deemed a [[JSON_OBJECT]] by [[llJsonValueType]], even if its contents are not valid JSON. Therefore it's always best to check the [[llJsonValueType]] of any specified value to make sure it's valid before using the information in your script.

{{LSL Tip|NOTE: if multiple members of the same name exist in the object, the function will return the value for the member closest to the end of the string!}}

The specifiers list may only consist of strings/keys (for object member keys), and integers (for array element positions), which define a path to the desired value in a JSON compound object.

* An empty list specifies the entire Json value.
* If the list is not empty, each element of the list is used to select the element at the same level of nesting in the JSON value:
** if the specifier list element is a string, then the corresponding element in the json value must be an object and the list element selects the value whose JSON name exactly matches the string.
** if the specifier list element is an integer, then the corresponding element in the json value must be an array and the list element is used as a zero-based index into the Json array.
* Additionally llJsonSetValue accepts [[JSON_APPEND]] as a specifier to indicate appending the value to the end of the array at that level. Be careful because If the value at that level is not an array, it will be overwritten and replaced with the array you're setting!

For example, given the JSON value:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
"a": 3.2,
"b": true
}
}
</javascript>
the contents of the string returned would be:
<lsl>
llJsonGetValue ( value, [ "alpha" ] ) ⇒ 1
llJsonGetValue ( value, [ "beta" ] ) ⇒ [ "x", "y", "z" ]
llJsonGetValue ( value, [ "beta", 2 ] ) ⇒ z
llJsonGetValue ( value, [ "gamma", "a" ] ) ⇒ 3.2
</lsl>

llJsonSetValue(string json, list specifiers, string value_to_set) will force the resulting JSON to conform with the specifiers supplied, as long as the specified path is traversable.

==Json Interrogation and Validation==

To determine the type of a json value:

<lsl>string type = llJsonValueType( string json, list specifiers );</lsl>

:returns one of several following special constants (see table below). Each constant has a name, JSON_XXXX, which unlike most LSL constants is not an integer—instead, it's a single-character string. The single character is not printable but has a specific escape value (if run through llEscapeURL) in the range of %EF%B7%90–97. The below table shows each constant's invocation and escape code:

{{LSL Constants/JSON}}

==Json to LSL Conversion==

To directly extract a Json value to an LSL string:

string value = llJsonGetValue( string json, list specifiers );
* ''json'' is a string containing a valid json array or object value
* ''specifiers'' is a list of specifiers (see Specifying Json Elements)
* returns a json string
* if the specifiers do not indicate a value that exists in the input, [[JSON_INVALID]] is returned

To convert a json compound value (either an array or an object) to an LSL List:

list values = llJson2List( string json );
* ''json'' is a string containing a valid json array or object value
* If the string in json is not a valid json object or array a list with a single item matching the conversion above is returned.

==Recursive Parsing==

Since any value in a Json array or object may be any arbitrary type, including an array or object, the parsing methods must handle nested values. Nested arrays or objects are not converted, but remain LSL String values. If an LSL script needs to use the components in such a nested value, it must explicitly pass that string to the appropriate method. For example, the following json value is passed to llJson2List:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
a: 3.2,
b: true
}
}
</javascript>
The result would be an LSL list with a stride of 2: the first elements of the 3 strides would be "alpha", "beta", and "gamma". The second element of the first stride would be the integer 1, but the second elements of the other two strides would be LSL strings containing the json representation of the array '[ "x", "y", "z" ]' and object '{ a: 3.2, b: true }' respectively.

==LSL to Json==

To convert a list to json:
string json = llList2Json( string type, list values );
* ''type'' must be either [[JSON_ARRAY]] or [[JSON_OBJECT]]
* ''values'' is the list to be converted to json.

:Produces an LSL String containing a Json compound value, either an array or an object depending on type, containing the values in the input list.

:If type is [[JSON_ARRAY]], the list may contain values of any LSL type; they are converted as described in Type Conversions above.

:If type is [[JSON_OBJECT]], the list must have a stride of 2. The first value of each stride must be a string. The second value of each stride may be any LSL type, and are converted as described in Type Conversions above. [[JSON_INVALID]] is returned if the stride is not 2.

:[[JSON_INVALID]] is returned if any other string or json type is specified as the type.

To directly set a Json value within a string:

string jsonresult = llJsonSetValue( string json, list specifiers, string value );
* ''json'' is a string containing a valid json array or object value
* ''specifiers'' is a list of specifiers (see [[#Specifying Json Elements]])
* ''value'' the value to be inserted into the specified place in json
* Returns the newly modified json string

:The only failure mode for llJsonSetValue is if an array index is specified in specifiers that is negative (but not [[JSON_APPEND]]) or more greater than the list size. In all other cases the json is modified so that the set can succeed. For example if an integer is specified for a level that is an object, the object will be removed completely and replaced with an array. If the object key does not exist it will be added, and JSON_APPEND or an index one larger than the last item in an array can be used to append to an array. These features are to allow building a Json string with llJsonSetValue.

==Recursive Construction of Compound Json Values==

Since LSL does not support nested lists, the construction method may only be used to convert a single level; to create a Json array or object whose values are nested arrays or objects, the LSL script must first construct the nested values and then pass those values as strings to another construction method call. For example, to construct the Json value:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
a: 3.2,
b: true
}
}
</javascript>
The following sequence could be used:
<pre>
string gamma_value = llList2Json( JSON_OBJECT, [ "a", 3.2, "b", TRUE ] );
string beta_value = llList2Json( JSON_ARRAY, [ "x", "y", "z" ] );
string value = llList2Json( JSON_OBJECT,[ "alpha", 1, "beta", beta_value, "gamma", gamma_value ] );
</pre>
or the equivalent without the intermediate variables:
<lsl>
string value =
llList2Json( JSON_OBJECT,
["alpha", 1,
"beta", llList2Json( JSON_ARRAY, [ "x", "y", "z" ] ),
"gamma", llList2Json( JSON_OBJECT, [ "a", 3.2, "b", TRUE ] )]
);
</lsl>

Json usage in LSL

2013-06-19T22:05:36Z

Gistya Eusebio: spelling correction

{{LSL Header|lm=*}}{{LSLC|}}{{LSLC|JSON|*Json usage in LSL}}
==Type Conversions==

Json has native representation for:
* numbers - directly mappable to LSL Integer and Float (json numbers without a decimal point are assumed to be Integers, those with a decimal point are Floats)
* strings - identical to LSL [[String]]
* arrays - a list of values of any type: directly analogous to an LSL [[List]]
* objects - represented in LSL as a strided list of name/value pairs (see below re: values)
* the constants 'true' and 'false' - directly mapped to and from the LSL constants [[JSON_TRUE]] and [[JSON_FALSE]]
* the constant 'null' - directly mapped to and from the LSL constant [[JSON_NULL]]
* All other LSL types (Key, Rotation, and Vector) are implicitly converted to their string representation when converting to Json; when converting from Json to LSL, these values are returned as String values, so the script must explicitly convert using the existing conversion methods.

==New LSL Methods==
===Specifying Json Elements===

[[llJsonGetValue]], [[llJsonValueType]] and [[llJsonSetValue]] each take the same first two arguments:
1. a JSON value in the form of a [[String|string]], and
2. a set of specifiers in the form of a [[List|list]].
[[llJsonSetValue]] additionally takes a third an argument:
3. a JSON value in the form of a [[String|string]].

To understand specifiers one must generally understand that JSON data is structured in a [http://en.wikipedia.org/wiki/Nested_set_model nested set model]. LSL's built-in JSON parser uses the supplied "specifiers" list to perform [http://en.wikipedia.org/wiki/Tree_traversal tree traversal] on the nodes of the supplied JSON [http://en.wikipedia.org/wiki/Tree_(data_structure) tree data structure]. A JSON tree may be visualized as a set of hierarchical levels of parents and children. Each level is contained within '''curly braces {for objects, which are lists of members, that are defined as key-value pairs}''' or '''square braces [for arrays of elements, that are defined as single values]'''.

When JSON is presented in human-readable form, it is traditionally formatted such that the first parent level of organization is indented farthest to the left, and each more deeply-nested child level of organization is indented farther and farther to the right. The left-most level of nodes have no parents, only children. They begin with the very first member that appears after the initial "{" character of the JSON string (if it starts as an object), or the first element that appears after the initial "[" character (if it starts as an array). A node is considered as being a parent only if it has a non-null JSON object or array as its value.

With that parent-child tree data structure in mind, the specifiers list that you supply in the above functions tell LSL's JSON parser how to [http://en.wikipedia.org/wiki/Tree_(data_structure)#Traversal_methods walk the tree] of the JSON data that you have supplied with the first argument of the function. The first specifier in the list tells the LSL JSON parser which node to walk to first. The next specifier tells it which of that node's children to walk to. Once the LSL parser has "walked" to the last destination node specified by your list of specifiers, it will then perform the function on the JSON value that it finds there.

If, anywhere along the line, any of the specified nodes do not exist, [[llJsonGetValue]] and [[llJsonValueType]] will almost always return [[JSON_INVALID]]. However there is a rare exception: if any specifier in the list leads to a node that has no characters in its JSON string value, JSON_NULL will be returned instead of JSON_INVALID—no matter what might come after it in the specifiers list. For example in:

<lsl>
string parent = "{\"parent\":,}";
string test1 = llJsonGetValue(example,[parent]);
string test2 = llJsonGetValue(example,["parent","child that doesn't exist","etc."]);
</lsl>
test1 and test2 will both be JSON_NULL.

The same is true for arrays: a specifier pointing to any element of a valid array will return JSON_NULL anywhere there is no JSON value specified at given position in the array:

<lsl>
string "{\"parent\":[ , , , , ]}";
string test1 = llJsonGetValue(example,["parent",2]);
string test2 = llJsonGetValue(example,["parent",1,"child that does not exist","etc."]);
</lsl>
test1 and test2 will also both be JSON_NULL.

These types of scenarios may be useful in determining valid JSON paths for the setter: in all the scenarios where JSON_NULL is returned, the same set of specifiers is able to be successfully used for [[llJsonSetValue]]. However if [[JSON_INVALID]] is returned, there is no guarantee the setter won't return an error.

For [[llJsonGetValue]], if a JSON value is present, it will be returned by the function. The value may an object that contains no valid JSON data, so be careful. Such an object will be deemed a [[JSON_OBJECT]] by [[llJsonValueType]], even if its contents are not valid JSON. Therefore it's always best to check the [[llJsonGetType]] of any specified value to make sure it's valid before using the information in your script.

The specifiers list may only consist of strings/keys (for object member keys), and integers (for array element positions), which define a path to the desired value in a JSON compound object.

* An empty list specifies the entire Json value.
* If the list is not empty, each element of the list is used to select the element at the same level of nesting in the JSON value:
** if the specifier list element is a string, then the corresponding element in the json value must be an object and the list element selects the value whose JSON name exactly matches the string.
** if the specifier list element is an integer, then the corresponding element in the json value must be an array and the list element is used as a zero-based index into the Json array.
* Additionally llJsonSetValue accepts [[JSON_APPEND]] as a specifier to indicate appending the value to the end of the array at that level. Be careful because If the value at that level is not an array, it will be overwritten and replaced with the array you're setting!

For example, given the JSON value:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
"a": 3.2,
"b": true
}
}
</javascript>
the contents of the string returned would be:
<lsl>
llJsonGetValue ( value, [ "alpha" ] ) ⇒ 1
llJsonGetValue ( value, [ "beta" ] ) ⇒ [ "x", "y", "z" ]
llJsonGetValue ( value, [ "beta", 2 ] ) ⇒ z
llJsonGetValue ( value, [ "gamma", "a" ] ) ⇒ 3.2
</lsl>

llJsonSetValue(string json, list specifiers, string value_to_set) will force the resulting JSON to conform with the specifiers supplied, as long as the specified path is traversable.

==Json Interrogation and Validation==

To determine the type of a json value:

<lsl>string type = llJsonValueType( string json, list specifiers );</lsl>

:returns one of several following special constants (see table below). Each constant has a name, JSON_XXXX, which unlike most LSL constants is not an integer—instead, it's a single-character string. The single character is not printable but has a specific escape value (if run through llEscapeURL) in the range of %EF%B7%90–97. The below table shows each constant's invocation and escape code:

{{LSL Constants/JSON}}

==Json to LSL Conversion==

To directly extract a Json value to an LSL string:

string value = llJsonGetValue( string json, list specifiers );
* ''json'' is a string containing a valid json array or object value
* ''specifiers'' is a list of specifiers (see Specifying Json Elements)
* returns a json string
* if the specifiers do not indicate a value that exists in the input, [[JSON_INVALID]] is returned

To convert a json compound value (either an array or an object) to an LSL List:

list values = llJson2List( string json );
* ''json'' is a string containing a valid json array or object value
* If the string in json is not a valid json object or array a list with a single item matching the conversion above is returned.

==Recursive Parsing==

Since any value in a Json array or object may be any arbitrary type, including an array or object, the parsing methods must handle nested values. Nested arrays or objects are not converted, but remain LSL String values. If an LSL script needs to use the components in such a nested value, it must explicitly pass that string to the appropriate method. For example, the following json value is passed to llJson2List:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
a: 3.2,
b: true
}
}
</javascript>
The result would be an LSL list with a stride of 2: the first elements of the 3 strides would be "alpha", "beta", and "gamma". The second element of the first stride would be the integer 1, but the second elements of the other two strides would be LSL strings containing the json representation of the array '[ "x", "y", "z" ]' and object '{ a: 3.2, b: true }' respectively.

==LSL to Json==

To convert a list to json:
string json = llList2Json( string type, list values );
* ''type'' must be either [[JSON_ARRAY]] or [[JSON_OBJECT]]
* ''values'' is the list to be converted to json.

:Produces an LSL String containing a Json compound value, either an array or an object depending on type, containing the values in the input list.

:If type is [[JSON_ARRAY]], the list may contain values of any LSL type; they are converted as described in Type Conversions above.

:If type is [[JSON_OBJECT]], the list must have a stride of 2. The first value of each stride must be a string. The second value of each stride may be any LSL type, and are converted as described in Type Conversions above. [[JSON_INVALID]] is returned if the stride is not 2.

:[[JSON_INVALID]] is returned if any other string or json type is specified as the type.

To directly set a Json value within a string:

string jsonresult = llJsonSetValue( string json, list specifiers, string value );
* ''json'' is a string containing a valid json array or object value
* ''specifiers'' is a list of specifiers (see [[#Specifying Json Elements]])
* ''value'' the value to be inserted into the specified place in json
* Returns the newly modified json string

:The only failure mode for llJsonSetValue is if an array index is specified in specifiers that is negative (but not [[JSON_APPEND]]) or more greater than the list size. In all other cases the json is modified so that the set can succeed. For example if an integer is specified for a level that is an object, the object will be removed completely and replaced with an array. If the object key does not exist it will be added, and JSON_APPEND or an index one larger than the last item in an array can be used to append to an array. These features are to allow building a Json string with llJsonSetValue.

==Recursive Construction of Compound Json Values==

Since LSL does not support nested lists, the construction method may only be used to convert a single level; to create a Json array or object whose values are nested arrays or objects, the LSL script must first construct the nested values and then pass those values as strings to another construction method call. For example, to construct the Json value:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
a: 3.2,
b: true
}
}
</javascript>
The following sequence could be used:
<pre>
string gamma_value = llList2Json( JSON_OBJECT, [ "a", 3.2, "b", TRUE ] );
string beta_value = llList2Json( JSON_ARRAY, [ "x", "y", "z" ] );
string value = llList2Json( JSON_OBJECT,[ "alpha", 1, "beta", beta_value, "gamma", gamma_value ] );
</pre>
or the equivalent without the intermediate variables:
<lsl>
string value =
llList2Json( JSON_OBJECT,
["alpha", 1,
"beta", llList2Json( JSON_ARRAY, [ "x", "y", "z" ] ),
"gamma", llList2Json( JSON_OBJECT, [ "a", 3.2, "b", TRUE ] )]
);
</lsl>

Json usage in LSL

2013-06-19T17:26:16Z

Gistya Eusebio: further formatting and corrections on my change

{{LSL Header|lm=*}}{{LSLC|}}{{LSLC|JSON|*Json usage in LSL}}
==Type Conversions==

Json has native representation for:
* numbers - directly mappable to LSL Integer and Float (json numbers without a decimal point are assumed to be Integers, those with a decimal point are Floats)
* strings - identical to LSL [[String]]
* arrays - a list of values of any type: directly analogous to an LSL [[List]]
* objects - represented in LSL as a strided list of name/value pairs (see below re: values)
* the constants 'true' and 'false' - directly mapped to and from the LSL constants [[JSON_TRUE]] and [[JSON_FALSE]]
* the constant 'null' - directly mapped to and from the LSL constant [[JSON_NULL]]
* All other LSL types (Key, Rotation, and Vector) are implicitly converted to their string representation when converting to Json; when converting from Json to LSL, these values are returned as String values, so the script must explicitly convert using the existing conversion methods.

==New LSL Methods==
===Specifying Json Elements===

[[llJsonGetValue]], [[llJsonValueType]] and [[llJsonSetValue]] each take the same first two arguments:
1. a JSON value in the form of a [[String|string]], and
2. a set of specifiers in the form of a [[List|list]].
[[llJsonSetValue]] additionally takes a third an argument:
3. a JSON value in the form of a [[String|string]].

To understand specifiers one must generally understand that JSON data is structured in a [http://en.wikipedia.org/wiki/Nested_set_model nested set model]. LSL's built-in JSON parser uses the supplied "specifiers" list to perform [http://en.wikipedia.org/wiki/Tree_traversal tree traversal] on the nodes of the supplied JSON [http://en.wikipedia.org/wiki/Tree_(data_structure) tree data structure]. A JSON tree may be visualized as a set of hierarchical levels of parents and children. Each level is contained within '''curly braces {for objects, which are lists of members, that are defined as key-value pairs}''' or '''square braces [for arrays of elements, that are defined as single values]'''.

When JSON is presented in human-readable form, it is traditionally formatted such that the first parent level of organization is indented farthest to the left, and each more deeply-nested child level of organization is indented farther and farther to the right. The left-most level of nodes have no parents, only children. They begin with the very first member that appears after the initial "{" character of the JSON string (if it starts as an object), or the first element that appears after the initial "[" character (if it starts as an array). A node is considered as being a parent only if it has a non-null JSON object or array as its value.

With that parent-child tree data structure in mind, the specifiers list that you supply in the above functions tell LSL's JSON parser how to [http://en.wikipedia.org/wiki/Tree_(data_structure)#Traversal_methods walk the tree] of the JSON data that you have supplied with the first argument of the function. The first specifier in the list tells the LSL JSON parser which node to walk to first. The next specifier tells it which of that node's children to walk to. Once the LSL parser has "walked" to the last destination node specified by your list of specifiers, it will then perform the function on the JSON value that it finds there.

If, anywhere along the line, any of the specified nodes do not exist, [[llJsonGetValue]] and [[llJsonValueType]] will almost always return [[JSON_INVALID]]. However there is a rare exception: if any specifier in the list leads to a node that has no characters in its JSON string value, JSON_NULL will be returned instead of JSON_INVALID—no matter what might come after it in the specifiers list. For example in:

<lsl>
string parent = "{\"parent\":,}";
string test1 = llJsonGetValue(example,[parent]);
string test2 = llJsonGetValue(example,["parent","child that doesn't exist","etc."]);
</lsl>
test1 and test2 will both be JSON_NULL.

The same is true for arrays: a specifier pointing to any element of a valid array will return JSON_NULL anywhere there is no JSON value specified at given position in the array:

<lsl>
string "{\"parent\":[ , , , , ]}";
string test1 = llJsonGetValue(example,["parent",2]);
string test2 = llJsonGetValue(example,["parent",1,"child that does not exist","etc."]);
</lsl>
test1 and test2 will also both be JSON_NULL.

These types of scenarios may be useful in determining valid JSON paths for the setter: in all the scenarios where JSON_NULL is returned, the same set of specifiers is able to be successfully used for [[llJsonSetValue]]. However if [[JSON_INVALID]] is returned, there is no guarantee the setter won't return an error.

For [[llJsonGetValue]], if a JSON value is present, it will be returned by the function. The value may an object that contains no valid JSON data, so be careful. Such an object will be deemed a [[JSON_OBJECT]] by [[llGetJsonType]], even if its contents are not valid JSON. Therefore it's always best to check the [[llJsonGetType]] of any specified value to make sure it's valid before using the information in your script.

The specifiers list may only consist of strings/keys (for object member keys), and integers (for array element positions), which define a path to the desired value in a JSON compound object.

* An empty list specifies the entire Json value.
* If the list is not empty, each element of the list is used to select the element at the same level of nesting in the JSON value:
** if the specifier list element is a string, then the corresponding element in the json value must be an object and the list element selects the value whose JSON name exactly matches the string.
** if the specifier list element is an integer, then the corresponding element in the json value must be an array and the list element is used as a zero-based index into the Json array.
* Additionally llJsonSetValue accepts [[JSON_APPEND]] as a specifier to indicate appending the value to the end of the array at that level. Be careful because If the value at that level is not an array, it will be overwritten and replaced with the array you're setting!

For example, given the JSON value:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
"a": 3.2,
"b": true
}
}
</javascript>
the contents of the string returned would be:
<lsl>
llJsonGetValue ( value, [ "alpha" ] ) ⇒ 1
llJsonGetValue ( value, [ "beta" ] ) ⇒ [ "x", "y", "z" ]
llJsonGetValue ( value, [ "beta", 2 ] ) ⇒ z
llJsonGetValue ( value, [ "gamma", "a" ] ) ⇒ 3.2
</lsl>

llJsonSetValue(string json, list specifiers, string value_to_set) will force the resulting JSON to conform with the specifiers supplied, as long as the specified path is traversable.

==Json Interrogation and Validation==

To determine the type of a json value:

<lsl>string type = llJsonValueType( string json, list specifiers );</lsl>

:returns one of several following special constants (see table below). Each constant has a name, JSON_XXXX, which unlike most LSL constants is not an integer—instead, it's a single-character string. The single character is not printable but has a specific escape value (if run through llEscapeURL) in the range of %EF%B7%90–97. The below table shows each constant's invocation and escape code:

{| class="wikitable"
|-
! Contant !! Escape value
|-
| [[JSON_INVALID]] || %EF%B7%90
|-
| [[JSON_OBJECT]] || %EF%B7%91
|-
| [[JSON_ARRAY]] || %EF%B7%92
|-
| [[JSON_NUMBER]] || %EF%B7%93
|-
| [[JSON_STRING]] || %EF%B7%94
|-
| [[JSON_NULL]] || %EF%B7%95
|-
| [[JSON_TRUE]] || %EF%B7%96
|-
| [[JSON_FALSE]] || %EF%B7%97
|}

==Json to LSL Conversion==

To directly extract a Json value to an LSL string:

string value = llJsonGetValue( string json, list specifiers );
* ''json'' is a string containing a valid json array or object value
* ''specifiers'' is a list of specifiers (see Specifying Json Elements)
* returns a json string
* if the specifiers do not indicate a value that exists in the input, [[JSON_INVALID]] is returned

To convert a json compound value (either an array or an object) to an LSL List:

list values = llJson2List( string json );
* ''json'' is a string containing a valid json array or object value
* If the string in json is not a valid json object or array a list with a single item matching the conversion above is returned.

==Recursive Parsing==

Since any value in a Json array or object may be any arbitrary type, including an array or object, the parsing methods must handle nested values. Nested arrays or objects are not converted, but remain LSL String values. If an LSL script needs to use the components in such a nested value, it must explicitly pass that string to the appropriate method. For example, the following json value is passed to llJson2List:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
a: 3.2,
b: true
}
}
</javascript>
The result would be an LSL list with a stride of 2: the first elements of the 3 strides would be "alpha", "beta", and "gamma". The second element of the first stride would be the integer 1, but the second elements of the other two strides would be LSL strings containing the json representation of the array '[ "x", "y", "z" ]' and object '{ a: 3.2, b: true }' respectively.

==LSL to Json==

To convert a list to json:
string json = llList2Json( string type, list values );
* ''type'' must be either [[JSON_ARRAY]] or [[JSON_OBJECT]]
* ''values'' is the list to be converted to json.

:Produces an LSL String containing a Json compound value, either an array or an object depending on type, containing the values in the input list.

:If type is [[JSON_ARRAY]], the list may contain values of any LSL type; they are converted as described in Type Conversions above.

:If type is [[JSON_OBJECT]], the list must have a stride of 2. The first value of each stride must be a string. The second value of each stride may be any LSL type, and are converted as described in Type Conversions above. [[JSON_INVALID] is returned if the stride is not 2.

:[[JSON_INVALID]] is returned if any other string or json type is specified as the type.

To directly set a Json value within a string:

string jsonresult = llJsonSetValue( string json, list specifiers, string value );
* ''json'' is a string containing a valid json array or object value
* ''specifiers'' is a list of specifiers (see [[#Specifying Json Elements]])
* ''value'' the value to be inserted into the specified place in json
* Returns the newly modified json string

:The only failure mode for llJsonSetValue is if an array index is specified in specifiers that is negative (but not [[JSON_APPEND]]) or more greater than the list size. In all other cases the json is modified so that the set can succeed. For example if an integer is specified for a level that is an object, the object will be removed completely and replaced with an array. If the object key does not exist it will be added, and JSON_APPEND or an index one larger than the last item in an array can be used to append to an array. These features are to allow building a Json string with llJsonSetValue.

==Recursive Construction of Compound Json Values==

Since LSL does not support nested lists, the construction method may only be used to convert a single level; to create a Json array or object whose values are nested arrays or objects, the LSL script must first construct the nested values and then pass those values as strings to another construction method call. For example, to construct the Json value:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
a: 3.2,
b: true
}
}
</javascript>
The following sequence could be used:
<pre>
string gamma_value = llList2Json( JSON_OBJECT, [ "a", 3.2, "b", TRUE ] );
string beta_value = llList2Json( JSON_ARRAY, [ "x", "y", "z" ] );
string value = llList2Json( JSON_OBJECT,[ "alpha", 1, "beta", beta_value, "gamma", gamma_value ] );
</pre>
or the equivalent without the intermediate variables:
<lsl>
string value =
llList2Json( JSON_OBJECT,
["alpha", 1,
"beta", llList2Json( JSON_ARRAY, [ "x", "y", "z" ] ),
"gamma", llList2Json( JSON_OBJECT, [ "a", 3.2, "b", TRUE ] )]
);
</lsl>

Json usage in LSL

2013-06-19T17:05:00Z

Gistya Eusebio: /* Specifying Json Elements */

{{LSL Header|lm=*}}{{LSLC|}}{{LSLC|JSON|*Json usage in LSL}}
==Type Conversions==

Json has native representation for:
* numbers - directly mappable to LSL Integer and Float (json numbers without a decimal point are assumed to be Integers, those with a decimal point are Floats)
* strings - identical to LSL [[String]]
* arrays - a list of values of any type: directly analogous to an LSL [[List]]
* objects - represented in LSL as a strided list of name/value pairs (see below re: values)
* the constants 'true' and 'false' - directly mapped to and from the LSL constants [[JSON_TRUE]] and [[JSON_FALSE]]
* the constant 'null' - directly mapped to and from the LSL constant [[JSON_NULL]]
* All other LSL types (Key, Rotation, and Vector) are implicitly converted to their string representation when converting to Json; when converting from Json to LSL, these values are returned as String values, so the script must explicitly convert using the existing conversion methods.

==New LSL Methods==
===Specifying Json Elements===

[[llJsonGetValue]], [[llJsonValueType]] and [[llJsonSetValue]] each take the same first two arguments:
1. a JSON value in the form of a [[String|string]], and
2. a set of specifiers in the form of a [[List|list]].
[[llJsonSetValue]] additionally takes a third an argument:
3. a JSON value in the form of a [[String|string]].

To understand specifiers one must generally understand that JSON data is structured in a [http://en.wikipedia.org/wiki/Nested_set_model nested set model]. LSL's built-in JSON parser uses the supplied "specifiers" list to perform [http://en.wikipedia.org/wiki/Tree_traversal tree traversal] on the nodes of the supplied JSON [http://en.wikipedia.org/wiki/Tree_(data_structure) tree data structure]. A JSON tree may be visualized as a set of hierarchical levels of parents and children. Each level is contained within '''curly braces {for objects, which are lists of members, that are defined as key-value pairs}''' or '''square braces [for arrays of elements, that are defined as single values]'''. When JSON is presented in human-readable form, it is traditionally formatted such that the first parent level of organization is indented farthest to the left, and each more deeply-nested child level of organization is indented farther and farther to the right. The left-most level of nodes have no parents, only children. They begin with the very first member that appears after the initial "{" character of the JSON string (if it starts as an object), or the first element that appears after the initial "[" character (if it starts as an array). A node is considered as being a parent only if it has a non-null JSON object or array as its value -- and if a node has no value, then its value is considered to be "null" (strings "{}" or "[]" or "").

With that parent-child tree data structure in mind, the specifiers list that you supply in the above function tells tells LSL's JSON parser how to [http://en.wikipedia.org/wiki/Tree_(data_structure)#Traversal_methods walk the tree] of the JSON data that you have supplied with the first argument of the function. The first specifier in the list tells the LSL JSON parser which node to walk to first. The next specifier tells it which of that node's children to walk to. Once the LSL parser has "walked" to the last destination node specified by your list of specifiers, it will then perform the function on the JSON value that it finds there.

If, anywhere along the line, any of the specified nodes do not exist, [[llJsonGetValue]] and [[llJsonValueType]] will almost always return [[JSON_INVALID]]. However there is a rare exception: if the specifiers list leads to a node that has no characters in its JSON string value, no matter what follows that "null-value node" in the specifiers list, JSON_NULL will be returned instead of JSON_INVALID -- even though, obviously, none of the following specifiers exist. For example, for the example object {"parent":,} llJsonGetValue(example,["parent"]) will return JSON_NULL, as will llJsonGetValue(example,["parent","child that doesn't exist","etc."]). Another example: a specifier pointing to any element of a valid array such as {"parent":[ , , , , ]} will return JSON_NULL anywhere there is no JSON value specified at given position in the array; in this case llJsonGetValue(example,["parent",2]) returns JSON_NULL, as does llJsonGetValue(example,["parent",1,"child that does not exist","etc."]). These rare scenarios may be useful in determining valid JSON paths for the setter: in all the scenarios where JSON_NULL is returned, the same set of specifiers is able to be used for [[llJsonSetValue]] -- whereas if JSON_INVALID is returned, there is no guarantee the setter won't return an error.

For llJsonGetValue(), if a JSON value is present, it will be returned by the function. The value may an object that contains no valid JSON data, so be careful. Such an object will be deemed a JSON_OBJECT by llGetJsonType(), even if its contents are not valid JSON. Therefore it's always best to check the llJsonType() of any specified value to make sure it's valid before using the information in your script.

The specifiers list may only consist of strings/keys (for object member keys), and integers (for array element positions), which define a path to the desired value in a JSON compound object.

* An empty list specifies the entire Json value.
* If the list is not empty, each element of the list is used to select the element at the same level of nesting in the Json value:
** if the specifier list element is a string, then the corresponding element in the json value must be an object and the list element selects the value whose Json name exactly matches the string.
** if the specifier list element is an integer, then the corresponding element in the json value must be an array and the list element is used as a zero-based index into the Json array.
* Additionally llJsonSetValue accepts [[JSON_APPEND]] as a specifier to indicate appending the value to the end of the array at that level.

For example, given the json value:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
"a": 3.2,
"b": true
}
}
</javascript>
the contents of the string returned would be:
<lsl>
llJsonGetValue ( value, [ "alpha" ] ) ⇒ 1
llJsonGetValue ( value, [ "beta" ] ) ⇒ [ "x", "y", "z" ]
llJsonGetValue ( value, [ "beta", 2 ] ) ⇒ z
llJsonGetValue ( value, [ "gamma", "a" ] ) ⇒ 3.2
</lsl>

llJsonSetValue(string json, list specifiers, string value_to_set) will force the resulting JSON to conform with the specifiers supplied, as long as the specified path is traversable.

==Json Interrogation and Validation==

To determine the type of a json value:

<lsl>string type = llJsonValueType( string json, list specifiers );</lsl>

:returns one of several following special constants (see table below). Each constant has a name, JSON_XXXX, which unlike most LSL constants is not an integer—instead, it's a single-character string. The single character is not printable but has a specific escape value (if run through llEscapeURL) in the range of %EF%B7%90–97. The below table shows each constant's invocation and escape code:

{| class="wikitable"
|-
! Contant !! Escape value
|-
| [[JSON_INVALID]] || %EF%B7%90
|-
| [[JSON_OBJECT]] || %EF%B7%91
|-
| [[JSON_ARRAY]] || %EF%B7%92
|-
| [[JSON_NUMBER]] || %EF%B7%93
|-
| [[JSON_STRING]] || %EF%B7%94
|-
| [[JSON_NULL]] || %EF%B7%95
|-
| [[JSON_TRUE]] || %EF%B7%96
|-
| [[JSON_FALSE]] || %EF%B7%97
|}

==Json to LSL Conversion==

To directly extract a Json value to an LSL string:

string value = llJsonGetValue( string json, list specifiers );
* ''json'' is a string containing a valid json array or object value
* ''specifiers'' is a list of specifiers (see Specifying Json Elements)
* returns a json string
* if the specifiers do not indicate a value that exists in the input, [[JSON_INVALID]] is returned

To convert a json compound value (either an array or an object) to an LSL List:

list values = llJson2List( string json );
* ''json'' is a string containing a valid json array or object value
* If the string in json is not a valid json object or array a list with a single item matching the conversion above is returned.

==Recursive Parsing==

Since any value in a Json array or object may be any arbitrary type, including an array or object, the parsing methods must handle nested values. Nested arrays or objects are not converted, but remain LSL String values. If an LSL script needs to use the components in such a nested value, it must explicitly pass that string to the appropriate method. For example, the following json value is passed to llJson2List:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
a: 3.2,
b: true
}
}
</javascript>
The result would be an LSL list with a stride of 2: the first elements of the 3 strides would be "alpha", "beta", and "gamma". The second element of the first stride would be the integer 1, but the second elements of the other two strides would be LSL strings containing the json representation of the array '[ "x", "y", "z" ]' and object '{ a: 3.2, b: true }' respectively.

==LSL to Json==

To convert a list to json:
string json = llList2Json( string type, list values );
* ''type'' must be either [[JSON_ARRAY]] or [[JSON_OBJECT]]
* ''values'' is the list to be converted to json.

:Produces an LSL String containing a Json compound value, either an array or an object depending on type, containing the values in the input list.

:If type is [[JSON_ARRAY]], the list may contain values of any LSL type; they are converted as described in Type Conversions above.

:If type is [[JSON_OBJECT]], the list must have a stride of 2. The first value of each stride must be a string. The second value of each stride may be any LSL type, and are converted as described in Type Conversions above. [[JSON_INVALID] is returned if the stride is not 2.

:[[JSON_INVALID]] is returned if any other string or json type is specified as the type.

To directly set a Json value within a string:

string jsonresult = llJsonSetValue( string json, list specifiers, string value );
* ''json'' is a string containing a valid json array or object value
* ''specifiers'' is a list of specifiers (see [[#Specifying Json Elements]])
* ''value'' the value to be inserted into the specified place in json
* Returns the newly modified json string

:The only failure mode for llJsonSetValue is if an array index is specified in specifiers that is negative (but not [[JSON_APPEND]]) or more greater than the list size. In all other cases the json is modified so that the set can succeed. For example if an integer is specified for a level that is an object, the object will be removed completely and replaced with an array. If the object key does not exist it will be added, and JSON_APPEND or an index one larger than the last item in an array can be used to append to an array. These features are to allow building a Json string with llJsonSetValue.

==Recursive Construction of Compound Json Values==

Since LSL does not support nested lists, the construction method may only be used to convert a single level; to create a Json array or object whose values are nested arrays or objects, the LSL script must first construct the nested values and then pass those values as strings to another construction method call. For example, to construct the Json value:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
a: 3.2,
b: true
}
}
</javascript>
The following sequence could be used:
<pre>
string gamma_value = llList2Json( JSON_OBJECT, [ "a", 3.2, "b", TRUE ] );
string beta_value = llList2Json( JSON_ARRAY, [ "x", "y", "z" ] );
string value = llList2Json( JSON_OBJECT,[ "alpha", 1, "beta", beta_value, "gamma", gamma_value ] );
</pre>
or the equivalent without the intermediate variables:
<lsl>
string value =
llList2Json( JSON_OBJECT,
["alpha", 1,
"beta", llList2Json( JSON_ARRAY, [ "x", "y", "z" ] ),
"gamma", llList2Json( JSON_OBJECT, [ "a", 3.2, "b", TRUE ] )]
);
</lsl>

Json usage in LSL

2013-06-19T17:04:16Z

Gistya Eusebio: /* Specifying Json Elements */

{{LSL Header|lm=*}}{{LSLC|}}{{LSLC|JSON|*Json usage in LSL}}
==Type Conversions==

Json has native representation for:
* numbers - directly mappable to LSL Integer and Float (json numbers without a decimal point are assumed to be Integers, those with a decimal point are Floats)
* strings - identical to LSL [[String]]
* arrays - a list of values of any type: directly analogous to an LSL [[List]]
* objects - represented in LSL as a strided list of name/value pairs (see below re: values)
* the constants 'true' and 'false' - directly mapped to and from the LSL constants [[JSON_TRUE]] and [[JSON_FALSE]]
* the constant 'null' - directly mapped to and from the LSL constant [[JSON_NULL]]
* All other LSL types (Key, Rotation, and Vector) are implicitly converted to their string representation when converting to Json; when converting from Json to LSL, these values are returned as String values, so the script must explicitly convert using the existing conversion methods.

==New LSL Methods==
===Specifying Json Elements===

[[llJsonGetValue]], [[llJsonValueType]] and [[llJsonSetValue]] each take the same first two arguments:
1. a JSON value in the form of a [[String|string]], and
2. a set of specifiers in the form of a [[List|list]].
[[llJsonSetValue]] additionally takes a third an argument:
3. a JSON value in the form of a [[String|string]].

To understand specifiers one must generally understand that JSON data is structured in a [http://en.wikipedia.org/wiki/Nested_set_model nested set model]. LSL's built-in JSON parser uses the supplied "specifiers" list to perform [http://en.wikipedia.org/wiki/Tree_traversal tree traversal] on the nodes of the supplied JSON [http://en.wikipedia.org/wiki/Tree_(data_structure) tree data structure]. A JSON tree may be visualized as a set of hierarchical levels of parents and children. Each level is contained within '''curly braces {for objects, which are lists of members, that are defined as key-value pairs}''' or '''square braces [for arrays of elements, that are defined as single values]'''. When JSON is presented in a human-readable, it is traditionally formatted such that the first parent level of organization is indented farthest to the left, and each more deeply-nested child level of organization is indented farther and farther to the right. The left-most level of nodes have no parents, only children. They begin with the very first member that appears after the initial "{" character of the JSON string (if it starts as an object), or the first element that appears after the initial "[" character (if it starts as an array). A node is considered as being a parent only if it has a non-null JSON object or array as its value -- and if a node has no value, then its value is considered to be "null" (strings "{}" or "[]" or "").

With that parent-child tree data structure in mind, the specifiers list that you supply in the above function tells tells LSL's JSON parser how to [http://en.wikipedia.org/wiki/Tree_(data_structure)#Traversal_methods walk the tree] of the JSON data that you have supplied with the first argument of the function. The first specifier in the list tells the LSL JSON parser which node to walk to first. The next specifier tells it which of that node's children to walk to. Once the LSL parser has "walked" to the last destination node specified by your list of specifiers, it will then perform the function on the JSON value that it finds there.

If, anywhere along the line, any of the specified nodes do not exist, [[llJsonGetValue]] and [[llJsonValueType]] will almost always return [[JSON_INVALID]]. However there is a rare exception: if the specifiers list leads to a node that has no characters in its JSON string value, no matter what follows that "null-value node" in the specifiers list, JSON_NULL will be returned instead of JSON_INVALID -- even though, obviously, none of the following specifiers exist. For example, for the example object {"parent":,} llJsonGetValue(example,["parent"]) will return JSON_NULL, as will llJsonGetValue(example,["parent","child that doesn't exist","etc."]). Another example: a specifier pointing to any element of a valid array such as {"parent":[ , , , , ]} will return JSON_NULL anywhere there is no JSON value specified at given position in the array; in this case llJsonGetValue(example,["parent",2]) returns JSON_NULL, as does llJsonGetValue(example,["parent",1,"child that does not exist","etc."]). These rare scenarios may be useful in determining valid JSON paths for the setter: in all the scenarios where JSON_NULL is returned, the same set of specifiers is able to be used for [[llJsonSetValue]] -- whereas if JSON_INVALID is returned, there is no guarantee the setter won't return an error.

For llJsonGetValue(), if a JSON value is present, it will be returned by the function. The value may an object that contains no valid JSON data, so be careful. Such an object will be deemed a JSON_OBJECT by llGetJsonType(), even if its contents are not valid JSON. Therefore it's always best to check the llJsonType() of any specified value to make sure it's valid before using the information in your script.

The specifiers list may only consist of strings/keys (for object member keys), and integers (for array element positions), which define a path to the desired value in a JSON compound object.

* An empty list specifies the entire Json value.
* If the list is not empty, each element of the list is used to select the element at the same level of nesting in the Json value:
** if the specifier list element is a string, then the corresponding element in the json value must be an object and the list element selects the value whose Json name exactly matches the string.
** if the specifier list element is an integer, then the corresponding element in the json value must be an array and the list element is used as a zero-based index into the Json array.
* Additionally llJsonSetValue accepts [[JSON_APPEND]] as a specifier to indicate appending the value to the end of the array at that level.

For example, given the json value:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
"a": 3.2,
"b": true
}
}
</javascript>
the contents of the string returned would be:
<lsl>
llJsonGetValue ( value, [ "alpha" ] ) ⇒ 1
llJsonGetValue ( value, [ "beta" ] ) ⇒ [ "x", "y", "z" ]
llJsonGetValue ( value, [ "beta", 2 ] ) ⇒ z
llJsonGetValue ( value, [ "gamma", "a" ] ) ⇒ 3.2
</lsl>

llJsonSetValue(string json, list specifiers, string value_to_set) will force the resulting JSON to conform with the specifiers supplied, as long as the specified path is traversable.

==Json Interrogation and Validation==

To determine the type of a json value:

<lsl>string type = llJsonValueType( string json, list specifiers );</lsl>

:returns one of several following special constants (see table below). Each constant has a name, JSON_XXXX, which unlike most LSL constants is not an integer—instead, it's a single-character string. The single character is not printable but has a specific escape value (if run through llEscapeURL) in the range of %EF%B7%90–97. The below table shows each constant's invocation and escape code:

{| class="wikitable"
|-
! Contant !! Escape value
|-
| [[JSON_INVALID]] || %EF%B7%90
|-
| [[JSON_OBJECT]] || %EF%B7%91
|-
| [[JSON_ARRAY]] || %EF%B7%92
|-
| [[JSON_NUMBER]] || %EF%B7%93
|-
| [[JSON_STRING]] || %EF%B7%94
|-
| [[JSON_NULL]] || %EF%B7%95
|-
| [[JSON_TRUE]] || %EF%B7%96
|-
| [[JSON_FALSE]] || %EF%B7%97
|}

==Json to LSL Conversion==

To directly extract a Json value to an LSL string:

string value = llJsonGetValue( string json, list specifiers );
* ''json'' is a string containing a valid json array or object value
* ''specifiers'' is a list of specifiers (see Specifying Json Elements)
* returns a json string
* if the specifiers do not indicate a value that exists in the input, [[JSON_INVALID]] is returned

To convert a json compound value (either an array or an object) to an LSL List:

list values = llJson2List( string json );
* ''json'' is a string containing a valid json array or object value
* If the string in json is not a valid json object or array a list with a single item matching the conversion above is returned.

==Recursive Parsing==

Since any value in a Json array or object may be any arbitrary type, including an array or object, the parsing methods must handle nested values. Nested arrays or objects are not converted, but remain LSL String values. If an LSL script needs to use the components in such a nested value, it must explicitly pass that string to the appropriate method. For example, the following json value is passed to llJson2List:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
a: 3.2,
b: true
}
}
</javascript>
The result would be an LSL list with a stride of 2: the first elements of the 3 strides would be "alpha", "beta", and "gamma". The second element of the first stride would be the integer 1, but the second elements of the other two strides would be LSL strings containing the json representation of the array '[ "x", "y", "z" ]' and object '{ a: 3.2, b: true }' respectively.

==LSL to Json==

To convert a list to json:
string json = llList2Json( string type, list values );
* ''type'' must be either [[JSON_ARRAY]] or [[JSON_OBJECT]]
* ''values'' is the list to be converted to json.

:Produces an LSL String containing a Json compound value, either an array or an object depending on type, containing the values in the input list.

:If type is [[JSON_ARRAY]], the list may contain values of any LSL type; they are converted as described in Type Conversions above.

:If type is [[JSON_OBJECT]], the list must have a stride of 2. The first value of each stride must be a string. The second value of each stride may be any LSL type, and are converted as described in Type Conversions above. [[JSON_INVALID] is returned if the stride is not 2.

:[[JSON_INVALID]] is returned if any other string or json type is specified as the type.

To directly set a Json value within a string:

string jsonresult = llJsonSetValue( string json, list specifiers, string value );
* ''json'' is a string containing a valid json array or object value
* ''specifiers'' is a list of specifiers (see [[#Specifying Json Elements]])
* ''value'' the value to be inserted into the specified place in json
* Returns the newly modified json string

:The only failure mode for llJsonSetValue is if an array index is specified in specifiers that is negative (but not [[JSON_APPEND]]) or more greater than the list size. In all other cases the json is modified so that the set can succeed. For example if an integer is specified for a level that is an object, the object will be removed completely and replaced with an array. If the object key does not exist it will be added, and JSON_APPEND or an index one larger than the last item in an array can be used to append to an array. These features are to allow building a Json string with llJsonSetValue.

==Recursive Construction of Compound Json Values==

Since LSL does not support nested lists, the construction method may only be used to convert a single level; to create a Json array or object whose values are nested arrays or objects, the LSL script must first construct the nested values and then pass those values as strings to another construction method call. For example, to construct the Json value:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
a: 3.2,
b: true
}
}
</javascript>
The following sequence could be used:
<pre>
string gamma_value = llList2Json( JSON_OBJECT, [ "a", 3.2, "b", TRUE ] );
string beta_value = llList2Json( JSON_ARRAY, [ "x", "y", "z" ] );
string value = llList2Json( JSON_OBJECT,[ "alpha", 1, "beta", beta_value, "gamma", gamma_value ] );
</pre>
or the equivalent without the intermediate variables:
<lsl>
string value =
llList2Json( JSON_OBJECT,
["alpha", 1,
"beta", llList2Json( JSON_ARRAY, [ "x", "y", "z" ] ),
"gamma", llList2Json( JSON_OBJECT, [ "a", 3.2, "b", TRUE ] )]
);
</lsl>

Json usage in LSL

2013-06-19T17:03:31Z

Gistya Eusebio: Explaining the JSON functions in much gretaer depth

{{LSL Header|lm=*}}{{LSLC|}}{{LSLC|JSON|*Json usage in LSL}}
==Type Conversions==

Json has native representation for:
* numbers - directly mappable to LSL Integer and Float (json numbers without a decimal point are assumed to be Integers, those with a decimal point are Floats)
* strings - identical to LSL [[String]]
* arrays - a list of values of any type: directly analogous to an LSL [[List]]
* objects - represented in LSL as a strided list of name/value pairs (see below re: values)
* the constants 'true' and 'false' - directly mapped to and from the LSL constants [[JSON_TRUE]] and [[JSON_FALSE]]
* the constant 'null' - directly mapped to and from the LSL constant [[JSON_NULL]]
* All other LSL types (Key, Rotation, and Vector) are implicitly converted to their string representation when converting to Json; when converting from Json to LSL, these values are returned as String values, so the script must explicitly convert using the existing conversion methods.

==New LSL Methods==
===Specifying Json Elements===

[[llJsonGetValue]], [[llJsonValueType]] and [[llJsonSetValue]] each take the same first two arguments:
1. a JSON value in the form of a [[String|string]], and
2. a set of specifiers in the form of a [[List|list]].
[[llJsonSetValue]] additionally takes a third an argument:
3. a JSON value in the form of a [[String|string]].

To understand specifiers one must generally understand that JSON data is structured in a [http://en.wikipedia.org/wiki/Nested_set_model nested set model]. LSL's built-in JSON parser uses the supplied "specifiers" list to perform [http://en.wikipedia.org/wiki/Tree_traversal tree traversal] on the nodes of the supplied JSON data [http://en.wikipedia.org/wiki/Tree_(data_structure) tree data structure]. A JSON tree may be visualized as a set of hierarchical levels of parents and children. Each level is contained within '''curly braces {for objects, which are lists of members, that are defined as key-value pairs}''' or '''square braces [for arrays of elements, that are defined as single values]'''. When JSON is presented in a human-readable, it is traditionally formatted such that the first parent level of organization is indented farthest to the left, and each more deeply-nested child level of organization is indented farther and farther to the right. The left-most level of nodes have no parents, only children. They begin with the very first member that appears after the initial "{" character of the JSON string (if it starts as an object), or the first element that appears after the initial "[" character (if it starts as an array). A node is considered as being a parent only if it has a non-null JSON object or array as its value -- and if a node has no value, then its value is considered to be "null" (strings "{}" or "[]" or "").

With that parent-child tree data structure in mind, the specifiers list that you supply in the above function tells tells LSL's JSON parser how to [http://en.wikipedia.org/wiki/Tree_(data_structure)#Traversal_methods walk the tree] of the JSON data that you have supplied with the first argument of the function. The first specifier in the list tells the LSL JSON parser which node to walk to first. The next specifier tells it which of that node's children to walk to. Once the LSL parser has "walked" to the last destination node specified by your list of specifiers, it will then perform the function on the JSON value that it finds there.

If, anywhere along the line, any of the specified nodes do not exist, [[llJsonGetValue]] and [[llJsonValueType]] will almost always return [[JSON_INVALID]]. However there is a rare exception: if the specifiers list leads to a node that has no characters in its JSON string value, no matter what follows that "null-value node" in the specifiers list, JSON_NULL will be returned instead of JSON_INVALID -- even though, obviously, none of the following specifiers exist. For example, for the example object {"parent":,} llJsonGetValue(example,["parent"]) will return JSON_NULL, as will llJsonGetValue(example,["parent","child that doesn't exist","etc."]). Another example: a specifier pointing to any element of a valid array such as {"parent":[ , , , , ]} will return JSON_NULL anywhere there is no JSON value specified at given position in the array; in this case llJsonGetValue(example,["parent",2]) returns JSON_NULL, as does llJsonGetValue(example,["parent",1,"child that does not exist","etc."]). These rare scenarios may be useful in determining valid JSON paths for the setter: in all the scenarios where JSON_NULL is returned, the same set of specifiers is able to be used for [[llJsonSetValue]] -- whereas if JSON_INVALID is returned, there is no guarantee the setter won't return an error.

For llJsonGetValue(), if a JSON value is present, it will be returned by the function. The value may an object that contains no valid JSON data, so be careful. Such an object will be deemed a JSON_OBJECT by llGetJsonType(), even if its contents are not valid JSON. Therefore it's always best to check the llJsonType() of any specified value to make sure it's valid before using the information in your script.

The specifiers list may only consist of strings/keys (for object member keys), and integers (for array element positions), which define a path to the desired value in a JSON compound object.

* An empty list specifies the entire Json value.
* If the list is not empty, each element of the list is used to select the element at the same level of nesting in the Json value:
** if the specifier list element is a string, then the corresponding element in the json value must be an object and the list element selects the value whose Json name exactly matches the string.
** if the specifier list element is an integer, then the corresponding element in the json value must be an array and the list element is used as a zero-based index into the Json array.
* Additionally llJsonSetValue accepts [[JSON_APPEND]] as a specifier to indicate appending the value to the end of the array at that level.

For example, given the json value:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
"a": 3.2,
"b": true
}
}
</javascript>
the contents of the string returned would be:
<lsl>
llJsonGetValue ( value, [ "alpha" ] ) ⇒ 1
llJsonGetValue ( value, [ "beta" ] ) ⇒ [ "x", "y", "z" ]
llJsonGetValue ( value, [ "beta", 2 ] ) ⇒ z
llJsonGetValue ( value, [ "gamma", "a" ] ) ⇒ 3.2
</lsl>

llJsonSetValue(string json, list specifiers, string value_to_set) will force the resulting JSON to conform with the specifiers supplied, as long as the specified path is traversable.

==Json Interrogation and Validation==

To determine the type of a json value:

<lsl>string type = llJsonValueType( string json, list specifiers );</lsl>

:returns one of several following special constants (see table below). Each constant has a name, JSON_XXXX, which unlike most LSL constants is not an integer—instead, it's a single-character string. The single character is not printable but has a specific escape value (if run through llEscapeURL) in the range of %EF%B7%90–97. The below table shows each constant's invocation and escape code:

{| class="wikitable"
|-
! Contant !! Escape value
|-
| [[JSON_INVALID]] || %EF%B7%90
|-
| [[JSON_OBJECT]] || %EF%B7%91
|-
| [[JSON_ARRAY]] || %EF%B7%92
|-
| [[JSON_NUMBER]] || %EF%B7%93
|-
| [[JSON_STRING]] || %EF%B7%94
|-
| [[JSON_NULL]] || %EF%B7%95
|-
| [[JSON_TRUE]] || %EF%B7%96
|-
| [[JSON_FALSE]] || %EF%B7%97
|}

==Json to LSL Conversion==

To directly extract a Json value to an LSL string:

string value = llJsonGetValue( string json, list specifiers );
* ''json'' is a string containing a valid json array or object value
* ''specifiers'' is a list of specifiers (see Specifying Json Elements)
* returns a json string
* if the specifiers do not indicate a value that exists in the input, [[JSON_INVALID]] is returned

To convert a json compound value (either an array or an object) to an LSL List:

list values = llJson2List( string json );
* ''json'' is a string containing a valid json array or object value
* If the string in json is not a valid json object or array a list with a single item matching the conversion above is returned.

==Recursive Parsing==

Since any value in a Json array or object may be any arbitrary type, including an array or object, the parsing methods must handle nested values. Nested arrays or objects are not converted, but remain LSL String values. If an LSL script needs to use the components in such a nested value, it must explicitly pass that string to the appropriate method. For example, the following json value is passed to llJson2List:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
a: 3.2,
b: true
}
}
</javascript>
The result would be an LSL list with a stride of 2: the first elements of the 3 strides would be "alpha", "beta", and "gamma". The second element of the first stride would be the integer 1, but the second elements of the other two strides would be LSL strings containing the json representation of the array '[ "x", "y", "z" ]' and object '{ a: 3.2, b: true }' respectively.

==LSL to Json==

To convert a list to json:
string json = llList2Json( string type, list values );
* ''type'' must be either [[JSON_ARRAY]] or [[JSON_OBJECT]]
* ''values'' is the list to be converted to json.

:Produces an LSL String containing a Json compound value, either an array or an object depending on type, containing the values in the input list.

:If type is [[JSON_ARRAY]], the list may contain values of any LSL type; they are converted as described in Type Conversions above.

:If type is [[JSON_OBJECT]], the list must have a stride of 2. The first value of each stride must be a string. The second value of each stride may be any LSL type, and are converted as described in Type Conversions above. [[JSON_INVALID] is returned if the stride is not 2.

:[[JSON_INVALID]] is returned if any other string or json type is specified as the type.

To directly set a Json value within a string:

string jsonresult = llJsonSetValue( string json, list specifiers, string value );
* ''json'' is a string containing a valid json array or object value
* ''specifiers'' is a list of specifiers (see [[#Specifying Json Elements]])
* ''value'' the value to be inserted into the specified place in json
* Returns the newly modified json string

:The only failure mode for llJsonSetValue is if an array index is specified in specifiers that is negative (but not [[JSON_APPEND]]) or more greater than the list size. In all other cases the json is modified so that the set can succeed. For example if an integer is specified for a level that is an object, the object will be removed completely and replaced with an array. If the object key does not exist it will be added, and JSON_APPEND or an index one larger than the last item in an array can be used to append to an array. These features are to allow building a Json string with llJsonSetValue.

==Recursive Construction of Compound Json Values==

Since LSL does not support nested lists, the construction method may only be used to convert a single level; to create a Json array or object whose values are nested arrays or objects, the LSL script must first construct the nested values and then pass those values as strings to another construction method call. For example, to construct the Json value:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
a: 3.2,
b: true
}
}
</javascript>
The following sequence could be used:
<pre>
string gamma_value = llList2Json( JSON_OBJECT, [ "a", 3.2, "b", TRUE ] );
string beta_value = llList2Json( JSON_ARRAY, [ "x", "y", "z" ] );
string value = llList2Json( JSON_OBJECT,[ "alpha", 1, "beta", beta_value, "gamma", gamma_value ] );
</pre>
or the equivalent without the intermediate variables:
<lsl>
string value =
llList2Json( JSON_OBJECT,
["alpha", 1,
"beta", llList2Json( JSON_ARRAY, [ "x", "y", "z" ] ),
"gamma", llList2Json( JSON_OBJECT, [ "a", 3.2, "b", TRUE ] )]
);
</lsl>

Json usage in LSL

2013-06-13T09:31:37Z

Gistya Eusebio: /* Specifying Json Elements */ explaining how the JSON_NULL type works

Json usage in LSL

2013-06-09T05:36:24Z

Gistya Eusebio: added table showing the escape codes of the json type constants

{{LSL Header|lm=*}}{{LSLC|}}{{LSLC|JSON}}
==Type Conversions==

Json has native representation for:
* numbers - directly mappable to LSL Integer and Float (json numbers without a decimal point are assumed to be Integers, those with a decimal point are Floats)
* strings - identical to LSL [[String]]
* arrays - a list of values of any type: directly analogous to an LSL [[List]]
* objects - represented in LSL as a strided list of name/value pairs (see below re: values)
* the constants 'true' and 'false' - directly mapped to and from the LSL constants [[JSON_TRUE]] and [[JSON_FALSE]]
* the constant 'null' - directly mapped to and from the LSL constant [[JSON_NULL]]
* All other LSL types (Key, Rotation, and Vector) are implicitly converted to their string representation when converting to Json; when converting from Json to LSL, these values are returned as String values, so the script must explicitly convert using the existing conversion methods.

==New LSL Methods==
===Specifying Json Elements===

[[llJsonGetValue]], [[llJsonValueType]] and [[llJsonSetValue]] take a Json value in an LSL string, and an LSL list of specifiers. The specifiers are a list consisting only of strings (or keys) and integers, which define a path to the desired value in a Json compound object.

* An empty list specifies the entire Json value.
* If the list is not empty, each element of the list is used to select the element at the same level of nesting in the Json value:
** if the specifier list element is a string, then the corresponding element in the json value must be an object and the list element selects the value whose Json name exactly matches the string.
** if the specifier list element is an integer, then the corresponding element in the json value must be an array and the list element is used as a zero-based index into the Json array.
* Additionally llJsonSetValue accepts [[JSON_APPEND]] as a specifier to indicate appending the value to the end of the array at that level.

For example, given the json value:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
"a": 3.2,
"b": true
}
}
</javascript>
the contents of the string returned would be:
<lsl>
llJsonGetValue ( value, [ "alpha" ] ) ⇒ 1
llJsonGetValue ( value, [ "beta" ] ) ⇒ [ "x", "y", "z" ]
llJsonGetValue ( value, [ "beta", 2 ] ) ⇒ z
llJsonGetValue ( value, [ "gamma", "a" ] ) ⇒ 3.2
</lsl>
For llJsonGetValue and llJsonValueType If the specifiers do not specify a valid path in the given json value, the constant [[JSON_INVALID]] is returned. llJsonSetValue will force the resulting json to conform with the specifiers supplied.

==Json Interrogation and Validation==

To determine the type of a json value:

<lsl>string type = llJsonValueType( string json, list specifiers );</lsl>

:returns one of several following special constants (see table below). Each constant has a name, JSON_XXXX, which unlike most LSL constants is not an integer—instead, it's a single-character string. The single character is not printable but has a specific escape value (if run through llEscapeURL) in the range of %EF%B7%90–97. The below table shows each constant's invocation and escape code:

{| class="wikitable"
|-
! Contant !! Escape value
|-
| [[JSON_INVALID]] || %EF%B7%90
|-
| [[JSON_OBJECT]] || %EF%B7%91
|-
| [[JSON_ARRAY]] || %EF%B7%92
|-
| [[JSON_NUMBER]] || %EF%B7%93
|-
| [[JSON_STRING]] || %EF%B7%94
|-
| [[JSON_NULL]] || %EF%B7%95
|-
| [[JSON_TRUE]] || %EF%B7%96
|-
| [[JSON_FALSE]] || %EF%B7%97
|}

==Json to LSL Conversion==

To directly extract a Json value to an LSL string:

string value = llJsonGetValue( string json, list specifiers );
* ''json'' is a string containing a valid json array or object value
* ''specifiers'' is a list of specifiers (see Specifying Json Elements)
* returns a json string.

To convert a json compound value (either an array or an object) to an LSL List:

list values = llJson2List( string json );
* ''json'' is a string containing a valid json array or object value
* If the string in json is not a valid json object or array a list with a single item matching the conversion above is returned.

==Recursive Parsing==

Since any value in a Json array or object may be any arbitrary type, including an array or object, the parsing methods must handle nested values. Nested arrays or objects are not converted, but remain LSL String values. If an LSL script needs to use the components in such a nested value, it must explicitly pass that string to the appropriate method. For example, the following json value is passed to llJson2List:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
a: 3.2,
b: true
}
}
</javascript>
The result would be an LSL list with a stride of 2: the first elements of the 3 strides would be "alpha", "beta", and "gamma". The second element of the first stride would be the integer 1, but the second elements of the other two strides would be LSL strings containing the json representation of the array '[ "x", "y", "z" ]' and object '{ a: 3.2, b: true }' respectively.

==LSL to Json==

To convert a list to json:
string json = llList2Json( string type, list values );
* ''type'' must be either [[JSON_ARRAY]] or [[JSON_OBJECT]]
* ''values'' is the list to be converted to json.

:Produces an LSL String containing a Json compound value, either an array or an object depending on type, containing the values in the input list.

:If type is [[JSON_ARRAY]], the list may contain values of any LSL type; they are converted as described in Type Conversions above.

:If type is [[JSON_OBJECT]], the list must have a stride of 2. The first value of each stride must be a string. The second value of each stride may be any LSL type, and are converted as described in Type Conversions above. [[JSON_INVALID] is returned if the stride is not 2.

:[[JSON_INVALID]] is returned if any other string or json type is specified as the type.

To directly set a Json value within a string:

string jsonresult = llJsonSetValue( string json, list specifiers, string value );
* ''json'' is a string containing a valid json array or object value
* ''specifiers'' is a list of specifiers (see Specifying Json Elements)
* ''value'' the value to be inserted into the specified place in json
* Returns the newly modified json string

:The only failure mode for llJsonSetValue is if an array index is specified in specifiers that is negative (but not [[JSON_APPEND]]) or more greater than the list size. In all other cases the json is modified so that the set can succeed. For example if an integer is specified for a level that is an object, the object will be removed completely and replaced with an array. If the object key does not exist it will be added, and JSON_APPEND or an index one larger than the last item in an array can be used to append to an array. These features are to allow building a Json string with llJsonSetValue.

==Recursive Construction of Compound Json Values==

Since LSL does not support nested lists, the construction method may only be used to convert a single level; to create a Json array or object whose values are nested arrays or objects, the LSL script must first construct the nested values and then pass those values as strings to another construction method call. For example, to construct the Json value:
<javascript>
{
alpha: 1,
beta: [
"x",
"y",
"z"
],
gamma: {
a: 3.2,
b: true
}
}
</javascript>
The following sequence could be used:
<pre>
string gamma_value = llList2Json( JSON_OBJECT, [ "a", 3.2, "b", TRUE ] );
string beta_value = llList2Json( JSON_ARRAY, [ "x", "y", "z" ] );
string value = llList2Json( JSON_OBJECT,[ "alpha", 1, "beta", beta_value, "gamma", gamma_value ] );
</pre>
or the equivalent without the intermediate variables:
<lsl>
string value =
llList2Json( JSON_OBJECT,
["alpha", 1,
"beta", llList2Json( JSON_OBJECT, [ "a", 3.2, "b", TRUE ] ),
"gamma", llList2Json( JSON_ARRAY, [ "x", "y", "z" ] )]
);
</lsl>

LlSHA1String

2013-06-03T17:39:14Z

Gistya Eusebio: corrected a typo in caveats

{{LSL_Function
|func_id=343|func_sleep=0.0|func_energy=10.0
|func=llSHA1String|return_type=string|p1_type=string|p1_name=src
|func_footnote
|func_desc
|return_text=of 40 hex characters that is the {{Wikipedia|SHA-1|SHA-1}} security hash of '''src'''.
|spec=LSL strings are stored in the UTF-8 format.
|caveats=There's no way to input a zero-byte value into this function, nor any byte value from 128-255, therefore it's currently broken for many purposes (like HMAC-SHA1). The reason is because LSL strings cannot have a unicode null character (U+0000) in them, and LSL has no escape code for the null character (many programming languages use \0 but LSL does not have this feature). llEscapeURL("%00") yields an empty string. As well, inside this function, each character with a Unicode integer value over U+0127 / 007F are dealt with in UTF-8 fashion: in the hex values, 0xC2 is appended to the byte value (hence 0x0080-0x00FF become 0xC280-0xC2FF inside the llSHA1String() routine). A JIRA has been filed for this.
|constants
|examples=
<lsl>
llSay(0, llSHA1String("Hello, Avatar!")); // returns 2E73318E547AF1B28CC0C96F95DDC9B1EE906B8D
</lsl>

====Linux Example====
<pre>
$ echo -n 'Hello, Avatar!' | openssl sha1
2E73318E547AF1B28CC0C96F95DDC9B1EE906B8D
</pre>
|helpers
|also_functions=
{{LSL DefineRow||[[llMD5String]]}}
|also_tests
|also_events
|also_articles=
{{LSL DefineRow||[[SHA-1]]}}
|notes
|deepnotes=
Prior to this, the only way to get the SHA-1 hash was to use the LSL SHA-1 port: [[SHA-1]]
|history=
*{{SVN|1291|rev=98903|trunk=*|anchor=file13|ver=1.21.5.97417|ser=1.24.9.98650}} Initial introduction.
*{{SVN|1298|rev=99021|branch=OpenAL|ver=1.21.5.97417|ser=1.24.9.98650|path=branches/openal/indra/lscript/lscript_library/lscript_library.cpp}} Integration into OpenAL branch.
|cat1=Hash
|cat2=Encoding
|cat3
|cat4
}}{{LSLC{{#var:lang}}|Encryption|llSHA1String}}

LlSHA1String

2013-06-03T17:38:21Z

Gistya Eusebio: Added another issue with the function to caveats.

{{LSL_Function
|func_id=343|func_sleep=0.0|func_energy=10.0
|func=llSHA1String|return_type=string|p1_type=string|p1_name=src
|func_footnote
|func_desc
|return_text=of 40 hex characters that is the {{Wikipedia|SHA-1|SHA-1}} security hash of '''src'''.
|spec=LSL strings are stored in the UTF-8 format.
|caveats=There's no way to input a zero-byte value into this function, nor any byte value from 128-255, therefore it's currently broken for many purposes (like HMAC-SHA1). The reason is because LSL strings cannot have a unicode null character (U+0000) in them, and LSL has no escape code for the null character (many programming languages use \0 but LSL does not have this feature). llEscapeURL("%00") yields an empty string. As well, inside this function, each character with a Unicode integer value byte values over U+0127 / 007F are dealt with in UTF-8 fashion: in the hex values, 0xC2 is appended to the byte value (hence 0x0080-0x00FF become 0xC280-0xC2FF inside the llSHA1String() routine). A JIRA has been filed for this.
|constants
|examples=
<lsl>
llSay(0, llSHA1String("Hello, Avatar!")); // returns 2E73318E547AF1B28CC0C96F95DDC9B1EE906B8D
</lsl>

====Linux Example====
<pre>
$ echo -n 'Hello, Avatar!' | openssl sha1
2E73318E547AF1B28CC0C96F95DDC9B1EE906B8D
</pre>
|helpers
|also_functions=
{{LSL DefineRow||[[llMD5String]]}}
|also_tests
|also_events
|also_articles=
{{LSL DefineRow||[[SHA-1]]}}
|notes
|deepnotes=
Prior to this, the only way to get the SHA-1 hash was to use the LSL SHA-1 port: [[SHA-1]]
|history=
*{{SVN|1291|rev=98903|trunk=*|anchor=file13|ver=1.21.5.97417|ser=1.24.9.98650}} Initial introduction.
*{{SVN|1298|rev=99021|branch=OpenAL|ver=1.21.5.97417|ser=1.24.9.98650|path=branches/openal/indra/lscript/lscript_library/lscript_library.cpp}} Integration into OpenAL branch.
|cat1=Hash
|cat2=Encoding
|cat3
|cat4
}}{{LSLC{{#var:lang}}|Encryption|llSHA1String}}

Talk:Json usage in LSL

2013-05-30T16:41:02Z

Gistya Eusebio: Asking how escaped characters in JSON strings will be rendered

User:Gistya Eusebio

2013-05-20T02:28:33Z

Gistya Eusebio: Created page with "I've been using second life since 2006. I own the sim, Korriban. I'm a scripter."

I've been using second life since 2006. I own the sim, Korriban. I'm a scripter.

LlSHA1String

2013-05-20T02:27:44Z

Gistya Eusebio: added caveat

{{LSL_Function
|func_id=343|func_sleep=0.0|func_energy=10.0
|func=llSHA1String|return_type=string|p1_type=string|p1_name=src
|func_footnote
|func_desc
|return_text=of 40 hex characters that is the {{Wikipedia|SHA-1|SHA-1}} security hash of '''src'''.
|spec=LSL strings are stored in the UTF-8 format.
|caveats=There's no way to input a zero-byte value into this function, therefore it's currently broken for many purposes (like HMAC-SHA1). The reason is because LSL strings cannot have a unicode null character (U+0000) in them, and LSL has no escape code for the null character (many programming languages use \0 but LSL does not have this feature). llEscapeURL("%00") yields an empty string. A JIRA has been filed for this.
|constants
|examples=
<lsl>
llSay(0, llSHA1String("Hello, Avatar!")); // returns 2E73318E547AF1B28CC0C96F95DDC9B1EE906B8D
</lsl>

====Linux Example====
<pre>
$ echo -n 'Hello, Avatar!' | openssl sha1
2E73318E547AF1B28CC0C96F95DDC9B1EE906B8D
</pre>
|helpers
|also_functions=
{{LSL DefineRow||[[llMD5String]]}}
|also_tests
|also_events
|also_articles=
{{LSL DefineRow||[[SHA-1]]}}
|notes
|deepnotes=
Prior to this, the only way to get the SHA-1 hash was to use the LSL SHA-1 port: [[SHA-1]]
|history=
*{{SVN|1291|rev=98903|trunk=*|anchor=file13|ver=1.21.5.97417|ser=1.24.9.98650}} Initial introduction.
*{{SVN|1298|rev=99021|branch=OpenAL|ver=1.21.5.97417|ser=1.24.9.98650|path=branches/openal/indra/lscript/lscript_library/lscript_library.cpp}} Integration into OpenAL branch.
|cat1=Hash
|cat2=Encoding
|cat3
|cat4
}}{{LSLC{{#var:lang}}|Encryption|llSHA1String}}

Category:LSL String

2013-05-20T01:48:19Z

Gistya Eusebio: it needs to be explained that strings cannot contain "NUL" characters.

{{LSL Header|ml=*}}{{LSLC|}}{{LSLC|Types}}
{{RightToc}}

See also [[:Category:LSL_Text|Text]].

A string is text data.

String values are enclosed in double quotes when defined in LSL text.

Any character may be used in a string, except for the "NUL" character, though some will need to be escaped (see the [[#Escape Codes|Escape Codes section]] on this page for more info.) The "NUL" character is Unicode value U+0000 and cannot exist in an LSL string. Therefore for example llUnescapeURL("%00") results in an empty string "".

The length of a string is only limited by available [[LlGetFreeMemory|script memory]]. (see the [[#String_Length_Restraints|String Length Restraints]] section on this page for some operational restraints.) But note that in Mono, strings use UTF-16 and occupy two memory bytes per character.

Strings can be concatenated (joined together) using the '''+''' operator. Note that concatenation cannot be done when defining a string as a global variable, as + is treated as an executable instruction, it's not handled by the compiler. Concatenation can only be done within executable code, i.e. inside a user defined function or in an event.

Some string operations can be done via built-in functions, such as those that can make text all upper and lower case. Other operations, such as replace, left, right, wrap, etc, must be done via functions invented by other LSL users (examples of which are at the bottom of this page.)

You have no control over the font face, size, weight or colour that string output is displayed in on user screens or on menus. The look of text that displays on screens, such as chat from a text, is controlled by users (though not many change the defaults.) You can only control whether the text is lower or upper case.

(The only time you have control over the colour of displayed text is when it is [[LlSetText|Floating Text]].)

{|
|
String examples:
<lsl>"Hello Avatar!"
"Yes"
"No"
"It's 10 o'clock."
"I am 21 years old!"
"Help " + "me"
EOF

//The following two strings have the same value (i.e. they will both produce text with line breaks in it.)

"I scream,\nyou scream,\nwe all scream,\nfor ice-cream!"
"I scream,
you scream,
we all scream,
for ice-cream!"
</lsl>
|}

{{#vardefine:p_name_desc|variable name
}}{{#vardefine:p_value_desc|string expression or constant
}}{{#vardefine:p_value_t_desc|expression or constant
}}
<div id="box">
== Variable: string {{LSL Param|name}}; ==
<div style="padding: 0.5em;">
<lsl>string name;</lsl>
Declares a variable of type string named '''name''', with the value {{HoverText|""|empty string}}
{|
{{LSL DefineRow|variable|name|{{#var:p_name_desc}}}}
|}
</div></div>

<div id="box">
== Variable: string {{LSL Param|name}} {{=}} {{LSL Param|value}}; ==
<div style="padding: 0.5em;">
<lsl>string name = value;</lsl>
Declares a variable of type string named '''name''', with the value '''value'''.
{|
{{LSL DefineRow|variable|name|{{#var:p_name_desc}}}}
{{LSL DefineRow|expression|value|{{#var:p_value_desc}}}}
|}
</div></div>

<div id="box">
== [[Typecast]]: (string){{LSL Param|value_t|value}} ==
<div style="padding: 0.5em;">
<lsl>(string)value</lsl>
Converts '''value''' to a value of type string.
{|
{{LSL DefineRow|expression|value|{{#var:p_value_t_desc}}}}
|}
</div></div>

<div id="box">

== [[LSL Operators|Operators]] ==
<div style="padding: 0.5em;">
See [[LSL Operators|Operators]] for more information.
<div id="box" style="padding-left: 0.5em;padding-right: 0.5em;padding-bottom: 0.5em;">
=== Combine: {{LSL Param|value|value1}} + {{LSL Param|value|value2}} ===
<lsl>(value1 + value2)</lsl>
Combines two strings into a single string without modifying the inputs. Appends '''value2''' to '''value1''' and returns the resulting string.
{|
{{LSL DefineRow|expression|value1|{{#var:p_value_desc}}}}
{{LSL DefineRow|expression|value2|{{#var:p_value_desc}}}}
|}
</div>
<div id="box" style="padding-left: 0.5em;padding-right: 0.5em;padding-bottom: 0.5em;">

=== Comparison: {{LSL Param|value|value1}} <nowiki>==</nowiki> {{LSL Param|value|value2}} ===
<lsl>(value1 == value2)</lsl>
Compares two strings, returns {{HoverText|one|1}} if same length and same characters, else returns zero.
This operator works exactly like <code>!strcmp('''value1''', '''value2''')</code> in C, thus technically differs from the counterintuitive behavior of the == operator in C and in Java.
{|
{{LSL DefineRow|expression|value1|{{#var:p_value_desc}}}}
{{LSL DefineRow|expression|value2|{{#var:p_value_desc}}}}
|}
</div>
<div id="box" style="padding-left: 0.5em;padding-right: 0.5em;padding-bottom: 0.5em;">
=== Comparison: {{LSL Param|value|value1}} != {{LSL Param|value|value2}} ===
<lsl>(value1 != value2)</lsl>
Compares two strings, returns {{HoverText|zero|0}} if same length and same characters, otherwise non-zero.
This operator works exactly like <code>strcmp('''value1''', '''value2''')</code> in C, thus technically differs from the counterintuitive behavior of the != operator in C and in Java.
{|
{{LSL DefineRow|expression|value1|{{#var:p_value_desc}}}}
{{LSL DefineRow|expression|value2|{{#var:p_value_desc}}}}
|}
</div>
</div></div>

<div id="box">
== Escape Codes==
<div style="padding: 0.5em;">
{|{{Prettytable|style=float:left;}}
|+
|-{{Hl2}}
!Substring
!Replaced with
|-
|| \t || four spaces
|-
|| \n || new line
|-
|| \" || double quote
|-
|| \\ || backslash
|}
Escape codes are translated when the script is compiled; not while it's running. The compiler will ignore any other combination of \ with a character by removing the \. So "\a" means "a".
The result is that only strings that are inside your script when it is compiled will get, say, \n turned into a "new line" character. Text you read in from a notecard, chat, http, object name or description, etc, will not be checked for escape codes -- that same \n typed in a notecard doesn't automatically turn into a "new line" character. You'll have to do that yourself, if you really really need it for some reason.

Those who are coming to LSL from such languages as C and Java may find these LSL string escape rules confusing at first. In LSL, "\n" means [[llUnescapeURL]]("%0A"), as it does in C and Java, but "\t" means [[llUnescapeURL]]("%20%20%20%20") rather than [[llUnescapeURL]]("%09"). Additionally there is no "\r" escape code and "\r" will translate to "r" rather than [[llUnescapeURL]]("%0D").

For runtime translation of escaped characters try the user function [[Unescape]].
</div></div>

<div id="box">

==Characters with Accents==
<div style="padding: 0.5em;">
It used to be that your script would not compile if you included in it a string containing a character with an accent, such as "écoutez", or punctuation not used in English, such as "¿Entiende?".

Sometime in late spring / early summer 2008, scripts began compiling with accents in text strings.

That is to say:

<lsl>string hello = "Avatar écoutez";</lsl>
</div></div>

<div id="box">
==String Length Restraints==
<div style="padding: 0.5em;">
As noted at the start of this page, the length of a single string is only limited by available [[script memory]]. However, there are some operational limitations. Many {{LSLGC|Communications}} functions and some other functions also impose limits on input strings. Those limits may result in error messages at runtime or "silent" truncation (i.e. you get no error notice, nor any indication that it has been done.).

'''Examples'''
* [[llSay]] - When using llSay, any text string being said will be truncated to 1024 CHARACTERS, both under LSO and Mono. (That's 2048 bytes of memory space in Mono (UTF-16) ).
* [[llGetNotecardLine]] - When reading in lines from notecards, lines longer than 255 characters will be truncated silently.
* [[llDialog]] - If the message or button texts are too long a non-fatal error is produced when the function is called.

'''Notes'''<br/>
Limits of this type are always documented, an absence of limits in the documentation means there are no known limits (that are outside the norm for the language).
</div></div>

<div id="box">

==Trimming a String==
<div style="padding: 0.5em;">
Trimming a string used to require user-created functions, such as those created for the purpose in Strife Onizuka's library.

Now, however, there is a native LSL function, [[llStringTrim]], which can be used to remove leading and/or trailing spaces. Note though that it does not remove excess spaces that a user may have entered in the middle of a sentence or string, nor is there any other native LSL function which does.

The following code ''will'' remove both all double spaces inside a string, as well as any leading and trailing spaces; it will how ever require a substantial amount of memory overhead.

<lsl>string myTrimmedText = llDumpList2String(llParseString2List(src, [" "], []), " ");</lsl>

When accepting user text input from chat, a notecard, or a prim name or description, or any other "free-wheeling" source, it's a good idea to always [[llStringTrim]] first before beginning to work with it.
</div></div>

<div id="box">
== Examples ==
<div style="padding: 0.5em;">
<lsl>integer int = 48934;
string str = (string)int;
string str_2;
str_2 = str;</lsl>
</div></div>
<div id="box">
== Useful Functions ==
<div style="padding: 0.5em;">
=== User-created utility functions ===
These functions have been created and contributed by LSL users to perform operations not covered by built-in LSL functions.

{|{{Prettytable}}
|+
|-{{Hl2}}
!function
!purpose
|-
|| [[Chr]] || Returns the Unicode character with the given code. See also [[Ord]].
|-
|| [[Float2String]] || Allows string output of a float in a tidy text format, with optional rounding.
|-
|| [[Left]] || Returns text left of a specified separator.
|-
|| [[Like]] || See if one word matches part of another.
|-
|| [[Ord]] || Returns the ordinal (Unicode code) of a character. See also [[Chr]].
|-
|| [[RandomString]] || Creates a random string.
|-
|| [[RemoveHTMLTags]] || Removes HTML tags from a string ( and newline characters )
|-
|| [[Right]] || Returns text right of a specified separator.
|-
|| [[Library_Combined_Library#str_replace|str_replace]] || replace all instances of a string with another string in a target string.
|-
|| [[Stristr]] || Returns a string from the first occurrence of needle to the end of haystack.
|-
|| [[SplitLine]] || Insert 'new line' escape codes at certain positions of a string.
|-
|| [[WrapText]] || Break text into line lengths of your specification.
|}

=== Text-Related Items from the Script Library ===
{| {{Prettytable}}
|-
|{{Hl2}}| '''Name'''
|{{Hl2}}| '''Creator'''
|{{Hl2}}| '''Description'''
|-
||[[ParseString2List]]
||[[User:Strife Onizuka|Strife Onizuka]]
||Same as [[llParseString2List]] and [[llParseStringKeepNulls]], but not limited to 8 spacers or separators. Thus substitute a call to the [[llParseString2List]] and [[llParseStringKeepNulls]] functions by a call to [[Parse_String_To_List|ParseString2List]] whenever you have more than 8 separators or more than 8 spacers.
|-

||[[String Compare]]
||[[User:Xaviar Czervik|Xaviar Czervik]]
||Compares two strings and reliably returns either 1, -1, or 0 if they are the same.
|-
||[[XyText 1.5|XyText]]
||[[User:Xylor Baysklef|Xylor Baysklef]]
|| Display text (up to 10 characters) on a prim. Use as many prims as desired.
|-
||[[XyyyyzText|XyyyyzText]]
||[[User:Criz Collins|Criz Collins]]
|| Display text (up to 10 characters) on a prim. Displays different text for each line instead of one single text, that will be broken into the next lines. Watch here for what that means: http://screencast.com/t/1wMLujLcEO
|-
||[[XyzzyText|XyzzyText]]
||[[User:Thraxis Epsilon|Thraxis Epsilon]] and [[User:Gigs Taggart|Gigs Taggart]]
|| Display text (up to 10 characters) on a prim. Way more efficient than XyText.
|}
</div>

File talk:Sculpted-preview-03.png

2007-05-24T10:42:08Z

Gistya Eusebio:

Why does the sculptedpreview program have an XBOX 360 controller for its icon?

Is LL going to put out an SL client for the 360? OMG that would be so sweet!!