summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.tex')
-rw-r--r--Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.tex32
1 files changed, 29 insertions, 3 deletions
diff --git a/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.tex b/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.tex
index 3fe058a3ea0..2b0eff21c80 100644
--- a/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.tex
+++ b/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.tex
@@ -11,8 +11,8 @@
% This work has the LPPL maintenance status `author-maintained'.
%
\documentclass[a4paper]{article}
-\def\jsonparsefileversion{0.5.5}
-\def\jsonparsefiledate{9 April 2024}
+\def\jsonparsefileversion{0.5.6}
+\def\jsonparsefiledate{11 April 2024}
\usepackage[T1]{fontenc}
\usepackage{Alegreya}
@@ -189,6 +189,7 @@
\changes{v0.3.0}{2024/04/08}{First public beta release.}
\changes{v0.5.0}{2024/04/09}{Changed from string token variables to token lists to support Unicode.}
\changes{v0.5.5}{2024/04/09}{Bug fixes, introduction and enhancement of user functions.}
+\changes{v0.5.6}{2024/04/11}{Bug fixes, escaping of special chars added.}
\begin{document}
@@ -200,6 +201,8 @@
The \macro{jsonparse} package provides an easy way to read in JSON data from files or strings in LaTeX documents, parse the data and store it in a user-defined token variable. The package allows accessing the stored data via a JavaScript-flavored syntax.
+This package is still in a beta stage and not thoroughly tested. Bugs or improvements can be issued via GitHub at \url{https://github.com/jasperhabicht/jsonparse/issues}.
+
\section{Loading the package}
To install the package, copy the package file \macro{jsonparse.sty} into the working directory or into the \macro{texmf} directory. After the package has been installted, the \macro{jsonparse} package is loaded by calling \macro{\usepackage{jsonparse}} in the preamble of the document.
@@ -209,6 +212,20 @@ The package does not load any dependencies.
\begin{macrodef}debug\end{macrodef}
The package can be loaded with the option \macro{debug}. It will then output to the log file every instance of a string, a boolean (true or false) value, a null value, a number as well as the start and end of every object and the start and end of every array that is found while parsing the JSON string or JSON file.
+\section{Escaping and special treatment of the input}
+
+The package allows for empty lines in JSON strings. During parsing, every instance of the TeX macro \macro{\par} is replaced by a space.
+
+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 macros \macro{\"}, \macro{\/} and \macro{\\}. During parsing, \macro{\"} expands to \macro{\exp_not:N \"} (i.\,e. it is prevented to expand during parsing) and only when typeset, \macro{\"} is expanded to \macro{"}, which ensures that strings are parsed properly. Similarly, \macro{\/} expands to \macro{\exp_not:N \/} and finally to \macro{/} while \macro{\\} expands to \macro{\exp_not:N \\} and finally to \macro{\c_backslash_str} (i.\,e. a backslash with category code 12).
+
+Due to the above procedure, the TeX macros \macro{\"} and \macro{\\} must be escaped twice in the JSON source, so that they become \macro{\\\"} and \macro{\\\\} respectively.
+
+Other escape sequences defined by JSON, such as \macro{\b}, \macro{\f}, \macro{\n}, \macro{\r}, \macro{\t} or \macro{\u} (the latter followed by a hex value) are not escaped and it is up to the user to process these sequences before feeding them into the commands provided by this package.
+
+Characters that are special to TeX are not handled in a special way and will be treated by TeX the same way as if the user had input them in the document.
+
+Setting the internal boolean \macro{\l_jsonparse_escape_input_bool} to false disables the treatment of the input as described in this section.
+
\section{Main user commands}
\begin{macrodef}
@@ -225,6 +242,7 @@ The command \macro{\JSONParseFromFile} is used to parse a JSON file and store th
\begin{macrodef}
|\JSONParseGetValue|{<token variable>}{<key>}
+|\JSONParseGetValue*|{<token variable>}{<key>}
\end{macrodef}
The command \macro{\JSONParseGetValue} 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.
@@ -232,10 +250,13 @@ If the JSON string \macro{{ "key" : "value" }} is parsed into the token variable
Nested objects and arrays are assigned keys that adhere to JavaScript syntax. For example, if the JSON string \macro{{ "outer_key" : { "inner_key" : "value" } }} is parsed into the token variable \macro{\myJSONdata}, to select the value associated with the key \macro{inner_key}, the command \macro{\JSONParseGetValue{\myJSONdata}{outer_key.inner_key}} can be used. The command \macro{\JSONParseGetValue{\myJSONdata}{key[0]}} selects the first value of the array associated with the key \macro{key} in the parsed JSON string \macro{{ "key" : [ "one" , "two" ] }}.
-When a key is associated with an object or array, the whole object or array is output as JSON string. This string can again be parsed using \macro{\JSONParse}. The special key \macro{.} (or the string defined using \macro{\JSONParseSetChildSeparator}) return the whole JSON object.
+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 \macro{\JSONParseSetChildSeparator}) returns the whole JSON object as string. The output of whole objects or arrays is not meant to be printed, but it can again be parsed using \macro{\JSONParse}.
+
+The starred variant, \macro{\JSONParseGetValue*}, rescans the token list before it is typeset, making it possible to place TeX commands in the JSON file. The starred variants of this and similar commands should not be placed in a \macro{\JSONParse} command. In order to adhere to proper JSON syntax, backslashes need to be escaped in the JSON source with another backslash.
\begin{macrodef}
|\JSONParseGetArrayValues|{<token variable>}{<key>}[<subkey>]{<string>}
+|\JSONParseGetArrayValues*|{<token variable>}{<key>}[<subkey>]{<string>}
\end{macrodef}
The command \macro{\JSONParseGetArrayValues} is used to select all values from an array from a parsed JSON string or JSON file. 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. The third argument is optional an can be used to pass a subkey, i.\,e. a key that is used to select a value for every item. The last argument takes a string that is inserted between all values when they are typeset.
@@ -258,8 +279,11 @@ For example, let us assume the following JSON data structure is parsed into the
Then using \macro{\JSONParseGetArrayValues{\myJSONdata}{array}[key_a]{, }}, the text \macro{one, three} is typeset to the document.
+The starred variant, \macro{\JSONParseGetArrayValues*}, rescans the token lists before they are typeset.
+
\begin{macrodef}
|\JSONParseUseArrayValues|{<token variable>}{<key>}[<subkey>]{<command name>}
+|\JSONParseUseArrayValues*|{<token variable>}{<key>}[<subkey>]{<command name>}
\end{macrodef}
The command \macro{\JSONParseUseArrayValues} takes the same first three arguments as the command \macro{\JSONParseGetArrayValues} 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 defintion, 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.
@@ -278,6 +302,8 @@ For example, let us assume the same JSON data structure as defined above parsed
\end{itemize}
\end{codeexamplecolumns}
+The starred variant, \macro{\JSONParseUseArrayValues*}, rescans the token lists before they are typeset.
+
\begin{macrodef}
|\JSONParseGetArrayCount|{<token variable>}{<key>}
\end{macrodef}