From 35a7a66b019f2ea0532ba65cd5475f5cfe46a860 Mon Sep 17 00:00:00 2001
From: Jermolene <jeremy@jermolene.com>
Date: Tue, 12 Sep 2017 16:04:07 +0100
Subject: [PATCH] Add "save" and "render" commands

A first pass at fixing #2973 - comments are welcome. If everybody is
happy, the next step is to deprecate the existing
rendertiddler(s)/savetiddler(s) commands and replace them in all
examples and tiddlywiki.info files with the new equivalents.
---
 core/language/en-GB/Help/render.tid         | 34 +++++++++++
 core/language/en-GB/Help/rendertiddler.tid  |  2 +
 core/language/en-GB/Help/rendertiddlers.tid |  2 +
 core/language/en-GB/Help/save.tid           | 25 ++++++++
 core/language/en-GB/Help/savetiddler.tid    |  2 +
 core/language/en-GB/Help/savetiddlers.tid   |  2 +
 core/modules/commands/render.js             | 65 +++++++++++++++++++++
 core/modules/commands/save.js               | 53 +++++++++++++++++
 8 files changed, 185 insertions(+)
 create mode 100644 core/language/en-GB/Help/render.tid
 create mode 100644 core/language/en-GB/Help/save.tid
 create mode 100644 core/modules/commands/render.js
 create mode 100644 core/modules/commands/save.js

diff --git a/core/language/en-GB/Help/render.tid b/core/language/en-GB/Help/render.tid
new file mode 100644
index 000000000..36d959b79
--- /dev/null
+++ b/core/language/en-GB/Help/render.tid
@@ -0,0 +1,34 @@
+title: $:/language/Help/render
+description: Renders individual tiddlers to files
+
+Render individual tiddlers and save the results to the specified files.
+
+Optionally the title of a template tiddler can be specified, in which case the template tiddler is rendered with the "currentTiddler" variable set to the title of the tiddler that is being rendered.
+
+A name and value for an additional variable may optionally also be specified.
+
+```
+--render <tiddler-filter> [<filename-filter>] [<render-type>] [<template>] [<name>] [<value>]
+```
+
+* ''tiddler-filter'': A filter identifying the tiddler(s) to be rendered
+* ''filename-filter'': Optional filter transforming tiddler titles into pathnames. If omitted, defaults to `[is[tiddler]addsuffix[.html]]`, which uses the unchanged tiddler title as the filename
+* ''template'': Optional template through which each tiddler is rendered
+* ''render-type'': Optional render type: `text/html` (the default) returns the full HTML text and `text/plain` just returns the text content (ie it ignores HTML tags and other unprintable material)
+* ''name'': Name of optional variable
+* ''value'': Value of optional variable
+
+By default, the filename is resolved relative to the `output` subdirectory of the edition directory. The `--output` command can be used to direct output to a different directory.
+
+Notes:
+
+* The output directory is not cleared of any existing files
+* Any missing directories in the path to the filename are automatically created.
+* When referring to a tiddler with spaces in its title, take care to use both the quotes required by your shell and also TiddlyWiki's double square brackets : `--render "[[Motovun Jack.jpg]]"`
+* The filename filter is evaluated with the selected items being set to the title of the tiddler currently being rendered, allowing the title to be used as the basis for computing the filename. For example `[encodeuricomponent[]addprefix[static/]]` applies URI encoding to each title, and then adds the prefix `static/`
+* The `--render` command is a more flexible replacement for both the `--rendertiddler` and `--rendertiddlers` commands, which are deprecated
+
+Examples:
+
+* `--render "[!is[system]]" "[encodeuricomponent[]addprefix[tiddlers/]addsuffix[.html]]"` -- renders all non-system tiddlers as files in the subdirectory "tiddlers" with URL-encoded titles and the extension HTML
+
diff --git a/core/language/en-GB/Help/rendertiddler.tid b/core/language/en-GB/Help/rendertiddler.tid
index f4508fb5e..96ddda1bf 100644
--- a/core/language/en-GB/Help/rendertiddler.tid
+++ b/core/language/en-GB/Help/rendertiddler.tid
@@ -1,6 +1,8 @@
 title: $:/language/Help/rendertiddler
 description: Render an individual tiddler as a specified ContentType
 
