document The Parser, take an emit function.

updatedshmup.p8

@@ -422,7 +422,25 @@ end
 parser = {}
 mknew(parser)
 
-function parser:ingest(str)
+-- calls parse_into with a nop
+-- emit function.
+function parser:parse(str)
+ self:parse_into(str, function() end)
+end
+
+-- read a file of commands and
+-- execute them, emitting the
+-- results from each call into
+-- `emit` as a table per row.
+--
+-- a "command" is a method on
+-- self. a row alternates
+-- commands with args. when
+-- calling a command, it also
+-- gets a table of previous
+-- results as the first arg.
+-- args are split on ','.
+function parser:parse_into(str, emit)
  for row in all(split(str, "\n")) do
   local prev = {}
   local sectors = split(row, ":")
@@ -430,9 +448,13 @@ function parser:ingest(str)
    local x = self[sectors[i]](self, prev, usplit(sectors[i+1]))
    if (x) add(prev, x)
   end
+  emit(prev)
  end
 end
 
+-- saves prev[sel] as self.name.
+-- if sel is unspecified, saves
+-- all of prev (as a table).
 function parser:saveas(prev, name, sel)
  self[name] = sel and prev[sel] or prev
 end