klammertext/mac/error.h

#pragma once

#include <string>
#include <utility>
#include <vector>

#include "locator.h"

inline std::string command_name { "Command executed on the command line" };
inline std::string command_pathname { "Pathname of command executed on the command line" };


class Error : std::exception {
public:
    Error(const std::string& error_type, const std::string& description,
          const Locator& locator = Locator())
        : m_type(error_type)
        , m_desc(description)
        , m_loc(locator)
        {}

    // The report text as the commands print it -- the header naming the
    // command and the error kind, the location when there is one, and the
    // description justified to 80 columns -- WITHOUT colour or the
    // surrounding newlines.  print_message() writes exactly this to stderr;
    // the Python binding (kpy/) makes it the exception's str(), which is
    // why the two are one function: an error reads the same from a script
    // as from ktext.  const: the former print_message mutated m_desc.
    std::string message(const std::string& epilog="") const;
    void print_message(const std::string& epilog="");

    // Where the error is reported: the OUTERMOST klammer application it
    // escaped through when there is one -- the place in the user's document
    // -- else where it was raised.  The commands' report headlines this and
    // the Python binding's line/column are this (2026-09-25; before, an
    // error raised inside a klammer's body, such as an @eval in
    // sks/image/image.k, was located there and the document never named).
    const Locator& location() const
        { return m_applications.empty() ? m_loc : m_applications.back().second; }

    std::string m_type {};
    std::string m_desc {};
    Locator m_loc; // {};
    // The klammer applications the error escaped through, innermost first:
    // (name, where applied).  Filled by Machine::apply_klammer_registry as
    // the exception unwinds; message() prints the chain after the headline.
    std::vector<std::pair<std::string, Locator>> m_applications {};
};


class Parsing_error : public Error {
public:
    explicit Parsing_error(
        const std::string& description, const Locator& locator=Locator()) 
        : Error("parsing", description, locator) {};
};

class File_error : public Error {
public:
    explicit File_error(
        const std::string& description, const Locator& locator=Locator()) 
        : Error("file", description, locator) {};
};

class Target_error : public Error {
public:
    explicit Target_error(
        const std::string& description, const Locator& locator=Locator()) 
        : Error("target", description, locator) {};
};

class Klammerset_error : public Error {
public:
    explicit Klammerset_error(
        const std::string& description, const Locator& locator=Locator())
        : Error("klammerset", description, locator) {};
};

class Definition_error : public Error {
public:
    explicit Definition_error(
        const std::string& description, const Locator& locator=Locator()) 
        : Error("definition", description, locator) {};
};

class Argument_error : public Error {
public:
    explicit Argument_error(
        const std::string& description, const Locator& locator=Locator()) 
        : Error("argument", description, locator) {};
};

class Environment_error : public Error {
public:
    explicit Environment_error(
        const std::string& description, const Locator& locator=Locator()) 
        : Error("environment", description, locator) {};
};

// Klammer application nested deeper than the engine's limit.  Raised by the
// depth guard in Machine::apply_klammer(); without it a klammer that applies
// itself (directly or through a cycle) exhausts the C++ stack and the process
// dies with SIGSEGV and no diagnostic at all.
class Recursion_error : public Error {
public:
    explicit Recursion_error(
        const std::string& description, const Locator& locator=Locator())
        : Error("recursion", description, locator) {};
};

class Internal_error : public Error {
public:
    explicit Internal_error(
        const std::string& description, const Locator& locator=Locator()) 
        : Error("internal", description, locator) {};
};