Add the timestamp suffix to the format operator (#7292)

* Create timestamp.js

Taken verbatim from @ericshulman.

* Add description of the timestamp suffix

* Add an example for timestamp use

I also snuck it a couple of cosmetic corrections, because I was too lazy to open a new PR. 😢

* Correct example 4 to use the right date formats

* Correct description of the default date format

* Add a test for the timestamp suffix

* Add more format:timestamp tests

* Drop invalid input

* Update version tag in docs

---------

Co-authored-by: jeremy@jermolene.com <jeremy@jermolene.com>

core/modules/filters/format/timestamp.js

@@ -0,0 +1,25 @@
+/*\
+title: $:/core/modules/filters/format/timestamp.js
+type: application/javascript
+module-type: formatfilteroperator
+\*/
+(function(){
+
+/*jslint node: true, browser: true */
+/*global $tw: false */
+"use strict";
+
+/*
+Export our filter function
+*/
+exports.timestamp = function(source,operand,options) {
+	var results = [];
+	source(function(tiddler,title) {
+		if (title.match(/^-?\d+$/)) {
+			var value = new Date(Number(title));
+			results.push($tw.utils.formatDateString(value,operand || "[UTC]YYYY0MM0DD0hh0mm0ss0XXX"));
+		}
+	});
+	return results;
+};
+})();

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

@@ -1060,6 +1060,9 @@ Tests the filtering mechanism.
 			expect(wiki.filterTiddlers("[[Hello There]] [[GettingStarted]] +[format:titlelist[]]").join(" ")).toBe("[[Hello There]] GettingStarted");
 			expect(wiki.filterTiddlers("[title[Hello There]] +[format:titlelist[]]").join(" ")).toBe("[[Hello There]]");
 			expect(wiki.filterTiddlers("[title[HelloThere]] +[format:titlelist[]]").join(" ")).toBe("HelloThere");		
+			expect(wiki.filterTiddlers("0 +[format:timestamp[]]").join(",")).toBe("19700101000000000");
+			expect(wiki.filterTiddlers("1603188514443 +[format:timestamp[]]").join(",")).toBe("20201020100834443");
+			expect(wiki.filterTiddlers("void +[format:timestamp[]]").join(",")).toBe("");
 		});
 	
 		it("should handle the deserializers operator", function() {

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

@@ -1,5 +1,5 @@
 created: 20201020102735123
-modified: 20220611104737314
+modified: 20230226135641976
 tags: [[Operator Examples]] [[format Operator]]
 title: format Operator (Examples)
 type: text/vnd.tiddlywiki
@@ -15,20 +15,23 @@ Created date with a format string supplied as operator parameter:
 Modified date shown as a relative date:
 <<.operator-example 3 "[[HelloThere]get[modified]format:relativedate[]]">>
 
+Get the date and time exactly 24 hours (86,400,000 milliseconds) from now:
+<<.operator-example 4 "[<now [UTC]YYYY0MM0DD0hh0mm0ss0XXX>format:date[TIMESTAMP]add[86400000]format:timestamp[DDth mmm YYYY 0hh:0mm:0ss]]">>
+
 A tiddler title with spaces formatted as a title list:
-<<.operator-example 4 """[[Hello There]format:titlelist[]]""">>
+<<.operator-example 5 """[[Hello There]format:titlelist[]]""">>
 
 All tiddler titles tagged with <<tag TableOfContents>> formatted as a title list:
-<<.operator-example 5 """[tag[TableOfContents]format:titlelist[]]""">>
+<<.operator-example 6 """[tag[TableOfContents]format:titlelist[]]""">>
 
 A JSON string formatted as JSON – note how the JSON string is normalised to remove the duplicated properties:
-<<.operator-example 6 """[[{"one":"first","one":"another","two":"second"}]format:json[]]""">>
+<<.operator-example 7 """[[{"one":"first","one":"another","two":"second"}]format:json[]]""">>
 
 <<.tip "To create a string to save a [[title list|Title List]] into a list field, use `format:titlelist[]` with the [[join operator|join Operator]]">>
-<<.operator-example 6 """[tag[TableOfContents]format:titlelist[]join[ ]]""">>
+<<.operator-example 8 """[tag[TableOfContents]format:titlelist[]join[ ]]""">>
 For example, to save titles tagged `TableOfContents` to the titles field of the tiddler [[format titlelist test]]:
 
 <$macrocall $name='wikitext-example-without-html'
-src='<$button> test
+src='<$button>Try it
 <$action-setfield $tiddler="format titlelist test" titles={{{ [tag[TableOfContents]format:titlelist[]join[ ]] }}}/>
 </$button>'/>

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

@@ -20,8 +20,11 @@ The suffix <<.place B>> is one of the following supported string formats:
 |^`date` |The input string is interpreted as a UTC date and displayed according to the DateFormat specified in the optional operator operand. (Defaults to "YYYY MM DD 0hh:0mm") |
 |^`json` |<<.from-version "5.2.4">> The input string is interpreted as JSON and displayed with standard formatting. The optional operator operand specifies the number of spaces to use for indenting, or a string to use for indenting. Nothing is returned if the input string is not valid JSON |
 |^`relativedate` |The input string is interpreted as a UTC date and displayed as the interval from the present instant. Any operator parameters are ignored |
+|^`timestamp` |<<.from-version "5.3.0">> The input string is interpreted as number of milliseconds since the [[ECMAScript epoch|https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#the_ecmascript_epoch_and_timestamps]], 1 January 1970, and displayed according to the DateFormat specified in the optional operator operand. (Defaults to "[UTC]YYYY0MM0DD0hh0mm0ss0XXX") |
 |^`titlelist` |<<.from-version "5.2.0">> The input string wrapped in double square brackets if it contains a space. Appropriate for use in a [[title list|Title List]]. |
 
+Invalid input strings are dropped by the <<.op format>> operator.
+
 <<.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.""">>
 
 <<.operator-examples "format">>