From fd68ef88ec736760330fb82c7210cd8213a9ce83 Mon Sep 17 00:00:00 2001
From: Kistaro Windrider <kistaro@gmail.com>
Date: Sat, 7 Oct 2023 23:53:40 -0700
Subject: [PATCH] document The Parser, take an emit function.

---
 updatedshmup.p8 | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/updatedshmup.p8 b/updatedshmup.p8
index d2ab8df..1a7ac7e 100644
--- a/updatedshmup.p8
+++ b/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