Merge remote-tracking branch 'upstream/pregmod-master' into pregmod-dev

devNotes/sugarcube stuff/building SugarCube.md

+# Obtaining and building SugarCube for FC
+
+## Intro
+
+This brief how-to guides through patching and building [SugarCube](https://github.com/tmedwards/sugarcube-2)
+for the Free Cities. SugarCube sources can be obtained locally by cloning its Git repository.
+
+Prerequisites (listed NOT in the installation order, please read the list to the end first):
+
+1. [Node.js](https://nodejs.org) with npm.
+2. To build some packages, Node.js requires python and a C/C++ compiler. On Windows you may want to
+install Visual Studio (or just the build tools) and Python 2.7 first. As of now, SugarCube does not
+depend on any of such packages.
+
+Windows: please choose to make the tools accessible from anywhere by allowing installers to modify
+the PATH environment variable.
+
+## Retrieving SugarCube sources and preparing build environment for it
+
+1. Open a terminal window where you want to clone the repository, and run the following command: `git clone https://github.com/tmedwards/sugarcube-2.git`. Change working directory into the cloned repository.
+
+2. The last step we need is downloading required JavaScript libraries that are used during the build.
+Run the node package manager (npm) in the repository: `npm install` or `npm update`
+
+*CAUTION*: dependencies list (located in the package.json file in the repository root) may change from
+commit to commit and it differs between branches! Make sure to install correct dependencies after switching working branch.
+
+## Applying the FC patch
+
+The FreeCities game relies on a few changes to the vanilla SugarCube code. In this repository they are kept as patch files. The SugarCube code changes from version to version that requires modification to the patch file, and therefore there are several of them, named after the highest SugarCube version they applies to. There are at least two different ways to manage the patches/changes, with the first one suitable for occasional users, while the second one works best if you maintain the SugarCube patch for the FC project or just want to keep building for more than a single SugarCube version.
+
+### Single time patching
+
+Find the correct patch in this repo and apply it to the sources:
+`git apply <full path to sugarcube-fc-changes.patch>`
+
+You are ready to build provided no errors were returned by `git apply`
+
+### Maintaining the patch
+
+#### Crating git branch with patched SugarCube sources
+
+For this purpose we will create a git branch with the changes and then update it, [rebasing](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) it on top of the SugarCube master branch when updating is needed.
+
+To start over, create a branch for the patched version (here it will be named "fc") and checkout it: `git checkout -b fc`. Now apply FC changes as in the previous section using `git apply`, but afterwards commit the changes.
+
+*Caveat*: to apply the patch you have to use the version of the SugarCube sources it applies to. If the latest patch does not apply to the current SugarCube master branch, check the `git log` to find the commit id of the SugarCube release you have the patch for. Then branch from that commit: `git branch fc <commit-id>` and checkout the "fc" branch: `git checkout fc`. To update the "fc" branch to the latest SugarCube see below.
+
+#### Updating git branch
+
+To update the branch we will use rebasing. First, fetch changes from the remote SugarCube repo: `git fetch origin`. Check that you are on the "fc" branch (`git checkout fc` if you are not). Now try to rebase your "fc" branch on top of the upstream master branch: `git rebase origin/master`. If that succeeds, the new patched SugarCube sources are ready in the "fc" branch. Proceed to building.
+
+If the rebasing resulted in a conflict, you have to resolve it first. Issue `git rebase --continue` to get the list of files with conflicts, look for conflict markers ('<<<<') in those files, make required changes, do not forget to save the files, and follow advices from `git rebase --continue` until you finally resolve all the conflicts and obtain a new patched sources.
+
+Now you need to update the patch files in the FC repo. First, rename the old patch file: `git mv sugarcube-fc-changes.patch sugarcube-fc-changes-<the last version it applies to>.patch`. Now create an new patch and add it to the repository: `git diff master fc > sugarcube-fc-changes.patch`, copy it to this dir and `git add sugarcube-fc-changes.patch`.
+
+## Building
+
+Run the build.js script. If you use Git bash, you can run the `build.js` file directly, otherwise run
+it as `node build.js`. See `build.js -h` for options, but reasonable sets are the following.
+
+* for release version: `node build.js -6 -b 2`
+* for debug version: `node build.js -6 -b 2 -u -d`
+
+Find result files in the `build` directory. After each build you have to copy `build/twine2/sugarcube-2/format.js` over to this repo and name it accordantly. The last step is to copy the release `format.js` to `devTools/tweeGo/storyFormats/sugarcube-2`. Do not forget to `git add` all three files.
+
+
+## APPENDIX Lists required steps very briefly
+
+1. Clone SugarCube repo: `git clone https://github.com/tmedwards/sugarcube-2.git`
+2. Change active directory into the directory of the sugarcube clone.
+3. Set active branch to "master": git checkout master
+4. Run npm install in the repo dir.
+
+*CAUTION*: Requited dependencies change during the project lifetime and vary from branch to branch;
+you may need to run npm install again after some time, or after branch/tag change. Try to run it in
+case of strange build errors.
+
+The next is done in the directory where SC repo was cloned. Loop over required SugarCube versions:
+
+### Setup:
+
+1. `git reset --hard` to clean any local changes.
+2. `git branch fc v2.30.1` (the tag for the version you have the latest patch for).
+3. `git checkout fc`
+
+### Update loop
+
+1. `git fetch origin`
+2. `git checkout fc`
+3. `git rebase origin/master`
+4. Conflict resolving, `git rebase --continue` and `git add` are needed.
+5. `git diff master fc > sugarcube-fc-changes.patch`; `git add sugarcube-fc-changes.patch`.
+
+### Build
+
+1. `node build.js -6 -b 2` to build release version
+2. `cp build/twine2/sugarcube-2/format.js <whenever you want>`
+3. `node build.js -6 -b 2 -u -d` to build debug version
+4. `cp dist/twine2/sugarcube-2/format.js <whenever you want to place the debug header>`

devNotes/sugarcube stuff/building sugarcube.txt

-This brief how-to guides through patching and building sugarcube (https://github.com/tmedwards/sugarcube-2)
-for the Free Cities. Sugarcube sources can be obtained locally by cloning its Git repository.
-
-Prerequisites (listed NOT in the installation order, please read the list to the end first):
-1. Node.js with npm (https://nodejs.org).
-2. To build some packages, Node.js requires python and a C/C++ compiler. On Windows you may want to
-install Visual Studio (or just the build tools) and Python 2.7 first. As of now, SugarCube does not
-depend on any of such packages.
-
-Windows: please choose to make the tools accessible from anywhere by allowing installers to modify
-the PATH environment variable.
-
-Retrieving SugarCube sources and preparing build environment for it.
-1. Open a terminal window where you want to clone the repository, and run the following command:
-	git clone https://github.com/tmedwards/sugarcube-2.git
-Change working directory into the cloned repository.
-
-2. The last step we need is downloading required JavaScript libraries that are used during the build.
-Run the node package manager (npm) in the repository:
-	npm install
-
-CAUTION: dependencies list (located in the package.json file in the repository root) may change from
-commit to commit and it differs between branches! Make sure to install correct dependencies after switching working branch.
-
-Patching and building SugarCube.
-
-3. Apply the patch:
-	git apply <full path to sugarcube-fc-changes.patch>
-
-Building
-Run the build.js script. If you use Git bash, you can run the build.js file directly, otherwise run
-it as "node build.js". See "build.js -h" for options, but reasonable sets are the following.
-For release version:
-	node ./build.js -b 2
-and for the debug version:
-	node ./build.js -b 2 -u -d
-
-Find result files in the dist directory.
-
-Patching
-create a new patch with
-git diff HEAD > <full path to sugarcube-fc-changes.patch>
-Make sure to stage new files first as otherwise they are lost.
-
-APPENDIX Lists required steps very briefly.
-
-1. Clone Sugarcube repo: git clone https://github.com/tmedwards/sugarcube-2.git
-2. Change active directory into the directory of the sugarcube clone.
-3. Set active branch to "master": git checkout master
-4. Run npm install in the repo dir.
-
-CAUTION: Requited dependencies change during the project lifetime and vary from branch to branch;
-you may need to run npm install again after some time, or after branch/tag change. Try to run it in
-case of strange build errors.
-
-The next is done in the directory where SC repo was cloned. Loop over required SugarCube versions:
-
-1. git reset --hard to clean any local changes
-2. (Optionally) git checkout v2.30.1 (any tag or head here, of course)
-3. git apply <full path to sugarcube-fc-changes.patch>
-4. node build.js -b 2 to build release version
-5. cp dist/twine2/sugarcube-2/format.js <whenever you want>
-6. node build.js -b 2 -u -d to build debug version
-7. cp dist/twine2/sugarcube-2/format.js <whenever you want to place the debug header>
\ No newline at end of file

devNotes/sugarcube stuff/sugarcube-fc-changes.patch

@@ -10,6 +10,34 @@ index bd4421f..1a64744 100644
  			'src/lib/simplestore/adapters/webstorage.js',
  			'src/lib/simplestore/adapters/cookie.js',
  			'src/lib/debugview.js',
+diff --git a/src/lib/helpers.js b/src/lib/helpers.js
+index ff3e30f..7ebbe0a 100644
+--- a/src/lib/helpers.js
++++ b/src/lib/helpers.js
+@@ -308,7 +308,7 @@ var { // eslint-disable-line no-var
+ 	/*
+ 		Appends an error view to the passed DOM element.
+ 	*/
+-	function throwError(place, message, source) {
++	function throwError(place, message, source, stack) {
+ 		const $wrapper = jQuery(document.createElement('div'));
+ 		const $toggle  = jQuery(document.createElement('button'));
+ 		const $source  = jQuery(document.createElement('pre'));
+@@ -346,6 +346,14 @@ var { // eslint-disable-line no-var
+ 				hidden        : 'hidden'
+ 			})
+ 			.appendTo($wrapper);
++		if (stack) {
++			const lines = stack.split('\n');
++			for (const ll of lines) {
++				const div = document.createElement('div');
++				div.append(ll.replace(/file:.*\//, '<path>/'));
++				$source.append(div);
++			}
++		}
+ 		$wrapper
+ 			.addClass('error-view')
+ 			.appendTo(place);
 diff --git a/src/lib/jquery-plugins.js b/src/lib/jquery-plugins.js
 index 792b01f..1811eaf 100644
 --- a/src/lib/jquery-plugins.js
@@ -239,6 +267,52 @@ index 75408a3..00f2c1b 100644
  		}
  	}
  
+diff --git a/src/macros/macrocontext.js b/src/macros/macrocontext.js
+index addd272..8b9758c 100644
+--- a/src/macros/macrocontext.js
++++ b/src/macros/macrocontext.js
+@@ -272,8 +272,8 @@ var MacroContext = (() => { // eslint-disable-line no-unused-vars, no-var
+ 			this._debugViewEnabled = false;
+ 		}
+ 
+-		error(message, source) {
+-			return throwError(this._output, `<<${this.name}>>: ${message}`, source ? source : this.source);
++		error(message, source, stack) {
++			return throwError(this._output, `<<${this.name}>>: ${message}`, source ? source : this.source, stack);
+ 		}
+ 	}
+ 
+diff --git a/src/macros/macrolib.js b/src/macros/macrolib.js
+index 3608880..b5cbf1d 100644
+--- a/src/macros/macrolib.js
++++ b/src/macros/macrolib.js
+@@ -89,7 +89,7 @@
+ 				Scripting.evalJavaScript(this.args.full);
+ 			}
+ 			catch (ex) {
+-				return this.error(`bad evaluation: ${typeof ex === 'object' ? ex.message : ex}`);
++				return this.error(`bad evaluation: ${typeof ex === 'object' ? `${ex.name}: ${ex.message}` : ex}`, null, ex.stack);
+ 			}
+ 
+ 			// Custom debug view setup.
+@@ -347,7 +347,7 @@
+ 				}
+ 			}
+ 			catch (ex) {
+-				return this.error(`bad evaluation: ${typeof ex === 'object' ? ex.message : ex}`);
++				return this.error(`bad evaluation: ${typeof ex === 'object' ? `${ex.name}: ${ex.message}` : ex}`, null, ex.stack);
+ 			}
+ 		}
+ 	});
+@@ -487,7 +487,7 @@
+ 				}
+ 			}
+ 			catch (ex) {
+-				return this.error(`bad conditional expression in <<${i === 0 ? 'if' : 'elseif'}>> clause${i > 0 ? ' (#' + i + ')' : ''}: ${typeof ex === 'object' ? ex.message : ex}`); // eslint-disable-line prefer-template
++				return this.error(`bad conditional expression in <<${i === 0 ? 'if' : 'elseif'}>> clause${i > 0 ? ' (#' + i + ')' : ''}: ${typeof ex === 'object' ? `${ex.name}: ${ex.message}` : ex}`, null, ex.stack); // eslint-disable-line prefer-template
+ 			}
+ 		}
+ 	});
 diff --git a/src/markup/wikifier.js b/src/markup/wikifier.js
 index bc8b018..df7285c 100644
 --- a/src/markup/wikifier.js
