app.lua

   1 -- love.run: main entrypoint function for LÖVE
   2 --
   3 -- Most apps can just use the default shown in https://love2d.org/wiki/love.run,
   4 -- but we need to override it to:
   5 --   * recover from errors (by switching to the source editor)
   6 --   * run all tests (functions starting with 'test_') on startup, and
   7 --   * save some state that makes it possible to switch between the main app
   8 --     and a source editor, while giving each the illusion of complete
   9 --     control.
  10 function love.run()
  11   Version, Major_version = App.love_version()
  12   App.snapshot_love()
  13   -- Tests always run at the start.
  14   App.run_tests_and_initialize()
  15 --?   print('==')
  16
  17   love.timer.step()
  18   local dt = 0
  19
  20   return function()
  21     if love.event then
  22       love.event.pump()
  23       for name, a,b,c,d,e,f in love.event.poll() do
  24         if name == "quit" then
  25           if not love.quit or not love.quit() then
  26             return a or 0
  27           end
  28         end
  29         xpcall(function() love.handlers[name](a,b,c,d,e,f) end, handle_error)
  30       end
  31     end
  32
  33     dt = love.timer.step()
  34     xpcall(function() App.update(dt) end, handle_error)
  35
  36     love.graphics.origin()
  37     love.graphics.clear(love.graphics.getBackgroundColor())
  38     xpcall(App.draw, handle_error)
  39     love.graphics.present()
  40
  41     love.timer.sleep(0.001)
  42   end
  43 end
  44
  45 function handle_error(err)
  46   local callstack = debug.traceback('', --[[stack frame]]2)
  47   Error_message = 'Error: ' .. tostring(err)..'\n'..cleaned_up_callstack(callstack)
  48   print(Error_message)
  49   if Current_app == 'run' then
  50     Settings.current_app = 'source'
  51     love.filesystem.write('config', json.encode(Settings))
  52     load_file_from_source_or_save_directory('main.lua')
  53     App.undo_initialize()
  54     App.run_tests_and_initialize()
  55   else
  56     -- abort without running love.quit handler
  57     Disable_all_quit_handlers = true
  58     love.event.quit()
  59   end
  60 end
  61
  62 -- I tend to read code from files myself (say using love.filesystem calls)
  63 -- rather than offload that to load().
  64 -- Functions compiled in this manner have ugly filenames of the form [string "filename"]
  65 -- This function cleans out this cruft from error callstacks.
  66 function cleaned_up_callstack(callstack)
  67   local frames = {}
  68   for frame in string.gmatch(callstack, '[^\n]+\n*') do
  69     local line = frame:gsub('^%s*(.-)\n?$', '%1')
  70     local filename, rest = line:match('([^:]*):(.*)')
  71     local core_filename = filename:match('^%[string "(.*)"%]$')
  72     -- pass through frames that don't match this format
  73     -- this includes the initial line "stack traceback:"
  74     local new_frame = (core_filename or filename)..':'..rest
  75     table.insert(frames, new_frame)
  76   end
  77   -- the initial "stack traceback:" line was unindented and remains so
  78   return table.concat(frames, '\n\t')
  79 end
  80
  81 -- The rest of this file wraps around various LÖVE primitives to support
  82 -- automated tests. Often tests will run with a fake version of a primitive
  83 -- that redirects to the real love.* version once we're done with tests.
  84 --
  85 -- Not everything is so wrapped yet. Sometimes you still have to use love.*
  86 -- primitives directly.
  87
  88 App = {}
  89
  90 function App.love_version()
  91   local major_version, minor_version = love.getVersion()
  92   local version = major_version..'.'..minor_version
  93   return version, major_version
  94 end
  95
  96 -- save/restore various framework globals we care about -- only on very first load
  97 function App.snapshot_love()
  98   if Love_snapshot then return end
  99   Love_snapshot = {}
 100   -- save the entire initial font; it doesn't seem reliably recreated using newFont
 101   Love_snapshot.initial_font = love.graphics.getFont()
 102 end
 103
 104 function App.undo_initialize()
 105   love.graphics.setFont(Love_snapshot.initial_font)
 106 end
 107
 108 function App.run_tests_and_initialize()
 109   App.load()
 110   Test_errors = {}
 111   App.run_tests()
 112   if #Test_errors > 0 then
 113     local error_message = ''
 114     if Warning_before_tests then
 115       error_message = Warning_before_tests..'\n\n'
 116     end
 117     error_message = error_message .. ('There were %d test failures:\n%s'):format(#Test_errors, table.concat(Test_errors))
 118     error(error_message)
 119   end
 120   App.disable_tests()
 121   App.initialize_globals()
 122   App.initialize(love.arg.parseGameArguments(arg), arg)
 123 end
 124
 125 function App.run_tests()
 126   local sorted_names = {}
 127   for name,binding in pairs(_G) do
 128     if name:find('test_') == 1 then
 129       table.insert(sorted_names, name)
 130     end
 131   end
 132   table.sort(sorted_names)
 133 --?   App.initialize_for_test() -- debug: run a single test at a time like these 2 lines
 134 --?   test_click_below_all_lines()
 135   for _,name in ipairs(sorted_names) do
 136     App.initialize_for_test()
 137 --?     print('=== '..name)
 138 --?     _G[name]()
 139     xpcall(_G[name], function(err) prepend_debug_info_to_test_failure(name, err) end)
 140   end
 141   -- clean up all test methods
 142   for _,name in ipairs(sorted_names) do
 143     _G[name] = nil
 144   end
 145 end
 146
 147 function App.initialize_for_test()
 148   App.screen.init{width=100, height=50}
 149   App.screen.contents = {}  -- clear screen
 150   App.filesystem = {}
 151   App.source_dir = ''
 152   App.current_dir = ''
 153   App.save_dir = ''
 154   App.fake_keys_pressed = {}
 155   App.fake_mouse_state = {x=-1, y=-1}
 156   App.initialize_globals()
 157 end
 158
 159 -- App.screen.resize and App.screen.move seem like better names than
 160 -- love.window.setMode and love.window.setPosition respectively. They'll
 161 -- be side-effect-free during tests, and they'll save their results in
 162 -- attributes of App.screen for easy access.
 163
 164 App.screen={}
 165
 166 -- Use App.screen.init in tests to initialize the fake screen.
 167 function App.screen.init(dims)
 168   App.screen.width = dims.width
 169   App.screen.height = dims.height
 170 end
 171
 172 function App.screen.resize(width, height, flags)
 173   App.screen.width = width
 174   App.screen.height = height
 175   App.screen.flags = flags
 176 end
 177
 178 function App.screen.size()
 179   return App.screen.width, App.screen.height, App.screen.flags
 180 end
 181
 182 function App.screen.move(x,y, displayindex)
 183   App.screen.x = x
 184   App.screen.y = y
 185   App.screen.displayindex = displayindex
 186 end
 187
 188 function App.screen.position()
 189   return App.screen.x, App.screen.y, App.screen.displayindex
 190 end
 191
 192 -- If you use App.screen.print instead of love.graphics.print,
 193 -- tests will be able to check what was printed using App.screen.check below.
 194 --
 195 -- One drawback of this approach: the y coordinate used depends on font size,
 196 -- which feels brittle.
 197
 198 function App.screen.print(msg, x,y)
 199   local screen_row = 'y'..tostring(y)
 200 --?   print('drawing "'..msg..'" at y '..tostring(y))
 201   local screen = App.screen
 202   if screen.contents[screen_row] == nil then
 203     screen.contents[screen_row] = {}
 204     for i=0,screen.width-1 do
 205       screen.contents[screen_row][i] = ''
 206     end
 207   end
 208   if x < screen.width then
 209     screen.contents[screen_row][x] = msg
 210   end
 211 end
 212
 213 function App.screen.check(y, expected_contents, msg)
 214 --?   print('checking for "'..expected_contents..'" at y '..tostring(y))
 215   local screen_row = 'y'..tostring(y)
 216   local contents = ''
 217   if App.screen.contents[screen_row] == nil then
 218     error('no text at y '..tostring(y))
 219   end
 220   for i,s in ipairs(App.screen.contents[screen_row]) do
 221     contents = contents..s
 222   end
 223   check_eq(contents, expected_contents, msg)
 224 end
 225
 226 -- If you access the time using App.get_time instead of love.timer.getTime,
 227 -- tests will be able to move the time back and forwards as needed using
 228 -- App.wait_fake_time below.
 229
 230 App.time = 1
 231 function App.get_time()
 232   return App.time
 233 end
 234 function App.wait_fake_time(t)
 235   App.time = App.time + t
 236 end
 237
 238 function App.width(text)
 239   return love.graphics.getFont():getWidth(text)
 240 end
 241
 242 -- If you access the clipboard using App.get_clipboard and App.set_clipboard
 243 -- instead of love.system.getClipboardText and love.system.setClipboardText
 244 -- respectively, tests will be able to manipulate the clipboard by
 245 -- reading/writing App.clipboard.
 246
 247 App.clipboard = ''
 248 function App.get_clipboard()
 249   return App.clipboard
 250 end
 251 function App.set_clipboard(s)
 252   App.clipboard = s
 253 end
 254
 255 -- In tests I mostly send chords all at once to the keyboard handlers.
 256 -- However, you'll occasionally need to check if a key is down outside a handler.
 257 -- If you use App.key_down instead of love.keyboard.isDown, tests will be able to
 258 -- simulate keypresses using App.fake_key_press and App.fake_key_release
 259 -- below. This isn't very realistic, though, and it's up to tests to
 260 -- orchestrate key presses that correspond to the handlers they invoke.
 261
 262 App.fake_keys_pressed = {}
 263 function App.key_down(key)
 264   return App.fake_keys_pressed[key]
 265 end
 266
 267 function App.fake_key_press(key)
 268   App.fake_keys_pressed[key] = true
 269 end
 270 function App.fake_key_release(key)
 271   App.fake_keys_pressed[key] = nil
 272 end
 273
 274 -- Tests mostly will invoke mouse handlers directly. However, you'll
 275 -- occasionally need to check if a mouse button is down outside a handler.
 276 -- If you use App.mouse_down instead of love.mouse.isDown, tests will be able to
 277 -- simulate mouse clicks using App.fake_mouse_press and App.fake_mouse_release
 278 -- below. This isn't very realistic, though, and it's up to tests to
 279 -- orchestrate presses that correspond to the handlers they invoke.
 280
 281 App.fake_mouse_state = {x=-1, y=-1}  -- x,y always set
 282
 283 function App.mouse_move(x,y)
 284   App.fake_mouse_state.x = x
 285   App.fake_mouse_state.y = y
 286 end
 287 function App.mouse_down(mouse_button)
 288   return App.fake_mouse_state[mouse_button]
 289 end
 290 function App.mouse_x()
 291   return App.fake_mouse_state.x
 292 end
 293 function App.mouse_y()
 294   return App.fake_mouse_state.y
 295 end
 296
 297 function App.fake_mouse_press(x,y, mouse_button)
 298   App.fake_mouse_state.x = x
 299   App.fake_mouse_state.y = y
 300   App.fake_mouse_state[mouse_button] = true
 301 end
 302 function App.fake_mouse_release(x,y, mouse_button)
 303   App.fake_mouse_state.x = x
 304   App.fake_mouse_state.y = y
 305   App.fake_mouse_state[mouse_button] = nil
 306 end
 307
 308 -- If you use App.open_for_reading and App.open_for_writing instead of other
 309 -- various Lua and LÖVE helpers, tests will be able to check the results of
 310 -- file operations inside the App.filesystem table.
 311
 312 function App.open_for_reading(filename)
 313   if App.filesystem[filename] then
 314     return {
 315       lines = function(self)
 316                 return App.filesystem[filename]:gmatch('[^\n]+')
 317               end,
 318       read = function(self)
 319                return App.filesystem[filename]
 320              end,
 321       close = function(self)
 322               end,
 323     }
 324   end
 325 end
 326
 327 function App.read_file(filename)
 328   return App.filesystem[filename]
 329 end
 330
 331 function App.open_for_writing(filename)
 332   App.filesystem[filename] = ''
 333   return {
 334     write = function(self, s)
 335               App.filesystem[filename] = App.filesystem[filename]..s
 336             end,
 337     close = function(self)
 338             end,
 339   }
 340 end
 341
 342 function App.write_file(filename, contents)
 343   App.filesystem[filename] = contents
 344   return --[[status]] true
 345 end
 346
 347 function App.mkdir(dirname)
 348   -- nothing in test mode
 349 end
 350
 351 function App.remove(filename)
 352   App.filesystem[filename] = nil
 353 end
 354
 355 -- Some helpers to trigger an event and then refresh the screen. Akin to one
 356 -- iteration of the event loop.
 357
 358 -- all textinput events are also keypresses
 359 -- TODO: handle chords of multiple keys
 360 function App.run_after_textinput(t)
 361   App.keypressed(t)
 362   App.textinput(t)
 363   App.keyreleased(t)
 364   App.screen.contents = {}
 365   App.draw()
 366 end
 367
 368 -- not all keys are textinput
 369 -- TODO: handle chords of multiple keys
 370 function App.run_after_keychord(chord, key)
 371   App.keychord_press(chord, key)
 372   App.keyreleased(key)
 373   App.screen.contents = {}
 374   App.draw()
 375 end
 376
 377 function App.run_after_mouse_click(x,y, mouse_button)
 378   App.fake_mouse_press(x,y, mouse_button)
 379   App.mousepressed(x,y, mouse_button)
 380   App.fake_mouse_release(x,y, mouse_button)
 381   App.mousereleased(x,y, mouse_button)
 382   App.screen.contents = {}
 383   App.draw()
 384 end
 385
 386 function App.run_after_mouse_press(x,y, mouse_button)
 387   App.fake_mouse_press(x,y, mouse_button)
 388   App.mousepressed(x,y, mouse_button)
 389   App.screen.contents = {}
 390   App.draw()
 391 end
 392
 393 function App.run_after_mouse_release(x,y, mouse_button)
 394   App.fake_mouse_release(x,y, mouse_button)
 395   App.mousereleased(x,y, mouse_button)
 396   App.screen.contents = {}
 397   App.draw()
 398 end
 399
 400 -- miscellaneous internal helpers
 401
 402 function App.color(color)
 403   love.graphics.setColor(color.r, color.g, color.b, color.a)
 404 end
 405
 406 -- prepend file/line/test
 407 function prepend_debug_info_to_test_failure(test_name, err)
 408   local err_without_line_number = err:gsub('^[^:]*:[^:]*: ', '')
 409   local stack_trace = debug.traceback('', --[[stack frame]]5)  -- most likely to be useful, but set to 0 for a complete stack trace
 410   local file_and_line_number = stack_trace:gsub('stack traceback:\n', ''):gsub(': .*', '')
 411   local full_error = file_and_line_number..':'..test_name..' -- '..err_without_line_number
 412   -- uncomment this line for a complete stack trace
 413 --?   local full_error = file_and_line_number..':'..test_name..' -- '..err_without_line_number..'\t\t'..stack_trace:gsub('\n', '\n\t\t')
 414   table.insert(Test_errors, full_error)
 415 end
 416
 417 nativefs = require 'nativefs'
 418
 419 local Keys_down = {}
 420
 421 -- call this once all tests are run
 422 -- can't run any tests after this
 423 function App.disable_tests()
 424   -- have LÖVE delegate all handlers to App if they exist
 425   -- make sure to late-bind handlers like LÖVE's defaults do
 426   for name in pairs(love.handlers) do
 427     if App[name] then
 428       -- love.keyboard.isDown doesn't work on Android, so emulate it using
 429       -- keypressed and keyreleased events
 430       if name == 'keypressed' then
 431         love.handlers[name] = function(key, scancode, isrepeat)
 432                                 Keys_down[key] = true
 433                                 return App.keypressed(key, scancode, isrepeat)
 434                               end
 435       elseif name == 'keyreleased' then
 436         love.handlers[name] = function(key, scancode)
 437                                 Keys_down[key] = nil
 438                                 return App.keyreleased(key, scancode)
 439                               end
 440       else
 441         love.handlers[name] = function(...) App[name](...) end
 442       end
 443     end
 444   end
 445
 446   -- test methods are disallowed outside tests
 447   App.run_tests = nil
 448   App.disable_tests = nil
 449   App.screen.init = nil
 450   App.filesystem = nil
 451   App.time = nil
 452   App.run_after_textinput = nil
 453   App.run_after_keychord = nil
 454   App.keypress = nil
 455   App.keyrelease = nil
 456   App.run_after_mouse_click = nil
 457   App.run_after_mouse_press = nil
 458   App.run_after_mouse_release = nil
 459   App.fake_keys_pressed = nil
 460   App.fake_key_press = nil
 461   App.fake_key_release = nil
 462   App.fake_mouse_state = nil
 463   App.fake_mouse_press = nil
 464   App.fake_mouse_release = nil
 465   -- other methods dispatch to real hardware
 466   App.screen.resize = love.window.setMode
 467   App.screen.size = love.window.getMode
 468   App.screen.move = love.window.setPosition
 469   App.screen.position = love.window.getPosition
 470   App.screen.print = love.graphics.print
 471   App.open_for_reading =
 472       function(filename)
 473         local result = nativefs.newFile(filename)
 474         local ok, err = result:open('r')
 475         if ok then
 476           return result
 477         else
 478           return ok, err
 479         end
 480       end
 481   App.read_file =
 482       function(path)
 483         if not is_absolute_path(path) then
 484           return --[[status]] false, 'Please use an unambiguous absolute path.'
 485         end
 486         local f, err = App.open_for_reading(path)
 487         if err then
 488           return --[[status]] false, err
 489         end
 490         local contents = f:read()
 491         f:close()
 492         return contents
 493       end
 494   App.open_for_writing =
 495       function(filename)
 496         local result = nativefs.newFile(filename)
 497         local ok, err = result:open('w')
 498         if ok then
 499           return result
 500         else
 501           return ok, err
 502         end
 503       end
 504   App.write_file =
 505       function(path, contents)
 506         if not is_absolute_path(path) then
 507           return --[[status]] false, 'Please use an unambiguous absolute path.'
 508         end
 509         local f, err = App.open_for_writing(path)
 510         if err then
 511           return --[[status]] false, err
 512         end
 513         f:write(contents)
 514         f:close()
 515         return --[[status]] true
 516       end
 517   App.files = nativefs.getDirectoryItems
 518   App.file_info = nativefs.getInfo
 519   App.mkdir = nativefs.createDirectory
 520   App.remove = nativefs.remove
 521   App.source_dir = love.filesystem.getSource()..'/'  -- '/' should work even on Windows
 522   App.current_dir = nativefs.getWorkingDirectory()..'/'
 523   App.save_dir = love.filesystem.getSaveDirectory()..'/'
 524   App.get_time = love.timer.getTime
 525   App.get_clipboard = love.system.getClipboardText
 526   App.set_clipboard = love.system.setClipboardText
 527   App.key_down = function(key) return Keys_down[key] end
 528   App.mouse_move = love.mouse.setPosition
 529   App.mouse_down = love.mouse.isDown
 530   App.mouse_x = love.mouse.getX
 531   App.mouse_y = love.mouse.getY
 532 end