summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2024-10-29 20:07:04 +0000
committerKarl Berry <karl@freefriends.org>2024-10-29 20:07:04 +0000
commit3131a910033040346e0646c559ff7e551e907814 (patch)
tree1b09c5211b617416d29be8ebeaa1b1103aba4fac /Master/texmf-dist/doc
parent4b193ed76d1c3f9270afdb9afaf805f8e85aee30 (diff)
jsonparse (29oct24)
git-svn-id: svn://tug.org/texlive/trunk@72698 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/latex/jsonparse/README.md2
-rw-r--r--Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.pdfbin434426 -> 437147 bytes
-rw-r--r--Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.tex23
3 files changed, 17 insertions, 8 deletions
diff --git a/Master/texmf-dist/doc/latex/jsonparse/README.md b/Master/texmf-dist/doc/latex/jsonparse/README.md
index e7dfc3a3e29..193df705116 100644
--- a/Master/texmf-dist/doc/latex/jsonparse/README.md
+++ b/Master/texmf-dist/doc/latex/jsonparse/README.md
@@ -1,4 +1,4 @@
-![Version 0.9.3](https://img.shields.io/badge/version-0.9.3-blue)
+![Version 0.9.5](https://img.shields.io/badge/version-0.9.5-blue)
![Jason, the JSON parsing horse](https://github.com/jasperhabicht/jsonparse/assets/6378801/ddfddc70-bf5f-4121-ba45-4b9128875d85)
diff --git a/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.pdf b/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.pdf
index 58b6bc55aba..02477b42177 100644
--- a/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.pdf
+++ b/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.tex b/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.tex
index 8f99efa2706..279ea209a64 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 `maintained'.
%
\documentclass[a4paper]{article}
-\def\jsonparsefileversion{0.9.3}
-\def\jsonparsefiledate{24 October 2024}
+\def\jsonparsefileversion{0.9.5}
+\def\jsonparsefiledate{27 October 2024}
\usepackage[T1]{fontenc}
\usepackage{Alegreya}
@@ -203,6 +203,7 @@
\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.}
\begin{document}
\vspace*{-1cm}
@@ -233,9 +234,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.
@@ -260,7 +263,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}
@@ -310,7 +313,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.
@@ -322,7 +324,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>}