@@ -270,15 +344,10 @@ index aa5c2f2..15d4221 100644
  			return frag;
  		}
 diff --git a/src/state.js b/src/state.js
-index 5ce7c55..f91c29f 100644
+index 5ce7c55..3ae79be 100644
 --- a/src/state.js
 +++ b/src/state.js
-@@ -100,11 +100,11 @@ var State = (() => { // eslint-disable-line no-unused-vars, no-var
- 			stateObj.history = clone(_history);
- 		}
- 		else {
--			stateObj.delta = historyDeltaEncode(_history);
-+			stateObj.delta = Config.history.maxStates === 1 ? _history : historyDeltaEncode(_history);
+@@ -104,7 +104,7 @@ var State = (() => { // eslint-disable-line no-unused-vars, no-var
  		}
  
  		if (_expired.length > 0) {
@@ -287,89 +356,6 @@ index 5ce7c55..f91c29f 100644
  		}
  
  		if (_prng !== null) {
-@@ -272,7 +272,7 @@ var State = (() => { // eslint-disable-line no-unused-vars, no-var
- 		*/
- 		switch (typeof moment) {
- 		case 'object':
--			_active = clone(moment);
-+			_active = Config.history.maxStates === 1 ? moment : clone(moment);
- 			break;
- 
- 		case 'number':
-@@ -284,7 +284,7 @@ var State = (() => { // eslint-disable-line no-unused-vars, no-var
- 				throw new RangeError(`moment activation attempted with out-of-bounds index; need [0, ${historySize() - 1}], got ${moment}`);
- 			}
- 
--			_active = clone(_history[moment]);
-+			_active = Config.history.maxStates === 1 ? _history[moment] : clone(_history[moment]);
- 			break;
- 
- 		default:
-@@ -424,35 +424,41 @@ var State = (() => { // eslint-disable-line no-unused-vars, no-var
- 	function historyCreate(title) {
- 		if (DEBUG) { console.log(`[State/historyCreate(title: "${title}")]`); }
- 
--		/*
--			TODO: It might be good to have some assertions about the passage title here.
--		*/
-+		if (Config.history.maxStates === 1 && historySize() === 1) {
-+			// we just replace the title
-+			_history[0].title = title;
-+		}
-+		else {
-+			/*
-+				TODO: It might be good to have some assertions about the passage title here.
-+			*/
- 
--		/*
--			If we're not at the top of the stack, discard the future moments.
--		*/
--		if (historyLength() < historySize()) {
--			if (DEBUG) { console.log(`\tnon-top push; discarding ${historySize() - historyLength()} future moments`); }
-+			/*
-+				If we're not at the top of the stack, discard the future moments.
-+			*/
-+			if (historyLength() < historySize()) {
-+				if (DEBUG) { console.log(`\tnon-top push; discarding ${historySize() - historyLength()} future moments`); }
- 
--			_history.splice(historyLength(), historySize() - historyLength());
--		}
-+				_history.splice(historyLength(), historySize() - historyLength());
-+			}
- 
--		/*
--			Push the new moment onto the history stack.
--		*/
--		_history.push(momentCreate(title, _active.variables));
-+			/*
-+				Push the new moment onto the history stack.
-+			*/
-+			_history.push(momentCreate(title, _active.variables));
- 
--		if (_prng) {
--			historyTop().pull = _prng.pull;
-+			/*
-+				Truncate the history, if necessary, by discarding moments from the bottom.
-+			*/
-+			if (Config.history.maxStates > 0) {
-+				while (historySize() > Config.history.maxStates) {
-+					_expired.push(_history.shift().title);
-+				}
-+			}
- 		}
- 
--		/*
--			Truncate the history, if necessary, by discarding moments from the bottom.
--		*/
--		if (Config.history.maxStates > 0) {
--			while (historySize() > Config.history.maxStates) {
--				_expired.push(_history.shift().title);
--			}
-+		if (_prng) {
-+			historyTop().pull = _prng.pull;
- 		}
- 
- 		/*
 diff --git a/src/ui.js b/src/ui.js
 index 44fb8fa..fecf8e8 100644
 --- a/src/ui.js