Merge pull request #181 from test-fullautomation/namsonx/task/stabi_b…

…ranch

Namsonx/task/stabi branch

config/robotframework_aio/release_items_JsonPreprocessor.json

@@ -45,20 +45,22 @@
 # ------------------------------------------
 
    "RELEASES"  : {
-                   "0.9." : [
-                              "JsonPreprocessor change 0.9 Implicit creation of data structures",
-                              "JsonPreprocessor change 0.9 Dotdict feature bug fixing",
-                              "JsonPreprocessor change 0.9 Update nested parameters handling in key name and value",
-                              "JsonPreprocessor change 0.9 Nested parameter feature bug fixing",
-                              "JsonPreprocessor change 0.9 Nested parameters substitution and overwriting improvement",
-                              "JsonPreprocessor change 0.9 Jsonp file path computation improvement"
-                            ],
                    "0.10." : [
-                               "JsonPreprocessor change 0.10 Add jsonDump method to write a file in JSON format",
-                               "JsonPreprocessor change 0.10 Improve nested parameter format",
-                               "JsonPreprocessor change 0.10 Improve error message log",
-                               "JsonPreprocessor change 0.10 Fix bugs of data structures implicitly",
-                               "JsonPreprocessor change 0.10 Improve index handling together with nested parameters"
+"
+* Added a ``jsonDump`` method to write the content of a Python dictionary to a file in JSON format
+
+  **Example:**
+
+  .. code::
+
+      dictTest = {\"A\"  1, \"B\"  2}
+      json_preprocessor = CJsonPreprocessor()
+      json_preprocessor.jsonDump(dictTest, \"./OutputFile.json\")
+
+* Improved format of nested parameters; improved error messages
+* Some bugs fixed in implicitly created data structures
+* Improved index handling together with nested parameters
+"
                              ]
                  }
-}
+}

packagedoc/additional_docs/Description.tex

@@ -32,16 +32,13 @@ \section{How to execute}
    print(f"'{reason}'")
 \end{pythoncode}
 
-\textbf{!!! Caution:} relative path bug:
-\href{https://github.com/test-fullautomation/python-jsonpreprocessor/issues/83}{issues/83} \textbf{!!!}
-
 The main method of the \pkg\ is: \pcode{jsonLoad}. Input is the path and the name of a JSON file.
 Output is a dictionary containing all values parsed from this JSON file.
 
 In case of any errors while computing the JSON file, the \pkg\ throws an exception. Therefore it is required
 to call the method \pcode{jsonLoad} inside a \pcode{try/except} block.
 
-\pcode{pprint} is used in this example to give the output a better readibility in console.
+\pcode{pprint} is used in this example to give the output a better readability in console.
 
 \vspace{2ex}
 

packagedoc/additional_docs/The JSONP format.tex

@@ -125,6 +125,28 @@ \section{Comments}
 
 All lines starting with \pcode{//}, are ignored by the \pkg. The output of this example is the same than in the previous example.
 
+\vspace{2ex}
+
+Also block comments and inline comments are possible, realized by a pair of \pcode{/* */}:
+
+\begin{pythoncode}
+{
+   /*
+   "param1" : 1,
+   "param2" : "A",
+   */
+
+   "testlist" : ["A1", /*"B2", "C3",*/ "D4"]
+}
+\end{pythoncode}
+
+\vspace{2ex}
+
+\textbf{Outcome:}
+
+\begin{pythonlog}
+{'testlist': ['A1', 'D4']}
+\end{pythonlog}
 
 % --------------------------------------------------------------------------------------------------------------
 
@@ -300,7 +322,7 @@ \section{Overwrite parameters}
    "common_param_2" : "common componentB value 2"
 \end{pythoncode}
 
-in \plog{componentB.jsonp} the initial definition
+in \plog{componentB.jsonp}, the initial definition
 
 \begin{pythoncode}
    "common_param_2" : "common value 2"
@@ -521,7 +543,7 @@ \section{Overwrite parameters}
 "int_val_b"            : "${int_val}",
 \end{pythoncode}
 
-the parameter \pcode{int_val_b} would be of type \pcode{string}.
+the parameter \pcode{int_val_b} is of type \pcode{string}.
 
 \vspace{2ex}
 
@@ -624,10 +646,76 @@ \section{Overwrite parameters}
 
 \vspace{2ex}
 
-\textbf{Use of a common dictionary}
+\textbf{Dictionary keys and indices as parameter}
+
+In all code examples above the indices of lists and the key names of dictionaries have been hard coded strings. It is also possible to use parameters:
+
+\begin{pythoncode}
+{
+   "index1"               : 0,
+   "index2"               : 1,
+   "key1"                 : "keyA",
+   "key2"                 : "keyB",
+   "testlist"             : ["A", "B"],
+   "testdict"             : {"keyA" : "A", "keyB" : "B"},
+   "tmp1"                 : ${testlist}[${index1}],
+   "tmp2"                 : ${testdict}[${key1}],
+   ${testlist}[${index1}] : ${testlist}[${index2}],
+   ${testdict}[${key1}]   : ${testdict}[${key2}],
+   ${testlist}[${index2}] : ${tmp1},
+   ${testdict}[${key2}]   : ${tmp2}
+}
+\end{pythoncode}
+
+\textbf{Outcome:}
+
+\vspace{2ex}
+
+\begin{pythonlog}
+{'index1': 0,
+ 'index2': 1,
+ 'key1': 'keyA',
+ 'key2': 'keyB',
+ 'testdict': {'keyA': 'B', 'keyB': 'A'},
+ 'testlist': ['B', 'A'],
+ 'tmp1': 'A',
+ 'tmp2': 'A'}
+\end{pythonlog}
+
+\newpage
+
+\textbf{Meaning of single quotes in square brackets}
+
+Single quotes are used to convert the content inside to a string.
+
+\begin{itemize}
+   \item In case of the parameter \pcode{param} is of type string, the expressions \pcode{[$\{param\}]} and \pcode{['$\{param\}']} have the same outcome:
+         The content inside the square brackets is a string. The single quotes have no meaning in this case (because the parameter is already of type string).
+   \item In case of the parameter \pcode{param} is of type integer, the quotes in \pcode{['$\{param\}']} convert the integer value to a string.
+         Without the quotes (\pcode{[$\{param\}]}), the content inside the square brackets is an integer.
+\end{itemize}
+
+In the context of \pkg\ JSON files, only strings and integers are expected to be inside square brackets (except the brackets are used to define a list).
+Other data types are not supported here.
+
+Whether a string or an integer is expected, depends on the data type of the parameter, the square bracket expression belongs to. Dictionaries require a string (a key name), lists require an integer (an index).
+Deviations will cause an error.
+
+Summarized the following combinations are valid (on both the left hand side of the colon and the right hand side of the colon):
+
+\begin{pythoncode}
+${listparam}[${intparam}]
+${listparam}[1]
+${dictparam}['${intparam}']
+${dictparam}[${stringparam}]
+${dictparam}['${stringparam}']
+${dictparam}['keyname']
+\end{pythoncode}
 
 \vspace{2ex}
 
+\textbf{Use of a common dictionary}
+
 The last example in this section covers the following use case:
 
 \begin{itemize}
@@ -639,6 +727,8 @@ \section{Overwrite parameters}
 
 To realize this, it is necessary to separate the initialization of the dictionary from all positions where keys are added to this dictionary.
 
+\newpage
+
 These are the JSON files:
 
 \vspace{2ex}
@@ -661,7 +751,7 @@ \section{Overwrite parameters}
 }
 \end{pythoncode}
 
-\newpage
+\vspace{2ex}
 
 \textbullet \plog{featureA.jsonp}
 
@@ -700,7 +790,7 @@ \section{Overwrite parameters}
 }
 \end{pythoncode}
 
