diff --git a/README.md b/README.md index 404989a..a20eac9 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,31 @@ # JSON Library ## Description + This Library will provides the possibility to serialize and deserialize JSON Files. ## Install this package Enter: + ```cli apax add @simatic-ax/json ``` -> to install this package you need to login into the GitHub registry. You'll find more information [here](https://github.com/simatic-ax/.sharedstuff/blob/main/doc/personalaccesstoken.md) +> to install this package you need to login into the GitHub registry. You'll find more information [here](https://github.com/simatic-ax/.sharedstuff/blob/main/doc/personalaccesstoken.md) ## Namespace + ``` Simatic.Ax.Json; ``` # Deserializing -Use the _Deserializer_ class to deserialize JSON documents and parse values from the document. + +Use the _Deserializer_ class to deserialize JSON documents and parse values from the document. ## Restrictions + In the current version we have several restrictions regarding the handling of JSON files. 1. The JSON File must be in the form of a ARRAY [] OF CHAR. Read more in the _Workflow_ part. @@ -54,14 +59,15 @@ In the current version we have several restrictions regarding the handling of JS ## Workflow -### Pre-requirements. -1. You need to use the library _Simatic.Ax.Conversion_ and _Simatic.Ax.Json_; +### Pre-requirements + +1. You need to use the library _Simatic.Ax.Conversion_ and _Simatic.Ax.Json_; 2. The deserializer currently expects an _ARRAY[0..999] OF CHAR_ as a buffer. If your JSON File is a STRING you can use the _Simatic.Ax.Conversion_ as shown in the example below. 3. Finally you must set the buffer for the deserializer with the _SetBuffer_ method. The buffer is expected as a reference. ### Get values -Use the _TryParse_ method to get values that match your provided STRING key . If you want to get values of nested elements you must instead provide a ARRAY [X] OF STRING, with a key for each nested layer. +Use the _TryParse_ method to get values that match your provided STRING key . If you want to get values of nested elements you must instead provide a ARRAY [X] OF STRING, with a key for each nested layer. The datatype _TryParse_ will return depends on the datatype of the value you provide. @@ -124,15 +130,18 @@ parsingWasSuccessfull:= TryParse('not a key', value3); |TryParse(input: key (STRING), output: value) : BOOL| Returns false when parsing not succesfull and provides the value. The method is overloaded and accepts different data types. | |TryParse(input: key(ARRAY OF STRING), output: value) : BOOL| Returns false when parsing not succesfull and provides the value. The method is overloaded and accepts different data types. The key array is used to access values in nested elements. | ||| + ### Duplicate keys The JSON Format allows a user to have duplicate keys in his json document, e.g. + ```JSON { "key" : "my value", "key" : 1234 } ``` + However, the norm does not define, how duplicate keys should be processed. In case of a duplicate key, this library will alwys try to parse the first key and ignore the second one. # Serializing @@ -143,8 +152,8 @@ However, the norm does not define, how duplicate keys should be processed. In ca # Examples - ## Example ho to use the JSON library + This example shows in how to create, serialize, parse and reset a JSON document. ``` @@ -230,4 +239,3 @@ Thanks for your interest in contributing. Anybody is free to report bugs, unclea ## License and Legal information Please read the [Legal information](LICENSE.md) - diff --git a/changelog.md b/changelog.md deleted file mode 100644 index 07a9290..0000000 --- a/changelog.md +++ /dev/null @@ -1,32 +0,0 @@ -# Changelog - -## January 2022-02-02 -0.0.1 First draft - -## February 2022-02-28 - -**Version:** 0.0.5 - -Deserializer and Serializer are shipped together. Including documentation - -**Version:** 0.0.6 - -JSonDocument.CleanBuffer() method added. [Issue](https://github.com/simatic-ax/Json/issues/12) - -## March 2022-03-14 - -**Version:** 0.1.0 - -* Fixing issue Now also nested objects will be serialized correctly -* JSonDocument and JsonObject implementing IJsonContainerElement now -* All public classes/types are FINAL, so they cant be inherited -* AddElement supports the create pattern now. `doc.AddElement(a).AddElement(b)` - - -## June 2022-06-24 - -**Version:** 0.2.0 - -* Depends now on System.Math 1.1.13 Update dependencies - -Version 1.0.0 \ No newline at end of file diff --git a/docs/JsonDocument.md b/docs/JsonDocument.md index 56e5af1..9524761 100644 --- a/docs/JsonDocument.md +++ b/docs/JsonDocument.md @@ -1,10 +1,11 @@ # Json Document ## Description -The JsonDocument contains the object model of the Json object. +The JsonDocument contains the object model of the Json object. ## Object + ```mermaid classDiagram IJsonContainerElement<|--JsonDocument @@ -24,21 +25,27 @@ JsonDocument : Reset() Returns the JSON string of the JSON document (max. 254 characters) ### Serialize() : BOOL + Serializes the JSON document ino a ARRAY OF CHAR. JsonDocument.buffer must be set before. ### GetRootElement() : IJsonElement + Returns root element of the JSON document ### AddElement(elem : IJsonElement) + Add a new element to the JSON document ### ClearBuffer(hard : BOOL) + Clear the buffer logically (fast). If `hard = TRUE` then delete the buffer also physically (slow) JsonDocument.buffer must be set before. ### 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; diff --git a/docs/JsonObject.md b/docs/JsonObject.md index 10b1d0d..19eef69 100644 --- a/docs/JsonObject.md +++ b/docs/JsonObject.md @@ -5,16 +5,18 @@ 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 +---