Feature: go to text/start reference in epub guide section at first start (#156)

This parses the guide section in the content.opf for text/start
references and jumps to this on first open of the book.

Currently, this behavior will be repeated in case the reader manually
jumps to Chapter 0 and then re-opens the book. IMO, this is an
acceptable edge case (for which I couldn't see a good fix other than to
drag a "first open" boolean around).

---------

Co-authored-by: Sam Davis <sam@sjd.co>
Co-authored-by: Dave Allie <dave@daveallie.com>

lib/Epub/Epub/parsers/ContentOpfParser.cpp

@@ -127,6 +127,18 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
     return;
   }
 
+  if (self->state == IN_PACKAGE && (strcmp(name, "guide") == 0 || strcmp(name, "opf:guide") == 0)) {
+    self->state = IN_GUIDE;
+    // TODO Remove print
+    Serial.printf("[%lu] [COF] Entering guide state.\n", millis());
+    if (!SdMan.openFileForRead("COF", self->cachePath + itemCacheFile, self->tempItemStore)) {
+      Serial.printf(
+          "[%lu] [COF] Couldn't open temp items file for reading. This is probably going to be a fatal error.\n",
+          millis());
+    }
+    return;
+  }
+
   if (self->state == IN_METADATA && (strcmp(name, "meta") == 0 || strcmp(name, "opf:meta") == 0)) {
     bool isCover = false;
     std::string coverItemId;
@@ -205,6 +217,29 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
       return;
     }
   }
+  // parse the guide
+  if (self->state == IN_GUIDE && (strcmp(name, "reference") == 0 || strcmp(name, "opf:reference") == 0)) {
+    std::string type;
+    std::string textHref;
+    for (int i = 0; atts[i]; i += 2) {
+      if (strcmp(atts[i], "type") == 0) {
+        type = atts[i + 1];
+        if (type == "text" || type == "start") {
+          continue;
+        } else {
+          Serial.printf("[%lu] [COF] Skipping non-text reference in guide: %s\n", millis(), type.c_str());
+          break;
+        }
+      } else if (strcmp(atts[i], "href") == 0) {
+        textHref = self->baseContentPath + atts[i + 1];
+      }
+    }
+    if ((type == "text" || (type == "start" && !self->textReferenceHref.empty())) && (textHref.length() > 0)) {
+      Serial.printf("[%lu] [COF] Found %s reference in guide: %s.\n", millis(), type.c_str(), textHref.c_str());
+      self->textReferenceHref = textHref;
+    }
+    return;
+  }
 }
 
 void XMLCALL ContentOpfParser::characterData(void* userData, const XML_Char* s, const int len) {
@@ -231,6 +266,12 @@ void XMLCALL ContentOpfParser::endElement(void* userData, const XML_Char* name)
     return;
   }
 
+  if (self->state == IN_GUIDE && (strcmp(name, "guide") == 0 || strcmp(name, "opf:guide") == 0)) {
+    self->state = IN_PACKAGE;
+    self->tempItemStore.close();
+    return;
+  }
+
   if (self->state == IN_MANIFEST && (strcmp(name, "manifest") == 0 || strcmp(name, "opf:manifest") == 0)) {
     self->state = IN_PACKAGE;
     self->tempItemStore.close();

lib/Epub/Epub/parsers/ContentOpfParser.h

@@ -15,6 +15,7 @@ class ContentOpfParser final : public Print {
     IN_BOOK_AUTHOR,
     IN_MANIFEST,
     IN_SPINE,
+    IN_GUIDE,
   };
 
   const std::string& cachePath;
@@ -35,6 +36,7 @@ class ContentOpfParser final : public Print {
   std::string author;
   std::string tocNcxPath;
   std::string coverItemHref;
+  std::string textReferenceHref;
 
   explicit ContentOpfParser(const std::string& cachePath, const std::string& baseContentPath, const size_t xmlSize,
                             BookMetadataCache* cache)