-\vspace{2ex}
+\newpage
 
 \textbf{Explanation:}
 
@@ -884,9 +974,6 @@ \section{Substitution of dollar operator expressions}
 }
 \end{pythoncode}
 
-\textbf{!!! Caution:} substitution bug:
-\href{https://github.com/test-fullautomation/python-jsonpreprocessor/issues/92}{issues/92} \textbf{!!!}
-
 \vspace{2ex}
 
 \textbf{Outcome:}
@@ -911,29 +998,35 @@ \section{Substitution of dollar operator expressions}
 }
 \end{pythoncode}
 
-\vspace{2ex}
-
-\textbf{Outcome:}
+If this would be allowed, the last line would cause a parameter with this name:
 
 \begin{pythonlog}
-!!! Error message expected; still under development !!!
+"test_parameter_['AB', 12, True, None, {'kA': 'kAval', 'kB': 'kBval'}]"
 \end{pythonlog}
 
-\textbf{!!! Caution:}
-\href{https://github.com/test-fullautomation/python-jsonpreprocessor/issues/69#issuecomment-1589581903}{issues/69 issuecomment-1589581903} \textbf{!!!}
+And this is absolutely not a valid name!
 
 \vspace{2ex}
 
-\textbf{Overwriting vs. substitution}
+To prevent the users from generating invalid parameter names, the \pkg\ throws an error:
 
-\vspace{2ex}
+\begin{pythonlog}
+"Error: 'Found expression '...' with at least one parameter of composite data type ...
+Because of this expression is the name of a parameter, only simple data types are allowed to be substituted inside.'!"
+\end{pythonlog}
+
+\newpage
+
+\section{Overwriting vs. substitution}
 
-With the last two examples in this section we take a deeper look at the syntax difference between overwriting and substitution.
+In this section we take a deeper look at the syntax difference between overwriting and substitution explained above.
 
 \vspace{2ex}
 
 \textbf{1. Overwriting:}
 
+\vspace{2ex}
+
 With \pcode{$\{param2\} : $\{param1\}} the initial value \pcode{"XYZ"} of parameter \pcode{param2} is overwritten with the value \pcode{"ABC"}
 of parameter \pcode{param1}.
 
@@ -959,6 +1052,8 @@ \section{Substitution of dollar operator expressions}
 
 \textbf{2. Substitution:}
 
+\vspace{2ex}
+
 With \pcode{"$\{param2\}" : $\{param1\}} a new parameter with name \pcode{XYZ} (the value of \pcode{param2}) and value \pcode{"ABC"}
 is created.
 
@@ -1060,11 +1155,41 @@ \section{Implicite creation of dictionaries}
 }
 \end{pythoncode}
 
