Home /Modules/advantage/advantage_store.cpp

advantage_store.cpp

advantage/advantage_store.cpp · 355 line(s) · c

// advantage_store.cpp - Implementation of the advantages.xml loader.
//
// A compact, dependency-free parser for the advantages.xml schema. It walks
// the document element-by-element, understanding exactly the tags this
// module emits: <advantages>, <sourceAdvantage>, <name>, <description>,
// <assumptions>/<assumption> (optional status="held|doubted">),
// <knowledge>/<string>, <knowledgeSource>, and <evidence>/<observation>.
// Unknown tags are skipped, but malformed values in the fields that feed the
// math (numbers, assumption status, duplicate ids, stray <observation>) are
// rejected with an error rather than silently coerced. This avoids pulling in an external XML library while still
// loading the data faithfully into memory for analysis.
#include "advantage_store.hpp"

#include <cctype>
#include <cerrno>
#include <cmath>
#include <cstdlib>
#include <fstream>
#include <string>

namespace advantage {

const SourceAdvantage* AdvantageStore::find(const std::string& id) const {
    for (const auto& s : sources) {
        if (s.id == id) return &s;
    }
    return nullptr;
}

std::size_t AdvantageStore::assumptionCount() const {
    std::size_t n = 0;
    for (const auto& s : sources) n += s.assumptions.size();
    return n;
}

std::size_t AdvantageStore::knowledgeCount() const {
    std::size_t n = 0;
    for (const auto& s : sources) n += s.knowledge.size();
    return n;
}

std::size_t AdvantageStore::evidenceCount() const {
    std::size_t n = 0;
    for (const auto& s : sources) n += s.evidence.size();
    return n;
}

namespace {

// Minimal cursor-based scanner over the XML text.
struct Scanner {
    const std::string& s;
    std::size_t i = 0;
    explicit Scanner(const std::string& text) : s(text) {}

    bool eof() const { return i >= s.size(); }

