Merge pull request #22 from simatic-ax/11-document-reset

feat: Add Reset method to JsonDocument

README.md

@@ -136,21 +136,9 @@ The JSON Format allows a user to have duplicate keys in his json document, e.g.
 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
-## JsonDocument
-### Definition
-Contains the root element of the JSON string
 
-### Methods
+## [JsonDocument](docs/JsonDocument.md)
 
-|||
-|-|-|
-|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 document|
-|ClearBuffer(hard : BOOL)| Clear the buffer logically (fast). If `hard = TRUE` then delete the buffer also physically (slow) |
-|||
-### 
----
 ### AbstractJsonElement
 
 ---

docs/JsonDocument.md

@@ -0,0 +1,41 @@
+# Json Document
+
+## Description
+The JsonDocument contains the object model of the Json object.
+
+
+## Object
+```mermaid
+classDiagram
+IJsonContainerElement<|--JsonDocument
+IJsonContainerElement : AddElement(IJsonElement)
+JsonDocument : STRING ToString()
+JsonDocument : BOOL Serialize(ARRAY[*] OF CHAR)
+JsonDocument : IJsonElement GetRootElement()
+JsonDocument : ClearBuffer(BOOL)
+JsonDocument : Reset()
+
+```
+
+## Methods
+
+### ToString() : STRING
+
+Returns the JSON string of the JSON document (max. 254 characters)
+
+### Serialize(IN_OUT buf : ARRAY[*] OF CHAR) : BOOL
+Serializes the JSON document ino a ARRAY OF CHAR
+
+### 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)
+
+### Reset()
+Reset the complete object tree and the destination buffer of the JSON document for the purpose, a new JSON object should be created.
+
+

src/Document/JsonDocument.st

@@ -1,6 +1,9 @@
 USING System.Strings;
 
 NAMESPACE Simatic.Ax.Json
+
+    /// The JsonDocument contains the object model of the Json object.
+    {axcode:docs-v0:@simatic-ax/json:JsonDocument.md}
     CLASS FINAL JsonDocument IMPLEMENTS IJsonContainerElement
         VAR PUBLIC
             buffer : ARRAY[0..999] OF CHAR;
@@ -15,6 +18,7 @@ NAMESPACE Simatic.Ax.Json
             _bufIndex : DINT;
         END_VAR
 
+        /// Returns the JSON string of the JSON document (max. 254 characters)
         METHOD PUBLIC ToString : STRING
             VAR_TEMP
                 _str : STRING;
@@ -34,6 +38,7 @@ NAMESPACE Simatic.Ax.Json
             ToString := _str;
         END_METHOD
 
+        /// Serializes the JSON document ino a ARRAY OF CHAR
         METHOD PUBLIC Serialize : BOOL
             VAR_IN_OUT
                 buf : ARRAY[*] OF CHAR;
@@ -86,14 +91,17 @@ NAMESPACE Simatic.Ax.Json
             AddString := TRUE;
         END_METHOD
 
+        /// Returns the count of the serialized cahracters
         METHOD PUBLIC GetLength : DINT
             GetLength := _lentgh;
         END_METHOD
 
+        /// Returns root element of the JSON document
         METHOD PUBLIC GetRootElement : IJsonElement
             GetRootElement := _rootElement;
         END_METHOD
 
+        /// Add a new element to the JSON document
         METHOD PUBLIC AddElement : IJsonContainerElement
             VAR_INPUT
                 elem : IJsonElement;
@@ -116,6 +124,9 @@ NAMESPACE Simatic.Ax.Json
             AddElement := THIS;
         END_METHOD
 
+        /// Clear the buffer logically (fast). 
+        /// If `hard = TRUE` then delete the buffer also 
+        /// physically (slow)
         METHOD PUBLIC ClearBuffer
             VAR_INPUT
                 hard : BOOL := FALSE;
@@ -134,5 +145,28 @@ NAMESPACE Simatic.Ax.Json
             _lentgh := 0;
         END_METHOD
 
