Kin filter: Recursively looking for kinship between tiddler titles

core/modules/filters/kin.js

@@ -0,0 +1,113 @@
+/*\
+title: $:/core/modules/filters/kin.js
+type: application/javascript
+module-type: filteroperator
+
+Finds out where a tiddler originates from and what other tiddlers originate from it
+
+\*/
+(function() {
+
+	/*jslint node: true, browser: true */
+	/*global $tw: true */
+	"use strict";
+
+	function collectTitlesRecursively(baseTiddler,baseTitle,options) {
+		var cacheName = "kin-filter-" + baseTitle + "-" + options.fieldName + "-",
+			titlesPointingFromBase = {},
+			titlesPointingToBase = {},
+			resultsFrom = [],
+			resultsTo = [];
+
+		function addToResultsIfNotFoundAlready(alreadyFound,title,depth) {
+			if(title in alreadyFound) {
+				return false;
+			}
+			alreadyFound[title] = depth;
+			return true
+		}
+
+		function collectTitlesPointingFrom(tiddler,title,currentDepth) {
+			if(addToResultsIfNotFoundAlready(titlesPointingFromBase,title,currentDepth)) {
+				currentDepth += 1;
+				if(tiddler) {
+					$tw.utils.each(tiddler.getFieldList(options.fieldName),function(targetTitle) {
+						collectTitlesPointingFrom(options.wiki.getTiddler(targetTitle),targetTitle,currentDepth);
+					});
+				}
+			}
+		}
+
+		function collectTitlesPointingTo(title,currentDepth) {
+			if(addToResultsIfNotFoundAlready(titlesPointingToBase,title,currentDepth)) {
+				currentDepth += 1;
+				$tw.utils.each(options.wiki.findTiddlersByField(title,options.fieldName),function(targetTitle) {
+					collectTitlesPointingTo(targetTitle,currentDepth);
+				});
+			}
+		}
+
+		function getResultsInGivenDepth(cachedData) {
+			if(options.depth) {
+				return $tw.utils.getObjectKeysByExpression(cachedData,function(value) {
+					return value <= options.depth;
+				})
+			} else {
+				return Object.keys(cachedData);
+			}
+		}
+
+		if((options.direction === "from") || (options.direction === "with")) {
+			resultsFrom = $tw.wiki.getGlobalCache(cacheName + "from",function() {
+				collectTitlesPointingFrom(baseTiddler,baseTitle,0);
+				return titlesPointingFromBase;
+			});
+			resultsFrom = getResultsInGivenDepth(resultsFrom);
+		}
+		if((options.direction === "to") || (options.direction === "with")) {
+			resultsTo = $tw.wiki.getGlobalCache(cacheName + "to",function() {
+				collectTitlesPointingTo(baseTitle,0);
+				return titlesPointingToBase;
+			});
+			resultsTo = getResultsInGivenDepth(resultsTo);
+		}
+		return $tw.utils.pushTop(resultsFrom,resultsTo);
+	}
+
+	/*
+	Export our filter function
+	*/
+	exports.kin = function(source,operator,options) {
+		var results = [],
+			needsExclusion = operator.prefix === "!",
+			suffixes = operator.suffixes || [],
+			filterOptions = {
+				wiki: options.wiki,
+				fieldName: ((suffixes[0] || [])[0] || "tags").toLowerCase(),
+				direction: ((suffixes[1] || [])[0] || "with").toLowerCase(),
+				depth: Number((suffixes[2] || [])[0]),
+			};
+
+		if((operator.operand === "") && (needsExclusion)) {
+			return [];
+		}
+
+		if(operator.operand !== "") {
+			var baseTitle = operator.operand,
+				baseTiddler = options.wiki.getTiddler(baseTitle),
+				foundTitles = collectTitlesRecursively(baseTiddler,baseTitle,filterOptions);
+
+			source(function(tiddler,title) {
+				if(needsExclusion === (foundTitles.indexOf(title) === -1)) {
+					results.push(title);
+				}
+			});
+		} else {
+			source(function(tiddler,title) {
+				results = $tw.utils.pushTop(results,collectTitlesRecursively(tiddler,title,filterOptions));
+			});
+		}
+
+		return results;
+	}
+})();

core/modules/filters/listed.js

@@ -19,7 +19,7 @@ exports.listed = function(source,operator,options) {
 	var field = operator.operand || "list",
 		results = [];
 	source(function(tiddler,title) {
-		$tw.utils.pushTop(results,options.wiki.findListingsOfTiddler(title,field));
+		$tw.utils.pushTop(results,options.wiki.findTiddlersByField(title,field));
 	});
 	return results;
 };

core/modules/utils/utils.js

@@ -223,6 +223,20 @@ exports.removeArrayEntries = function(array,value) {
 	}
 };
 