+(Note: The `--rendertiddler` command is deprecated in favour of the new, more flexible `--render` command)
+
 Render an individual tiddler as a specified ContentType, defaulting to `text/html` and save it to the specified filename.
 
 Optionally the title of a template tiddler can be specified, in which case the template tiddler is rendered with the "currentTiddler" variable set to the tiddler that is being rendered (the first parameter value).
diff --git a/core/language/en-GB/Help/rendertiddlers.tid b/core/language/en-GB/Help/rendertiddlers.tid
index 69f4e0a38..a0e76d147 100644
--- a/core/language/en-GB/Help/rendertiddlers.tid
+++ b/core/language/en-GB/Help/rendertiddlers.tid
@@ -1,6 +1,8 @@
 title: $:/language/Help/rendertiddlers
 description: Render tiddlers matching a filter to a specified ContentType
 
+(Note: The `--rendertiddlers` command is deprecated in favour of the new, more flexible `--render` command)
+
 Render a set of tiddlers matching a filter to separate files of a specified ContentType (defaults to `text/html`) and extension (defaults to `.html`).
 
 ```
diff --git a/core/language/en-GB/Help/save.tid b/core/language/en-GB/Help/save.tid
new file mode 100644
index 000000000..153d933ea
--- /dev/null
+++ b/core/language/en-GB/Help/save.tid
@@ -0,0 +1,25 @@
+title: $:/language/Help/save
+description: Saves individual raw tiddlers to files
+
+Saves individual tiddlers in their raw text or binary format to the specified files.
+
+```
+--save <tiddler-filter> <filename-filter>
+```
+
+* ''tiddler-filter'': A filter identifying the tiddler(s) to be saved
+* ''filename-filter'': Optional filter transforming tiddler titles into pathnames. If omitted, defaults to `[is[tiddler]]`, which uses the unchanged tiddler title as the filename
+
+By default, the filename is resolved relative to the `output` subdirectory of the edition directory. The `--output` command can be used to direct output to a different directory.
+
+Notes:
+
+* The output directory is not cleared of any existing files
+* Any missing directories in the path to the filename are automatically created.
+* When saving a tiddler with spaces in its title, take care to use both the quotes required by your shell and also TiddlyWiki's double square brackets : `--save "[[Motovun Jack.jpg]]"`
+* The filename filter is evaluated with the selected items being set to the title of the tiddler currently being saved, allowing the title to be used as the basis for computing the filename. For example `[encodeuricomponent[]addprefix[static/]]` applies URI encoding to each title, and then adds the prefix `static/`
+* The `--save` command is a more flexible replacement for both the `--savetiddler` and `--savetiddlers` commands, which are deprecated
+
+Examples:
+
+* `--save "[!is[system]is[image]]" "[encodeuricomponent[]addprefix[tiddlers/]]"` -- saves all non-system image tiddlers as files in the subdirectory "tiddlers" with URL-encoded titles
diff --git a/core/language/en-GB/Help/savetiddler.tid b/core/language/en-GB/Help/savetiddler.tid
index 643d318fd..c3d820d9a 100644
--- a/core/language/en-GB/Help/savetiddler.tid
+++ b/core/language/en-GB/Help/savetiddler.tid
@@ -1,6 +1,8 @@
 title: $:/language/Help/savetiddler
 description: Saves a raw tiddler to a file
 
+(Note: The `--savetiddler` command is deprecated in favour of the new, more flexible `--save` command)
+
 Saves an individual tiddler in its raw text or binary format to the specified filename.
 
 ```
diff --git a/core/language/en-GB/Help/savetiddlers.tid b/core/language/en-GB/Help/savetiddlers.tid
index 8cac2a950..35330c498 100644
--- a/core/language/en-GB/Help/savetiddlers.tid
+++ b/core/language/en-GB/Help/savetiddlers.tid
@@ -1,6 +1,8 @@
 title: $:/language/Help/savetiddlers
 description: Saves a group of raw tiddlers to a directory
 
