Docs for new operators (#4994)

* Docs for is[draft]

* Better error handling for suffixes

* Docs for search-replace operator

* Added tests for search-replace operator

* Docs for toggle operator

core/modules/filters/strings.js

@@ -118,7 +118,7 @@ exports.splitregexp = function(source,operator,options) {
 exports["search-replace"] = function(source,operator,options) {
 	var results = [],
 		suffixes = operator.suffixes || [],
-		flagSuffix = suffixes[0] || [],
+		flagSuffix = (suffixes[0] ? (suffixes[0][0] || "") : ""),
 		flags = (flagSuffix.indexOf("g") !== -1 ? "g" : "") + (flagSuffix.indexOf("i") !== -1 ? "i" : ""),
 		isRegExp = (suffixes[1] && suffixes[1][0] === "regexp") ? true : false,
 		searchTerm,

editions/test/tiddlers/tests/test-filters.js

@@ -752,6 +752,23 @@ function runTests(wiki) {
 		expect(wiki.filterTiddlers("[!sortsub:string<sort2>]",anchorWidget).join(",")).toBe("filter regexp test,$:/TiddlerTwo,Tiddler Three,a fourth tiddler,$:/ShadowPlugin,has filter,hasList,TiddlerOne,one");
 		expect(wiki.filterTiddlers("[[TiddlerOne]] [[$:/TiddlerTwo]] [[Tiddler Three]] [[a fourth tiddler]] +[!sortsub:number<sort3>]",anchorWidget).join(",")).toBe("$:/TiddlerTwo,Tiddler Three,TiddlerOne,a fourth tiddler");
 	});
+
+	it("should handle multiple operands for search-replace", function() {
+		var widget = require("$:/core/modules/widgets/widget.js");
+		var rootWidget = new widget.widget({ type:"widget", children:[ {type:"widget", children:[]} ] },
+										   { wiki:wiki, document:$tw.document});
+		rootWidget.makeChildWidgets();
+		var anchorWidget = rootWidget.children[0];
+		rootWidget.setVariable("var1","different");
+		rootWidget.setVariable("myregexp","e|o");
+		rootWidget.setVariable("name","(\w+)\s(\w+)");
+		expect(wiki.filterTiddlers("[[Welcome to TiddlyWiki, a unique non-linear webpage.]search-replace[webpage],[notebook]]").join(",")).toBe("Welcome to TiddlyWiki, a unique non-linear notebook.");
+		expect(wiki.filterTiddlers("[[Welcome to TiddlyWiki, a unique non-linear notebook.]search-replace[unique],<var1>]",anchorWidget).join(",")).toBe("Welcome to TiddlyWiki, a different non-linear notebook.");
+		expect(wiki.filterTiddlers("[[Welcome to TiddlyWiki, a unique non-linear notebook.]search-replace[TiddlyWiki],{one}]",anchorWidget).join(",")).toBe("Welcome to This is the text of tiddler [[one]], a unique non-linear notebook.");
+		expect(wiki.filterTiddlers("[[Hello There]search-replace:g:regexp<myregexp>,[]]",anchorWidget).join(",")).toBe("Hll Thr");
+		expect(wiki.filterTiddlers("[[Hello There]search-replace::regexp<myregexp>,[]]",anchorWidget).join(",")).toBe("Hllo There");
+		expect(wiki.filterTiddlers("[[Hello There]search-replace:gi[H],[]]",anchorWidget).join(",")).toBe("ello Tere");	
+	});
 }
 
 });

editions/tw5.com/tiddlers/filters/is.tid

@@ -1,15 +1,15 @@
+caption: is
 created: 20140410103123179
-modified: 20190916151432497
+modified: 20201107110947882
+op-input: a [[selection of titles|Title Selection]]
+op-neg-output: those input tiddlers that do <<.em not>> belong to category <<.place C>>
+op-output: those input tiddlers that belong to category <<.place C>>
+op-parameter: a category
+op-parameter-name: C
+op-purpose: filter the input by fundamental category
 tags: [[Filter Operators]] [[Common Operators]] [[Negatable Operators]]
 title: is Operator
 type: text/vnd.tiddlywiki
-caption: is
-op-purpose: filter the input by fundamental category
-op-input: a [[selection of titles|Title Selection]]
-op-parameter: a category
-op-parameter-name: C
-op-output: those input tiddlers that belong to category <<.place C>>
-op-neg-output: those input tiddlers that do <<.em not>> belong to category <<.place C>>
 
 The parameter <<.place C>> is one of the following fundamental categories:
 
