From b08281a20b890b4137fa8fb1e8dd4fecd4bea4ce Mon Sep 17 00:00:00 2001 From: Mateusz Wilczek <36714554+mateuszwilczek@users.noreply.github.com> Date: Wed, 29 Nov 2023 10:01:46 +0100 Subject: [PATCH] Improve `jsonstringify` and `stringify` operators docs: part 2 (#7748) --- .../jsonstringify Operator (Examples).tid | 11 ++++++++ .../stringify_Operator_(Examples).tid | 6 +++-- .../filters/jsonstringify Operator.tid | 27 +++++++++++++++++-- .../tiddlers/filters/stringify_Operator.tid | 19 ++++++------- .../howtos/Constructing JSON tiddlers.tid | 4 +-- 5 files changed, 50 insertions(+), 17 deletions(-) create mode 100644 editions/tw5.com/tiddlers/filters/examples/jsonstringify Operator (Examples).tid diff --git a/editions/tw5.com/tiddlers/filters/examples/jsonstringify Operator (Examples).tid b/editions/tw5.com/tiddlers/filters/examples/jsonstringify Operator (Examples).tid new file mode 100644 index 000000000..39113ea38 --- /dev/null +++ b/editions/tw5.com/tiddlers/filters/examples/jsonstringify Operator (Examples).tid @@ -0,0 +1,11 @@ +created: 20230922121858167 +modified: 20230922122333325 +tags: [[Operator Examples]] [[jsonstringify Operator]] +title: jsonstringify Operator (Examples) +type: text/vnd.tiddlywiki + +Compare the encoding of quotes and control characters in the first example with the analogue [[example for the stringify operator|stringify Operator (Examples)]]. +<<.operator-example 1 """[[Backslash \, double quote ", single quote ', tab , line feed +]] +[jsonstringify[]]""">> +<<.operator-example 2 """[[Accents and emojis -> äñøßπ ⌛🎄🍪🍓 without suffix]] +[jsonstringify[]]""">> +<<.operator-example 3 """[[Accents and emojis -> äñøßπ ⌛🎄🍪🍓 with rawunicode suffix]] +[jsonstringify:rawunicode[]]""">> \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/filters/examples/stringify_Operator_(Examples).tid b/editions/tw5.com/tiddlers/filters/examples/stringify_Operator_(Examples).tid index cc5a51429..4b67993b0 100644 --- a/editions/tw5.com/tiddlers/filters/examples/stringify_Operator_(Examples).tid +++ b/editions/tw5.com/tiddlers/filters/examples/stringify_Operator_(Examples).tid @@ -1,9 +1,11 @@ created: 20161017154944352 -modified: 20230919124059118 +modified: 20230922122319674 tags: [[Operator Examples]] [[stringify Operator]] title: stringify Operator (Examples) type: text/vnd.tiddlywiki -<<.operator-example 1 """[[Title with "double quotes" and single ' and \backslash]] +[stringify[]]""">> +Compare the encoding of quotes and control characters in the first example with the analogue [[example for the jsonstringify operator|jsonstringify Operator (Examples)]]. +<<.operator-example 1 """[[Backslash \, double quote ", single quote ', tab , line feed +]] +[stringify[]]""">> <<.operator-example 2 """[[Accents and emojis -> äñøßπ ⌛🎄🍪🍓 without suffix]] +[stringify[]]""">> <<.operator-example 3 """[[Accents and emojis -> äñøßπ ⌛🎄🍪🍓 with rawunicode suffix]] +[stringify:rawunicode[]]""">> \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/filters/jsonstringify Operator.tid b/editions/tw5.com/tiddlers/filters/jsonstringify Operator.tid index 748a851bb..edd48432a 100644 --- a/editions/tw5.com/tiddlers/filters/jsonstringify Operator.tid +++ b/editions/tw5.com/tiddlers/filters/jsonstringify Operator.tid @@ -1,12 +1,35 @@ caption: jsonstringify created: 20171029155051467 from-version: 5.1.14 -modified: 20230919124826880 +modified: 20230922121404577 +op-input: a [[selection of titles|Title Selection]] +op-output: the input with JSON string encodings applied op-parameter: op-parameter-name: -op-purpose: deprecated, use <<.olink stringify>> instead +op-purpose: apply JSON string encoding to a string, see also the similar <<.olink stringify>> +op-suffix: <<.from-version "5.1.23">> optionally, the keyword `rawunicode` op-suffix-name: R tags: [[Filter Operators]] [[String Operators]] title: jsonstringify Operator type: text/vnd.tiddlywiki +The following substitutions are made: + +|!Character |!Replacement |!Condition | +|`\` |`\\` |Always | +|`"` |`\"` |Always | +|Carriage return (0x0d) |`\r` |Always | +|Line feed (0x0a) |`\n` |Always | +|Backspace (0x08) |`\b` |Always | +|Form field (0x0c) |`\f` |Always | +|Tab (0x09) |`\t` |Always| +|Characters from 0x00 to 0x1f, except listed above |`\u####` where #### is four hex digits |Always | +|Characters from from 0x80 to 0xffff|`\u####` where #### is four hex digits |If `rawunicode` suffix is not present (default) | +|Characters from 0x80 to 0xffff|<<.from-version "5.1.23">> Unchanged |If `rawunicode` suffix is present | + +<<.from-version "5.1.23">> If the suffix `rawunicode` is present, Unicode characters above 0x80 (such as ß, ä, ñ or 🎄) will be passed through unchanged. Without the suffix, they will be substituted with `\u` codes, which was the default behavior before 5.1.23. Characters outside the Basic Multilingual Plane, such as 🎄 and other emojis, will be encoded as a UTF-16 surrogate pair, i.e. with two `\u` sequences. + +<<.note """Mind the differences compared to <<.olink stringify>> in encoding of single quotes and control characters (0x00 to 0x1f). +""">> + +<<.operator-examples "jsonstringify">> \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/filters/stringify_Operator.tid b/editions/tw5.com/tiddlers/filters/stringify_Operator.tid index 73dabb1c2..6178517f7 100644 --- a/editions/tw5.com/tiddlers/filters/stringify_Operator.tid +++ b/editions/tw5.com/tiddlers/filters/stringify_Operator.tid @@ -1,12 +1,12 @@ caption: stringify created: 20161017153038029 from-version: 5.1.14 -modified: 20230919130847809 +modified: 20230922121406947 op-input: a [[selection of titles|Title Selection]] op-output: the input with ~JavaScript string encodings applied op-parameter: op-parameter-name: -op-purpose: apply ~JavaScript string encoding to a string +op-purpose: apply ~JavaScript string encoding to a string, see also the similar <<.olink jsonstringify>> op-suffix: <<.from-version "5.1.23">> optionally, the keyword `rawunicode` op-suffix-name: R tags: [[Filter Operators]] [[String Operators]] @@ -18,19 +18,16 @@ The following substitutions are made: |!Character |!Replacement |!Condition | |`\` |`\\` |Always | |`"` |`\"` |Always | -|Carriage return (0x0d) |`\r` |Always | +|`'` |`\'` |Always | |Line feed (0x0a) |`\n` |Always | -|Backspace (0x08) |`\b` |Always | -|Form field (0x0c) |`\f` |Always | -|Tab (0x09) |`\t` |Always | -|Characters from 0x00 to 0x1f |`\x##` where ## is two hex digits |Always | +|Carriage return (0x0d) |`\r` |Always | +|Characters from 0x00 to 0x1f, except listed above |`\x##` where ## is two hex digits |Always | |Characters from 0x80 to 0xffff|`\u####` where #### is four hex digits |If `rawunicode` suffix is not present (default) | |Characters from 0x80 to 0xffff|<<.from-version "5.1.23">> Unchanged |If `rawunicode` suffix is present | -<<.from-version "5.1.23">> If the suffix `rawunicode` is present, Unicode characters above 0x80 (such as ß, ä, ñ or 🎄) will be passed through unchanged. Without the suffix, they will be substituted with `\u` codes, which was the default behavior before 5.1.23. +<<.from-version "5.1.23">> If the suffix `rawunicode` is present, Unicode characters above 0x80 (such as ß, ä, ñ or 🎄) will be passed through unchanged. Without the suffix, they will be substituted with `\u` codes, which was the default behavior before 5.1.23. Characters outside the Basic Multilingual Plane, such as 🎄 and other emojis, will be encoded as a UTF-16 surrogate pair, i.e. with two `\u` sequences. -<<.note """Characters outside the Basic Multilingual Plane, such as 🎄 and other emojis, will be encoded as a UTF-16 surrogate pair, i.e. with two `\u` sequences.""">> - -<<.olink jsonstringify>> is considered deprecated, as it duplicates the functionality of <<.op stringify>>. +<<.note """Mind the differences compared to <<.olink jsonstringify>> in encoding of single quotes and control characters (0x00 to 0x1f). +""">> <<.operator-examples "stringify">> \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/howtos/Constructing JSON tiddlers.tid b/editions/tw5.com/tiddlers/howtos/Constructing JSON tiddlers.tid index ff4c7927c..93d78ac16 100644 --- a/editions/tw5.com/tiddlers/howtos/Constructing JSON tiddlers.tid +++ b/editions/tw5.com/tiddlers/howtos/Constructing JSON tiddlers.tid @@ -1,5 +1,5 @@ created: 20220427174702859 -modified: 20230809113620964 +modified: 20230922122551197 tags: [[JSON in TiddlyWiki]] Learning title: Constructing JSON tiddlers @@ -13,4 +13,4 @@ At a high level, we have several ways to generate JSON data in TiddlyWiki's own * [[jsontiddler Macro]] * [[jsontiddlers Macro]] -When constructing JSON data manually, the [[stringify Operator]] is needed to ensure that any special characters are properly escaped. +When constructing JSON data manually, the [[jsonstringify Operator]] is needed to ensure that any special characters are properly escaped.