Documentation extended (special characters inside key names)

packagedoc/additional_docs/The JSONP format.tex

@@ -1471,6 +1471,63 @@ \section{Python inline code}
     % "element" : <<eval import itertools; combined_list=list(itertools.combinations([1, 2, 3], 2)); element=combined_list[0]>>
     % C:\workplace\ROBFW\components\python-jsonpreprocessor\test\testfiles\jpp-test_config_2108.jsonp
 
+% --------------------------------------------------------------------------------------------------------------
+
+\newpage
+
+\section{Special characters within key names}
+
+Basically, the \textbf{JsonPreprocessor} considers the JSON naming convention for key names. Within JSONP files allowed is what JSON allows,
+but with the following limitation: The JSONP format extends the JSON format with some features using square, curly and angle brackets as syntax elements:
+\pcode{[}, \pcode{]}, \pcode{\{}, \pcode{\}}, \pcode{<}, \pcode{>}. \textbf{It is urgently recommended not to use these brackets inside key names!}
+
+This JSONP code:
+
+\begin{pythoncode}
+{
+    "[" : 1,
+    "B" : ${[}
+}
+\end{pythoncode}
+
+causes:
+
+\begin{pythonlog}
+Error: 'Invalid expression found: '${[}' - The brackets mismatch!!!'!
+\end{pythonlog}
+
+All other special characters can be used immediately:
+
+\begin{pythoncode}
+{
+    "$" : 1,
+    "B" : ${$}
+}
+\end{pythoncode}
+
+Result:
+
+\begin{pythonlog}
+DotDict({'$': 1, 'B': 1})
+\end{pythonlog}
+
+Strings are handled as raw strings. Therefore, masking has no effect:
+
+\begin{pythoncode}
+{
+    "\\$" : 1,
+    "B" : ${\\$}
+}
+\end{pythoncode}
+
+The backslashes are part of the key name:
+
+\begin{pythonlog}
+DotDict({'\\$': 1, 'B': 1})
+\end{pythonlog}
+
+\textit{The masking requires two backslashes! A single backslash will cause a JSON syntax error!}
+
 
 % --------------------------------------------------------------------------------------------------------------