JSON - Format Points into Javascript - JSON Format
| str = JSON ( opttag pt1 (name pt2) (pt3) ... ) |
| str | The resulting string in one of various JSON formats. | |
| opttag | Zero or more optional tags below. | |
| pt1 | One or more points to be formatted with the dimension name as the JSON tag name. | |
| name | An explicit name to be used as the JSON tag name. | |
| pt2 | A value to be used with the prior tag name. | |
| pt3 | A single point within a list is taken as a literal value (i.e. no tag name is used). This is for embedding fully formatted JSON strings within another JSON entry. |
| Array::list | The list is a list of XML tag names that are to be treated as JSON arrays, not objects. Multiple consecutive instances of any XML tags matched in the list are consolidated into a single named JSON array, not multiple JSON objects of the same name. | |
| Array::tagname | The following arguments are elements of the named JSON array. | |
| Attributes::logical | If TRUE (default) then return XML attributes in the JSON expressions. If FALSE then ignore XML attributes. See below for more discussion. | |
| Delete::name | Delete the top-level JSON object with the given name. | |
| Function::val | Same as the Name except that val is considered a JavaScript function and is not enclosed in quotes. | |
| Ignore::list | The list is a list of XML tag names that are to be ignored. This option can be used to simplify the resulting JSON object when parsing an XML string. | |
| JSON::str | Append the str unchanged (it is assumed to be in valid JSON format). | |
| Name::name | Specifies the name of the JSON field. The next argument must be a Value or untagged argument and is treated as the value of the JSON name variable/element. | |
| Object::tagname | The following arguments are elements of the named JSON object. | |
| Parse::str | Parse the str as a JSON string and store the resulting object for future reference. | |
| Parse::list | Parse the contents of the V4 list as a JSON string. | |
| Parse::id | Parses the contents of Output buffer id as a JSON string. | |
| Quoted::logical | This is a global option that determines whether or not each name in a name:value pair is quoted or note. If TRUE then the name is always quoted, if FALSE then it is only quoted if it is not a valid Javascript identifier. Once this option is set it remains in effect until explicitly changed. | |
| Style::option | Various parsing options can be controlled with this tagged argument. If option is Comma then a JSON string with extra commas is allowed. If the option is LeadingZero then numeric values with leading zeros are treated as strings, not numbers. Options set with this apply only to the current JSON call. | |
| Style::list | Multiple style options may be specified as a list. | |
| Suffix::str | Append str to each of the following argument tag names. If str is empty then no suffix is appended. The case of the suffix is not affected by any of the case tags (Dim?, LC?, UC?). If the argument is UV4:none then there is no suffix. | |
| Top::name | Specifies the name of the top-level JSON object when converting/parsing JSON or XML. The default name is xml when converting XML to JSON. Setting name to UV4:none will eliminate the top-level object for XML to JSON parsing. | |
| Value::val | The value for the current JSON element (see Name tag). | |
| XML::stream | Convert the XML contained in the named (buffered) stream to JSON. | |
| XML::list | Convert the XML described within the elements of list to JSON. | |
| XML::str | Convert the XML str to the equivalent JSON format. If this is used in conjunction with the Parse? tag then the JSON string will be parsed and the resulting object stored within the V4 runtime. The top-level object name is xml |
| Array? | Enclose the following arguments within brackets ('[ ... ]') but without a tag name. | |
| Dim? | If the element name has a corresponding dimension then use the exact dimension name (case). If no corresponding dimension exists then the element name is not changed. | |
| LC? | Convert all following element names to lower case. | |
| Object? | Enclose the following arguments within braces ('{ ... }') but without a tag name. | |
| Parse? | Parse the non-JSON string as a JSON string. This argument is currently used with the XML tag. | |
| UC? | Convert all following element names to upper case. |
This module formats V4 points into a valid JSON string. This module may be nested allowing for nested JSON strings of varying complexity.
Note that javascript is case sensitive. The upper and lower case tags can be used to force all upper or lower case. The Dim? option will normalize element names to those of the parent dimension (if the dimension exists).
If an argument is UV4:none then it is ignored.
The JSON module is limited to the length of a V4 string for the value. There are two methods for outputting extremely long JSON values. The first is with the JSON option in the Echo module. This allows you use the contents of a file as a json value. The other method is with the EchoP module. The V4 web interface treats newlines as value delimiters when dealing with json values. The EchoP module does not output a newline. Therefore you can construct json values of virtually unlimited size. See below for an example.
The Attributes tagged argument is used to control whether or not XML attributes are included in the resulting JSON expression. Including attributes presents somewhat of a representational problem. XML tags that do not have values will have their attributes given as a sub-element to 'attr'. Tags that have values will have attributes given as a separate JSON object named tag_attr. For instance <tag1 a="b" c="d"><tag2 e="f">g</tag2></tag1> converts to the JSON expression {TAG1:{ATTR:{A:'b',C:'d'},TAG2_ATTR:{E:'f'},TAG2:'g'}}.
| JSON(Object::ob1 123 hoho "moo") | ob1':{'Int':123,'NId':"hoho",'Alpha':"moo"} | |
| JSON(Object::ob1 Suffix::"_x" 123 hoho "moo") | 'ob1':{'Int_x':123,'NId_x':"hoho",'Alpha_x':"moo"} | |
| JSON(Object? JSON(Object::ob1 123 hoho "moo") (nid 456) (Logical:yes))) | {'ob1':{'Int':123,'NId':"hoho",'Alpha':"moo"},'nid':456,true} | |
| JSON(Dim? Object? JSON(Object::ob1 123 hoho "moo") (nid 456) (Logical:yes))) | {'ob1':{'Int':123,'NId':"hoho",'Alpha':"moo"},'NId':456,true} | |
| JSON(UC? Object::ob1 123 hoho "moo") | 'ob1':{'INT':123,'NID':"hoho",'ALPHA':"moo"} | |
| JSON(Name::var1 Value::(1 2 3 4)) | 'var1':[1,2,3,4] | |
| JSON(Name::var1 (1 2 3 4)) | 'var1':[1,2,3,4] | |
| JSON(Style:LeadingZero Parse::"... zipcode:02139 ...") | zipcode will be represented as the string "02139", not numeric 2139 | |
| JSON(XML::"<cus><name>John Doe</name><address>1234 Anywhere</address></cus>") | xml:{cus:{name:"John Doe",address:"1234 Anywhere"}} | |
| JSON(Ignore::(cus) XML::"<cus><name>John Doe</name><address>1234 Anywhere</address></cus>") | xml:{name:"John Doe",address:"1234 Anywhere"} | |
| JSON(Top::UV4:none XML::"<cus><name>John Doe</name><address>1234 Anywhere</address></cus>") | cus:{name:"John Doe",address:"1234 Anywhere"} | |
| JSON(XML::"<toDelete><item>123</item><item>443</item><item>545</item><item>444</item><item>998</item></toDelete>") | xml:{toDelete:{item:123,item:443,item:545,item:444,item:998}} | |
| JSON(Array::(item) XML::"<toDelete><item>123</item><item>443</item><item>545</item><item>444</item><item>998</item></toDelete>") | xml:{toDelete:{item:[123,443,545,444,998]}} | |
| JSON(Top::"foo" Parse::"{x1:1, x2:2, x3:3}") | Parses JSON string with top level name of 'foo' (ex: $(foo.x1)) |
Example 30 - Returning Large JSON Value
|
[returnOrderAsJSON ordId..] Do(Context::ordHeader[ordId*],EchoW("Order does not exist: " ordId*) EchoP("order:{") EchoP("header:{" List(JSON(EvalPt("ordHeader." NId*))/(ordId ordStatus entryDate ...) Column::",") "}") EchoP(",detail:[") Enum(ordDetail:(ordHeader*) Index::Dim:Int @EchoP(If({Int* > 1} Then::",") "{" List(JSON(EvalPt("ordDetail." NId*))/(item desc qty price extendAmt ...) Column::",") "}")) EchoP("]") /* Close off ordDetail array */ Echo("}") /* Close off main bracket and end with newline */ ) |
JSONRef - Return Value of JSON Reference
| value = JSONRef ( name name ... ) | |
| value = JSONRefDim ( arguments same as JSONRef ) | |
| value = $ ( name.name... ) | |
| value = $$ ( name.name... ) |
| value | The resulting referenced JSON element | |
| name | A JSON object or array subscript |
This module is used to reference a particular element within a JSON object and return its value. The JSONRef module returns the value as a point on Dim:Alpha, Dim:Num, Dim:Int or Dim:Logical. The JSONRefDim module returns the value as a point on the dimension name given in the reference. For example, given the JSON object: 'obj:{el1:?Dim:NId a?Dim:NId String, el2:234, el3:false}' then JSONRef(obj el2) returns the point Num:234 while JSONRefDim(obj el2) returns the point el2:234. If the referenced dimension does not exist then the module fails.
The raw usage of these two modules is counter-intuitive to Javascript programming. V4 supports two additional formats that more closely resemble the dot notation dereferencing of JSON objects. The '$()' syntax can be used in place of the JSONRef modules and the '$$()' syntax to replace the JSONRefDim module. A dot notation is used within these two dollar sign modules. For example $(obj.el1) is equivalent to JSONRef(obj el1) and $$(obj.el3) is equivalent to JSONRefDim(obj el3).
JSON arrays and objects may be indexed directly with an integer reference. Given an object such as 'arg:{name:"John", relatives:[{name:"John",relation:"father"},{...},{...}], ...}' then $(arg.relatives.4.name) references the fourth relative. Note that indexing is 1-based, not 0-based.
JSON arrays and objects may also be enumerated with the Enum and EnumCL modules. Use the Shell argument within these two modules to reference the enumerated values.
V4 supports several reserved reference names that are described below-
Table 13 - Reserved JSON Reference Names
| elementNames | Returns a list of the referenced element names |
| length | Returns the integer length of the object or array |
| serialize | Returns a string representation of the referenced object |
| typeOf | Returns a point on Dim:UV4 describing the referenced object, one of UV4:object,array,integer,undefined |
| nameOf | Returns the name of the referenced object |
| JSON(Parse::"empTime:[{tdT:235,date:'20-Jan-2014',hours:6,desc:'MTS - combine stuff'},{tdT:194,date:'13-Jan-2014',hours:1,desc:'2014S review meeting'}]") | parse a JSON string | |
| $(empTime.date) | Alpha:"20-Jan-2014" | |
| $(empTime.date) | date:20-Jan-2014 | |
| EnumCL($(empTime.1) Shell::Dim:s @s*) | (Int:235 Alpha:"20-Jan-2014" Int:6 Alpha:"MTS - combine stuff") | |
| EnumCL($$(empTime.1) Shell::Dim:s @s*) | (tdt:235 date:20-Jan-2014 hours:6 desc:"MTS - combine stuff") | |
| $(empTime.1.elementNames) | (tdt date hours desc) | |
| $(empTime.length) | 2 | |
| $(empTime.typeOf) | UV4:array | |
| $(empTime.description.typeOf) | UV4:undefined |