Add an alternative to script_environment() that requires scripts to

recognize use as a module

Also document the use of enable/disable with lua scripts
develop
lethosor 2015-05-09 09:21:00 -04:00
parent 9ce0616325
commit a47a5f8b0a
3 changed files with 49 additions and 6 deletions

@ -3457,6 +3457,30 @@ Note that this function lets errors propagate to the caller.
This will not be an issue in most cases. This will not be an issue in most cases.
This function also permits circular dependencies of scripts. This function also permits circular dependencies of scripts.
* ``dfhack.reqscript(name)`` or ``reqscript(name)``
Nearly identical to script_environment() but requires scripts being loaded to
include a line similar to::
--@ module = true
This is intended to only allow scripts that take appropriate action when used
as a module to be loaded.
Enabling and disabling scripts
==============================
Scripts can choose to recognize the built-in ``enable`` and ``disable`` commands
by including the following line anywhere in their file::
--@ enable = true
When the ``enable`` and ``disable`` commands are invoked, a ``dfhack_flags``
table will be passed to the script with the following fields set:
* ``enable``: Always true if the script is being enabled *or* disabled
* ``enable_state``: True if the script is being enabled, false otherwise
Save init script Save init script
================ ================

@ -4,6 +4,8 @@ DFHack Future
Developer plugins can be ignored on startup by setting the DFHACK_NO_DEV_PLUGINS environment variable Developer plugins can be ignored on startup by setting the DFHACK_NO_DEV_PLUGINS environment variable
The console on Linux and OS X now recognizes keyboard input between prompts The console on Linux and OS X now recognizes keyboard input between prompts
Lua Lua
Scripts can be enabled with the built-in enable/disable commands
A new function, reqscript(), is available as a safer alternative to script_environment()
New internal commands New internal commands
New plugins New plugins
New scripts New scripts

@ -440,7 +440,14 @@ end
local valid_script_flags = { local valid_script_flags = {
enable = {required = true, error = 'Does not recognize enable/disable commands'}, enable = {required = true, error = 'Does not recognize enable/disable commands'},
enable_state = {required = false}, enable_state = {required = false},
module = {required = true, error = 'Cannot be used as a module'}, module = {
required = function(flags)
if flags.module_strict == false then return false end
return true
end,
error = 'Cannot be used as a module'
},
module_strict = {required = false},
} }
function dfhack.run_script(name,...) function dfhack.run_script(name,...)
@ -455,10 +462,16 @@ function dfhack.enable_script(name, state)
end end
end end
function dfhack.script_environment(name) function dfhack.reqscript(name)
_, env = dfhack.run_script_with_env(nil, name, {module=true}) _, env = dfhack.run_script_with_env(nil, name, {module=true})
return env return env
end end
reqscript = dfhack.reqscript
function dfhack.script_environment(name)
_, env = dfhack.run_script_with_env(nil, name, {module=true, module_strict=false})
return env
end
function dfhack.run_script_with_env(envVars, name, flags, ...) function dfhack.run_script_with_env(envVars, name, flags, ...)
if type(flags) ~= 'table' then flags = {} end if type(flags) ~= 'table' then flags = {} end
@ -473,11 +486,15 @@ function dfhack.run_script_with_env(envVars, name, flags, ...)
local script_flags = scripts[file]:get_flags() local script_flags = scripts[file]:get_flags()
for flag, value in pairs(flags) do for flag, value in pairs(flags) do
if value then if value then
if not valid_script_flags[flag] then local v = valid_script_flags[flag]
if not v then
error('Invalid flag: ' .. flag) error('Invalid flag: ' .. flag)
elseif valid_script_flags[flag].required and not script_flags[flag] then elseif ((type(v.required) == 'boolean' and v.required) or
local msg = valid_script_flags[flag].error or 'Flag "' .. flag .. '" not recognized' (type(v.required) == 'function' and v.required(flags))) then
error(name .. ': ' .. msg) if not script_flags[flag] then
local msg = v.error or 'Flag "' .. flag .. '" not recognized'
error(name .. ': ' .. msg)
end
end end
end end
end end