diff --git a/editions/tw5.com/tiddlers/concepts/Macros.tid b/editions/tw5.com/tiddlers/concepts/Macros.tid index 8377046f6..884551996 100644 --- a/editions/tw5.com/tiddlers/concepts/Macros.tid +++ b/editions/tw5.com/tiddlers/concepts/Macros.tid @@ -1,9 +1,15 @@ created: 20140211171341271 -modified: 20230419103154328 +modified: 20230922094937115 tags: Concepts Reference title: Macros type: text/vnd.tiddlywiki +!! Important + +<<.from-version "5.3.0">> Macros have been [[superseded|Macro Pitfalls]] by [[Procedures]], [[Functions]] and [[Custom Widgets]] which together provide more robust and flexible ways to encapsulate and re-use code. + +For text substitutions it is now recommended to use: [[Substituted Attribute Values]], [[substitute Operator]] and [[Transclusion and Substitution]] + !! Introduction A <<.def macro>> is a named snippet of text. They are typically defined with the [[Pragma: \define]]: @@ -26,8 +32,6 @@ The parameters that are specified in the macro call are substituted for special * `$parameter-name$` is replaced with the value of the named parameter * `$(variable-name)$` is replaced with the value of the named [[variable|Variables]]). -<<.from-version "5.3.0">> Macros have been [[superseded|Macro Pitfalls]] by [[Procedures]], [[Custom Widgets]] and [[Functions]] which together provide more robust and flexible ways to encapsulate and re-use code. It is now recommended to only use macros when textual substitution is specifically required. - !! How Macros Work Macros are implemented as a special kind of [[variable|Variables]]. The only thing that distinguishes them from ordinary variables is the way that the parameters are handled. diff --git a/editions/tw5.com/tiddlers/concepts/Title List.tid b/editions/tw5.com/tiddlers/concepts/Title List.tid index a49a665ad..67bb4e339 100644 --- a/editions/tw5.com/tiddlers/concepts/Title List.tid +++ b/editions/tw5.com/tiddlers/concepts/Title List.tid @@ -1,5 +1,5 @@ created: 20150117152418000 -modified: 20220523075540462 +modified: 20231019155036098 tags: Concepts title: Title List type: text/vnd.tiddlywiki @@ -15,3 +15,7 @@ Title lists are used in various places, including PermaLinks and the ListField. They are in fact the simplest case of a [[filter|Filters]], and are thus a way of expressing a [[selection of titles|Title Selection]]. <<.warning """The [[Title List]] format cannot reliably represent items that contain certain specific character sequences such as `]] `. Thus it should not be used where there is a possibility of such sequences occurring.""">> + +See also: + +* The [[format Operator]] with the 'titlelist' suffix conditionally wraps double square brackets around a string if it contains whitespace 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/hellothere/HelloThere.tid b/editions/tw5.com/tiddlers/hellothere/HelloThere.tid index 92d4cd6c5..ddb91a41e 100644 --- a/editions/tw5.com/tiddlers/hellothere/HelloThere.tid +++ b/editions/tw5.com/tiddlers/hellothere/HelloThere.tid @@ -20,7 +20,7 @@ TiddlyWiki lets you choose where to keep your data, guaranteeing that in the dec