    // Advance to the next '<'. Returns false at end of input.
    bool toNextTag() {
        while (i < s.size() && s[i] != '<') ++i;
        return i < s.size();
    }
};

// Replace the handful of XML entities our documents can contain.
std::string unescape(const std::string& in) {
    std::string out;
    out.reserve(in.size());
    for (std::size_t k = 0; k < in.size();) {
        if (in[k] == '&') {
            if (in.compare(k, 5, "&amp;") == 0) { out += '&'; k += 5; continue; }
            if (in.compare(k, 4, "&lt;") == 0)  { out += '<'; k += 4; continue; }
            if (in.compare(k, 4, "&gt;") == 0)  { out += '>'; k += 4; continue; }
            if (in.compare(k, 6, "&quot;") == 0){ out += '"'; k += 6; continue; }
            if (in.compare(k, 6, "&apos;") == 0){ out += '\''; k += 6; continue; }
        }
        out += in[k++];
    }
    return out;
}

std::string trim(const std::string& in) {
    std::size_t a = 0, b = in.size();
    while (a < b && std::isspace(static_cast<unsigned char>(in[a]))) ++a;
    while (b > a && std::isspace(static_cast<unsigned char>(in[b - 1]))) --b;
    return in.substr(a, b - a);
}

// Represents one parsed start/end/empty/decl/comment tag.
struct Tag {
    enum Type { Start, End, Empty, Skip } type = Skip;
    std::string name;
    std::string attrs;  // raw attribute text (between name and '>')
};

// Read the next tag starting at a '<'. Advances the scanner past '>'.
bool readTag(Scanner& sc, Tag& tag) {
    if (!sc.toNextTag()) return false;
    ++sc.i;  // consume '<'

    // Comments and declarations: skip wholesale.
    if (sc.i < sc.s.size() && (sc.s[sc.i] == '!' || sc.s[sc.i] == '?')) {
        if (sc.s.compare(sc.i, 3, "!--") == 0) {
            std::size_t end = sc.s.find("-->", sc.i);
            sc.i = (end == std::string::npos) ? sc.s.size() : end + 3;
        } else {
            std::size_t end = sc.s.find('>', sc.i);
            sc.i = (end == std::string::npos) ? sc.s.size() : end + 1;
        }
        tag.type = Tag::Skip;
        return true;
    }

    bool closing = false;
    if (sc.i < sc.s.size() && sc.s[sc.i] == '/') { closing = true; ++sc.i; }

    // Tag name.
    std::size_t start = sc.i;
    while (sc.i < sc.s.size() && sc.s[sc.i] != '>' && sc.s[sc.i] != '/' &&
           !std::isspace(static_cast<unsigned char>(sc.s[sc.i]))) {
        ++sc.i;
    }
    tag.name = sc.s.substr(start, sc.i - start);

    // Remainder up to '>' is attributes (and possible self-closing '/').
    std::size_t gt = sc.s.find('>', sc.i);
    if (gt == std::string::npos) return false;
    std::string rest = sc.s.substr(sc.i, gt - sc.i);
    sc.i = gt + 1;

    bool selfClose = (!rest.empty() && rest.back() == '/');
    if (selfClose) rest.pop_back();
    tag.attrs = rest;

    if (closing)       tag.type = Tag::End;
    else if (selfClose) tag.type = Tag::Empty;
    else               tag.type = Tag::Start;
    return true;
}

// Pull a single attribute value out of a raw attribute string. The name must
// match whole: it has to start the string or follow whitespace, so looking up
// "weight" can never be satisfied by "xweight" and "id" never by "uuid".
std::string attr(const std::string& attrs, const std::string& key) {
    const std::string needle = key + "=\"";
    std::size_t p = 0;
    while ((p = attrs.find(needle, p)) != std::string::npos) {
        const bool boundary =
            p == 0 || std::isspace(static_cast<unsigned char>(attrs[p - 1]));
        if (boundary) {
            std::size_t v = p + needle.size();
            std::size_t q = attrs.find('"', v);
            if (q == std::string::npos) return "";
            return unescape(attrs.substr(v, q - v));
        }
        p += 1;
    }
    return "";
}

// Read text content from the current position up to the next '<'.
std::string readText(Scanner& sc) {
    std::size_t start = sc.i;
    while (sc.i < sc.s.size() && sc.s[sc.i] != '<') ++sc.i;
    return trim(unescape(sc.s.substr(start, sc.i - start)));
}

// Strict number parse: the whole string must be a finite number. Fails
// closed so a typo in the XML can never silently become 0.
bool parseNumber(const std::string& text, double& out) {
    if (text.empty()) return false;
    char* end = nullptr;
    errno = 0;
    double v = std::strtod(text.c_str(), &end);
    if (errno != 0 || end == text.c_str() || *end != '\0') return false;
    if (!std::isfinite(v)) return false;
    out = v;
    return true;
}

}  // namespace

bool loadFromString(const std::string& xml,
                    AdvantageStore& out,
                    std::string& error) {
    out = AdvantageStore{};
    if (xml.size() > kMaxDocumentBytes) {
        error = "document exceeds the " + std::to_string(kMaxDocumentBytes) +
                "-byte limit";
        return false;
    }
    Scanner sc(xml);
    Tag tag;

    SourceAdvantage* current = nullptr;
    bool inAssumptions = false;
    bool inKnowledge = false;
    bool inEvidence = false;
    bool sawRoot = false;
    bool closedRoot = false;

    while (readTag(sc, tag)) {
        if (tag.type == Tag::Skip) continue;

        if (tag.type == Tag::Start || tag.type == Tag::Empty) {
            if (tag.name == "advantages") {
                sawRoot = true;
                out.version = attr(tag.attrs, "version");
            } else if (tag.name == "sourceAdvantage") {
                if (out.sources.size() >= kMaxSources) {
                    error = "more than " + std::to_string(kMaxSources) +
                            " sourceAdvantage elements";
                    return false;
                }
                out.sources.emplace_back();
                current = &out.sources.back();
                current->id = attr(tag.attrs, "id");
                if (!current->id.empty()) {
                    for (std::size_t k = 0; k + 1 < out.sources.size(); ++k) {
                        if (out.sources[k].id == current->id) {
                            error = "duplicate sourceAdvantage id '" +
                                    current->id + "'";
                            return false;
                        }
                    }
                }
                current->kind = attr(tag.attrs, "kind");
            } else if (tag.name == "knowledgeSource") {
                // Declared remote origin. Recorded only; never fetched here.
                if (current) {
                    KnowledgeSource ks;
                    ks.url = attr(tag.attrs, "url");
                    ks.sha256 = attr(tag.attrs, "sha256");
                    if (!ks.url.empty()) current->knowledgeSources.push_back(ks);
                }
            } else if (tag.name == "assumptions") {
                inAssumptions = true;
            } else if (tag.name == "knowledge") {
                inKnowledge = true;
            } else if (tag.name == "evidence" && current) {
                inEvidence = tag.type == Tag::Start;
                std::string w = attr(tag.attrs, "weight");
                if (!w.empty() && !parseNumber(w, current->evidenceWeight)) {
                    error = "source '" + current->id +
                            "': invalid evidence weight '" + w + "'";
                    return false;
                }
                if (current->evidenceWeight < 0.0) {
                    error = "source '" + current->id +
                            "': evidence weight must not be negative";
                    return false;
                }
            } else if (tag.name == "observation" && current && inEvidence) {
                Observation ob;
                if (!parseNumber(attr(tag.attrs, "reward"), ob.reward) ||
                    !parseNumber(attr(tag.attrs, "baseline"), ob.baseline)) {
                    error = "source '" + current->id +
                            "': <observation> needs numeric reward and baseline";
                    return false;
                }
                if (current->evidence.size() >= kMaxObservationsPerSource) {
                    error = "source '" + current->id + "': more than " +
                            std::to_string(kMaxObservationsPerSource) +
                            " observations";
                    return false;
                }
                current->evidence.push_back(ob);
            } else if (tag.name == "observation") {
                error = "<observation> must appear inside <evidence> within a "
                        "<sourceAdvantage>";
                return false;
            } else if (current && tag.type == Tag::Start) {
                if (tag.name == "name") {
                    current->name = readText(sc);
                } else if (tag.name == "description") {
                    current->description = readText(sc);
                } else if (tag.name == "assumption" && inAssumptions) {
                    const std::string status = attr(tag.attrs, "status");
                    if (!status.empty() && status != "held" &&
                        status != "doubted") {
                        error = "source '" + current->id +
                                "': assumption status must be 'held' or "
                                "'doubted', got '" + status + "'";
                        return false;
                    }
                    current->assumptions.push_back(readText(sc));
                    current->assumptionHeld.push_back(status != "doubted");
                } else if (tag.name == "string" && inKnowledge) {
                    current->knowledge.push_back(readText(sc));
                }
            }
        } else if (tag.type == Tag::End) {
            if (tag.name == "assumptions") inAssumptions = false;
            else if (tag.name == "knowledge") inKnowledge = false;
            else if (tag.name == "evidence") inEvidence = false;
            else if (tag.name == "advantages") closedRoot = true;
            else if (tag.name == "sourceAdvantage") current = nullptr;
        }
    }

    // The tag scanner stops quietly at end of input or at a tag with no
    // closing '>'. Either way, anything left open means the document was cut
    // short, and a partial store must not pass for a complete one.
    if (!sc.eof()) {
        error = "malformed document: tag is missing its closing '>'";
        return false;
    }
    if (current != nullptr || inAssumptions || inKnowledge || inEvidence ||
        !sawRoot || !closedRoot) {
        error = "truncated document: unclosed element (expected "
                "</advantages> after every </sourceAdvantage>)";
        return false;
    }
    if (out.sources.empty()) {
        error = "no <sourceAdvantage> elements found";
        return false;
    }
    error.clear();
    return true;
}

bool loadFromFile(const std::string& path,
                  AdvantageStore& out,
                  std::string& error) {
    std::ifstream in(path, std::ios::binary);
    if (!in) {
        error = "could not open file: " + path;
        return false;
    }
    // Learn the size first so an enormous file is rejected without being
    // pulled into memory, and a small one allocates only what it needs.
    in.seekg(0, std::ios::end);
    const std::streamoff len = in.tellg();
    if (len < 0) {
        error = "could not determine size of file: " + path;
        return false;
    }
    if (static_cast<std::size_t>(len) > kMaxDocumentBytes) {
        out = AdvantageStore{};
        error = "document exceeds the " + std::to_string(kMaxDocumentBytes) +
                "-byte limit";
        return false;
    }
    in.seekg(0, std::ios::beg);
    std::string text(static_cast<std::size_t>(len), '\0');
    in.read(&text[0], len);
    if (static_cast<std::streamoff>(in.gcount()) != len) {
        error = "short read from file: " + path;
        return false;
    }
    return loadFromString(text, out, error);
}

}  // namespace advantage