language_handler.h
impl/frontend/language_handler.h · 110 line(s) · c
// ===========================================================================
// language_handler.h -- the neutral interface between the SLeeLa compiler and
// a source-language handler module.
// ===========================================================================
// The compiler (parser, semantic analysis, code generation, driver) knows
// nothing about any foreign language. A language such as Java is supported by a
// HANDLER MODULE that implements this interface and registers itself at load
// time (see frontend/java/java_handler.cpp). The compiler asks the registry
// at a small number of fixed hook points and acts on the answer; it never
// names a foreign library, marker, or naming convention itself.
//
// Removing a handler's object file from FE_SRC in impl/Makefile removes that
// language's support entirely and leaves the SLeeLa language, the VM and the
// runtime unchanged. With no handler registered every hook is a no-op:
// references resolve by exact name, there are no document markers, and a
// program that needs a handler-provided library reports it as not loaded.
//
// Spec: Java Specific Section, lib/java/JAVA.SPEC.md (handler architecture).
// Review: impl/frontend/COMPILER-JAVA-REVIEW.md.
// ===========================================================================
#ifndef SLEELA_LANGUAGE_HANDLER_H
#define SLEELA_LANGUAGE_HANDLER_H
#include "ast.h"
#include "version.h"
#include <map>
#include <string>
#include <vector>
namespace sleela {
using ClassIndexMap = std::map<std::string,const ClassDecl*>;
// A contextual Preonem document marker a handler claims (e.g. `spark;`).
struct DocumentMarker {
std::string word;
SyntaxVersion minSyntax; // the marker needs #sleela >= minSyntax
};
class LanguageHandler {
public:
virtual ~LanguageHandler() {}
virtual const char* name() const = 0;
// Preonem markers this handler claims; the parser records them in
// Program::markers and semantic analysis enforces minSyntax.
virtual std::vector<DocumentMarker> documentMarkers() const { return {}; }
// Resolve a declared type reference against the loaded classes. Return the
// class name it denotes, or "" for "no opinion" (the caller keeps `declared`).
virtual std::string resolveReference(const ClassIndexMap&, const std::string&) const { return ""; }
// Erase a declared signature type to a type the VM supports. `typeVars` is
// the parser's stack of declared type-variable scopes. Return "" for no opinion.
virtual std::string eraseSignatureType(const std::string&, const std::vector<std::vector<std::string>>&) const { return ""; }
// Library class that provides instance methods on a String receiver (""
// when the handler provides none) and the document syntax from which the
// facility is available.
virtual std::string stringMethodLibrary() const { return ""; }
// Library function ("Class::method", static, two parameters: kind, message)
// that builds the exception a VM fault throws inside a try ("" for none).
virtual std::string faultFunction() const { return ""; }
// Library classes the program needs loaded, given its parsed form, its
// source text and the classes already present. Used by the driver's seeding loop.
virtual std::vector<std::string> libraryNeeds(const Program&, const std::string& /*source*/) const { return {}; }
// Narrow the library units that share the simple name `name`. `paths` are the
// candidates (library-relative paths) already restricted to the preferred
// import roots; return the subset to keep. Used for families that ship
// several kinds of unit for one name (real sources, generated reference
// files, per-edition trees). Default: keep all.
virtual std::vector<std::string> filterLibraryCandidates(const std::string& /*name*/,const std::vector<std::string>& paths,const std::vector<std::string>& /*preferredRoots*/) const { return paths; }
// Execution host: offer the arguments of `sleela run <args...>` (or a single
// file path) to the handler. Return true when the handler ran them, with
// the process exit status in `rc`; false leaves the arguments to the core.
// A handler that launches an external runtime implements this in its own
// host object so the compile-time module has no runtime dependency.
virtual bool runHost(const std::vector<std::string>& /*args*/, int& /*rc*/) const { return false; }
// Validate handler-owned metadata on the parsed program; throw on violation.
virtual void validateProgram(const Program&) const {}
};
namespace lang {
// Registry (function-local static: safe during static initialization).
void registerHandler(LanguageHandler* h);
const std::vector<LanguageHandler*>& handlers();
// Self-registration helper: a handler defines one static Registrar.
struct Registrar { explicit Registrar(LanguageHandler* h) { registerHandler(h); } };
// Dispatch helpers: ask every handler in registration order.
std::vector<DocumentMarker> documentMarkers();
bool isDocumentMarker(const std::string& word);
const DocumentMarker* findDocumentMarker(const std::string& word);
// Resolve a reference; returns `declared` unchanged when no handler claims it.
std::string resolveReference(const ClassIndexMap& byName, const std::string& declared);
std::string eraseSignatureType(const std::string& source, const std::vector<std::vector<std::string>>& typeVars);
std::string stringMethodLibrary();
std::string faultFunction();
std::vector<std::string> libraryNeeds(const Program&, const std::string& source);
void validateProgram(const Program&);
std::vector<std::string> filterLibraryCandidates(const std::string& name,const std::vector<std::string>& paths,const std::vector<std::string>& preferredRoots);
// Offer `run` arguments to each handler host; true when one ran them.
bool runHost(const std::vector<std::string>& args,int& rc);
}
}
#endif