@@ -25,6 +25,7 @@ The parameter <<.place C>> is one of the following fundamental categories:
 |^`tiddler` |exists as a non-shadow tiddler |
 |^`variable` |<<.from-version "5.1.20">> exists as a variable (whether or not that variable has a non-blank value) |
 |^`blank` |<<.from-version "5.1.20">> is blank (i.e. is a zero length string) |
+|^`draft` |<<.from-version "5.1.23">> is a draft of another tiddler. Synonym for `[has[draft.of]]` |
 
 If <<.place C>> is anything else an error message is returned. <<.from-version "5.1.14">> if <<.place C>> is blank, the output is passed through unchanged (in earlier versions an error message was returned).
 

editions/tw5.com/tiddlers/filters/search-replace Operator (Examples).tid

@@ -0,0 +1,25 @@
+created: 20201107112846692
+modified: 20201107113536230
+tags: [[Operator Examples]] [[search-replace Operator]]
+title: search-replace Operator (Examples)
+type: text/vnd.tiddlywiki
+
+\define myregexp() e|o
+
+\define names() (\w+)\s(\w+)
+
+Replace one string with another:
+<<.operator-example 1 """[[The quick brown fox jumps over the lazy dog]search-replace[dog],[cat]]""">>
+
+Replace all matches of a regular expression:
+
+`\define myregexp() e|o`
+<<.operator-example 2 """[[Hello There]search-replace:g:regexp<myregexp>,[]]""">>
+
+Replace all matches of a string irrespective of case:
+<<.operator-example 3 """[[Hello There]search-replace:gi[H],[]]""">>
+
+You can also use regular expression capture groups in the replacement string:
+
+`\define names() (\w+)\s(\w+)`
+<<.operator-example 4 """[[John Smith]search-replace::regexp<names>,[$2,$1]]""" >>

editions/tw5.com/tiddlers/filters/search-replace Operator.tid

@@ -0,0 +1,28 @@
+caption: search-replace
+created: 20201107111139011
+modified: 20201107122008854
+op-input: a [[selection of titles|Title Selection]]
+op-output: the input titles with the search string replaced with the replacement string
+op-parameter: the <<.op search-replace>> operator requires 2 parameters, see below for details
+op-purpose: returns each item in the list, replacing within each title the string specified by the first parameter with the second parameter
+op-suffix: the <<.op search-replace>> operator uses a rich suffix, see below for details
+tags: [[Filter Operators]] [[String Operators]]
+title: search-replace Operator
+type: text/vnd.tiddlywiki
+
+<<.from-version "5.1.23">>
+
+The <<.op search-replace>> operator uses an extended syntax that allows for multiple suffixes and parameters to be passed:
+
+```
+[search-replace:<flag list>:<regexp-mode>[<search-term>],[<replacement>]]
+```
+
+* ''flag-list'': ''g'' for global mode to replace all matches, ''i'' for case-insensitive mode, "gi" for both. (optional)
+* ''regexp-mode'': ''regexp'' to treat the first parameter as a regular expression (optional).
+* ''search-term'': string or regular expression that should be replaced
+* ''replacement'': string that should replace the search-term
+
+<<.tip "Either [[parameter|Filter Parameter]] can be a string, a text reference or a variable">>
+
+<<.operator-examples "search-replace">>

editions/tw5.com/tiddlers/filters/toggle Operator (Examples).tid

@@ -0,0 +1,20 @@
+created: 20201107154352695
+modified: 20201107155030228
+title: toggle Operator (Examples)
+type: text/vnd.tiddlywiki
+
+<<.using-days-of-week>>
+
+<<.operator-example 1 """[list[Days of the Week]] +[toggle[Wednesday]]""">>
+
+To toggle a tag in a tiddler:
+
+```
+<$action-listops  $tiddler="target" $tags="+[toggle[done]]" />
+```
+
+To toggle a title in a field:
+
+```
+<$action-listops $tiddler="target" $field="my-field" $subfilter="+[toggle[done]]" />
+```

editions/tw5.com/tiddlers/filters/toggle Operator.tid

@@ -0,0 +1,13 @@
+caption: toggle
+created: 20201107153758990
+modified: 20201107154300086
+op-input: a list of items
+op-output: the input list with the title  <<.place R>> toggled
+op-parameter: an item to toggle in the input list
+op-parameter-name: R
+op-purpose: toggle the title specified in the operand in the input
+tags: [[Filter Operators]] [[Listops Operators]] [[Order Operators]]
+title: toggle Operator
+type: text/vnd.tiddlywiki
+
+<<.operator-examples "toggle">>