Merge branch 'master' into dynamic-build-commands

This commit adds support for dynamic tokens within build commands. See the tiddlywiki.info file. Also adds an echo command to make debugging easier.

I also intend to add a node type for prompting the user for a string.

core/language/en-GB/Help/echo.tid

@@ -0,0 +1,8 @@
+title: $:/language/Help/echo
+description: Displays all the passed arguments
+
+Displays all the passed arguments to a command. Useful for debugging.
+
+```
+--echo <text> *
+```

core/modules/commander.js

@@ -13,7 +13,7 @@ The $tw.Commander class is a command interpreter
 Parse a sequence of commands
 	commandTokens: an array of command string tokens
 	wiki: reference to the wiki store object
-	streams: {output:, error:}, each of which has a write(string) method
+	streams: {output:, input:, error:}
 	callback: a callback invoked as callback(err) where err is null if there was no error
 */
 var Commander = function(commandTokens,callback,wiki,streams) {
@@ -61,69 +61,172 @@ Commander.prototype.execute = function() {
 	this.executeNextCommand();
 };
 
+/*
+Returns the next string token without consuming it, or null if there are none left. Callback invoked(err,data)
+*/
+Commander.prototype.peekNextToken = function(callback) {
+	var self = this;
+	if(this.nextToken >= this.commandTokens.length) {
+		return callback(null,null);
+	} else {
+		return this.stringifyToken(this.nextToken,function(err,data) {
+			if(!err) {
+				// Save the stringified token for next time so that we don't run prompts twice
+				self.commandTokens[self.nextToken] = data;
+			}
+			callback(err,data);
+		});
+	}
+};
+
+/*
+Returns and consumes the next string token, or null if there are none left. Callback invoked(err,data)
+*/
+Commander.prototype.getNextToken = function(callback) {
+	if(this.nextToken >= this.commandTokens.length) {
+		return callback(null,null);
+	} else {
+		return this.stringifyToken(this.nextToken++,callback);
+	}
+};
+
+/*
+Returns and consumes the string tokens until the end of the token stream or the first token that starts with "--".
+Callback invoked(err,tokenArray)
+*/
+Commander.prototype.getTokensUntilCommand = function(callback) {
+	var self = this,
+		tokens = [];
+	function processNextToken() {
+		self.peekNextToken(function(err,data) {
+			if(err) {
+				return callback(err);
+			}
+			if(data === null || data.substr(0,2) === "--") {
+				return callback(null,tokens);
+			} else {
+				self.getNextToken(function(err,data) {
+					if(err) {
+						return callback(err);
+					}
+					tokens.push(data);
+					processNextToken();
+				});
+			}
+		});	
+	}
+	processNextToken();
+};
+
+/*
+Returns a specified stringified token, or null if the index does not exist. Callback invoked(err,data)
+*/
+Commander.prototype.stringifyToken = function(index,callback) {
+	var self = this;
+	if(index >= this.commandTokens.length) {
+		return callback(null,null);
+	} else {
+		var token = this.commandTokens[index];
+		if(typeof token === "string") {
+			return callback(null,token);
+		} else if(typeof token === "object") {
+			switch(token.type) {
+				case "filter":
+					return callback(null,this.wiki.filterTiddlers(token.text)[0] || "");
+				case "wikify":
+					return callback(null,this.wiki.renderText("text/plain","text/vnd.tiddlywiki",token.text,{
+						parseAsInline: false,
+						parentWidget: $tw.rootWidget
+					}));
+				case "prompt":
+					$tw.utils.terminalQuestion({
+						promptText: token.prompt || "Please enter a value",
+						defaultResult: token["default"] || "",
+						callback: function(err,userText) {
+							if(err) {
+								callback(err);
+							} else {
+								if(token.transformFilter) {
+									userText = self.wiki.filterTiddlers(token.transformFilter,null,self.wiki.makeTiddlerIterator([userText]))[0] || "";
+								}
+								callback(null,userText);
+							}
+						},
+						input: self.streams.input,
+						output: self.streams.output,
+					});
+					break;
+				default:
+					throw "Unknown dynamic command token type: " + token.type;
+			}
+		}
+	}
+};
+
 /*
 Execute the next command in the sequence
 */
 Commander.prototype.executeNextCommand = function() {
 	var self = this;
-	// Invoke the callback if there are no more commands
+	// Get and check the command token
-	if(this.nextToken >= this.commandTokens.length) {
+	var commandName = this.getNextToken(function(err,commandName) {
-		this.callback(null);
+		if(err) {
-	} else {
+			return self.callback(err);
-		// Get and check the command token
+		}
-		var commandName = this.commandTokens[this.nextToken++];
+		if(!commandName) {
+			return self.callback(null);
+		}
 		if(commandName.substr(0,2) !== "--") {
-			this.callback("Missing command: " + commandName);
+			return self.callback("Missing command: " + commandName);
 		} else {
 			commandName = commandName.substr(2); // Trim off the --
-			// Accumulate the parameters to the command
+			// Get the parameters to the command
-			var params = [];
+			self.getTokensUntilCommand(function(err,params) {
-			while(this.nextToken < this.commandTokens.length && 
+				if(err) {
-				this.commandTokens[this.nextToken].substr(0,2) !== "--") {
+					return self.callback(err);
-				params.push(this.commandTokens[this.nextToken++]);
-			}
-			// Get the command info
-			var command = $tw.commands[commandName],
-				c,err;
-			if(!command) {
-				this.callback("Unknown command: " + commandName);
-			} else {
-				if(this.verbose) {
-					this.streams.output.write("Executing command: " + commandName + " " + params.join(" ") + "\n");
 				}
-				// Parse named parameters if required
+				var command = $tw.commands[commandName],
-				if(command.info.namedParameterMode) {
+					c,err;
-					params = this.extractNamedParameters(params,command.info.mandatoryParameters);
+				if(!command) {
-					if(typeof params === "string") {
+					self.callback("Unknown command: " + commandName);
-						return this.callback(params);
-					}
-				}
-				if(command.info.synchronous) {
-					// Synchronous command
-					c = new command.Command(params,this);
-					err = c.execute();
-					if(err) {
-						this.callback(err);
-					} else {
-						this.executeNextCommand();
-					}
 				} else {
-					// Asynchronous command
+					if(self.verbose) {
-					c = new command.Command(params,this,function(err) {
+						self.streams.output.write("Executing command: " + commandName + " " + params.join(" ") + "\n");
+					}
+					// Parse named parameters if required
+					if(command.info.namedParameterMode) {
+						params = self.extractNamedParameters(params,command.info.mandatoryParameters);
+						if(typeof params === "string") {
+							return self.callback(params);
+						}
+					}
+					if(command.info.synchronous) {
+						// Synchronous command
+						c = new command.Command(params,self);
+						err = c.execute();
 						if(err) {
 							self.callback(err);
 						} else {
 							self.executeNextCommand();
 						}
-					});
+					} else {
-					err = c.execute();
+						// Asynchronous command
-					if(err) {
+						c = new command.Command(params,self,function(err) {
-						this.callback(err);
+							if(err) {
+								self.callback(err);
+							} else {
+								self.executeNextCommand();
+							}
+						});
+						err = c.execute();
+						if(err) {
+							self.callback(err);
+						}
 					}
 				}
-			}
+			});
 		}
-	}
+	});
 };
 
 /*

core/modules/commands/echo.js

@@ -0,0 +1,32 @@
+/*\
+title: $:/core/modules/commands/echo.js
+type: application/javascript
+module-type: command
+
+Command to echo input parameters
+
+\*/
+(function(){
+
+/*jslint node: true, browser: true */
+/*global $tw: false */
+"use strict";
+
+exports.info = {
+	name: "echo",
+	synchronous: true
+};
+
+var Command = function(params,commander) {
+	this.params = params;
+	this.commander = commander;
+};
+
+Command.prototype.execute = function() {
+	this.commander.streams.output.write(JSON.stringify(this.params,null,4) + "\n");
+	return null;
+};
+
+exports.Command = Command;
+
+})();

core/modules/startup/commands.js

@@ -26,7 +26,11 @@ exports.startup = function(callback) {
 			callback();
 		},
 		$tw.wiki,
-		{output: process.stdout, error: process.stderr}
+		{
+			output: process.stdout,
+			input: process.stdin,
+			error: process.stderr
+		}
 	);
 	commander.execute();
 };

core/modules/utils/utils.js

@@ -18,29 +18,127 @@ exports.log = function(text,colour) {
 	console.log($tw.node ? exports.terminalColour(colour) + text + exports.terminalColour() : text);
 };
 
-exports.terminalColour = function(colour) {
+/*
+Prompts the user for input and handles the input using a callback function. Options:
+promptText: Prompt text
+defaultResult: Default result returned if the user types enter
+callback: callback invoked (err,usertext)
+input: optional input stream
+output: optional output stream
+*/
+exports.terminalQuestion = function(options) {
+	var readline = require("readline"),
+		promptText = options.promptText,
+		defaultResult = options.defaultResult,
+		callback = options.callback,
+		inputStream = options.input || process.stdin,
+		outputStream = options.output || process.stdout;
+	var rl = readline.createInterface({
+		input: inputStream,
+		output: outputStream
+	});
+	// Handle errors on the input stream
+	rl.on("error",function(err) {
+		rl.close();
+		callback(err); // Pass the error to the callback
+	});
+	// Prompt user for input
+	var prompt = exports.terminalColourText(promptText,["yellow","bold"]);
+	if(defaultResult) {
+		prompt += " ";
+		prompt += exports.terminalColourText("(" + defaultResult + ")",["blue","underline"]);
+	}
+	prompt += exports.terminalColourText(": ");
+	rl.question(prompt,function(input) {
+		// Use default value for the empty string
+		if(input === "" && defaultResult) {
+			input = defaultResult;
+		}
+		callback(null,input);  // Pass the input to the callback
+		rl.close();
+	});
+};
+
+/*
+Wrap a string in colour codes. Colour can be an array
+*/
+exports.terminalColourText = function(text,colour) {
+	if(!$tw.utils.isArray(colour)) {
+		colour = [colour];
+	}
+	$tw.utils.each(colour,function(code) {
+		text = exports.terminalColour(code) + text + exports.terminalColour(code,true);
+	});
+	return text;
+};
+
+/*
+Returns a terminal colour string. Set "closed" to true to return the closing code
+*/
+exports.terminalColour = function(colour,closed) {
 	if(!$tw.browser && $tw.node && process.stdout.isTTY) {
 		if(colour) {
 			var code = exports.terminalColourLookup[colour];
 			if(code) {
-				return "\x1b[" + code + "m";
+				return "\x1b[" + code[closed ? 1 : 0] + "m";
 			}
-		} else {
-			return "\x1b[0m"; // Cancel colour
 		}
+		return "\x1b[0m"; // Reset
 	}
 	return "";
 };
 
 exports.terminalColourLookup = {
-	"black": "0;30",
+	// Modifiers
-	"red": "0;31",
+	"reset": [0,0],
-	"green": "0;32",
+	"bold": [1,22],
-	"brown/orange": "0;33",
+	"dim": [2,22],
-	"blue": "0;34",
+	"italic": [3,23],
-	"purple": "0;35",
+	"underline": [4,24],
-	"cyan": "0;36",
+	"overline": [53,55],
-	"light gray": "0;37"
+	"inverse": [7,27],
+	"hidden": [8,28],
+	"strikethrough": [9,29],
+	// Colours
+	"black": [30,39],
+	"red": [31,39],
+	"green": [32,39],
+	"yellow": [33,39],
+	"brown/orange": [33,39], // Backwards compatbility
+	"blue": [34,39],
+	"magenta": [35,39], // Backwards compatbility
+	"purple": [35,39],
+	"cyan": [36,39],
+	"white": [37,39],
+	"gray": [90,39],
+	"light red": [91,39],
+	"light green": [92,39],
+	"light yellow": [93,39],
+	"light blue": [94,39],
+	"light magenta": [95,39],
+	"light purple": [95,39], // Backwards compatbility
+	"light cyan": [96,39],
+	"light gray": [97,39],
+	// Background colours
+	"black background": [40,49],
+	"red background": [41,49],
+	"green background": [42,49],
+	"yellow background": [43,49],
+	"brown/orange background": [43,49], // Backwards compatbility
+	"blue background": [44,49],
+	"magenta background": [45,49], // Backwards compatbility
+	"purple background": [45,49],
+	"cyan background": [46,49],
+	"white background": [47,49],
+	"gray background": [100,49],
+	"light red background": [101,49],
+	"light green background": [102,49],
+	"light yellow background": [103,49],
+	"light blue background": [104,49],
+	"light magenta background": [105,49],
+	"light purple background": [105,49], // Backwards compatbility
+	"light cyan background": [106,49],
+	"light gray background": [107,49]
 };
 
 /*

editions/tw5.com/tiddlers/commands/EchoCommand.tid

@@ -0,0 +1,8 @@
+caption: echo
+created: 20241019150907690
+modified: 20241019150907690
+tags: Commands
+title: EchoCommand
+type: text/vnd.tiddlywiki
+
+{{$:/language/Help/echo}}

editions/tw5.com/tiddlers/nodejs/tiddlywiki.info_Files.tid

@@ -6,12 +6,12 @@ type: text/vnd.tiddlywiki
 
 [[TiddlyWikiFolders]] are configured with a single `tiddlywiki.info` file in the root of the wiki folder. It should contain a JSON object comprising the following properties:
 
-* ''plugins'' - an array of plugin names to be included in the wiki
+* ''plugins'' - optional array of plugin names to be included in the wiki
-* ''themes'' - an array of theme names to be included in the wiki
+* ''themes'' - optional array of theme names to be included in the wiki
-* ''languages'' - an array of language names to be included in the wiki
+* ''languages'' - optional array of language names to be included in the wiki
-* ''includeWikis'' - an array of references to external wiki folders to be included in the wiki
+* ''includeWikis'' - optional array of references to external wiki folders to be included in the wiki
-* ''build'' - a hashmap of named build targets, each defined by an array of command tokens (see BuildCommand)
+* ''build'' - optional hashmap of named build targets, each defined by an array of command tokens (see BuildCommand)
-* ''config'' - an optional hashmap of configuration options (see below)
+* ''config'' - optional hashmap of configuration options (see below)
 
 !!! ''includeWikis''
 
@@ -22,8 +22,45 @@ The entries in the ''includeWikis'' array can be either a string specifying the
 
 !!! ''build''
 
+The ''build'' property contains a hashmap of named build targets. Each of the build targets is defined as an array of command tokens.
+
 Note that the build targets of included wikis are merged if a target of that name isn't defined in the current `tiddlywiki.info` file.
 
+Command tokens can be a simple string or <<.from-version "5.3.6">> a command token object with a ''type'' property. The following types are defined to allow the command token to be dynamically defined:
+
+* ''filter'': the value of the first result of a filter expression specified in the ''text'' property of the command token object
+* ''wikify'': the result of wikifying a text string specified in the ''text'' property of the command token object
+* ''prompt'': the result of prompting the user for a string. The ''prompt'' property of the command token object specifies the textual prompt to be used. The optional ''default'' property specifies a string value to be used if the user presses enter in response to the prompt. The optional ''transformFilter'' property specifies a filter to be applied to the user input to transform it into a command token. The string input by the user is available in the variable `user-input`
+
+The EchoCommand is useful for debugging complex dynamic command tokens.
+
+For example:
+
+```
+"build": {
+	"dynamic": [
+		"--echo","testing",
+		"the following argument is wikified",
+		{
+			"type": "wikify",
+			"text": "<<version>>-prod.html"
+		},
+		"the following argument is a filter result",
+		{
+			"type": "filter",
+			"text": "[<version>!match[5.3.6-prerelease]then[text/html]else[text/plain]]"
+		},
+		"the following argument was provided by the user",
+		{
+			"type": "prompt",
+			"prompt": "Please enter some text and type enter",
+			"default": "Nothing"
+		}
+	],
+...
+```
+
+
 !!! ''config''
 
 Configuration options include:

editions/tw5.com/tiddlywiki.info

@@ -23,6 +23,26 @@
 	"languages": [
 	],
 	"build": {
+		"dynamic-example": [
+			"--echo","testing",
+			"the following argument is wikified",
+			{
+				"type": "wikify",
+				"text": "<<version>>-prod.html"
+			},
+			"the following argument is a filter result",
+			{
+				"type": "filter",
+				"text": "[<version>!match[5.3.6-prerelease]then[text/html]else[text/plain]]"
+			},
+			"the following argument was provided by the user",
+			{
+				"type": "prompt",
+				"prompt": "Please enter some text and type enter",
+				"default": "Nothing",
+				"transformFilter": "[addprefix[testing ]]"
+			}
+		],
 		"index": [
 			"--savetiddlers","[tag[external-image]]","images",
 			"--render","[tag[external-text]]","[encodeuricomponent[]addprefix[text/]addsuffix[.tid]]","text/plain","$:/core/templates/tid-tiddler",