-you will \textit{not} get an error message! The entire data structure will be created implicitely. The impact is that this method
+you will \textit{not} get an error message! The entire data structure will be created implicitly. The impact is that this method
 is very susceptible to typing mistakes.
 
 The implicite creation of data structures does not work with lists! In case you use a list index out of range, you will get
 a corresponding error message.
 
+\newpage
+
+\textbf{Key names}
+
+The implicit creation of data structures is only possible with \textit{hard coded} key names. Parameters are not supported.
+
+\vspace{2ex}
+
+\textbf{Example:}
+
+\begin{pythoncode}
+{
+   "paramA" : "ABC",
+   "subKey" : "ABC",
+   ${testdict.subKey.subKey.paramA} : "DEF"
+}
+\end{pythoncode}
+
+All sub key levels within the expression \pcode{$\{testdict.subKey.subKey.paramA\}} are interpreted as hard coded strings, even in case of parameters with the same name do exist.
+
+For example: The name of the implicitly created key at bottom level is \pcode{"paramA"}, and not the value \pcode{"ABC"} of the parameter with the same name (\pcode{"paramA"}).
+
+\vspace{2ex}
+
+\textbf{Therefore the outcome is:}
+
+\begin{pythonlog}
+{'paramA': 'ABC', 'subKey': 'ABC', 'testdict': {'subKey': {'subKey': {'paramA': 'DEF'}}}}
+\end{pythonlog}
+
 % --------------------------------------------------------------------------------------------------------------
 

test/JPP_TestUsecases.csv

@@ -69,6 +69,7 @@ JPP_0507|COMPOSITE_EXPRESSIONS|GOODCASE|JSON file containing several string conc
 JPP_0508|COMPOSITE_EXPRESSIONS|GOODCASE|JSON file containing several string concatenations in separate lines (2)
 JPP_0509|COMPOSITE_EXPRESSIONS|GOODCASE|JSON file containing several parameter assignments in separate lines (different syntax)
 JPP_0510|COMPOSITE_EXPRESSIONS|GOODCASE|JSON file containing several parameter assignments in separate lines (extended string concatenation)
+JPP_0511|COMPOSITE_EXPRESSIONS|GOODCASE|JSON file containing a list; list index is defined by a parameter
 JPP_0550|COMPOSITE_EXPRESSIONS|BADCASE|JSON file with composite data structure (nested lists and dictionaries / some key names with dots inside)
 JPP_0600|CODE_COMMENTS|GOODCASE|JSON file with several combinations of code comments
 JPP_0950|COMMON_SYNTAX_VIOLATIONS|BADCASE|JSON file with syntax error (1)
@@ -78,6 +79,15 @@ JPP_0953|COMMON_SYNTAX_VIOLATIONS|BADCASE|JSON file with syntax error (4): file
 JPP_0954|COMMON_SYNTAX_VIOLATIONS|BADCASE|JSON file with syntax error (5): file is empty (multiple pairs of brackets only)
 JPP_1000|IMPLICIT_CREATION|GOODCASE|JSON file with dictionary keys to be created implicitly
 JPP_1001|IMPLICIT_CREATION|GOODCASE|JSON file with dictionary keys to be created implicitly (same key names at all levels)
+JPP_1050|IMPLICIT_CREATION|BADCASE|JSON file with implicit creation of data structures based on parameters (1)
+JPP_1051|IMPLICIT_CREATION|BADCASE|JSON file with implicit creation of data structures based on parameters (2)
+JPP_1052|IMPLICIT_CREATION|BADCASE|JSON file with implicit creation of data structures based on parameters (3)
+JPP_1053|IMPLICIT_CREATION|BADCASE|JSON file with implicit creation of data structures based on parameters (4)
+JPP_1054|IMPLICIT_CREATION|BADCASE|JSON file with implicit creation of data structures based on parameters (5)
+JPP_1055|IMPLICIT_CREATION|BADCASE|JSON file with implicit creation of data structures based on parameters (5)
+JPP_1056|IMPLICIT_CREATION|BADCASE|JSON file with implicit creation of data structures based on parameters (6)
+JPP_1057|IMPLICIT_CREATION|BADCASE|JSON file with implicit creation of data structures based on parameters (7)
+JPP_1058|IMPLICIT_CREATION|BADCASE|JSON file with implicit creation of data structures based on parameters (8)
 JPP_1150|CYCLIC_IMPORTS|BADCASE|JSON file with cyclic imports (JSON file imports itself)
 JPP_1151|CYCLIC_IMPORTS|BADCASE|JSON file with cyclic imports (JSON file imports another file, that is already imported)
 JPP_1200|PATH_FORMATS|GOODCASE|Relative path to JSON file