Stringify (Json function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Template:Json:Stringify subtitle}}
{{Template:Json:Stringify subtitle}}
This function serializes a Json object tree as a unicode JSON string.
This function serializes a <var>Json</var> object tree as a unicode JSON string.
 
==Syntax==
==Syntax==
{{Template:Json:Stringify syntax}}
{{Template:Json:Stringify syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table>
<tr><th>%unicode</th><td>A unicode string that contains the JSON format serialization of the Json object tree.</td></tr>
<tr><th nowrap>%unicode</th>
<td>A unicode string that contains the JSON format serialization of the <var>Json</var> object tree.</td></tr>
 
<tr><th>Json</th>
<tr><th>Json</th>
<td>Json object, which may be <var>Null</var> or any underlying Json object type (boolean, number, string, array, or object).</td></tr>
<td><var>Json</var> object, which may be <var>Null</var> or any underlying <var>Json</var> object type (boolean, number, string, array, or object).</td></tr>
 
<tr><th><var>Indent</var></th>
<tr><th><var>Indent</var></th>
<td>The number of space characters to add in front of each line for each nesting level (see below for moe details). The default value of <var>Indent</var> is 0 which means lines won't be indented.</td></tr>
<td>The number of space characters to add in front of each line for each nesting level (see below for more details). The default value of <var>Indent</var> is 0, which means lines will not be indented.</td></tr>
</table>
</table>
==Usage notes==
==Usage notes==
<ul>
<ul>
<li>The name <i>Stringify</i> derives from the equivalent JavaScript method: [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify JSON.stringify].</li>
<li>The name <code>Stringify</code> derives from the equivalent JavaScript method: [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify JSON.stringify].</li>
<li>The functionality of Stringify is practically identical to that of [[ToString (Json function)|ToString]]. The only difference is that Stringify throws a [[JsonCircularReference class|JsonCircularReference]]Exception if the Json object leads to a [[Json class#Circular references|circular reference]]. Because the JSON specification does not allow for circular references, Stringify is probably the preferred function to use for generating JSON to send to another platform &ndash; it's better to request cancel in 204 than to send bad JSON data to someone else.</li>
 
<li>If no indentation is used (<var>Indent</var> defaults or is set to 0) no whitespace is added between any of the JSON tokens and separator characters (curly and square braces, commas, and colons). This format is very compact but can be tough for humans to read.</li>
<li>The functionality of <var>Stringify</var> is practically identical to that of <var>[[ToString (Json function)|ToString]]</var>. The only difference is that <var>Stringify</var> throws a <var>[[JsonCircularReference class|JsonCircularReference]]</var> exception if the <var>Json</var> object leads to a [[Json class#Circular references|circular reference]]. Because the JSON specification does not allow for circular references, <var>Stringify</var> is probably the preferred function to use for generating JSON to send to another platform &mdash; it's better to catch the exception in Model&nbsp;204 than to send bad JSON data to someone else.</li>
 
<li>If no indentation is used (<var>Indent</var> defaults or is set to 0), no whitespace is added between any of the JSON tokens and separator characters (curly and square braces, commas, and colons). This format is very compact but can be tough for humans to read.</li>
 
<li>If indentation is used, a [http://en.wikipedia.org/wiki/Newline unicode linefeed character] (u+000a) is added before each array item or object property and after the last array item or object property. If the unicode data is printed or audited, the unicode linefeed characters will cause a new line to be started on the screen or audit trail. This will make the serialized JSON data much nicer and easier to read.</li>
<li>If indentation is used, a [http://en.wikipedia.org/wiki/Newline unicode linefeed character] (u+000a) is added before each array item or object property and after the last array item or object property. If the unicode data is printed or audited, the unicode linefeed characters will cause a new line to be started on the screen or audit trail. This will make the serialized JSON data much nicer and easier to read.</li>
<li>The <var>Indent</var> value indicates the number of blank characters per indentation level to place before each new line of data. Every array and object increases the indentation level by one inside its boundaries. So if an array is inside an object which is inside another object that array's indentation level is 3. With an <var>Indent</var> value of 2 each array item in that array will have 6 space characters in front of it.</li>
 
<li>The <var>Indent</var> value indicates the number of blank characters per indentation level to place before each new line of data. Every array and object increases the indentation level by one inside its boundaries. So if an array is inside an object which is inside another object, that array's indentation level is 3. With an <var>Indent</var> value of 2, each array item in that array will have 6 space characters in front of it.</li>
 
<li>If a non-zero <var>Indent</var> value is used, a single space character is always placed after the colon in an object property name.</li>
<li>If a non-zero <var>Indent</var> value is used, a single space character is always placed after the colon in an object property name.</li>
<li>If the serialized JSON data is to be sent to another platform, the unicode JSON data generally needs to be UTF-8 or UTF-16 encoded which can be done by using the [[UnicodeToUtf8 (Unicode function)|UnicodeToUtf8]] or [[UnicodeToUtf16 (Unicode function)|UnicodeToUtf16]] Unicode functions. Even if the data is known to only contain data that is translatable to EBCDIC it is best to avoid converting it to EBCDIC, if possible.</li>
 
<li>A null Json object serializes as the unicode literal <code>null</code>.</li>  
<li>If the serialized JSON data is to be sent to another platform, the unicode JSON data generally needs to be UTF-8 or UTF-16 encoded, which can be done by using the <var>[[UnicodeToUtf8 (Unicode function)|UnicodeToUtf8]]</var> or <var>[[UnicodeToUtf16 (Unicode function)|UnicodeToUtf16]]</var> <var>Unicode</var> functions. Even if the data is known to contain only data that is translatable to EBCDIC, it is best to avoid converting it to EBCDIC, if possible.</li>
 
<li>A null <var>Json</var> object serializes as the unicode literal <code>null</code>.</li>  
</ul>
</ul>


==Examples==
==Examples==
The following example builds a Json object tree then serializes it using Stringify and prints the result:
The following example builds a <var>Json</var> object tree, then serializes it using <var>Stringify</var> and prints the result:
<p class="code">b
<p class="code">b


Line 42: Line 55:
</p>
</p>
This prints:
This prints:
<p class="code">%json:stringify(indent=2)={
<p class="output">%json:stringify(indent=2)={
   "Lee": "To Kill a Mockingbird",
   "Lee": "To Kill a Mockingbird",
   "Faulkner": [
   "Faulkner": [
Line 56: Line 69:
}
}
</p>
</p>
If the <code>indent=2</code> were removed from the above code, it would print (wrapping at column 80):
If the <code>indent=2</code> is removed from the above code, it prints (wrapping at column 80):
<p class="code">%json:stringify(indent=0)={"Lee":"To Kill a Mockingbird","Faulkner":["As I Lay -
<p class="output">%json:stringify(indent=0)={"Lee":"To Kill a Mockingbird","Faulkner":["As I Lay -
Dying","Absalom, Absalom","The Sound and the Fury"],"Hurston":["Jonah's Gourd V-
Dying","Absalom, Absalom","The Sound and the Fury"],"Hurston":["Jonah's Gourd V-
ine","Their Eyes Were Watching God"],"Ellison":"Invisible Man"}
ine","Their Eyes Were Watching God"],"Ellison":"Invisible Man"}
</p>
</p>
==See also==
==See also==
{{Template:Json:Stringify footer}}
{{Template:Json:Stringify footer}}

Latest revision as of 16:02, 23 August 2016

Serialize a JSON object (Json class)

[Introduced in Model 204 7.6]

This function serializes a Json object tree as a unicode JSON string.

Syntax

%unicode = json:Stringify[( [Indent= number])] Throws JsonCircularReference

Syntax terms

%unicode A unicode string that contains the JSON format serialization of the Json object tree.
Json Json object, which may be Null or any underlying Json object type (boolean, number, string, array, or object).
Indent The number of space characters to add in front of each line for each nesting level (see below for more details). The default value of Indent is 0, which means lines will not be indented.

Usage notes

  • The name Stringify derives from the equivalent JavaScript method: JSON.stringify.
  • The functionality of Stringify is practically identical to that of ToString. The only difference is that Stringify throws a JsonCircularReference exception if the Json object leads to a circular reference. Because the JSON specification does not allow for circular references, Stringify is probably the preferred function to use for generating JSON to send to another platform — it's better to catch the exception in Model 204 than to send bad JSON data to someone else.
  • If no indentation is used (Indent defaults or is set to 0), no whitespace is added between any of the JSON tokens and separator characters (curly and square braces, commas, and colons). This format is very compact but can be tough for humans to read.
  • If indentation is used, a unicode linefeed character (u+000a) is added before each array item or object property and after the last array item or object property. If the unicode data is printed or audited, the unicode linefeed characters will cause a new line to be started on the screen or audit trail. This will make the serialized JSON data much nicer and easier to read.
  • The Indent value indicates the number of blank characters per indentation level to place before each new line of data. Every array and object increases the indentation level by one inside its boundaries. So if an array is inside an object which is inside another object, that array's indentation level is 3. With an Indent value of 2, each array item in that array will have 6 space characters in front of it.
  • If a non-zero Indent value is used, a single space character is always placed after the colon in an object property name.
  • If the serialized JSON data is to be sent to another platform, the unicode JSON data generally needs to be UTF-8 or UTF-16 encoded, which can be done by using the UnicodeToUtf8 or UnicodeToUtf16 Unicode functions. Even if the data is known to contain only data that is translatable to EBCDIC, it is best to avoid converting it to EBCDIC, if possible.
  • A null Json object serializes as the unicode literal null.

Examples

The following example builds a Json object tree, then serializes it using Stringify and prints the result:

b %json is object json %title is string len 64 %i is float %json = object %json("Lee") = "To Kill a Mockingbird" %json("Faulkner") = array("As I Lay Dying", "Absalom, Absalom", "The Sound and the Fury") %json("Hurston") = array("Jonah's Gourd Vine", "Their Eyes Were Watching God") %json("Ellison") = "Invisible Man" printText {~=%json:stringify(indent=2)} end

This prints:

%json:stringify(indent=2)={ "Lee": "To Kill a Mockingbird", "Faulkner": [ "As I Lay Dying", "Absalom, Absalom", "The Sound and the Fury" ], "Hurston": [ "Jonah's Gourd Vine", "Their Eyes Were Watching God" ], "Ellison": "Invisible Man" }

If the indent=2 is removed from the above code, it prints (wrapping at column 80):

%json:stringify(indent=0)={"Lee":"To Kill a Mockingbird","Faulkner":["As I Lay - Dying","Absalom, Absalom","The Sound and the Fury"],"Hurston":["Jonah's Gourd V- ine","Their Eyes Were Watching God"],"Ellison":"Invisible Man"}

See also