+(Note: The `--savetiddlers` command is deprecated in favour of the new, more flexible `--save` command)
+
 Saves a group of tiddlers in their raw text or binary format to the specified directory.
 
 ```
diff --git a/core/modules/commands/render.js b/core/modules/commands/render.js
new file mode 100644
index 000000000..e9321c2b0
--- /dev/null
+++ b/core/modules/commands/render.js
@@ -0,0 +1,65 @@
+/*\
+title: $:/core/modules/commands/render.js
+type: application/javascript
+module-type: command
+
+Render individual tiddlers and save the results to the specified files
+
+\*/
+(function(){
+
+/*jslint node: true, browser: true */
+/*global $tw: false */
+"use strict";
+
+var widget = require("$:/core/modules/widgets/widget.js");
+
+exports.info = {
+	name: "render",
+	synchronous: true
+};
+
+var Command = function(params,commander,callback) {
+	this.params = params;
+	this.commander = commander;
+	this.callback = callback;
+};
+
+Command.prototype.execute = function() {
+	if(this.params.length < 1) {
+		return "Missing tiddler filter";
+	}
+	var self = this,
+		fs = require("fs"),
+		path = require("path"),
+		wiki = this.commander.wiki,
+		tiddlerFilter = this.params[0],
+		filenameFilter = this.params[1] || "[is[tiddler]addsuffix[.html]]",
+		type = this.params[2] || "text/html",
+		template = this.params[3],
+		varName = this.params[4],
+		varValue = this.params[5],
+		tiddlers = wiki.filterTiddlers(tiddlerFilter);
+	$tw.utils.each(tiddlers,function(title) {
+		var parser = wiki.parseTiddler(template || title),
+			variables = {currentTiddler: title};
+		if(varName) {
+			variables[varName] = varValue || "";
+		}
+		var widgetNode = wiki.makeWidget(parser,{variables: variables}),
+			container = $tw.fakeDocument.createElement("div");
+		widgetNode.render(container,null);
+		var text = type === "text/html" ? container.innerHTML : container.textContent,
+			filepath = path.resolve(self.commander.outputPath,wiki.filterTiddlers(filenameFilter,$tw.rootWidget,wiki.makeTiddlerIterator([title]))[0]);
+		if(self.commander.verbose) {
+			console.log("Rendering \"" + title + "\" to \"" + filepath + "\"");
+		}
+		$tw.utils.createFileDirectories(filepath);
+		fs.writeFileSync(filepath,text,"utf8");
+	});
+	return null;
+};
+
+exports.Command = Command;
+
+})();
diff --git a/core/modules/commands/save.js b/core/modules/commands/save.js
new file mode 100644
index 000000000..d8c44e1f3
--- /dev/null
+++ b/core/modules/commands/save.js
@@ -0,0 +1,53 @@
+/*\
+title: $:/core/modules/commands/save.js
+type: application/javascript
+module-type: command
+
+Saves individual tiddlers in their raw text or binary format to the specified files
+
+\*/
+(function(){
+
+/*jslint node: true, browser: true */
+/*global $tw: false */
+"use strict";
+
+exports.info = {
+	name: "save",
+	synchronous: true
+};
+
+var Command = function(params,commander,callback) {
+	this.params = params;
+	this.commander = commander;
+	this.callback = callback;
+};
+
+Command.prototype.execute = function() {
+	if(this.params.length < 1) {
+		return "Missing filename filter";
+	}
+	var self = this,
+		fs = require("fs"),
+		path = require("path"),
+		wiki = this.commander.wiki,
+		tiddlerFilter = this.params[0],
+		filenameFilter = this.params[1] || "[is[tiddler]]",
+		tiddlers = wiki.filterTiddlers(tiddlerFilter);
+	$tw.utils.each(tiddlers,function(title) {
+		var tiddler = self.commander.wiki.getTiddler(title),
+			type = tiddler.fields.type || "text/vnd.tiddlywiki",
+			contentTypeInfo = $tw.config.contentTypeInfo[type] || {encoding: "utf8"},
+			filepath = path.resolve(self.commander.outputPath,wiki.filterTiddlers(filenameFilter,$tw.rootWidget,wiki.makeTiddlerIterator([title]))[0]);
+		if(self.commander.verbose) {
+			console.log("Saving \"" + title + "\" to \"" + filepath + "\"");
+		}
+		$tw.utils.createFileDirectories(filepath);
+		fs.writeFileSync(filepath,tiddler.fields.text,contentTypeInfo.encoding);
+	});
+	return null;
+};
+
+exports.Command = Command;
+
+})();