Skip to content

Documentation adapted to latest changes in the JSONP format #396

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 28, 2024
Merged

Documentation adapted to latest changes in the JSONP format #396

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified JsonPreprocessor/JsonPreprocessor.pdf
View file
Open in desktop
Binary file not shown.
148 changes: 142 additions & 6 deletions packagedoc/additional_docs/The JSONP format.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ \section{Boolean and null values}

JSON supports the boolean values \pcode{true} and \pcode{false}, and also the null value \pcode{null}.

In Python the corresponding values are different: \pcode{True}, \pcode{False} and \pcode{None}.
In Python, the corresponding values differ: \pcode{True}, \pcode{False} and \pcode{None}.

Because the \pkg\ is a Python application and therefore the returned content is required to be formatted Python compatible,
the \pkg\ does a conversion automatically.
Expand Down Expand Up @@ -151,6 +151,19 @@ \section{Comments}
{'testlist': ['A1', 'D4']}
\end{pythonlog}

\vspace{2ex}

\section{Naming convention}

All key names in JSONP files must adhere to the following rules:

\begin{itemize}
\item Key names can only consist of letters, digits and the following special characters: \pcode{_ + - * / \\}
(\textit{backslashes are allowed but have to be masked}).
\item Key names have to start with a letter, a digit or an underscore.
\item Key names must not be empty strings. But leading and trailing blanks will be removed (and therefore do not cause errors).
\end{itemize}

% --------------------------------------------------------------------------------------------------------------

\newpage
Expand Down Expand Up @@ -260,10 +273,102 @@ \section{Import of JSON files}

It can be seen that the returned dictionary contains both the parameters from the loaded JSON file and the parameters imported by the loaded JSON file.

\vspace{2ex}

\textbf{Multiple imports of the same file}

A JSONP file can be imported more than once anywhere in the set of JSONP configuration files. This mechanism can be used to define a common part for different subkeys.

\vspace{2ex}

\textbf{Example:}

\vspace{2ex}

\textbullet \plog{common.jsonp}

\begin{pythoncode}
{
// common parameters
"common_param_1" : "common value 1",
"common_param_2" : "common value 2"
}
\end{pythoncode}

\textbullet \plog{componentA.jsonp}

\begin{pythoncode}[linebackgroundcolor=\hlcode{6,12}]
{
// component A parameters
"componentA_param_1" : {
"componentA_param_1_a" : "componentA_param_1_a value",
// common parameters within componentA_param_1
"[import]" : "./common_config/common.jsonp",
"componentA_param_1_b" : "componentA_param_1_b value"
},
"componentA_param_2" : {
"componentA_param_2_a" : "componentA_param_2_a value",
// common parameters within componentA_param_2
"[import]" : "./common_config/common.jsonp",
"componentA_param_2_b" : "componentA_param_2_b value"
}
}
\end{pythoncode}

\vspace{2ex}

\textbf{Outcome:}

% \vspace{2ex}

The content of \plog{common.jsonp} is part of \pcode{componentA_param_1} and also part of \pcode{componentA_param_2}.

\begin{pythonlog}
{'componentA_param_1': {'common_param_1': 'common value 1',
'common_param_2': 'common value 2',
'componentA_param_1_a': 'componentA_param_1_a value',
'componentA_param_1_b': 'componentA_param_1_b value'},
'componentA_param_2': {'common_param_1': 'common value 1',
'common_param_2': 'common value 2',
'componentA_param_2_a': 'componentA_param_2_a value',
'componentA_param_2_b': 'componentA_param_2_b value'}}
\end{pythonlog}

\newpage

\textbf{Dynamic import paths}

The values of \pcode{"[import]"} keys must be of type \pcode{str}. Therefore it's possible to use
dollar operator expressions inside import paths.

An alternative version of the file \plog{componentA.jsonp} from the example above, can look like this:

\begin{pythoncode}[linebackgroundcolor=\hlcode{2,7,13}]
{
"common_config_dir" : "./common_config",
// component A parameters
"componentA_param_1" : {
"componentA_param_1_a" : "componentA_param_1_a value",
// common parameters within componentA_param_1
"[import]" : "${common_config_dir}/common.jsonp",
"componentA_param_1_b" : "componentA_param_1_b value"
},
"componentA_param_2" : {
"componentA_param_2_a" : "componentA_param_2_a value",
// common parameters within componentA_param_2
"[import]" : "${common_config_dir}/common.jsonp",
"componentA_param_2_b" : "componentA_param_2_b value"
}
}
\end{pythoncode}

The outcome is the same like in the previous example.

% --------------------------------------------------------------------------------------------------------------

\section{Overwrite parameters}\label{overwrite-parameters}
\newpage

\section{Overwriting parameters}\label{overwriting-parameters}

We take over the scenario from the previous section: We still have a JSON file \plog{componentA.jsonp} containig the parameters for
component \textit{A}, a JSON file \plog{componentB.jsonp} for component \textit{B} and a JSON file \plog{common.jsonp} for both components.
Expand Down Expand Up @@ -530,8 +635,8 @@ \section{Overwrite parameters}\label{overwrite-parameters}

\begin{itemize}
\item Existing parameters are accessed by a dollar operator and a pair of curly brackets (\pcode{$\{...\}}) with the parameter name inside.
\item If the entire expression of the right hand side of the colon is such a dollar operator expression, it is not required any more
to encapsulate this expression in quotes.
\item If the entire expression of the right hand side of the colon is such a dollar operator expression, it is not required
to encapsulate this expression in quotes (in opposite to what pure JSON would require).
\item Without quotes, the dollar operator keeps the data type of the referenced parameter. If you use quotes, the value of the used parameter
will be converted to type \pcode{str}. This implicit string conversion is limited to parameters of simple data types like integers and floats.
Composite data types like lists and dictionaries cannot be used for that.
Expand All @@ -552,7 +657,7 @@ \section{Overwrite parameters}\label{overwrite-parameters}
"int_val_b" : ${int_val},
\end{pythoncode}

It is not required any more to encapsulate dollar operator expressions at the right hand side of the colon in quotes.
It is not required to encapsulate dollar operator expressions at the right hand side of the colon in quotes.
But nevertheless, it is possible to use quotes. In case of:

\begin{pythoncode}
Expand Down Expand Up @@ -992,13 +1097,44 @@ \section{\texttt{dotdict} notation}\label{dotdict-notation}
'dict_2_A_key_2 value 2']}}]}
\end{pythonlog}


% commented out because of
% https://github.com/test-fullautomation/python-jsonpreprocessor/issues/349

% \vspace{2ex}

% \textbf{Parameter scope}

% The following JSONP example defines a parameter with name \pcode{"param"} two times.
% In case of the innermost \pcode{"param"} shall be overwritten, the full scope of this
% parameter must be used.

% \begin{pythoncode}
% {
% "param" : 1,
% "params" : {"001" : {
% "param" : 2
% }
% },
% ${params.001.param} : 3
% }
% \end{pythoncode}

% \vspace{2ex}

% \textbf{Outcome:}

% \begin{pythonlog}
% DotDict({'params': DotDict({'001': DotDict({'param': 3})}), 'param': 1})
% \end{pythonlog}

% --------------------------------------------------------------------------------------------------------------

\newpage

\section{Dynamic key names}

In section \hyperref[overwrite-parameters]{Overwrite parameters} we mentioned the possibility to define the value of string parameters dynamically, e.g. in this way:
In section \hyperref[overwriting-parameters]{Overwriting parameters} we mentioned the possibility to define the value of string parameters dynamically, e.g. in this way:

\begin{pythoncode}
"str_val" : "ABC",
Expand Down