Cycle operator improvements plus docs (#5069)

* Tweak cycle operator to support step size parameter and add docs for toggle and cycle

* Mention that title list should have no duplicates

core/modules/filters/x-listops.js

@@ -188,19 +188,21 @@ Extended filter operators to manipulate the current list.
 		return set;
 	};
 
-	var cycleValueInArray = function(results,operands) {
+	var cycleValueInArray = function(results,operands,stepSize) {
 		var resultsIndex,
+			step = stepSize || 1,
 			i = 0,
+			opLength = operands.length,
 			nextOperandIndex;		
-		for(i; i < operands.length; i++) {
+		for(i; i < opLength; i++) {
 			resultsIndex = results.indexOf(operands[i]);
 			if(resultsIndex !== -1) {
 				break;
 			}
 		}
 		if(resultsIndex !== -1) {
-			i++;
-			nextOperandIndex = (i === operands.length ? 0 : i);
+			i = i + step;
+			nextOperandIndex = (i < opLength ? i : i - opLength);
 			if(operands.length > 1) {
 				results.splice(resultsIndex,1,operands[nextOperandIndex]);
 			} else {
@@ -221,11 +223,13 @@ Extended filter operators to manipulate the current list.
 
 	exports.cycle = function(source,operator) {
 		var results = prepare_results(source),
-			operands = (operator.operand.length ? $tw.utils.parseStringArray(operator.operand, "true") : [""]);
-		if(operator.suffix === "reverse") {
+			operands = (operator.operand.length ? $tw.utils.parseStringArray(operator.operand, "true") : [""]),
+			step = $tw.utils.getInt(operator.operands[1]||"",1);
+		if(step < 0) {
 			operands.reverse();
-		}
-		return cycleValueInArray(results,operands);
+			step = Math.abs(step);
+		}	
+		return cycleValueInArray(results,operands,step);
 	}
 	
 })();

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

@@ -0,0 +1,24 @@
+caption: cycle
+created: 20201118172906835
+modified: 20201118192136472
+op-input: a list of items
+op-output: the input list with the titles specified in the parameter toggled in a cyclical manner
+op-parameter: the <<.op cycle>> operator accepts 1 or 2 parameters, see below for details
+op-purpose: toggle in the input, the titles specified in the first operand in a cyclical manner
+tags: [[Filter Operators]] [[Listops Operators]] [[Order Operators]]
+title: cycle Operator
+type: text/vnd.tiddlywiki
+
+<<.from-version "5.1.23">>
+
+The <<.op cycle>> operator requires at least one parameter.
+
+```
+[toggle[<titles>],[step-size]]
+```
+* ''titles'' : a title list to toggle in the input list cyclically. If no title from the parameter is present in the input, the first title is added. If a title from the parameter is present in the input, it is replaced with the next title from the parameter. Note that all titles specified in this parameter should be unique.
+* ''step-size'': (optional). Defaults to 1. Specifies the number of steps in the parameter list to move each time. Can be a negative number.
+
+<$macrocall $name=".tip" _="While the <<.op cycle>> operator interprets its first parameter as a list of titles to cycle through, the [[toggle Operator]] accepts an unlimited number of distinct parameters and offers similar functionality."/>
+
+<<.operator-examples "cycle">>

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

@@ -0,0 +1,21 @@
+created: 20201118174250896
+modified: 20201118175415868
+tags: [[Operator Examples]] [[cycle Operator]]
+title: cycle Operator (Examples)
+type: text/vnd.tiddlywiki
+
+Cycle through a list of values to add as a tag:
+
+```
+<$action-listops $tiddler="target" $tags="+[cycle[todo soon now maybe done ]]" />
+```
+
+Cycle through a list of values to add as a tag, in reverse order:
+
+```
+<$action-listops $tiddler="target" $tags="+[cycle[todo soon now maybe done ],[-1]]" />
+```
+
+<<.using-days-of-week>>
+<<.operator-example 1 """[list[Days of the Week]first[]] +[cycle{Days of the Week!!list}]""">>
+<<.operator-example 1 """[list[Days of the Week]first[]] +[cycle{Days of the Week!!list},[2]]""">>

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

@@ -1,5 +1,6 @@
 created: 20201107154352695
-modified: 20201109104951727
+modified: 20201118174726982
+tags: [[Operator Examples]] [[toggle Operator]]
 title: toggle Operator (Examples)
 type: text/vnd.tiddlywiki
 

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

@@ -1,9 +1,9 @@
 caption: toggle
 created: 20201107153758990
-modified: 20201109104654310
+modified: 20201118192155504
 op-input: a list of items
 op-output: the input list with the title specified in the parameter toggled
-op-parameter: the <<.op toggle>> operator accepts 1 or 2 parameters, see below for details
+op-parameter: the <<.op toggle>> operator accepts 1 or more parameters, see below for details
 op-purpose: toggle the title specified in the operand in the input
 tags: [[Filter Operators]] [[Listops Operators]] [[Order Operators]]
 title: toggle Operator
@@ -11,7 +11,7 @@ type: text/vnd.tiddlywiki
 
 <<.from-version "5.1.23">>
 
-The <<.op toggle>> operator requires at least one parameter and can accept a second optional parameter:
+The <<.op toggle>> operator requires at least one parameter and can accept additional optional parameters. With a second optional parameter it can be used to toggle between a pair of titles:
 
 ```
 [toggle[<title1>],[<title2>]]
@@ -19,5 +19,8 @@ The <<.op toggle>> operator requires at least one parameter and can accept a sec
 * ''title1'' : a title to toggle in the input list. If it is already present, it is removed. Otherwise, it is added.
 * ''title2'': (optional). When the second parameter is provided, the operator toggles between the two values in the input list. If neither is present, the first parameter takes precedence is added to the list.
 
+With more than two parameters, the <<.op toggle>> behaves similar to the [[cycle|cycle Operator]] and can be used to cycle through a list of values. Note that all operands should be unique.
+
+<$macrocall $name=".tip" _="While the <<.op cycle>> operator interprets its first parameter as a list of titles to cycle through and offers similar functionality, the <<.op toggle>> operator accepts an unlimited number of distinct parameters."/>
 
 <<.operator-examples "toggle">>