+/*
+Collect keys of object (probably hash) where callback yields to true
+ */
+exports.getObjectKeysByExpression = function(object,callback) {
+	var key,
+		results = [];
+	for (key in object) {
+		if (object.hasOwnProperty(key) && callback(object[key])) {
+			results.push(key);
+		}
+	}
+	return results;
+};
+
 /*
 Check whether any members of a hashmap are present in another hashmap
 */

core/modules/wiki.js

@@ -522,7 +522,7 @@ exports.getTagMap = function() {
 /*
 Lookup a given tiddler and return a list of all the tiddlers that include it in the specified list field
 */
-exports.findListingsOfTiddler = function(targetTitle,fieldName) {
+exports.findTiddlersByField = function(targetTitle,fieldName) {
 	fieldName = fieldName || "list";
 	var titles = [];
 	this.each(function(tiddler,title) {
@@ -534,6 +534,10 @@ exports.findListingsOfTiddler = function(targetTitle,fieldName) {
 	return titles;
 };
 
+exports.findListingsOfTiddler = function(targetTitle,fieldName) {
+	return this.findTiddlersByField(targetTitle, fieldName)
+};
+
 /*
 Sorts an array of tiddler titles according to an ordered list
 */

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

@@ -203,6 +203,48 @@ describe("Filter tests", function() {
 		expect(wiki.filterTiddlers("[!untagged[]sort[title]]").join(",")).toBe("$:/TiddlerTwo,Tiddler Three,TiddlerOne");
 	});
 
+	it("should handle the kin operator",function() {
+		// It needs a tree-like wiki to test recursion.
+		var treeWiki = new $tw.Wiki();
+		treeWiki.addTiddler({
+			title: "A",
+			tags: ["B"],
+			list: "C"
+		});
+		treeWiki.addTiddler({
+			title: "B",
+			tags: ["C"],
+		});
+		treeWiki.addTiddler({
+			title: "C",
+			tags: ["A"],
+			list: ["E"]
+		});
+		treeWiki.addTiddler({
+			title: "D",
+			tags: ["B"],
+		});
+		treeWiki.addTiddler({
+			title: "E",
+			tags: ["D"],
+		});
+		treeWiki.addTiddler({
+			title: "F",
+			tags: ["E"],
+		});
+		treeWiki.addTiddler({
+			title: "G",
+			tags: ["D"],
+		});
+
+		expect(treeWiki.filterTiddlers("[kin[A]sort[title]]").join(",")).toBe("A,B,C,D,E,F,G");
+		expect(treeWiki.filterTiddlers("[kin::from[A]sort[title]]").join(",")).toBe("A,B,C");
+		expect(treeWiki.filterTiddlers("[kin::to[A]sort[title]]").join(",")).toBe("A,B,C,D,E,F,G");
+		expect(treeWiki.filterTiddlers("[kin[A]!kin::to[D]sort[title]]").join(",")).toBe("A,B,C");
+		expect(treeWiki.filterTiddlers("[kin::from:2[F]sort[title]]").join(",")).toBe("D,E,F");
+		expect(treeWiki.filterTiddlers("[kin:list[C]]").join(",")).toBe("A,C,E");
+	});
+
 	it("should handle the links operator", function() {
 		expect(wiki.filterTiddlers("[!is[shadow]links[]sort[title]]").join(",")).toBe("$:/TiddlerTwo,a fourth tiddler,one,Tiddler Three,TiddlerSix,TiddlerZero");
 		expect(wiki.filterTiddlers("[all[shadows]links[]sort[title]]").join(",")).toBe("TiddlerOne");

editions/tw5.com/tiddlers/filters/examples/kin.tid

@@ -0,0 +1,63 @@
+created: 20181026114434874
+modified: 20181108070317997
+tags: [[Operator Examples]] [[kin Operator]]
+title: kin Operator (Examples)
+type: text/vnd.tiddlywiki
+
+\define item-class(highlightfilter) <$list filter="""[$highlightfilter$is[current]first[]]""">highlighted-toc-item</$list>
+
+\define each-level(tiddlername, highlightfilter)
+  <li>
+  <$wikify name="transcluded-item-class" text=<<item-class """$highlightfilter$""">> >
+  <$link class=<<transcluded-item-class """$highlightfilter$""">> >[[$(currentTiddler)$]]</$link>
+  </$wikify>
+  <ul>
+  <$list filter="""$tiddlername$ +[kin[]tag[$(currentTiddler)$]]""">
+    <<each-level """$tiddlername$""" """$highlightfilter$""">>
+  </$list>
+  </ul>
+  </li>
+\end
+
+\define kin-toc(highlightfilter)
+  <div class="tc-table-of-contents">
+  <$tiddler tiddler="TableOfContents">
+    <ul>
+      <<each-level "[[Filter Syntax]] [[kin Operator]]"  """$highlightfilter$""">>
+    </ul>
+  </$tiddler>
+  </div>
+\end
+
+\define kin-example-with-toc(number filter comment)
+<<.operator-example """$number$""" """[$filter$]""" """$comment$""">>
+<$reveal type="nomatch" state="""$:/state/kin-example-with-toc-$number$""" text="show">
+<$button set="""$:/state/kin-example-with-toc-$number$""" setTo="show">Show tree</$button>
+</$reveal>
+<$reveal type="match" state="""$:/state/kin-example-with-toc-$number$""" text="show">
+<$button set="""$:/state/kin-example-with-toc-$number$""" setTo="hide">Hide tree</$button>
+<<kin-toc """$filter$""">>
+</$reveal>
+\end
+
+<style>
+.highlighted-toc-item a {
+  color: red !important;
+}
+</style>
+
+Family tree of [[Filter Syntax]] and [[kin Operator]] (to really understand, look at the [[TableOfContents]])
+
+<<kin-toc "!is[current]">>
+
+''The "Show tree" button below the examples only helps in understanding the filter, it's not part of the output.''
+
+<<kin-example-with-toc 1 "kin[Filter Syntax]" "input titles which are family members of the parameter title">>
+<<kin-example-with-toc 2 "kin[Filter Syntax]kin[kin Operator]" "common family members of each of the specified titles (intersection)">>
+<<kin-example-with-toc 3 "[Filter Syntax]] [[kin Operator]] +[kin[]" "collected titles which are family members of any of the input tiddlers">>
+<<kin-example-with-toc 4 "kin::to[Filters]" "successors of the given tiddler">>
+<<kin-example-with-toc 5 "kin::from[Filter Expression]kin::to[Filters]" "subset of the family tree">>
+<<kin-example-with-toc 6 "kin::from:2[Filter Expression]" "ancestors of the given tiddler until the given depth">>
+<<kin-example-with-toc 7 "kin:tags:from[Filter Syntax]" "ancestors of tiddler based on `tags` field (`tags` points to parents)">>
+<<kin-example-with-toc 8 "kin:list:to[Filter Syntax]" "ancestors of tiddler based on `list` field (`list` points to children)<br>[[Reference]] listing [[Concepts]], but [[Concepts]] does not listing [[Filters]] so they do not belong to the same family based on `list`">>
+<<.operator-example 9 "[!is[system]type[text/vnd.tiddlywiki]!kin[TableOfContents]first[10]]" "first 10 tiddlers which are not related to [[TableOfContents]] (by `tags`)">>

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

@@ -0,0 +1,40 @@
+caption: kin
+created: 20181025133804171
+modified: 20181107224931131
+op-input: a [[selection of titles|Title Selection]]
+op-neg-output: ''with parameter <<.place B>>''<br>&raquo; those input titles which are ''<<.em not>> kin with <<.place B>>''<br>''without parameter <<.place B>>''<br>&raquo; ignored
+op-output: ''with parameter <<.place B>>''<br>&raquo; those input titles which are ''kin with <<.place B>>'' <br>''without <<.place B>>''<br>&raquo; ''all'' tiddler titles which are ''kin with input titles'' (treat input titles as base tiddlers)
+op-parameter: base tiddler title or nothing
+op-parameter-name: B
+op-purpose: recursively looking for kinship between tiddler titles
+op-suffix: the <<.op kin>> operator uses a rich suffix, see below for details
+tags: [[Negatable Operators]] [[Tag Operators]] [[Filter Operators]] [[Field Operators]]
+title: kin Operator
+type: text/vnd.tiddlywiki
+
+The purpose of the <<.op {{!!caption}}>> operator with examples:
+
+* Finds out where base tiddler originates and what other elements originate from it
+* Finds the ancestors and successors of a family member
+* Finds the "leaves" of the branch of the base tiddler in a tree-like structure (where the base tiddler is a leaf)
+* Finds the super- and subsets / groups of a mathematical set (where the base tiddler is a set)
+
+[img[kin Operator.svg]]
+
+The <<.op {{!!caption}}>> operator uses an extended syntax that permits multiple fields and flags to be passed:
+
+```
+[kin:<field>:<direction>:<depth>[<operand>]]
+```
+
+* ''field'': name of the [[field|TiddlerFields]] which connecting tiddlers (assumed to be a [[title list|Title List]], defaulting to <<.field tags>>)
+* ''direction'':  collect the tiddler titles in this direction relative to the base tiddler
+** ''from'': collect kins of base tiddler pointing from it (including the base tiddler title itself)
+** ''to'': collect kins of base tiddler pointing to it (including the base tiddler title itself)
+** ''with'': (the default) union of the aboves
+* ''depth'': maximum depth of the collected labels in the tree structure relative to the base tiddler (a positive number, not limited by default)
+* ''operand'': filter operand, the base tiddler
+
+<<.op {{!!caption}}>> is a [[modifier|Selection Constructors]], but without <<.place B>> parameter is a [[constructor|Selection Constructors]].
+
+<<.operator-examples "kin">>

editions/tw5.com/tiddlers/images/kin Operator.svg.meta

@@ -0,0 +1,3 @@
+tags: picture
+title: kin Operator.svg
+type: image/svg+xml