diff options
Diffstat (limited to 'macros/latex/contrib/jsonparse/jsonparse-doc.tex')
| -rw-r--r-- | macros/latex/contrib/jsonparse/jsonparse-doc.tex | 92 |
1 files changed, 79 insertions, 13 deletions
diff --git a/macros/latex/contrib/jsonparse/jsonparse-doc.tex b/macros/latex/contrib/jsonparse/jsonparse-doc.tex index 801970d419..a700978416 100644 --- a/macros/latex/contrib/jsonparse/jsonparse-doc.tex +++ b/macros/latex/contrib/jsonparse/jsonparse-doc.tex @@ -11,8 +11,8 @@ % This work has the LPPL maintenance status `maintained'. % \documentclass[a4paper]{article} -\def\jsonparsefileversion{0.9.0} -\def\jsonparsefiledate{27 August 2024} +\def\jsonparsefileversion{0.9.7} +\def\jsonparsefiledate{5 November 2024} \usepackage[T1]{fontenc} \usepackage{Alegreya} @@ -201,6 +201,11 @@ \changes{v0.8.6}{2024/05/09}{Bug fix in nesting function.} \changes{v0.8.7}{2024/08/08}{Corrections in documentation, error messages.} \changes{v0.9.0}{2024/08/27}{Adaption to updated verbatim tokenization.} +\changes{v0.9.1}{2024/09/21}{Added functions to test for valid JSON numbers.} +\changes{v0.9.3}{2024/10/24}{Fixed a bug that prevented tabs in source from being parsed properly.} +\changes{v0.9.5}{2024/10/27}{Streamlining of code, clarification of explanations in documentation.} +\changes{v0.9.6}{2024/10/31}{Allowing for multiple return values when mapping over arrays.} +\changes{v0.9.7}{2024/11/05}{Streamlining of code, ensuring backward compatibility.} \begin{document} \vspace*{-1cm} @@ -231,9 +236,11 @@ The package can be loaded with the option \macro{debug}. It will then output to This key can be set either as package option or using \macro{\JSONParseSet}. It can also be set locally as option to the commands \macro{\JSONParse} and \macro{\JSONParseFromFile}. -\section{Escaping and special treatment of the input}\label{sec:escaping} +\section{General remarks of the parsing procedure} + +In general, the package will read and store the JSON source and data as string, which means that all characters have category code 12 (``other''), except for spaces and (horizontal) tabs which have category code 10 (``space''). The \macro{\endlinechar} value is set to $-1$ which means that linefeeds and carriage returns are ignored by TeX. These settings are in line with the JSON specification of handling whitespace. Furthermore, if PDFLaTeX is used, the upper-half of the 8-bit range is set to ``active''. Additionally, JSON defines a small set of escape sequences and in order to be able to process these, the category code of the backslash is set to 0 (``escape''). -In general, the package reads the JSON source as string, which means that all characters have category code 12 (other), except for spaces which have category code 10 (space). The \macro{\endlinechar} value is set to $-1$. Furthermore, if PDFLaTeX is used, the upper-half of the 8-bit range is set to ``active''. JSON, however, defines a small set of escape sequences and in order to be able to process these, the category code of the backslash is set to 0 (escape). +\section{Escaping and special treatment of the input}\label{sec:escaping} JSON strings cannot contain the two characters \macro{"} and \macro{\}. These two characters need to be escaped with a preceding backslash (\macro{\}). This package therefore redefines locally the TeX control symbols \macro{\"}, \macro{\/}, \macro{\\}, \macro{\b}, \macro{\f}, \macro{\n}, \macro{\r}, \macro{\t} and \macro{\u}. These control symbols are prevented from expanding during parsing. For example, \macro{\"} is first defined as \macro{\exp_not:N \"} and only when typeset, \macro{\"} is expanded to \macro{"}, which ensures that strings are parsed properly. @@ -258,7 +265,7 @@ Using the control sequence \macro{\x}, it is possible to nest JSON strings into \JSONParseValue{\myJSONdataB}{d.b} \end{codeexamplecolumns} -Note that the control sequence \macro{\x} is replaced by the value exactly. Therefore, if the value happens to be a string, the control sequence \macro{\x} should be placed between quotation marks (\macro{"}) in order for the resulting string to be valid JSON. +Note that the control sequence \macro{\x} is replaced by the value exactly. Therefore, if the value happens to be a string, the control sequence \macro{\x} should be placed between quotation marks (\macro{"}) in order for the resulting string to be valid JSON. The control sequence \macro{\x} is only available inside the \macro{\JSONParse} command, but not inside the \macro{\JSONParseFromFile} command. \begin{macrodef} |escape|={all} @@ -308,7 +315,6 @@ The command \macro{\JSONParseKeys} is used to store all top-level keys of a pars \begin{macrodef} |\JSONParseValue|[<options>]{<token variable>}{<key>} -|\JSONParseExpandableValue|{<token variable>}{<key>} \end{macrodef} The command \macro{\JSONParseValue} is used to select values from the token variable (property list) that has been created using the commands \macro{\JSONParse} or \macro{\JSONParseFromFile}. The first argument takes the token variable that holds the parsed JSON data. The second argument takes the key to select the relevant entry from the parsed JSON data using JavaScript syntax. @@ -320,7 +326,14 @@ The first optional argument can be used to pass options to the command, such as When a key is associated with an object or array, the whole object or array is output as JSON string. The special key \macro{.} (or the string defined using the key \macro{child sep}) returns the whole JSON object as string. -Whole objects or arrays can also be output as JSON string for further use in other macros using the expandable command \macro{\JSONParseExpandableValue}. +The command \macro{\JSONParseValue} is not expandable and can therefore not be used as argument of certain other arguments where expansion is needed. In such cases, the expandable command \macro{\JSONParseExpandableValue} should be used. + +\begin{macrodef} +|\JSONParseExpandableValue|{<token variable>}{<key>} +\end{macrodef} +Whole objects or arrays can be output as JSON string for further use in other macros using the expandable command \macro{\JSONParseExpandableValue}. The value that is returned by this command is typically a string variable where all characters have category code 12 (``other''), except for spaces and (horizontal) tabs that have category code 10 (``space''). This should be kept in mind if string comparisons should be made. A comparison against a token list with the default category codes used by TeX won't work, since letters will have category code 11 (``letter''), but it is possible to use \macro{\detokenize} to set the category codes of the token list in such a way that the comparison works. + +For example, if the JSON string \macro{{ "key" : "value" }} has been parsed into the token variable \macro{\myJSONdata}, the command \macro{\JSONParseExpandableValue{\myJSONdata}{key}} will expand to the exact same token list as \macro{\detokenize{value}} with all characters having category code 12 (``other''). \begin{macrodef} |\JSONParseArrayValues|[<options>]{<token variable>}{<key>}[<subkey>]{<string>} @@ -343,21 +356,20 @@ For example, let us assume the following JSON data structure is parsed into the ] } \end{codeexample} +\JSONParse{\myJSONdata}{ { "array" : [ { "key_a" : "one" , "key_b" : "two" } , { "key_a" : "three" , "key_b" : "four" } ] } } -Then, when using \macro{\JSONParseArrayValues{\myJSONdata}{array}[key_a]{, }}, `one, three' is typeset to the document. +Then, when using \macro{\JSONParseArrayValues{\myJSONdata}{array}[key_a]{, }}, `\JSONParseArrayValues{\myJSONdata}{array}[key_a]{, }' is typeset to the document. The first optional argument can be used to pass options to the command, such as \macro{escape} or \macro{rescan}, that are then applied locally. \begin{macrodef} |\JSONParseArrayValuesMap|[<options>]{<token variable>}{<key>}[<subkey>] - {<command name>} + {<command name>}[<before code>][<after code>] \end{macrodef} -The command \macro{\JSONParseArrayValuesMap} takes the same first three arguments as the command \macro{\JSONParseArrayValues} and works in a similar way. However, instead of a string that is added between the array items, it takes a command name as fourth argument. This command can be defined beforehand and will be called for every array item. Inside its definition, the commands \macro{\JSONParseArrayIndex}, \macro{\JSONParseArrayKey} and \macro{\JSONParseArrayValue} can be used which are updated for each item and output the index, the key and the value of the current item respectively. +The command \macro{\JSONParseArrayValuesMap} takes the same first three arguments as the command \macro{\JSONParseArrayValues} and works in a similar way. However, instead of a string that is added between the array items, it takes a command name as fourth argument. This command can be defined beforehand and will be called for every array item. Inside its definition, the commands \macro{\JSONParseArrayIndex}, \macro{\JSONParseArrayKey} and \macro{\JSONParseArrayValue} can be used which are updated for each item and output the index, the key and the value of the current item respectively. Note that these commands are defined globally to make accessing them as easy as possible. For example, let us assume the same JSON data structure as defined above parsed into the token variable \macro{\myJSONdata}. Then, the following can be done: -\JSONParse{\myJSONdata}{ { "array" : [ { "key_a" : "one" , "key_b" : "two" } , { "key_a" : "three" , "key_b" : "four" } ] } } - \begin{codeexamplecolumns} \newcommand{\myJSONitem}{ \item \emph{\JSONParseArrayValue} @@ -369,7 +381,41 @@ For example, let us assume the same JSON data structure as defined above parsed \end{itemize} \end{codeexamplecolumns} -The first optional argument can be used to pass options to the command, such as \macro{escape} or \macro{rescan}, that are then applied locally. +It is possible to make use of multiple subkeys by passing them as a comma separated list as third argument to the command. Inside the command that is called for every array item, the different keys and values can be access via commands numbered with uppercase Roman numerals such as \macro{\JSONParseArrayKeyI}, \macro{\JSONParseArrayKeyII}, \macro{\JSONParseArrayKeyIII} etc.\ and \macro{\JSONParseArrayValueI}, \macro{\JSONParseArrayValueII}, \macro{\JSONParseArrayValueIII} etc. + +We can extend the above example in the following way: + +\begin{codeexamplecolumns} +\newcommand{\myJSONitem}{ + \item \emph{\JSONParseArrayValueI :} + \JSONParseArrayValueII +} + +\begin{itemize} + \JSONParseArrayValuesMap{\myJSONdata} + {array}[key_a,key_b]{myJSONitem} +\end{itemize} +\end{codeexamplecolumns} + +The command additionally takes two optional arguments at sixth and seventh position. These arguments can be used to place code before and after the output that is generated by the command called for every array item, for example for typesetting tabular contents. + +Typesetting the above example in a tabular way can be achieved as follows: + +\begin{codeexamplecolumns} +\newcommand{\myJSONitem}{ + \JSONParseArrayValueI & + \JSONParseArrayValueII \\ +} + +\JSONParseArrayValuesMap{\myJSONdata} + {array}[key_a,key_b]{myJSONitem} + [\begin{tabular}{ c c } + \textbf{key a} & + \textbf{key b} \\ \hline] + [\hline \end{tabular}] +\end{codeexamplecolumns} + +Finally, the first optional argument of the command can be used to pass options to the command, such as \macro{escape} or \macro{rescan}, that are then applied locally. \begin{macrodef} |\JSONParseArrayCount|{<token variable>}{<key>} @@ -461,7 +507,14 @@ replace/|horizontal tab|={<string>} These keys can be used to set the replacement text for the JSON escape sequences \macro{\b} (backspace), \macro{\f} (formfeed), \macro{\n} (linefeed), \macro{\r} (carriage return) and \macro{\t} (horizontal tab). The default replacement string is a space. Only strings can be used as replacement. These replacements take place only during typesetting. These keys can be set using \macro{\JSONParseSet}. They can also be set locally as option to the commands \macro{\JSONParseValue}, \macro{\JSONParseArrayValues} and \macro{\JSONParseArrayValuesMap}. +\begin{macrodef} +|check num| +|check num|={<boolean>} +\end{macrodef} +If set to \macro{false}, the key \macro{check num} omits an internal check of numerical expressions against the JSON specification for numbers. Turning off this feature can increase the parsing speed. +This key can be set using \macro{\JSONParseSet}. It can also be set locally as option to the commands \macro{\JSONParse} and \macro{\JSONParseFromFile}. + \subsection{L3 commands} \begin{macrodef} @@ -479,6 +532,19 @@ The command \macro{\jsonparse_parse_to_prop:Nn} creates the token variable given \end{macrodef} The command \macro{\jsonparse_parse_to_prop:Nn} processes the token variable given as the first arguments as property list and filters it according to the key given as second argument. Filtering means that for every entry in the property list, the key of this entry is compared against the key given to the command. If the key in the property list starts with the given key, the matching part is removed from the key in the property list. If the keys do not match, the entry is completely removed from the property list. +\begin{macrodef} +|\jsonparse_array_count:NN| <token variable> <integer variable> +\end{macrodef} +The command \macro{\jsonparse_array_count:NN} processes the token variable given as the first arguments as property list and, assuming that it is an array, counts its items and stores the result in the integer variable. If the token variable does not expand to a key that represents an array item, that is if the key does not start with the character defined by \macro{separator/array left}, the command will return an error. The command \macro{\JSONParseArrayCount} serves as a wrapper of this command. + +\begin{macrodef} +|\jsonparse_if_num:nTF| {<string>} {<true code>} {<false code>} +|\jsonparse_if_num:nT| {<string>} {<true code>} +|\jsonparse_if_num:nF| {<string>} {<false code>} +|\jsonparse_if_num_p:n| {<string>} +\end{macrodef} +The command \macro{\jsonparse_if_num:nTF} checks whether a string is a valid JSON number according the relevant specification. It executes the true code if the string is a valid JSON number and the false code if not. The variants \macro{\jsonparse_if_num:nT} and \macro{\jsonparse_if_num:nF} work accordingly. The command \macro{\jsonparse_if_num_p:n} returns a boolean true or false. + % ===== \printchanges |