+        /// Reset the complete object tree and the destination buffer 
+        /// of the JSON document for the purpose, a new JSON object should
+        /// be created.
+        METHOD PUBLIC Reset
+            VAR_TEMP
+                _currentElement : IJsonElementMuteable;
+                _nextElement : IJsonElementMuteable;
+            END_VAR
+
+            _currentElement := _firstElement;
+            WHILE _currentElement <> NULL DO
+                _nextElement := _currentElement.GetNext();           
+                _currentElement.Reset();      
+                _currentElement := _nextElement;    
+            END_WHILE;
+
+            // Clear the buffer
+            THIS.ClearBuffer(hard := TRUE);
+            _firstElement := NULL;
+            _lastElement := NULL;
+            _rootElement := NULL;
+        END_METHOD
+
     END_CLASS
 END_NAMESPACE

src/Elements/AbstractJsonElement.st

@@ -53,6 +53,11 @@ NAMESPACE Simatic.Ax.Json
             GetNext := _next;
         END_METHOD
 
+        METHOD PUBLIC Reset
+            _next := NULL;
+        END_METHOD
+
+
         METHOD PUBLIC Insert
             VAR_INPUT
                 elem : IJsonElement;

src/Elements/IJsonElementMuteable.st

@@ -15,5 +15,7 @@ NAMESPACE Simatic.Ax.Json
                 doc : REF_TO JsonDocument;
             END_VAR
         END_METHOD
+        METHOD Reset
+        END_METHOD
     END_INTERFACE
 END_NAMESPACE

src/Elements/Object/JsonObject.st

@@ -65,6 +65,23 @@ NAMESPACE Simatic.Ax.Json
             Serialize := TRUE;
         END_METHOD
 
+        METHOD PUBLIC OVERRIDE Reset
+            VAR_TEMP
+                _currentElement : IJsonElementMuteable;
+                _nextElement : IJsonElementMuteable;
+            END_VAR
+
+            SUPER.Reset();
+
+            _currentElement := _firstElement;
+            WHILE _currentElement <> NULL DO
+                _nextElement := _currentElement.GetNext();           
+                _currentElement.Reset();      
+                _currentElement := _nextElement;    
+            END_WHILE;
+
+        END_METHOD
+
         METHOD PUBLIC AddElement : IJsonContainerElement
             VAR_INPUT
                 elem : IJsonElement;

test/Document/TestResetMethod.st

@@ -0,0 +1,57 @@
+USING AxUnit.Assert;
+USING System.Strings;
+USING Simatic.Ax.Conversion;
+USING Simatic.Ax.Json;
+
+NAMESPACE Document
+    {TestFixture}
+    CLASS TestResetDocument
+
+        VAR PROTECTED
+            e1 : JsonDInt := (Value := 999, Key := 'e1');
+            e2 : JsonBoolean := (Key := 'e2', Value := TRUE);
+            e3 : JsonString := (Key := 'e3', Value := 'MyString');
+            o1 : JSonObject := (Key := 'o1');
+            oi1 : JsonSInt := (Key := 'oi1', Value := SINT#1);
+            oi2 : JsonSInt := (Key := 'oi2', Value := SINT#1);
+            e4 : JsonLInt := (Key := 'e4', Value := LINT#1);
+
+
+            doc : JsonDocument;
+            cmpBuff : ARRAY[0..399] OF CHAR;
+            cmpBuffEmpty : ARRAY[0..399] OF CHAR;
+            len : DINT;
+        END_VAR
+
+        {Test}
+        METHOD PUBLIC Reset_flat_document_removes_all_next_elements_from_the_json_objects
+            VAR_TEMP
+                _to : IJsonElementMuteable;
+                _elem : IJsonElement;                    
+            END_VAR
+
+            doc.AddElement(e1);
+            doc.AddElement(e2);
+            doc.AddElement(e3);
+            doc.AddElement(o1);
+            doc.AddElement(e4);
+            o1.AddElement(oi1);
+            o1.AddElement(oi2);
+
+
+            doc.Reset();
+
+            Equal(expected := FALSE, actual := e1.HasNext());
+            Equal(expected := FALSE, actual := e2.HasNext());
+            Equal(expected := FALSE, actual := e3.HasNext());
+            Equal(expected := FALSE, actual := e4.HasNext());
+            Equal(expected := FALSE, actual := o1.HasNext());
+            Equal(expected := FALSE, actual := oi1.HasNext());
+            Equal(expected := FALSE, actual := oi2.HasNext());
+            Equal(expected := TRUE, actual := doc.GetRootElement() = NULL);
+            Equal(expected := DINT#0, actual := doc.GetLength());
+
+        END_METHOD
+
+    END_CLASS
+END_NAMESPACE