forked from DFHack/dfhack
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathdfhack.lua
More file actions
1230 lines (1096 loc) · 33.2 KB
/
dfhack.lua
File metadata and controls
1230 lines (1096 loc) · 33.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
-- Common startup file for all dfhack scripts and plugins with lua support
-- The global dfhack table is already created by C++ init code.
-- Setup the global environment.
-- BASE_G is the original lua global environment,
-- preserved as a common denominator for all modules.
-- This file uses it instead of the new default one.
---@class dfhack
---@field BASE_G _G Original Lua global environment
---@field is_core_context boolean
---@field is_interactive fun(): boolean
local dfhack = dfhack
local base_env = dfhack.BASE_G
local _ENV = base_env
-- Types
---@alias dfhack.truthy
---| true
---| integer
---| string
---| table
---| function
---| userdata
---| fun(...): true|string|integer|table|function|userdata
CR_LINK_FAILURE = -3
CR_NEEDS_CONSOLE = -2
CR_NOT_IMPLEMENTED = -1
CR_OK = 0
CR_FAILURE = 1
CR_WRONG_USAGE = 2
CR_NOT_FOUND = 3
-- Console color constants
COLOR_RESET = -1
COLOR_BLACK = 0
COLOR_BLUE = 1
COLOR_GREEN = 2
COLOR_CYAN = 3
COLOR_RED = 4
COLOR_MAGENTA = 5
COLOR_BROWN = 6
COLOR_GREY = 7
COLOR_DARKGREY = 8
COLOR_LIGHTBLUE = 9
COLOR_LIGHTGREEN = 10
COLOR_LIGHTCYAN = 11
COLOR_LIGHTRED = 12
COLOR_LIGHTMAGENTA = 13
COLOR_YELLOW = 14
COLOR_WHITE = 15
COLOR_GRAY = COLOR_GREY
COLOR_DARKGRAY = COLOR_DARKGREY
---@alias dfhack.color
---| `COLOR_RESET`
---| `COLOR_BLACK`
---| `COLOR_BLUE`
---| `COLOR_GREEN`
---| `COLOR_CYAN`
---| `COLOR_RED`
---| `COLOR_MAGENTA`
---| `COLOR_BROWN`
---| `COLOR_GREY`
---| `COLOR_DARKGREY`
---| `COLOR_LIGHTBLUE`
---| `COLOR_LIGHTGREEN`
---| `COLOR_LIGHTCYAN`
---| `COLOR_LIGHTRED`
---| `COLOR_LIGHTMAGENTA`
---| `COLOR_YELLOW`
---| `COLOR_WHITE`
---| `COLOR_GRAY`
---| `COLOR_DARKGRAY`
-- Events
if dfhack.is_core_context then
SC_WORLD_LOADED = 0
SC_WORLD_UNLOADED = 1
SC_MAP_LOADED = 2
SC_MAP_UNLOADED = 3
SC_VIEWSCREEN_CHANGED = 4
SC_CORE_INITIALIZED = 5
SC_PAUSED = 7
SC_UNPAUSED = 8
end
-- User-changeable options
local HIDE_CONSOLE_ON_STARTUP = true
---@nodiscard
---@return boolean
function dfhack.getHideConsoleOnStartup()
return HIDE_CONSOLE_ON_STARTUP
end
function dfhack.setHideConsoleOnStartup(value)
HIDE_CONSOLE_ON_STARTUP = value
end
local HIDE_ARMOK_TOOLS = false
---@nodiscard
---@return boolean
function dfhack.getMortalMode()
return HIDE_ARMOK_TOOLS
end
function dfhack.setMortalMode(value)
HIDE_ARMOK_TOOLS = value
dfhack.internal.setMortalMode(value)
end
-- Error handling
safecall = dfhack.safecall
curry = dfhack.curry
---@generic T
---@param f fun(...): T
---@param ... any
---@return boolean success
---@return T|string ...
function dfhack.pcall(f, ...)
return xpcall(f, dfhack.onerror, ...)
end
---@param msg string
---@param level? integer
function qerror(msg, level)
local name = dfhack.current_script_name()
if name and not tostring(msg):match(name) then
msg = name .. ': ' .. tostring(msg)
end
dfhack.error(msg, (level or 1) + 1, false)
end
---@generic T
---@param cleanup_fn function
---@param fn fun(...): T
---@param ... any
---@return T
function dfhack.with_finalize(cleanup_fn,fn,...)
return dfhack.call_with_finalizer(0,true,cleanup_fn,fn,...)
end
---@generic T
---@param cleanup_fn function
---@param fn fun(...): T
---@param ... any
---@return T
function dfhack.with_onerror(cleanup_fn,fn,...)
return dfhack.call_with_finalizer(0,false,cleanup_fn,fn,...)
end
---@param obj DFObject
local function call_delete(obj)
if obj then obj:delete() end
end
---@generic T
---@param obj DFObject
---@param fn fun(...):T
---@param ... any
---@return T ...
function dfhack.with_temp_object(obj,fn,...)
return dfhack.call_with_finalizer(1,true,call_delete,obj,fn,obj,...)
end
dfhack.exception.__index = dfhack.exception
-- Module loading
local function find_required_module_arg()
-- require -> module code -> mkmodule -> find_...
if debug.getinfo(4,'f').func == require then
return debug.getlocal(4, 1)
end
-- reload -> dofile -> module code -> mkmodule -> find_...
if debug.getinfo(5,'f').func == reload then
return debug.getlocal(5, 1)
end
end
---@nodiscard
---@param module string
---@param env? table|metatable
---@return _G pkg
function mkmodule(module,env)
-- Verify that the module name is correct
local _, rq_modname = find_required_module_arg()
if not rq_modname then
error('The mkmodule function must be used at the start of a module')
end
if rq_modname ~= module then
error('Found module '..module..' during require '..rq_modname)
end
-- Reuse the already loaded module table
local pkg = package.loaded[module]
if pkg == nil then
pkg = {}
else
if type(pkg) ~= 'table' then
error("Not a table in package.loaded["..module.."]")
end
end
-- Inject the plugin-exported functions when appropriate
local plugname = string.match(module,'^plugins%.([%w%-]+)$')
if plugname then
dfhack.open_plugin(pkg,plugname)
end
setmetatable(pkg, { __index = (env or base_env) })
return pkg
end
---@param module string
function reload(module)
if type(package.loaded[module]) ~= 'table' then
error("Module not loaded: "..module)
end
local path,err = package.searchpath(module,package.path)
if not path then
error(err)
end
dofile(path)
end
-- Trivial classes
function rawset_default(target,source)
for k,v in pairs(source) do
if rawget(target,k) == nil then
rawset(target,k,v)
end
end
end
---@type any
DEFAULT_NIL = DEFAULT_NIL or {} -- Unique token
-- Create or updates a class; a class has metamethods and thus own metatable.
---@nodiscard
---@generic T: dfhack.class
---@param class? T
---@param parent? table
---@return T
function defclass(class,parent)
return require('class').defclass(class,parent)
end
-- An instance uses the class as metatable
---@generic T: dfhack.class
---@param class T
---@param table? table
---@return T
function mkinstance(class,table)
return require('class').mkinstance(class,table)
end
-- Misc functions
NEWLINE = "\n"
COMMA = ","
PERIOD = "."
local function _wrap_iterator(next_fn, ...)
local wrapped_iter = function(...)
local ret = {pcall(next_fn, ...)}
local ok = table.remove(ret, 1)
if ok then
return table.unpack(ret)
end
end
return wrapped_iter, ...
end
function safe_pairs(t, iterator_fn)
iterator_fn = iterator_fn or pairs
if (pcall(iterator_fn, t)) then
return _wrap_iterator(iterator_fn(t))
else
return function() end
end
end
-- calls elem_cb(k, v) for each element of the table
-- returns true if we iterated successfully, false if not
-- this differs from safe_pairs() above in that it only calls pcall() once per
-- full iteration and it returns whether iteration succeeded or failed.
local function safe_iterate(table, iterator_fn, elem_cb)
local function iterate()
for k,v in iterator_fn(table) do elem_cb(k, v) end
end
return pcall(iterate)
end
local function print_element(k, v)
dfhack.println(string.format("%-23s\t = %s", tostring(k), tostring(v)))
end
---@param table table
function printall(table)
safe_iterate(table, pairs, print_element)
end
---@param table table
function printall_ipairs(table)
safe_iterate(table, ipairs, print_element)
end
local do_print_recurse
local function print_string(printfn, v, seen, indent)
local str = tostring(v)
printfn(str)
return #str;
end
local fill_chars = {
__index = function(table, key, value)
local rv = string.rep(' ', 23 - key) .. ' = '
rawset(table, key, rv)
return rv
end,
}
setmetatable(fill_chars, fill_chars)
local function print_fields(value, seen, indent, prefix)
local prev_value = "not a value"
local repeated = 0
local print_field = function(k, v)
-- Only show set values of bitfields
if value._kind ~= "bitfield" or v then
local continue = false
if type(k) == "number" then
if prev_value == v then
repeated = repeated + 1
continue = true
else
prev_value = v
end
else
prev_value = "not a value"
end
if not continue then
if repeated > 0 then
dfhack.println(prefix .. "<Repeated " .. repeated .. " times>")
repeated = 0
end
dfhack.print(prefix)
local len = do_print_recurse(dfhack.print, k, seen, indent + 1)
dfhack.print(fill_chars[len <= 23 and len or 23])
do_print_recurse(dfhack.println, v, seen, indent + 1)
end
end
end
if not safe_iterate(value, pairs, print_field) then
dfhack.print(prefix)
dfhack.println('<Type doesn\'t support iteration with pairs>')
elseif repeated > 0 then
dfhack.println(prefix .. "<Repeated " .. repeated .. " times>")
end
return 0
end
-- This should be same as print_array but userdata doesn't compare equal even if
-- they hold same pointer.
local function print_userdata(printfn, value, seen, indent)
local prefix = string.rep(' ', indent)
local strvalue = tostring(value)
dfhack.println(strvalue)
if seen[strvalue] then
dfhack.print(prefix)
dfhack.println('<Cyclic reference! Skipping fields>\n')
return 0
end
seen[strvalue] = true
return print_fields(value, seen, indent, prefix)
end
local function print_array(printfn, value, seen, indent)
local prefix = string.rep(' ', indent)
dfhack.println(tostring(value))
if seen[value] then
dfhack.print(prefix)
dfhack.println('<Cyclic reference! skipping fields>\n')
return 0
end
seen[value] = true
return print_fields(value, seen, indent, prefix)
end
local recurse_type_map = {
number = print_string,
string = print_string,
boolean = print_string,
['function'] = print_string,
['nil'] = print_string,
userdata = print_userdata,
table = print_array,
}
do_print_recurse = function(printfn, value, seen, indent)
local t = type(value)
if not recurse_type_map[t] then
printfn("Unknown type " .. t .. " " .. tostring(value))
return
end
return recurse_type_map[t](printfn, value, seen, indent)
end
function printall_recurse(value, seen)
local seen = seen or {}
do_print_recurse(dfhack.println, value, seen, 0)
end
---@generic T
---@param table T
---@return T
function copyall(table)
local rv = {}
for k,v in pairs(table) do rv[k] = v end
return rv
end
---@param pos df.coord
---@return number? x
---@return number? y
---@return number? z
function pos2xyz(pos)
if pos then
local x = pos.x
if x and x >= 0 then
return x, pos.y, pos.z
end
end
end
---@nodiscard
---@param x number
---@param y number
---@param z number
---@return df.coord
function xyz2pos(x,y,z)
if x then
return {x=x,y=y,z=z}
else
return {x=-30000,y=-30000,z=-30000}
end
end
---@nodiscard
---@param a df.coord
---@param b df.coord
---@return boolean
function same_xyz(a,b)
return a and b and a.x == b.x and a.y == b.y and a.z == b.z
end
---@nodiscard
---@param path df.coord_path
---@param i number
---@return number x
---@return number y
---@return number z
function get_path_xyz(path,i)
return path.x[i], path.y[i], path.z[i]
end
---@nodiscard
---@param pos df.coord|df.coord2d
---@return number? x
---@return number? y
function pos2xy(pos)
if pos then
local x = pos.x
if x and x >= 0 then
return x, pos.y
end
end
end
---@nodiscard
---@param x number
---@param y number
---@return df.coord2d
function xy2pos(x,y)
if x then
return {x=x,y=y}
else
return {x=-30000,y=-30000}
end
end
---@nodiscard
---@param a df.coord|df.coord2d
---@param b df.coord|df.coord2d
---@return boolean
function same_xy(a,b)
return a and b and a.x == b.x and a.y == b.y
end
---@nodiscard
---@param path df.coord_path|df.coord2d_path
---@param i number
---@return integer x
---@return integer y
function get_path_xy(path,i)
return path.x[i], path.y[i]
end
-- Walks a sequence of dereferences, which may be represented by numbers or
-- strings. Returns nil if any of obj or indices is nil, or a numeric index is
-- out of array bounds.
---@param obj table
---@param idx number|string
---@param ... number|string
---@return any obj
function safe_index(obj,idx,...)
local obj_type = type(obj)
if obj == nil or idx == nil or (obj_type ~= "table" and obj_type ~= "userdata") then
return nil
end
if type(idx) == 'number' and
obj_type == 'userdata' and -- this check is only relevant for c++
(idx < 0 or idx >= #obj)
then
return nil
end
obj = obj[idx]
if select('#',...) > 0 then
return safe_index(obj,...)
else
return obj
end
end
---@param t table
---@param key integer|string
---@param default_value? any
---@return any
function ensure_key(t, key, default_value)
if t[key] == nil then
t[key] = (default_value ~= nil) and default_value or {}
end
return t[key]
end
---@param t table
---@param key integer|string
---@param ... integer|string
---@return table
function ensure_keys(t, key, ...)
t = ensure_key(t, key)
if select('#', ...) > 0 then
return ensure_keys(t, ...)
end
return t
end
-- String class extentions
-- prefix is a literal string, not a pattern
---@nodiscard
---@param self string
---@param prefix string
---@return boolean
function string:startswith(prefix)
return self:sub(1, #prefix) == prefix
end
-- suffix is a literal string, not a pattern
---@nodiscrd
---@param self string
---@param suffix string
---@return boolean
function string:endswith(suffix)
return self:sub(-#suffix) == suffix or #suffix == 0
end
-- Split a string by the given delimiter. If no delimiter is specified, space
-- (' ') is used. The delimter is treated as a pattern unless a <plain> is
-- specified and set to true. To treat multiple successive delimiter characters
-- as a single delimiter, e.g. to avoid getting empty string elements, pass a
-- pattern like ' +'. Be aware that passing patterns that match empty strings
-- (like ' *') will result in improper string splits.
---@nodiscard
---@param self string
---@param delimiter? string
---@param plain? boolean
---@return string[]
function string:split(delimiter, plain)
delimiter = delimiter or ' '
local result = {}
local from = 1
local delim_from, delim_to = self:find(delimiter, from, plain)
-- delim_from will be greater than delim_to when the delimiter matches the
-- empty string, which would lead to an infinite loop if we didn't check it
while delim_from and delim_from <= delim_to do
table.insert(result, self:sub(from, delim_from - 1))
from = delim_to + 1
delim_from, delim_to = self:find(delimiter, from, plain)
end
table.insert(result, self:sub(from))
return result
end
-- Removes spaces (i.e. everything that matches '%s') from the start and end of
-- a string. Spaces between non-space characters are left untouched.
---@nodiscard
---@param self string
---@return string
function string:trim()
return self:match('^%s*(.-)%s*$')
end
local function insert_wrapped_line(wrapped_text, words, opts)
local wrapped_line = table.concat(words, '')
if not opts.keep_trailing_spaces then
local content, eol = wrapped_line:match('(.-)%s*(\n?)$')
wrapped_line = content .. eol
end
table.insert(wrapped_text, wrapped_line)
end
local function wrap_word(word, width, wrapped_text, words, cur_line_len, opts)
local word_len = #word
-- word fits within the current line
if cur_line_len + word_len <= width then
table.insert(words, word)
cur_line_len = cur_line_len + word_len
return words, cur_line_len
end
local trimmed_word = word
if not opts.keep_trailing_spaces then
trimmed_word = word:trim()
-- trimmed word fits on the current line and ends it
if cur_line_len + #trimmed_word <= width then
table.insert(words, trimmed_word)
insert_wrapped_line(wrapped_text, words, opts)
return {}, 0
end
end
-- word needs to go on the next line, but is not itself longer
-- than the specified width
if word_len <= width then
insert_wrapped_line(wrapped_text, words, opts)
return {word}, word_len
end
-- word is too long to fit on one line and needs to be split up
local emitted_chars, trimmed_word_len = 0, #trimmed_word
repeat
if #words > 0 then
insert_wrapped_line(wrapped_text, words, opts)
end
local word_frag = word:sub(emitted_chars + 1, emitted_chars + width)
words, cur_line_len = {word_frag}, #word_frag
emitted_chars = emitted_chars + cur_line_len
until emitted_chars >= trimmed_word_len
return words, cur_line_len
end
-- Inserts newlines into a string so no individual line exceeds the given width.
---@nodiscard
---@param self string
---@param width number
---@param opts {return_as_table:boolean, keep_trailing_spaces:boolean, keep_original_newlines:boolean}
---@return string|string[]
function string:wrap(width, opts)
width, opts = width or 72, opts or {}
if width <= 0 then error('expected width > 0; got: '..tostring(width)) end
local wrapped_text = {}
for line in self:gmatch('[^\n]*'..(opts.keep_original_newlines and '\n?' or '')) do
local prespace = line:match('^(%s*)')
local words, cur_line_len = {}, 0
if #prespace > 0 then
words, cur_line_len = wrap_word(prespace, width, wrapped_text, words, cur_line_len, opts)
end
for word in line:gmatch('%S+%s*') do
words, cur_line_len = wrap_word(word, width, wrapped_text, words, cur_line_len, opts)
end
insert_wrapped_line(wrapped_text, words, opts)
end
if self:sub(#self) == '\n' then
table.insert(wrapped_text, '')
end
return opts.return_as_table and wrapped_text or table.concat(wrapped_text, '\n')
end
-- Escapes regex special chars in a string. E.g. "a+b" -> "a%+b"
local regex_chars_pattern = '(['..('%^$()[].*+-?'):gsub('(.)', '%%%1')..'])'
---@nodiscard
---@param self string
---@return string
function string:escape_pattern()
return self:gsub(regex_chars_pattern, '%%%1')
end
-- String conversions
---@nodiscard
---@param self self
---@return string
function dfhack.matinfo:__tostring()
return "<material "..self.type..":"..self.index.." "..self:getToken()..">"
end
dfhack.random.__index = dfhack.random
---@nodiscard
---@param self self
---@return string
function dfhack.random:__tostring()
return "<random generator>"
end
dfhack.penarray.__index = dfhack.penarray
---@nodiscard
---@return string
function dfhack.penarray.__tostring()
return "<penarray>"
end
---@nodiscard
---@return number x
---@return number y
---@return number z
function dfhack.maps.getSize()
local map = df.global.world.map
return map.x_count_block, map.y_count_block, map.z_count_block
end
---@nodiscard
---@return number x
---@return number y
---@return number z
function dfhack.maps.getTileSize()
local map = df.global.world.map
return map.x_count, map.y_count, map.z_count
end
---@param bld building
---@return number width
---@return number height
---@return number centerx
---@return number centery
function dfhack.buildings.getSize(bld)
local x, y = bld.x1, bld.y1
return bld.x2+1-x, bld.y2+1-y, bld.centerx-x, bld.centery-y
end
---@nodiscard
---@param scr_type _viewscreen
---@param n? number
---@return viewscreen|nil
function dfhack.gui.getViewscreenByType(scr_type, n)
-- translated from modules/Gui.cpp
if n == nil then
n = 1
end
local limit = (n > 0)
local scr = dfhack.gui.getCurViewscreen()
while scr do
if limit then
n = n - 1
if n < 0 then
return nil
end
end
if scr_type:is_instance(scr) then
return scr
end
scr = scr.parent
end
end
---@nodiscard
---@return world_site|nil
function dfhack.world.getCurrentSite()
return df.world_site.find(dfhack.world.GetCurrentSiteId())
end
---@nodiscard
---@param which string
---@param key string
---@param default? any
---@return any
local function persistent_getData(which, key, default)
local serialized = dfhack.persistent['get'..which..'DataString'](key)
if not serialized then return default end
return require('json').decode(serialized) or default
end
---@param which string
---@param key string
---@param data any
local function persistent_saveData(which, key, data)
local serialized = require('json').encode(data)
dfhack.persistent['save'..which..'DataString'](key, serialized)
end
---@nodiscard
---@param key string
---@param default? any
---@return any
function dfhack.persistent.getSiteData(key, default)
return persistent_getData('Site', key, default)
end
---@param key string
---@param data any
function dfhack.persistent.saveSiteData(key, data)
persistent_saveData('Site', key, data)
end
---@param key string
---@param default? any
---@return any
function dfhack.persistent.getWorldData(key, default)
return persistent_getData('World', key, default)
end
---@param key string
---@param data any
function dfhack.persistent.saveWorldData(key, data)
persistent_saveData('World', key, data)
end
-- Interactive
local print_banner = true
---@param prompt? string
---@param hfile? string
---@param env? table|metatable
---@return boolean|nil
---@return string|nil
function dfhack.interpreter(prompt,hfile,env)
if not dfhack.is_interactive() then
return nil, 'not interactive'
end
print("Type quit to exit interactive lua interpreter.")
if print_banner then
print("Shortcuts:\n"..
" '= foo' => '_1,_2,... = foo'\n"..
" '! foo' => 'print(foo)'\n"..
" '~ foo' => 'printall(foo)'\n"..
" '^ foo' => 'printall_recurse(foo)'\n"..
" '@ foo' => 'printall_ipairs(foo)'\n"..
"All of these save the first result as '_'.")
print_banner = false
end
local prompt_str = "["..(prompt or 'lua').."]# "
local prompt_cont = string.rep(' ',#prompt_str-4)..">>> "
local prompt_env = {}
local cmdlinelist = {}
local t_prompt = nil
local vcnt = 1
local pfix_handlers = {
['!'] = function(data)
print(table.unpack(data,2,data.n))
end,
['~'] = function(data)
print(table.unpack(data,2,data.n))
printall(data[2])
end,
['@'] = function(data)
print(table.unpack(data,2,data.n))
printall_ipairs(data[2])
end,
['^'] = function(data)
printall_recurse(data[2])
end,
['='] = function(data)
for i=2,data.n do
local varname = '_'..vcnt
prompt_env[varname] = data[i]
dfhack.print(varname..' = ')
safecall(print, data[i])
vcnt = vcnt + 1
end
end
}
setmetatable(prompt_env, { __index = env or _G })
while true do
local cmdline = dfhack.lineedit(t_prompt or prompt_str, hfile)
if cmdline == nil or cmdline == 'quit' then
break
elseif cmdline ~= '' then
local pfix = string.sub(cmdline,1,1)
if not t_prompt and pfix_handlers[pfix] then
cmdline = 'return '..string.sub(cmdline,2)
else
pfix = nil
end
table.insert(cmdlinelist,cmdline)
cmdline = table.concat(cmdlinelist,'\n')
local code,err = load(cmdline, '=(interactive)', 't', prompt_env)
if code == nil then
if not pfix and err:sub(-5)=="<eof>" then
t_prompt=prompt_cont
else
dfhack.printerr(err)
cmdlinelist={}
t_prompt=nil
end
else
cmdlinelist={}
t_prompt=nil
local data = table.pack(safecall(code))
if data[1] and data.n > 1 then
prompt_env._ = data[2]
safecall(pfix_handlers[pfix], data)
end
end
end
end
return true
end
-- Command scripts
local internal = dfhack.internal
Script = defclass(Script)
function Script:init(path)
self.path = path
self.mtime = dfhack.filesystem.mtime(path)
self._flags = {}
end
function Script:needs_update()
return (not self.env) or self.mtime ~= dfhack.filesystem.mtime(self.path)
end
function Script:get_flags()
local mtime = dfhack.filesystem.mtime(self.path)
if self.flags_mtime ~= mtime then
self.flags_mtime = mtime
self._flags = {}
local f = io.open(self.path)
for line in f:lines() do
local at_tag = line:match('^%-%-@(.+)')
if not at_tag then goto continue end
local chunk = load(at_tag, self.path, 't', self._flags)
if chunk then
chunk()
else
dfhack.printerr('Parse error: ' .. line)
end
::continue::
end
f:close()
end
return self._flags
end
internal.scripts = internal.scripts or {}
function dfhack.findScript(name)
return dfhack.internal.findScript(name .. '.lua')
end
local valid_script_flags = {
enable = {required = true, error = 'Does not recognize enable/disable commands'},
enable_state = {required = false},
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},
alias = {required = false},
alias_count = {required = false},
scripts = {required = false},
}
local checked_scripts = {}
function dfhack.run_script(name,...)
if not checked_scripts[name] then