diff options
Diffstat (limited to 'Master/texmf-dist/doc')
| -rw-r--r-- | Master/texmf-dist/doc/latex/jsonparse/README.md | 10 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.pdf | bin | 386673 -> 394387 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.tex | 167 |
3 files changed, 96 insertions, 81 deletions
diff --git a/Master/texmf-dist/doc/latex/jsonparse/README.md b/Master/texmf-dist/doc/latex/jsonparse/README.md index b2253c2a85c..ba872453747 100644 --- a/Master/texmf-dist/doc/latex/jsonparse/README.md +++ b/Master/texmf-dist/doc/latex/jsonparse/README.md @@ -1,10 +1,10 @@ - + # The `jsonparse` package -The `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. +The `jsonparse` package provides a handy 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. -Using the commands `\JSONParseFromFile` or `\JSONParse`, JSON data can be stored in a token variable. Using the command `\JSONParseGetValue`, certain entried can be extracted from the stored data. +Using the commands `\JSONParseFromFile` or `\JSONParse`, JSON data can be stored in a token variable. Using the command `\JSONParseValue`, certain entried can be extracted from the stored data. --- @@ -32,7 +32,7 @@ Let's assume a file with the name `example.json` is stored in the working direct } ], "children": [ - "Tom, + "Tom", "Doug", "Harry" ], @@ -40,6 +40,6 @@ Let's assume a file with the name `example.json` is stored in the working direct } ``` -We can store it in the token variable `\myJSONdata` using the command `\JSONParseFromFile{\myJSONdata}{example.json}`. Calling the command `\JSONParseGetValue{\myJSONdata}{contactPoint[0].telephone}` would then result in the output `+1 (555) 555-1234` (indices are zero-based per default). +We can store it in the token variable `\myJSONdata` using the command `\JSONParseFromFile{\myJSONdata}{example.json}`. Calling the command `\JSONParseValue{\myJSONdata}{contactPoint[0].telephone}` would then result in the output `+1 (555) 555-1234` (indices are zero-based per default). This package including all files is subject to the LPPL 1.3c license. diff --git a/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.pdf b/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.pdf Binary files differindex 6e81ca7c446..eae5ebc7ac1 100644 --- a/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.pdf +++ b/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.pdf diff --git a/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.tex b/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.tex index 2b0eff21c80..90de47fa5d1 100644 --- a/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.tex +++ b/Master/texmf-dist/doc/latex/jsonparse/jsonparse-doc.tex @@ -5,14 +5,14 @@ % conditions of the LaTeX Project Public License version 1.3c, % available at http://www.latex-project.org/lppl/. % -% This file is part of the `jsonparse' package (The Work in LPPL) +% This file is part of the `jsonparse' package (The Work in LPPL) % and all files in that bundle must be distributed together. % -% This work has the LPPL maintenance status `author-maintained'. +% This work has the LPPL maintenance status `maintained'. % \documentclass[a4paper]{article} -\def\jsonparsefileversion{0.5.6} -\def\jsonparsefiledate{11 April 2024} +\def\jsonparsefileversion{0.7.1} +\def\jsonparsefiledate{20 April 2024} \usepackage[T1]{fontenc} \usepackage{Alegreya} @@ -190,6 +190,10 @@ \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.} +\changes{v0.5.7}{2024/04/14}{Bug fixes, key-value option setting added.} +\changes{v0.6.0}{2024/04/15}{Bug fixes, renaming of several commands.} +\changes{v0.7.0}{2024/04/18}{Renaming and rearranging of keys, escaping of special JSON escape sequences added.} +\changes{v0.7.1}{2024/04/20}{Access to first-level keys of object added.} \begin{document} @@ -199,32 +203,51 @@ \section{Introduction} -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. +The \macro{jsonparse} package provides a handy 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. +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 installed, the \macro{jsonparse} package is loaded by calling \macro{\usepackage{jsonparse}} in the preamble of the document. The package does not load any dependencies. -\begin{macrodef}debug\end{macrodef} +\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} +\section{Escaping and special treatment of the input}\label{sec:escaping} + +\begin{macrodef} +|escape|={<choice>} +\end{macrodef} + +In general, characters in the JSON source 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. However, certain escaping procedures are available to conform with the way JSON treats certain escape sequences. + +The key \macro{escape} takes one of the values \macro{false}, \macro{basic} or \macro{full}. If no value is given, \macro{basic} is assumed and \macro{basic} is also the default setting if the key is not set at all. See more on setting keys below in section \ref{sec:settings}. The three values select different escape modes that are designed to have as little influence as possible to how TeX normally acts. While it would surely be possible to parse and rescan the input by changing category codes and rescanning the output per default, such practice might result un unintended output in special cases. Therefore, the current approach was chosen where changes to category codes are only introduced with the most most extensive escaping mode and rescanning of token sequences can be controlled by the user. -The package allows for empty lines in JSON strings. During parsing, every instance of the TeX macro \macro{\par} is replaced by a space. +Setting the key to \macro{false} disables the treatment of the input as described in the following of this section. The source code will be read and parsed as is. If the source does not contain any escape sequences, empty lines or TeX macro, this choice should be used. -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). +If the key \macro{escape} is set to \macro{basic}, the package allows for empty lines in JSON strings. During parsing, every instance of the TeX macro \macro{\par} is replaced by a space. -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. +JSON strings cannot contain the two characters \macro{"} and \macro{\}. These two characters need to be escaped with a preceding backslash (\macro{\}). If the key \macro{escape} is set to \macro{basic}, this package therefore redefines locally the TeX control symbols \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, the control symbol \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 this 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. +With the key \macro{escape} set to \macro{basic}, 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. -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. +If the key \macro{escape} is set to \macro{full}, apart from the above, the JSON escape sequences \macro{\b}, \macro{\f}, \macro{\n}, \macro{\r}, \macro{\t} or \macro{\u} (followed by a hex value) are parsed if the JSON source is read in as file using \macro{\JSONParseFromFile} (in other words, full escaping functionality is not supported for the command \macro{\JSONParse}). During parsing, these escape sequences are not expanded and only when being typeset expand to their relevant replacement. The escape sequence \macro{\u} followed by a hex value consisting of four digits eventually expands to \macro{\char"} followed by the relevant four hex digits. The escape sequences \macro{\b} (backspace), \macro{\f} (formfeed), \macro{\n} (linefeed), \macro{\r} (carriage return) and \macro{\t} (horizontal tab) expand to token variables of which the contents can be set using the relevant \macro{replacement} key. See more on setting keys below in section \ref{sec:settings}. -Setting the internal boolean \macro{\l_jsonparse_escape_input_bool} to false disables the treatment of the input as described in this section. +Note that if the key \macro{escape} is set to \macro{full}, the category code of \macro{b}, \macro{f}, \macro{n}, \macro{r}, \macro{t} and \macro{u} will be set to 12 (other). Changing the category codes is necessary to be able to define single-letter control sequences in TeX. The category codes of these characters are changed back to 10 (letter) when stored in the property list that contains the parsed JSON string. + +\begin{macrodef} +replacement/|backspace|={<string>} +replacement/|formfeed|={<string>} +replacement/|linefeed|={<string>} +replacement/|carriage return|={<string>} +replacement/|horizontal tab|={<string>} +\end{macrodef} +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. \section{Main user commands} @@ -233,32 +256,42 @@ Setting the internal boolean \macro{\l_jsonparse_escape_input_bool} to false dis \end{macrodef} The command \macro{\JSONParse} is used to parse a JSON string and store the parsed result in a token variable (a property list). The first argument takes the name of the token variable that is created by the command. The second argument takes the JSON string to be parsed. -For example, using \macro{\JSONParse{\myJSONdata}{ { "key" : "value" } }}, the relevant JSON string will be parsed and the result stored in the token variable \macro{\myJSONdata} as property list. In this case, the property list only consists of one entry with the key \macro{key} and the value \macro{value}. The command \macro{\JSONParseGetValue{\myJSONdata}{key}}, for example, can then be used to extract the relevant value from this property list (see the description below). +For example, using \macro{\JSONParse{\myJSONdata}{ { "key" : "value" } }}, the relevant JSON string will be parsed and the result stored in the token variable \macro{\myJSONdata} as property list. In this case, the property list only consists of one entry with the key \macro{key} and the value \macro{value}. The command \macro{\JSONParseValue{\myJSONdata}{key}}, for example, can then be used to extract the relevant value from this property list (see the description below). \begin{macrodef} |\JSONParseFromFile|{<token variable>}{<JSON file>} \end{macrodef} The command \macro{\JSONParseFromFile} is used to parse a JSON file and store the parsed result in a token variable (a property list). It works the same way as \macro{\JSONParse}, but instead of a JSON string, it takes as second argument the path to the JSON file relative to the working directory. +This command will temporarily change the category code of \macro{b}, \macro{f}, \macro{n}, \macro{r}, \macro{t} and \macro{u} to 12 (other) if full escaping is activated. See more on escaping above in section \ref{sec:escaping}. + +\begin{macrodef} +|\JSONParseKeys|{<token variable>}{<token variable>} +\end{macrodef} +The command \macro{\JSONParseKeys} is used to store all top-level keys of a parsed JSON object as array into a token variable. The command takes as first argument the token variable that holds the parsed JSON data. The second argument takes the token variable that is assigned a JSON array containing the top-level keys of the object represented by the token variable in the first argument. The token variable to store the keys as array is created if it does not exist. + \begin{macrodef} -|\JSONParseGetValue|{<token variable>}{<key>} -|\JSONParseGetValue*|{<token variable>}{<key>} +|\JSONParseValue|{<token variable>}{<key>} +|\JSONParseValue*|{<token variable>}{<key>} +|\JSONParseExpandableValue|{<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. +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. -If the JSON string \macro{{ "key" : "value" }} is parsed into the token variable \macro{\myJSONdata}, using \macro{\JSONParseGetValue{\myJSONdata}{key}} would extract the value associated with the key \macro{key}, which in this case is \macro{value}, and typeset it to the document. +If the JSON string \macro{{ "key" : "value" }} is parsed into the token variable \macro{\myJSONdata}, using \macro{\JSONParseValue{\myJSONdata}{key}} would extract the value associated with the key \macro{key}, which in this case is \macro{value}, and typeset it to the document. -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" ] }}. +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{\JSONParseValue{\myJSONdata}{outer_key.inner_key}} can be used. To give an example for an array, the command \macro{\JSONParseValue{\myJSONdata}{key[0]}} selects the first value of the array associated with the key \macro{key} in the 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. 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{\JSONParseValue*}, rescans the token list before it is typeset (which means that all category codes that may have been changed before are set to the default values), 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. -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. +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. + +If the output of whole objects or arrays is meant to be parsed again using \macro{\JSONParse}, the expandable command \macro{\JSONParseExpandableValue} is to be used. \begin{macrodef} -|\JSONParseGetArrayValues|{<token variable>}{<key>}[<subkey>]{<string>} -|\JSONParseGetArrayValues*|{<token variable>}{<key>}[<subkey>]{<string>} +|\JSONParseArrayValues|{<token variable>}{<key>}[<subkey>]{<string>} +|\JSONParseArrayValues*|{<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. +The command \macro{\JSONParseArrayValues} 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 and 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. For example, let us assume the following JSON data structure is parsed into the token variable \macro{\myJSONdata}: @@ -277,15 +310,15 @@ For example, let us assume the following JSON data structure is parsed into the } \end{codeexample} -Then using \macro{\JSONParseGetArrayValues{\myJSONdata}{array}[key_a]{, }}, the text \macro{one, three} is typeset to the document. +Then, when using \macro{\JSONParseArrayValues{\myJSONdata}{array}[key_a]{, }}, `one, three' is typeset to the document. -The starred variant, \macro{\JSONParseGetArrayValues*}, rescans the token lists before they are typeset. +The starred variant, \macro{\JSONParseArrayValues*}, rescans the token lists before they are typeset. \begin{macrodef} -|\JSONParseUseArrayValues|{<token variable>}{<key>}[<subkey>]{<command name>} -|\JSONParseUseArrayValues*|{<token variable>}{<key>}[<subkey>]{<command name>} +|\JSONParseArrayValuesMap|{<token variable>}{<key>}[<subkey>]{<command name>} +|\JSONParseArrayValuesMap*|{<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. +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. 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: @@ -297,85 +330,67 @@ For example, let us assume the same JSON data structure as defined above parsed } \begin{itemize} - \JSONParseUseArrayValues{\myJSONdata} + \JSONParseArrayValuesMap{\myJSONdata} {array}[key_a]{myJSONitem} \end{itemize} \end{codeexamplecolumns} -The starred variant, \macro{\JSONParseUseArrayValues*}, rescans the token lists before they are typeset. +The starred variant, \macro{\JSONParseArrayValuesMap*}, rescans the token lists before they are typeset. \begin{macrodef} -|\JSONParseGetArrayCount|{<token variable>}{<key>} +|\JSONParseArrayCount|{<token variable>}{<key>} \end{macrodef} -The command \macro{\JSONParseGetArrayCount} takes as frist argument a token variable that holds a parsed JSON string or JSON file and as second argument a key. It returns an integer representing the number of items contained in the selected array. +The command \macro{\JSONParseArrayCount} takes as first argument a token variable holding a parsed JSON string or JSON file and as second argument a key. It returns an integer representing the number of items contained in the selected array. -\subsection{Commands to alter separators and output} +\subsection{Changing separators, output and other settings}\label{sec:settings} -The package provides a set of commands that can be used to change the separators used to select the relevant value in the JSON structure as well as the output that is generated from the JSON data. +The package provides a set of keys can be set to change the separators used to select the relevant value in the JSON structure, the output that is generated from the JSON data as well as other things. \begin{macrodef} -|\JSONParseSetChildSeparator|{<string>} -|\JSONParseSetArraySeparator|{<string>}{<string>} +|\JSONParseSet|{<key-value list>} \end{macrodef} -The two commands \macro{\JSONParseSetChildSeparator} and \macro{\JSONParseSetArraySeparator} can be used to change the separators for child objects or array items in the syntax used to select a specific value in the JSON data structure. Per default, the child separator is a dot (\macro{.}) while the array separators are sqare brackets (\macro{[} and \macro{]}). The command \macro{\JSONParseSetArraySeparator} takes two arguments of which the first is the character used before the array separator and the second is used after. Changing the separators can be useful if keys in the JSON structure already use these characters. +The commands \macro{\JSONParseSet} can be used to specify settings via key-value pairs (separated by commas). Keys that are presented here as a subkey (i.\,e. preceded by another key and a slash) can also be set using the syntax \macro{key={subkey}} and multiple subkeys belonging to one key can be combined using a comma as separator. The following keys are available: \begin{macrodef} -|\JSONParseSetTrueString|{<string>} -|\JSONParseSetFalseString|{<string>} -|\JSONParseSetNullString|{<string>} +separator/|child|={<string>} \end{macrodef} -The commands \macro{\JSONParseSetTrueString} and \macro{\JSONParseSetFalseString} as well as the command \macro{\JSONParseSetNullString} can be used to change the output that is typeset if the JSON value is \macro{true}, \macro{false} or \macro{null}. The default strings that are typeset are \macro{true}, \macro{false} or \macro{null} resepctively. +With the key \macro{child sep}, the separator for child objects that is used in the syntax to select a specific value in the JSON data structure can be changed. Per default, the child separator is a dot (\macro{.}). Changing the separator can be useful if keys in the JSON structure already use these characters. \begin{macrodef} -|\JSONParseSetArrayIndexZeroBased| -|\JSONParseSetArrayIndexOneBased| +separator/|array left|={<string>} +separator/|array right|={<string>} \end{macrodef} -The command \macro{\JSONParseSetArrayIndexZeroBased} sets the numbering of the index of array items to zero-based. With the command \macro{\JSONParseSetArrayIndexOneBased}, the indexing starts with one instead. Per default, the package uses zero-based indexing to resemble JavaScript notation. - -\subsection{Internal variables and commands} +With the keys \macro{array sep left} and \macro{array sep right}, the separators for arrays that are used in the syntax to select a specific value in the JSON data structure can be changed. Per default, the separators are square brackets (\macro{[} and \macro{]}). Changing the separators can be useful if keys in the JSON structure already use these characters. \begin{macrodef} -|\l_jsonparse_debug_mode_bool| +replacement/|true|={<string>} +replacement/|false|={<string>} +replacement/|null|={<string>} \end{macrodef} -The token variable \macro{\l_jsonparse_debug_mode_bool} holds the boolean value true if the package is loaded with the \macro{debug} option and false otherwise. If set to true, the debug mode will be used for the following use of \macro{\jsonparse_parse:n}. +With the keys \macro{true}, \macro{false} and \macro{null}, the string that is typeset for true, false and null values can be changed. The default strings that are typeset are \macro{true}, \macro{false} and \macro{null} respectively. Only strings can be used as replacement. \begin{macrodef} -|\l_jsonparse_child_sep_str| -|\l_jsonparse_array_sep_left_str| -|\l_jsonparse_array_sep_right_str| -|\l_jsonparse_true_str| -|\l_jsonparse_false_str| -|\l_jsonparse_null_str| -|\l_jsonparse_array_index_zero_based_bool| +|array index zero-based| +|array index zero-based|={<boolean>} \end{macrodef} -The token variable \macro{\l_jsonparse_child_sep_str} holds the string \macro{.} per default or the string set by the user command \macro{\JSONParseSetChildSeparator}. - -The token variable \macro{\l_jsonparse_array_sep_left_str} holds the string \macro{[} per default or the string given as first argument to the user command \macro{\JSONParseSetArraySeparator}. - -The token variable \macro{\l_jsonparse_array_sep_right_str} holds the string \macro{]} per default or the string given as second argument to the user command \macro{\JSONParseSetArraySeparator}. - -The token variable \macro{\l_jsonparse_true_str} holds the string \macro{true} per default or the string set by the user command \macro{\JSONParseSetTrueString}. - -{\sloppy The token variable \macro{\l_jsonparse_false_str} holds the string \macro{false} per default or the string set by the user command \macro{\JSONParseSetFalseString}. \par} - -The token variable \macro{\l_jsonparse_null_str} holds the string \macro{null} per default or the string set by the user command \macro{\JSONParseSetNullString}. +If set (or explicitly set to \macro{true}), the key \macro{array index zero-based} sets the numbering of the index of array items to zero-based. If set to false, the indexing starts with one instead. Per default, the package uses zero-based indexing to resemble JavaScript notation. -The token variable \macro{\l_jsonparse_array_index_zero_based_bool} holds a boolean value which is \macro{true} per default or if the user command \macro{\JSONParseSetArrayIndexZeroBased} was called. The boolean value is \macro{false} if the user command \macro{\JSONParseSetArrayIndexOneBased} was called. - -\begin{macrodef} -|\g_jsonparse_entries_prop| -\end{macrodef} -The token variable (property list) \macro{\g_jsonparse_entries_prop} holds key-value pairs representing all elements of a JSON data structure generated by a previous run of \macro{\jsonparse_parse:n}. +\subsection{L3 commands} \begin{macrodef} |\jsonparse_parse:n| {<JSON string>} \end{macrodef} -The command \macro{\jsonparse_parse:n} takes as argument a JSON string and populates the token variable (property list) \macro{\g_jsonparse_entries_prop} with key-value pairs representing all elements of the JSON data structure represented by this string. +The command \macro{\jsonparse_parse:n} takes as argument a JSON string and populates the token variable (property list) \macro{\g_jsonparse_entries_prop} with key-value pairs representing all elements of the JSON data structure represented by this string. This command does not escape the input in any way. \begin{macrodef} |\jsonparse_parse_to_prop:Nn| <token variable> {<JSON string>} \end{macrodef} -The command \macro{\jsonparse_parse_to_prop:Nn} creates the token variable given as the first arguments as property list and, after having called \macro{\jsonparse_parse:n} using the second argument, sets this newly created property list equal to \macro{\g_jsonparse_entries_prop}. +The command \macro{\jsonparse_parse_to_prop:Nn} creates the token variable given as the first arguments as property list and, after having called \macro{\jsonparse_parse:n} using the second argument, sets this newly created property list equal to \macro{\g_jsonparse_entries_prop}. If escaping is activated, this command will pre-process the input according to the selected escaping mode before forwarding it to \macro{\jsonparse_parse:n}. See more on escaping above in section \ref{sec:escaping}. + +\begin{macrodef} +|\jsonparse_filter:Nn| <token variable> {<key>} +\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. % ===== |