diff --git a/README.md b/README.md index f81c0f8..4d19def 100644 --- a/README.md +++ b/README.md @@ -139,78 +139,87 @@ However, the norm does not define, how duplicate keys should be processed. In ca ## [JsonDocument](docs/JsonDocument.md) -### AbstractJsonElement +## [JsonObject](docs/JsonObject.md) ---- -## JsonObject +# Examples -### Definition -Inheritance: AbstractJsonElement-->JsonObject +## Example ho to use the JSON library +This example shows in how to create, serialize, parse and reset a JSON document. -### Public members -||| -|-|-| -|value : DINT;| Value of this element -|key : STRING := 'NoKeySet';| Key of this element -### Methods -||| -|-|-| -|ToString() : STRING;| Returns the JSON string of this element| -|GetRootElement() : IJsonElement| Returns root element of the JSON object| -|AddElement(elem : IJsonElement)| Add a new element to the JSON object| -||| ---- -## DoubleInt - -### Definition - -Inheritance: AbstractJsonElement-->JsonNumber-->DoubleInt +``` +USING Simatic.Ax.Conversion; +USING Simatic.Ax.Json; -### Public members -||| -|-|-| -|value : DINT;| Value of this element -|key : STRING := 'NoKeySet';| Key of this element +CONFIGURATION MyConfiguration + TASK Main (INTERVAL := T#100ms, PRIORITY := 1); + PROGRAM P1 WITH Main: MyProgram; + VAR_GLOBAL + SerializedDocument : STRING; + ParsedValue : DINT; + END_VAR +END_CONFIGURATION + +PROGRAM MyProgram + VAR_EXTERNAL + SerializedDocument : STRING; + ParsedValue : DINT; + END_VAR + VAR + doc : JsonDocument; + myBoolean : JsonBoolean := (Value := TRUE, Key := 'myBoolean'); + myInt : JsonInt := (Value := 1234, Key := 'myInt'); + myDint : JsonDInt := (Value := DINT#12345678, Key := 'myDint'); + myObject : JsonObject := (Key := 'myObject'); + deserializer : Deserializer; + keyFound : BOOL; + dintValue : DINT; + keyArray : ARRAY[0..1] OF STRING := ['myObject', 'myDint']; + step : Steps; + END_VAR + VAR_TEMP + END_VAR + CASE step OF + Steps#CreateDocument2: + // Create nested JSON document which looks like: + // {"myBoolean": true, "myObject": {"myInt": 1234, "myDint": 12345678}} + myObject.AddElement(myInt); + myObject.AddElement(myDint); + doc.AddElement(myBoolean); + doc.AddElement(myObject); + step := Steps#SerializeDocument2; + Steps#SerializeDocument2: + // Serialize the document {"myBoolean": true, "myObject": {"myInt": 1234, "myDint": 12345678}} + doc.Serialize(doc.buffer); + SerializedDocument := Arrays.ToString(arr := doc.buffer); + step := Steps#ParseDocument2; + ; + Steps#ParseDocument2: + // Parse Document for the value of the nested key `myObject.myDint` and expect `12345678` + // Get Values from a nested element + deserializer.SetBuffer(REF(doc.buffer)); + keyFound := deserializer.TryParse(keyArray, dintValue); + ParsedValue := dintValue; + step := Steps#ResetJSonDocument2; + ; + Steps#ResetJSonDocument2: + // ResetJSonDocument 2nd configuration + doc.Reset(); + step := Steps#CreateDocument2; + ; + END_CASE; +END_PROGRAM + +TYPE + Steps : (CreateDocument2, SerializeDocument2, ParseDocument2, ResetJSonDocument2) := CreateDocument2; +END_TYPE +``` -### Methods +## Application Example -||| -|-|-| -|ToString() : STRING;| Returns the JSON string of this element +A complete application example, you can find here: -## Example -```iec-st -USING Simatic.Ax.Json; -USING AxUnit.Assert; - -NAMESPACE Simatic.Ax - CLASS JsonExample - VAR PUBLIC - - END_VAR - VAR PROTECTED - doc : JsonDocument; - e1 : JsonDoubleInt := (key := 'Element1', value := 1); - e2 : JsonDoubleInt := (key := 'Element2', value := 2); - e3 : JsonDoubleInt := (key := 'Element3', value := 3); - o1 : JsonObject := (key := 'NestedObject'); - - END_VAR - - METHOD PUBLIC Init; - // Example String: - // {"Element1": 1, {"Element2": 2, "Element3": 3}} - doc.AddElement(e1).AddElement(o1); - o1.AddElement(e2).AddElement(e3); - END_METHOD - - METHOD PUBLIC ToString : STRING - ToString := doc.ToString(); - END_METHOD - END_CLASS -END_NAMESPACE -``` +[JSON Application Example](https://github.com/simatic-ax/ae-json-library) ## Contribution diff --git a/docs/JsonDocument.md b/docs/JsonDocument.md index 657882f..c152941 100644 --- a/docs/JsonDocument.md +++ b/docs/JsonDocument.md @@ -38,4 +38,35 @@ Clear the buffer logically (fast). If `hard = TRUE` then delete the buffer also ### Reset() Reset the complete object tree and the destination buffer of the JSON document for the purpose, a new JSON object should be created. +## Example +```iec-st +USING Simatic.Ax.Json; +USING AxUnit.Assert; +NAMESPACE Simatic.Ax + CLASS JsonExample + VAR PUBLIC + + END_VAR + VAR PROTECTED + doc : JsonDocument; + e1 : JsonDoubleInt := (key := 'Element1', value := 1); + e2 : JsonDoubleInt := (key := 'Element2', value := 2); + e3 : JsonDoubleInt := (key := 'Element3', value := 3); + o1 : JsonObject := (key := 'NestedObject'); + + END_VAR + + METHOD PUBLIC Init; + // Example String: + // {"Element1": 1, {"Element2": 2, "Element3": 3}} + doc.AddElement(e1).AddElement(o1); + o1.AddElement(e2).AddElement(e3); + END_METHOD + + METHOD PUBLIC ToString : STRING + ToString := doc.ToString(); + END_METHOD + END_CLASS +END_NAMESPACE +``` diff --git a/docs/JsonObject.md b/docs/JsonObject.md new file mode 100644 index 0000000..10b1d0d --- /dev/null +++ b/docs/JsonObject.md @@ -0,0 +1,20 @@ +# JsonObject + +### Definition + +Inheritance: AbstractJsonElement-->JsonObject + +### Public members +||| +|-|-| +|value : DINT;| Value of this element +|key : STRING := 'NoKeySet';| Key of this element + +### Methods +||| +|-|-| +|ToString() : STRING;| Returns the JSON string of this element| +|GetRootElement() : IJsonElement| Returns root element of the JSON object| +|AddElement(elem : IJsonElement)| Add a new element to the JSON object| +||| +--- \ No newline at end of file diff --git a/src/Document/JsonDocument.st b/src/Document/JsonDocument.st index 7412cc6..bc550d1 100644 --- a/src/Document/JsonDocument.st +++ b/src/Document/JsonDocument.st @@ -19,6 +19,7 @@ NAMESPACE Simatic.Ax.Json END_VAR /// Returns the JSON string of the JSON document (max. 254 characters) + {axcode:docs-v0:@simatic-ax/json:JsonDocument.md} METHOD PUBLIC ToString : STRING VAR_TEMP _str : STRING; @@ -39,6 +40,7 @@ NAMESPACE Simatic.Ax.Json END_METHOD /// Serializes the JSON document ino a ARRAY OF CHAR + {axcode:docs-v0:@simatic-ax/json:JsonDocument.md} METHOD PUBLIC Serialize : BOOL VAR_IN_OUT buf : ARRAY[*] OF CHAR; @@ -66,6 +68,7 @@ NAMESPACE Simatic.Ax.Json Serialize := TRUE; END_METHOD + {axcode:docs-v0:@simatic-ax/json:JsonDocument.md} METHOD PUBLIC AddChar : BOOL VAR_INPUT c : CHAR; @@ -76,6 +79,7 @@ NAMESPACE Simatic.Ax.Json AddChar := TRUE; END_METHOD + {axcode:docs-v0:@simatic-ax/json:JsonDocument.md} METHOD PUBLIC AddString : BOOL VAR_INPUT s : STRING; @@ -92,16 +96,19 @@ NAMESPACE Simatic.Ax.Json END_METHOD /// Returns the count of the serialized characters + {axcode:docs-v0:@simatic-ax/json:JsonDocument.md} METHOD PUBLIC GetLength : DINT GetLength := _lentgh; END_METHOD /// Returns root element of the JSON document + {axcode:docs-v0:@simatic-ax/json:JsonDocument.md} METHOD PUBLIC GetRootElement : IJsonElement GetRootElement := _rootElement; END_METHOD /// Add a new element to the JSON document + {axcode:docs-v0:@simatic-ax/json:JsonDocument.md} METHOD PUBLIC AddElement : IJsonContainerElement VAR_INPUT elem : IJsonElement; @@ -127,6 +134,7 @@ NAMESPACE Simatic.Ax.Json /// Clear the buffer logically (fast). /// If `hard = TRUE` then delete the buffer also /// physically (slow) + {axcode:docs-v0:@simatic-ax/json:JsonDocument.md} METHOD PUBLIC ClearBuffer VAR_INPUT hard : BOOL := FALSE; @@ -148,6 +156,7 @@ NAMESPACE Simatic.Ax.Json /// Reset the complete object tree and the destination buffer /// of the JSON document for the purpose, a new JSON object should /// be created. + {axcode:docs-v0:@simatic-ax/json:JsonDocument.md} METHOD PUBLIC Reset VAR_TEMP _currentElement : IJsonElementMuteable; diff --git a/src/Elements/Object/JsonObject.st b/src/Elements/Object/JsonObject.st index 11ebd68..5fd7ddf 100644 --- a/src/Elements/Object/JsonObject.st +++ b/src/Elements/Object/JsonObject.st @@ -1,6 +1,8 @@ USING System.Strings; NAMESPACE Simatic.Ax.Json + /// The Object contains nested JsonElements + {axcode:docs-v0:@simatic-ax/json:JsonObject.md} CLASS FINAL JsonObject EXTENDS AbstractJsonElement IMPLEMENTS IJsonContainerElement VAR PROTECTED