diff options
| author | Alexander Gavrilov | 2012-06-30 16:25:41 +0400 |
|---|---|---|
| committer | Alexander Gavrilov | 2012-06-30 16:25:41 +0400 |
| commit | 07dc20055a599811b6ae517467d6a75392e47a60 (patch) | |
| tree | 4a714f17c3a8a02daffe75bb760309b36faa3349 | |
| parent | bd5aea994b31341c6d6568fa578407fb5ea00f30 (diff) | |
| download | dfhack-07dc20055a599811b6ae517467d6a75392e47a60.tar.gz dfhack-07dc20055a599811b6ae517467d6a75392e47a60.tar.bz2 dfhack-07dc20055a599811b6ae517467d6a75392e47a60.tar.xz | |
Tweak documentation for utils.make_sort_order and devel/prepare-save
| -rw-r--r-- | LUA_API.rst | 16 | ||||
| -rw-r--r-- | Lua API.html | 19 | ||||
| -rw-r--r-- | scripts/devel/prepare-save.lua | 15 |
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 |
