backport some doc updates and renames

live.lua

@@ -1,20 +1,22 @@
 -- A general architecture for free-wheeling, live programs:
 --  on startup:
 --    scan both the app directory and the save directory for files with numeric prefixes
---    from the largest numeric prefix found, obtain a manifest
---    load all files (which must start with a numeric prefix) from the manifest)
+--    from the numeric prefix in file 'head', obtain a manifest
+--    load all files (which must start with a numeric prefix) from the manifest
 --
 --  then start drawing frames on screen and reacting to events
 --
 --  events from keyboard and mouse are handled as the app desires
 --
 --  on incoming messages to a specific file, however, the app must:
---    save the message's value to a specific, unused numeric prefix
+--    save the message's value to a new, smallest unused numeric prefix
 --    execute the value
+--      if there's an error, go back to the previous value of the same
+--      definition if one exists
 --
---  if a game encounters an error:
---    find the previous version of the definition in the 'head' numeric prefix
---    decrement 'head'
+--  if a game encounters a run-time error, send it to the driver and await
+--  further instructions. The app will go unresponsive in the meantime, that
+--  is expected. To shut it down cleanly, type C-q in the driver.
 
 -- namespace for these functions
 live = {}
@@ -145,7 +147,7 @@ end
 
 function live.update(dt)
   if Current_time - Live.previous_read > 0.1 then
-    local buf = live.receive()
+    local buf = live.receive_from_driver()
     if buf then
       live.run(buf)
       if on.code_change then on.code_change() end
@@ -155,7 +157,7 @@ function live.update(dt)
 end
 
 -- look for a message from outside, and return nil if there's nothing
-function live.receive()
+function live.receive_from_driver()
   local f = io.open(love.filesystem.getAppdataDirectory()..'/_love_akkartik_driver_app')
   if f == nil then return nil end
   local result = f:read('*a')
@@ -170,7 +172,7 @@ function live.receive()
   return result
 end
 
-function live.send(msg)
+function live.send_to_driver(msg)
   local f = io.open(love.filesystem.getAppdataDirectory()..'/_love_akkartik_app_driver', 'w')
   if f == nil then return end
   f:write(msg)
@@ -203,13 +205,13 @@ end
 
 -- define or undefine top-level bindings
 function live.run(buf)
-  local cmd = buf:match('^%S+')
+  local cmd = live.get_cmd_from_buffer(buf)
   assert(cmd)
   print('command is '..cmd)
   if cmd == 'QUIT' then
     love.event.quit(1)
   elseif cmd == 'MANIFEST' then
-    live.send(json.encode(Live.manifest))
+    live.send_to_driver(json.encode(Live.manifest))
   elseif cmd == 'DELETE' then
     local binding = buf:match('^%S+%s+(%S+)')
     Live.manifest[binding] = nil
@@ -225,7 +227,7 @@ function live.run(buf)
     Live.next_version = Live.next_version + 1
   elseif cmd == 'GET' then
     local binding = buf:match('^%S+%s+(%S+)')
-    live.send(live.get_binding(binding))
+    live.send_to_driver(live.get_binding(binding))
   -- other commands go here
   else
     local binding = cmd
@@ -246,12 +248,16 @@ function live.run(buf)
       local previous_manifest_filename = live.versioned_manifest(Live.head)
       Live.manifest = json.decode(love.filesystem.read(previous_manifest_filename))
       -- throw an error
-      live.send('ERROR '..tostring(err))
+      live.send_to_driver('ERROR '..tostring(err))
     end
-    live.send('ok')
+    live.send_to_driver('ok')
   end
 end
 
+function live.get_cmd_from_buffer(buf)
+  return buf:match('^%s*(%S+)')
+end
+
 function live.get_binding(name)
   if Live.manifest[name] then
     return love.filesystem.read(live.versioned_filename(Live.manifest[name], name))
@@ -296,10 +302,10 @@ function live.handle_error(err)
   print('Look in the driver for options to investigate further.')
   print("(You probably can't close the app window at this point. If you don't have the driver set up, you might need to force-quit.)")
   -- send stack trace to driver and wait for a response
-  live.send_run_time_error(stack_trace)
+  live.send_run_time_error_to_driver(stack_trace)
   local buf
   repeat
-    buf = live.receive()
+    buf = live.receive_from_driver()
   until buf
   if buf == 'QUIT' then
     return true