summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--LUA_API.rst16
-rw-r--r--Lua API.html19
-rw-r--r--scripts/devel/prepare-save.lua15
3 files changed, 45 insertions, 5 deletions
diff --git a/LUA_API.rst b/LUA_API.rst
index 252be337..2bb2c949 100644
--- a/LUA_API.rst
+++ b/LUA_API.rst
@@ -1428,7 +1428,7 @@ utils
* ``utils.make_sort_order(data, ordering)``
- Computes an ordering of objects in data, as a table of integer
+ Computes a sorted permutation of objects in data, as a table of integer
indices into the data sequence. Uses ``data.n`` as input length
if present.
@@ -1436,7 +1436,7 @@ utils
as lua tables with following possible fields:
ord.key = *function(value)*
- Computes comparison key from a data value. Not called on nil.
+ Computes comparison key from input data value. Not called on nil.
If omitted, the comparison key is the value itself.
ord.key_table = *function(data)*
Computes a key table from the data table in one go.
@@ -1448,6 +1448,18 @@ utils
ord.reverse = *true/false*
If true, sort non-nil keys in descending order.
+ For every comparison during sorting the specs are applied in
+ order until an unambiguous decision is reached. Sorting is stable.
+
+ Example of sorting a sequence by field foo::
+
+ local spec = { key = function(v) return v.foo end }
+ local order = utils.make_sort_order(data, { spec })
+ local output = {}
+ for i = 1,#order do output[i] = data[order[i]] end
+
+ Separating the actual reordering of the sequence in this
+ way enables applying the same permutation to multiple arrays.
This function is used by the sort plugin.
* ``utils.assign(tgt, src)``
diff --git a/Lua API.html b/Lua API.html
index 0496d7e5..2c9a6a8d 100644
--- a/Lua API.html
+++ b/Lua API.html
@@ -1571,14 +1571,14 @@ Returns <em>nil</em> if any of obj or indices is <em>nil</em>, or a numeric inde
<p>Returns a lua sequence of numbers in start..end.</p>
</li>
<li><p class="first"><tt class="docutils literal">utils.make_sort_order(data, ordering)</tt></p>
-<p>Computes an ordering of objects in data, as a table of integer
+<p>Computes a sorted permutation of objects in data, as a table of integer
indices into the data sequence. Uses <tt class="docutils literal">data.n</tt> as input length
if present.</p>
<p>The ordering argument is a sequence of ordering specs, represented
as lua tables with following possible fields:</p>
<dl class="docutils">
<dt>ord.key = <em>function(value)</em></dt>
-<dd><p class="first last">Computes comparison key from a data value. Not called on nil.
+<dd><p class="first last">Computes comparison key from input data value. Not called on nil.
If omitted, the comparison key is the value itself.</p>
</dd>
<dt>ord.key_table = <em>function(data)</em></dt>
@@ -1595,7 +1595,18 @@ Called on non-nil keys; nil sorts last.</p>
<dd><p class="first last">If true, sort non-nil keys in descending order.</p>
</dd>
</dl>
-<p>This function is used by the sort plugin.</p>
+<p>For every comparison during sorting the specs are applied in
+order until an unambiguous decision is reached. Sorting is stable.</p>
+<p>Example of sorting a sequence by field foo:</p>
+<pre class="literal-block">
+local spec = { key = function(v) return v.foo end }
+local order = utils.make_sort_order(data, { spec })
+local output = {}
+for i = 1,#order do output[i] = data[order[i]] end
+</pre>
+<p>Separating the actual reordering of the sequence in this
+way enables applying the same permutation to multiple arrays.
+This function is used by the sort plugin.</p>
</li>
<li><p class="first"><tt class="docutils literal">utils.assign(tgt, src)</tt></p>
<p>Does a recursive assignment of src into tgt.
@@ -1728,6 +1739,8 @@ calls lua code to perform the actual ordering of list items.</p>
are automatically used by the DFHack core as commands. The
matching command name consists of the name of the file sans
the extension.</p>
+<p>If the first line of the script is a one-line comment, it is
+used by the built-in <tt class="docutils literal">ls</tt> and <tt class="docutils literal">help</tt> commands.</p>
<p><strong>NOTE:</strong> Scripts placed in subdirectories still can be accessed, but
do not clutter the <tt class="docutils literal">ls</tt> command list; thus it is preferred
for obscure developer-oriented scripts and scripts used by tools.
diff --git a/scripts/devel/prepare-save.lua b/scripts/devel/prepare-save.lua
index 781e3b89..c282c8a4 100644
--- a/scripts/devel/prepare-save.lua
+++ b/scripts/devel/prepare-save.lua
@@ -1,7 +1,22 @@
-- Prepare the current save for use with devel/find-offsets.
+local utils = require 'utils'
+
df.global.pause_state = true
+print[[
+WARNING: THIS SCRIPT IS STRICTLY FOR DFHACK DEVELOPERS.
+
+This script prepares the current savegame to be used
+with devel/find-offsets. It CHANGES THE GAME STATE
+to predefined values, and initiates an immediate
+quicksave, thus PERMANENTLY MODIFYING the save.
+]]
+
+if not utils.prompt_yes_no('Proceed?') then
+ return
+end
+
--[[print('Placing anchor...')
do