From a77353b2e6beca48e6b0a296fc92462b491d7763 Mon Sep 17 00:00:00 2001 From: Gabe Rau Date: Wed, 17 Mar 2021 23:17:01 -0600 Subject: [PATCH 1/5] Update Lua API.rst Corrected the dfhack.run_script documentation and added an example. --- docs/Lua API.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/Lua API.rst b/docs/Lua API.rst index 3eb053e73..a2d9c4979 100644 --- a/docs/Lua API.rst +++ b/docs/Lua API.rst @@ -4079,10 +4079,11 @@ DFHack core invokes the scripts in the *core context* (see above); however it is possible to call them from any lua code (including from other scripts) in any context, via the same function the core uses: -* ``dfhack.run_script(name[,args...])`` - +* ``dfhack.run_script("name arg1 arg2 arg3")`` + Run a lua script in hack/scripts/, as if it was started from dfhack command-line. - The ``name`` argument should be the name stem, as would be used on the command line. + The argument should be the exact command that would be written to the command line. + For example: dfhack.run_command("createitem WEAPON:ITEM_WEAPON_PICK COPPER 9999") Note that this function lets errors propagate to the caller. From 5aa3c6bfc6232e9bae57d4d957785c68d143bd91 Mon Sep 17 00:00:00 2001 From: Gabe Rau Date: Fri, 19 Mar 2021 21:58:24 -0600 Subject: [PATCH 2/5] Revised Lua API.rst to better explain command. Added proper examples and explantion of difference between run_command and run_script. --- docs/Lua API.rst | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/Lua API.rst b/docs/Lua API.rst index a2d9c4979..92d80f3c5 100644 --- a/docs/Lua API.rst +++ b/docs/Lua API.rst @@ -4079,11 +4079,22 @@ DFHack core invokes the scripts in the *core context* (see above); however it is possible to call them from any lua code (including from other scripts) in any context, via the same function the core uses: -* ``dfhack.run_script("name arg1 arg2 arg3")`` +* ``dfhack.run_script(command[, ...])`` Run a lua script in hack/scripts/, as if it was started from dfhack command-line. - The argument should be the exact command that would be written to the command line. - For example: dfhack.run_command("createitem WEAPON:ITEM_WEAPON_PICK COPPER 9999") + The syntax for the argument is similar to dfhack.run_command. + The command can be passed as a table, multiple string + arguments, or a single string argument (not recommended - in this case, the + usual DFHack console tokenization is used). + The following examples are equivalent:: + dfhack.run_script({'ls', '-a'}) + dfhack.run_script('ls', '-a') + dfhack.run_script('ls -a') -- not recommended + + Unlike ``dfhack.run_command``, ``dfhack.run_script`` is capable of taking the + return value of a lua script as an argument. + For example:: + dfhack.run_scipt("process", dfhack.gui.getDwarfmodeViewDims()); Note that this function lets errors propagate to the caller. From 374fc763ebd000123ccfc0070929668a06fc4fb7 Mon Sep 17 00:00:00 2001 From: Gabe Rau Date: Sat, 20 Mar 2021 01:55:45 -0600 Subject: [PATCH 3/5] Fixed whitespace issues that cause a failed build on lint. --- docs/Lua API.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/Lua API.rst b/docs/Lua API.rst index 0ae3e8192..7f2a35b56 100644 --- a/docs/Lua API.rst +++ b/docs/Lua API.rst @@ -4418,20 +4418,20 @@ General script API Example:: dfhack.run_script("armoks-blessing", "all") Scipts that use a dash(``-``) in their arguments still require one when called - from ``dfhack.run_script``. + from ``dfhack.run_script``. Example:: dfhack.run_script("gaydar", "-all") - - Unlike ``dfhack.run_command``, ``dfhack.run_script`` allows a different - different script to be executed and its value passed as an argument to the main + + Unlike ``dfhack.run_command``, ``dfhack.run_script`` allows a different + different script to be executed and its value passed as an argument to the main function called by ``dfhack.run_script``. - + Example:: dfhack.run_script("some_script", dfhack.gui.getDwarfmodeViewDims()); - + While this implmenation is currently a functional, its purpose and stability are limited. As such, ``dfhack.reqscript(name)`` should be used. - + Note that the ``dfhack.run_script()`` function allows Lua errors propagate to the caller. To run other types of commands (such as built-in commands, plugin commands, or From cc376eeb55181e7c88b8dc00d8605cdcfb7c881d Mon Sep 17 00:00:00 2001 From: Gabe Rau Date: Sat, 20 Mar 2021 15:49:53 -0600 Subject: [PATCH 4/5] Fixed a number of spelling and grammatical errors. Should be set now. Added better examples and removed redundant words. --- docs/Lua API.rst | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/docs/Lua API.rst b/docs/Lua API.rst index 7f2a35b56..2789889ad 100644 --- a/docs/Lua API.rst +++ b/docs/Lua API.rst @@ -4415,29 +4415,22 @@ General script API command-line. The ``name`` argument should be the name of the script without its extension, as would be used on the command line. - Example:: - dfhack.run_script("armoks-blessing", "all") - Scipts that use a dash(``-``) in their arguments still require one when called - from ``dfhack.run_script``. - Example:: - dfhack.run_script("gaydar", "-all") + Example: - Unlike ``dfhack.run_command``, ``dfhack.run_script`` allows a different - different script to be executed and its value passed as an argument to the main - function called by ``dfhack.run_script``. + In DFHack prompt:: - Example:: - dfhack.run_script("some_script", dfhack.gui.getDwarfmodeViewDims()); + repeat -time 14 -timeUnits days -command [ workorder ShearCreature ] -name autoShearCreature - While this implmenation is currently a functional, its purpose and stability - are limited. As such, ``dfhack.reqscript(name)`` should be used. + In lua script:: - Note that the ``dfhack.run_script()`` function allows Lua errors propagate to the caller. + dfhack.run_script("repeat", "-time", "14", "-timeUnits", "days", "-command", "[", "workorder", "ShearCreature", "]", "-name", "autoShearCreature") + + Note that the ``dfhack.run_script()`` function allows Lua errors to propagate to the caller. To run other types of commands (such as built-in commands, plugin commands, or Ruby scripts), see ``dfhack.run_command()``. Note that this is slightly slower than ``dfhack.run_script()`` for Lua scripts. - + * ``dfhack.script_help([name, [extension]])`` Returns the contents of the embedded documentation of the specified script. From 81b6d93701d137f6319687b7b84394fd83f07110 Mon Sep 17 00:00:00 2001 From: Gabe Rau Date: Sat, 20 Mar 2021 15:51:35 -0600 Subject: [PATCH 5/5] Minor grammer fixes. --- docs/Lua API.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/Lua API.rst b/docs/Lua API.rst index 2789889ad..1278711b5 100644 --- a/docs/Lua API.rst +++ b/docs/Lua API.rst @@ -4411,9 +4411,9 @@ General script API * ``dfhack.run_script(name[,args...])`` - Run a Lua script in hack/scripts/, as if it was started from the DFHack + Run a Lua script in hack/scripts/, as if it were started from the DFHack command-line. The ``name`` argument should be the name of the script without - its extension, as would be used on the command line. + its extension, as it would be used on the command line. Example: @@ -4421,7 +4421,7 @@ General script API repeat -time 14 -timeUnits days -command [ workorder ShearCreature ] -name autoShearCreature - In lua script:: + In Lua script:: dfhack.run_script("repeat", "-time", "14", "-timeUnits", "days", "-command", "[", "workorder", "ShearCreature", "]", "-name", "autoShearCreature")