From b9bb704fb7270ad695468db5e64f8f0c8db52e49 Mon Sep 17 00:00:00 2001 From: panayotis_kalaitzoglou Date: Tue, 10 Nov 2026 20:05:22 +0200 Subject: [PATCH 1/8] refactor: share declaration resolution across interpreters --- CSharp/Interpreter/ArcscriptContext.cs | 45 +++++++++++++ CSharp/Interpreter/ArcscriptParserBase.cs | 17 ++--- CSharp/Interpreter/ArcscriptState.cs | 11 ++++ CSharp/Interpreter/ArcscriptTranspiler.cs | 19 ++++-- CSharp/Interpreter/ArcscriptVisitor.cs | 66 ++++++++----------- Cpp/src/ArcscriptContext.h | 30 +++++++++ Cpp/src/ArcscriptHelpers.h | 25 ++++--- Cpp/src/ArcscriptParserBase.cpp | 2 +- Cpp/src/ArcscriptParserBase.h | 8 ++- Cpp/src/ArcscriptTranspiler.cpp | 16 ++++- Cpp/src/ArcscriptTranspiler.h | 3 + Cpp/src/ArcscriptVisitor.cpp | 47 +++++++------ Cpp/src/ArcscriptVisitor.h | 6 +- TypeScript/src/ArcscriptContext.ts | 35 ++++++++++ TypeScript/src/ArcscriptState.ts | 6 ++ TypeScript/src/ArcscriptVisitor.ts | 52 ++++++++------- .../src/Generated/ArcscriptParserBase.ts | 19 ++---- TypeScript/src/antlr4.interpreter.ts | 20 +++--- 18 files changed, 285 insertions(+), 142 deletions(-) create mode 100644 CSharp/Interpreter/ArcscriptContext.cs create mode 100644 Cpp/src/ArcscriptContext.h create mode 100644 TypeScript/src/ArcscriptContext.ts diff --git a/CSharp/Interpreter/ArcscriptContext.cs b/CSharp/Interpreter/ArcscriptContext.cs new file mode 100644 index 0000000..d8c2a7b --- /dev/null +++ b/CSharp/Interpreter/ArcscriptContext.cs @@ -0,0 +1,45 @@ +using System; +using System.Collections.Generic; +using System.Linq; +using Arcweave.Project; + +namespace Arcweave.Interpreter +{ + public enum ReferenceKind { Variable } + + public sealed class ArcscriptReference + { + public ReferenceKind Kind { get; } + public string VariableId { get; } + public Type Type { get; } + + internal ArcscriptReference(ReferenceKind kind, Type type, string variableId) + { + Kind = kind; + Type = type; + VariableId = variableId; + } + } + + // A snapshot of declarations, shared by parsing and execution. + public sealed class ArcscriptContext + { + private readonly Dictionary _references = new Dictionary(); + + public ArcscriptContext(IEnumerable variables = null) + { + foreach (var variable in variables ?? Enumerable.Empty()) + { + var name = variable.Parent == null ? variable.Name : variable.Parent.CustomId + "." + variable.Name; + // Preserve the existing first-match behavior for ordinary variable names. + if (!_references.ContainsKey(name)) + _references.Add(name, new ArcscriptReference(ReferenceKind.Variable, variable.Type, variable.Id)); + } + } + + public ArcscriptReference Resolve(string name) + { + return _references.TryGetValue(name, out var reference) ? reference : null; + } + } +} diff --git a/CSharp/Interpreter/ArcscriptParserBase.cs b/CSharp/Interpreter/ArcscriptParserBase.cs index f8f9f91..7ee2b96 100644 --- a/CSharp/Interpreter/ArcscriptParserBase.cs +++ b/CSharp/Interpreter/ArcscriptParserBase.cs @@ -10,7 +10,7 @@ namespace Arcweave.Interpreter public class ArcscriptParserBase : Parser { private protected IProject Project { get; private set; } - private protected List VariableNames = new List(); + public ArcscriptContext Declarations { get; private set; } internal int currentLine; internal int openTagEndPos; @@ -24,14 +24,9 @@ public ArcscriptParserBase(ITokenStream input, TextWriter output, TextWriter err { } - public void SetProject(IProject project) { + public void SetProject(IProject project, ArcscriptContext declarations = null) { this.Project = project; - foreach (var projectVariable in project.GetAllVariables()) - { - VariableNames.Add(projectVariable.Parent == null - ? projectVariable.Name - : projectVariable.Parent.CustomId + "." + projectVariable.Name); - } + Declarations = declarations ?? new ArcscriptContext(variables: project.GetAllVariables()); } public override string[] RuleNames => throw new System.NotImplementedException(); @@ -43,10 +38,8 @@ public void SetProject(IProject project) { public bool assertVariable(ArcscriptParser.IdentifierContext identifierContext) { var variableName = identifierContext.GetText(); - var found = VariableNames.First(name => name == variableName); - if ( found != null ) { - return false; - } + if (Declarations.Resolve(variableName) == null) + throw new ParseException($"The variable {variableName} does not exist"); return true; } diff --git a/CSharp/Interpreter/ArcscriptState.cs b/CSharp/Interpreter/ArcscriptState.cs index f474ec4..e2c9827 100644 --- a/CSharp/Interpreter/ArcscriptState.cs +++ b/CSharp/Interpreter/ArcscriptState.cs @@ -68,6 +68,17 @@ public object GetVarValue(string name, string? scope = null) return this.VariableChanges.ContainsKey(v.Id) ? VariableChanges[v.Id] : v.ObjectValue; } + public Variable GetVariableById(string id) => Variables[id]; + + public object GetVarValueById(string id) => + VariableChanges.TryGetValue(id, out var value) ? value : GetVariableById(id).ObjectValue; + + public void SetVarValueById(string id, object value) + { + if (!Variables.ContainsKey(id)) throw new System.InvalidOperationException($"Variable {id} not found"); + VariableChanges[id] = value; + } + public void SetVarValue(IVariable v, object value) { VariableChanges[v.Id] = value; diff --git a/CSharp/Interpreter/ArcscriptTranspiler.cs b/CSharp/Interpreter/ArcscriptTranspiler.cs index 889fea2..527cfff 100644 --- a/CSharp/Interpreter/ArcscriptTranspiler.cs +++ b/CSharp/Interpreter/ArcscriptTranspiler.cs @@ -26,8 +26,13 @@ public AwInterpreter(IProject project, string elementId = "", System.Action new ArcscriptContext(Project.GetAllVariables()); + + public ArcscriptParser.InputContext Parse(string code) => ParseWithContext(code).Tree; + + private (ArcscriptParser.InputContext Tree, ArcscriptContext Declarations) ParseWithContext(string code) { + var declarations = CreateContext(); ICharStream stream = CharStreams.fromString(code); ArcscriptLexer lexer = new ArcscriptLexer(stream); var lexerErrorListener = new ErrorListener(); @@ -36,7 +41,7 @@ private ArcscriptParser.InputContext GetParseTree(string code) var parserErrorListener = new ErrorListener(); ArcscriptParser parser = new ArcscriptParser(tokens); parser.AddErrorListener(parserErrorListener); - parser.SetProject(Project); + parser.SetProject(Project, declarations); ArcscriptParser.InputContext tree = parser.input(); @@ -49,7 +54,7 @@ private ArcscriptParser.InputContext GetParseTree(string code) throw new ParseException("Parsing errors:\n" + string.Join("\n", parserErrorListener.Errors)); } - return tree; + return (tree, declarations); } public TranspilerOutput RunScript(string code) @@ -59,17 +64,19 @@ public TranspilerOutput RunScript(string code) return new TranspilerOutput(); } - ArcscriptParser.InputContext tree; + (ArcscriptParser.InputContext Tree, ArcscriptContext Declarations) parsed; try { - tree = this.GetParseTree(code); + parsed = ParseWithContext(code); } catch (System.Exception e) { throw new ParseException(e.Message, e); } - ArcscriptVisitor visitor = new ArcscriptVisitor(this.ElementId, this.Project, _emit); + var tree = parsed.Tree; + ArcscriptVisitor visitor = new ArcscriptVisitor(this.ElementId, this.Project, _emit, + parsed.Declarations); object result; try { diff --git a/CSharp/Interpreter/ArcscriptVisitor.cs b/CSharp/Interpreter/ArcscriptVisitor.cs index 4c750bf..0092a1b 100644 --- a/CSharp/Interpreter/ArcscriptVisitor.cs +++ b/CSharp/Interpreter/ArcscriptVisitor.cs @@ -17,7 +17,9 @@ public class ArcscriptVisitor : ArcscriptParserBaseVisitor public string elementId; private readonly Functions _functions; private System.Action _emit; - public ArcscriptVisitor(string elementId, IProject project, System.Action? emit = null) { + private readonly ArcscriptContext _declarations; + public ArcscriptVisitor(string elementId, IProject project, System.Action? emit = null, ArcscriptContext? declarations = null) { + _declarations = declarations ?? new ArcscriptContext(variables: project.GetAllVariables()); this.elementId = elementId; this.project = project; this.state = new ArcscriptState(elementId, project, emit); @@ -163,14 +165,14 @@ public override object VisitElse_if_clause([NotNull] ArcscriptParser.Else_if_cla public override object VisitStatement_assignment([NotNull] ArcscriptParser.Statement_assignmentContext context) { - var identifier = (IdentifierDef) this.VisitAssignable(context.assignable()); + var identifier = (ArcscriptReference) this.VisitAssignable(context.assignable()); - var identifierValue = new Expression(this.state.GetVarValue(identifier.Name, identifier.Scope)); + var identifierValue = new Expression(ReadReference(identifier)); var re = (Expression)Visit(context.expression())!; if ( context.ASSIGN() != null ) { - this.state.SetVarValue(identifier, re.Value); + this.state.SetVarValueById(identifier.VariableId, re.Value); return null!; } @@ -186,7 +188,7 @@ public override object VisitStatement_assignment([NotNull] ArcscriptParser.State identifierValue %= re; } - this.state.SetVarValue(identifier, identifierValue.Value); + this.state.SetVarValueById(identifier.VariableId, identifierValue.Value); return null!; } @@ -316,8 +318,7 @@ public override object VisitParenthesizedExpression(ArcscriptParser.Parenthesize public override object VisitIdentifierExpression(ArcscriptParser.IdentifierExpressionContext context) { - var identifier = (IdentifierDef)VisitIdentifier(context.identifier()); - return new Expression(this.state.GetVarValue(identifier.Name, identifier.Scope)); + return new Expression(ReadReference((ArcscriptReference)VisitIdentifier(context.identifier()))); } public override object VisitLiteralExpression(ArcscriptParser.LiteralExpressionContext context) @@ -369,26 +370,13 @@ public override object VisitFunction_call([NotNull] ArcscriptParser.Function_cal if (context.identifier_list() != null) { - argument_list_result = (IList)this.VisitIdentifier_list(context.identifier_list()); - if (Functions.FunctionDefinitions.ContainsKey(fname)) - { - if (Functions.FunctionDefinitions[fname].ArgumentsType == typeof(Variable)) - { - for (int i = 0; i < argument_list_result.Count; i++) - { - IdentifierDef identifierDef = (IdentifierDef)argument_list_result[i]; - argument_list_result[i] = this.state.GetVariable(identifierDef.Name, identifierDef.Scope); - } - } - else - { - for (int i = 0; i < argument_list_result.Count; i++) - { - IdentifierDef identifierDef = (IdentifierDef)argument_list_result[i]; - argument_list_result[i] = new Expression(this.state.GetVarValue(identifierDef.Name, identifierDef.Scope)); - } - } - } + var references = (IList)VisitIdentifier_list(context.identifier_list()); + argument_list_result = references.Select(value => { + var reference = (ArcscriptReference)value; + return Functions.FunctionDefinitions[fname].ArgumentsType == typeof(Variable) + ? (object)ReadVariable(reference) + : new Expression(ReadReference(reference)); + }).ToList(); } object returnValue = this._functions.functions[fname](argument_list_result); @@ -420,20 +408,18 @@ public override object VisitIdentifier_list(ArcscriptParser.Identifier_listConte public override object VisitIdentifier(ArcscriptParser.IdentifierContext context) { - string name = ""; - string? scope = null; - if (context.IDENTIFIER().Length == 1) - { - name = context.IDENTIFIER(0).GetText(); - } - else - { - scope = context.IDENTIFIER(0).GetText(); - name = context.IDENTIFIER(1).GetText(); - } - return new IdentifierDef(name, scope); + return _declarations.Resolve(context.GetText()) + ?? throw new RuntimeException($"Variable {context.GetText()} not found"); } + private Variable ReadVariable(ArcscriptReference reference) + { + return state.GetVariableById(reference.VariableId); + } + + private object ReadReference(ArcscriptReference reference) => + state.GetVarValueById(reference.VariableId); + public override object VisitMention([NotNull] ArcscriptParser.MentionContext context) { Dictionary attrs = new Dictionary(); @@ -499,4 +485,4 @@ public struct IdentifierDef public IdentifierDef(string name, string? scope = null) { Name = name; Scope = scope; } } } -} \ No newline at end of file +} diff --git a/Cpp/src/ArcscriptContext.h b/Cpp/src/ArcscriptContext.h new file mode 100644 index 0000000..d3f04ba --- /dev/null +++ b/Cpp/src/ArcscriptContext.h @@ -0,0 +1,30 @@ +#pragma once +#include "ArcscriptHelpers.h" + +namespace Arcweave { +enum class ReferenceKind { Variable }; + +struct ArcscriptReference { + ReferenceKind kind; + VariableType type; + std::string variableId; +}; + +// A snapshot of declarations, shared by parsing and execution. +class ArcscriptContext { + std::map references; +public: + explicit ArcscriptContext(const std::map& variables = {}) { + for (const auto& [id, variable] : variables) { + auto name = variable.scope.empty() ? variable.name : variable.scope + "." + variable.name; + // Match the existing native name map's last-match behavior. + references[name] = {ReferenceKind::Variable, variable.type, id}; + } + } + + const ArcscriptReference* resolve(const std::string& name) const { + auto reference = references.find(name); + return reference == references.end() ? nullptr : &reference->second; + } +}; +} diff --git a/Cpp/src/ArcscriptHelpers.h b/Cpp/src/ArcscriptHelpers.h index 77c42c0..930dcf2 100755 --- a/Cpp/src/ArcscriptHelpers.h +++ b/Cpp/src/ArcscriptHelpers.h @@ -77,20 +77,29 @@ class ArcscriptState { } inline std::any getVarValue(IdentifierDef identifier) { - std::string varId = varNameToID[getVarFullName(identifier)]; - if (variableChanges.count(varId)) { - return variableChanges[varId]; - } - return variableValues[varId].value; + return getVarValueById(varNameToID.at(getVarFullName(identifier))); } inline Variable getVar(IdentifierDef identifier) { - return variableValues[varNameToID[getVarFullName(identifier)]]; + return getVarById(varNameToID.at(getVarFullName(identifier))); } inline void setVarValue(IdentifierDef identifier, std::any value) { - std::string varId = varNameToID[getVarFullName(identifier)]; - variableChanges[varId] = value; + setVarValueById(varNameToID.at(getVarFullName(identifier)), std::move(value)); + } + + inline std::any getVarValueById(const std::string& id) const { + auto change = variableChanges.find(id); + return change != variableChanges.end() ? change->second : variableValues.at(id).value; + } + + inline const Variable& getVarById(const std::string& id) const { + return variableValues.at(id); + } + + inline void setVarValueById(const std::string& id, std::any value) { + variableValues.at(id); + variableChanges[id] = std::move(value); } inline void resetVars(std::vector vars) { diff --git a/Cpp/src/ArcscriptParserBase.cpp b/Cpp/src/ArcscriptParserBase.cpp index 8b00b6c..2bea360 100755 --- a/Cpp/src/ArcscriptParserBase.cpp +++ b/Cpp/src/ArcscriptParserBase.cpp @@ -9,7 +9,7 @@ using namespace antlr4; bool ArcscriptParserBase::assertVariable(antlr4::ParserRuleContext *identifierContext) const { std::string variableName = identifierContext->getText(); - if (_state->varNameToID.count(variableName) > 0) { + if (_declarations->resolve(variableName)) { return true; } throw Arcweave::ParseErrorException("Unknown variable \"" + variableName + "\""); diff --git a/Cpp/src/ArcscriptParserBase.h b/Cpp/src/ArcscriptParserBase.h index 7673d28..f535d71 100755 --- a/Cpp/src/ArcscriptParserBase.h +++ b/Cpp/src/ArcscriptParserBase.h @@ -1,16 +1,20 @@ #pragma once #include "antlr4-runtime.h" -#include "ArcscriptHelpers.h" +#include "ArcscriptContext.h" class ArcscriptParserBase : public antlr4::Parser { private: Arcweave::ArcscriptState* _state; + const Arcweave::ArcscriptContext* _declarations; size_t openTagEndPos; public: int currentLine = 0; ArcscriptParserBase(antlr4::TokenStream *input) : Parser(input) { } - inline void setArcscriptState(Arcweave::ArcscriptState *state) { _state = state; }; + inline void setArcscriptState(Arcweave::ArcscriptState *state, const Arcweave::ArcscriptContext& declarations) { + _state = state; + _declarations = &declarations; + }; bool assertVariable(antlr4::ParserRuleContext *variable) const; bool assertMention(std::any attrCtxList); bool assertFunctionArguments(antlr4::Token *fname, std::any listContext); diff --git a/Cpp/src/ArcscriptTranspiler.cpp b/Cpp/src/ArcscriptTranspiler.cpp index 8346243..fcd155a 100755 --- a/Cpp/src/ArcscriptTranspiler.cpp +++ b/Cpp/src/ArcscriptTranspiler.cpp @@ -16,10 +16,19 @@ using namespace Arcweave; using namespace antlr4; TranspilerOutput ArcscriptTranspiler::runScript(std::string code) { + return process(std::move(code), true); +} + +void ArcscriptTranspiler::validate(std::string code) { + process(std::move(code), false); +} + +TranspilerOutput ArcscriptTranspiler::process(std::string code, bool execute) { + const ArcscriptContext declarations(state.variableValues); ANTLRInputStream input(code); ArcscriptLexer lexer(&input); - TranspilerOutput result; + TranspilerOutput result{}; ErrorListener lexerErrorListener; lexer.removeErrorListeners(); @@ -31,7 +40,7 @@ TranspilerOutput ArcscriptTranspiler::runScript(std::string code) { tokens.fill(); ArcscriptParser parser(&tokens); - parser.setArcscriptState(&state); + parser.setArcscriptState(&state, declarations); ErrorListener parserErrorListener; parser.removeErrorListeners(); parser.addErrorListener(&parserErrorListener); @@ -40,8 +49,9 @@ TranspilerOutput ArcscriptTranspiler::runScript(std::string code) { // Run the parser tree = parser.input(); + if (!execute) return result; - ArcscriptVisitor visitor(&state); + ArcscriptVisitor visitor(&state, declarations); // Run the visitor std::any res(visitor.visitInput(tree)); diff --git a/Cpp/src/ArcscriptTranspiler.h b/Cpp/src/ArcscriptTranspiler.h index 6bbec85..1795fa1 100755 --- a/Cpp/src/ArcscriptTranspiler.h +++ b/Cpp/src/ArcscriptTranspiler.h @@ -145,6 +145,7 @@ namespace Arcweave * */ class ArcscriptTranspiler { + TranspilerOutput process(std::string code, bool execute); public: ArcscriptState state; @@ -158,6 +159,8 @@ namespace Arcweave */ TranspilerOutput runScript(std::string code); + void validate(std::string code); + //ARCSCRIPTTRANSPILER_API UTranspilerOutput URunScript(char* code); }; }; diff --git a/Cpp/src/ArcscriptVisitor.cpp b/Cpp/src/ArcscriptVisitor.cpp index c738cb5..da90618 100755 --- a/Cpp/src/ArcscriptVisitor.cpp +++ b/Cpp/src/ArcscriptVisitor.cpp @@ -136,19 +136,19 @@ std::any ArcscriptVisitor::visitElse_if_clause(ArcscriptParser::Else_if_clauseCo } std::any ArcscriptVisitor::visitStatement_assignment(ArcscriptParser::Statement_assignmentContext *ctx) { - auto identifier = std::any_cast(visitAssignable(ctx->assignable())); + auto identifier = std::any_cast(visitAssignable(ctx->assignable())); auto identifierExpr = Expression(); - identifierExpr.setValue(state->getVarValue(identifier)); + identifierExpr.setValue(readReference(identifier)); auto re = std::any_cast(visit(ctx->expression())); if (ctx->ASSIGN() != nullptr) { - state->setVarValue(identifier, re.value); + state->setVarValueById(identifier.variableId, re.value); return {}; } Expression varValue; - varValue.setValue(state->getVarValue(identifier)); + varValue.setValue(readReference(identifier)); if (ctx->ASSIGNADD() != nullptr) { varValue += re; @@ -162,7 +162,7 @@ std::any ArcscriptVisitor::visitStatement_assignment(ArcscriptParser::Statement_ varValue %= re; } - state->setVarValue(identifier, varValue.value); + state->setVarValueById(identifier.variableId, varValue.value); return {}; } @@ -264,9 +264,9 @@ std::any ArcscriptVisitor::visitParenthesizedExpression(ArcscriptParser::Parenth } std::any ArcscriptVisitor::visitIdentifierExpression(ArcscriptParser::IdentifierExpressionContext *ctx) { - auto idDef = std::any_cast(visitIdentifier(ctx->identifier())); + auto idDef = std::any_cast(visitIdentifier(ctx->identifier())); auto result = Expression(); - result.setValue(state->getVarValue(idDef)); + result.setValue(readReference(idDef)); return result; } @@ -309,15 +309,15 @@ std::any ArcscriptVisitor::visitFunction_call(ArcscriptParser::Function_callCont } if (ctx->identifier_list() != nullptr) { - auto identifierList = std::any_cast>(visitIdentifier_list(ctx->identifier_list())); + auto identifierList = std::any_cast>(visitIdentifier_list(ctx->identifier_list())); if (ArcscriptFunctions::functions[fname].argsType == "variable") { for (size_t i = 0; i < identifierList.size(); i++) { - argument_list_result.push_back(state->getVar(identifierList[i])); + argument_list_result.push_back(readVariable(identifierList[i])); } } else { for (size_t i = 0; i < identifierList.size(); i++) { auto e = Expression(); - e.setValue(state->getVarValue(identifierList[i])); + e.setValue(readReference(identifierList[i])); argument_list_result.push_back(e); } } @@ -348,26 +348,25 @@ std::any ArcscriptVisitor::visitArgument(ArcscriptParser::ArgumentContext *ctx) } std::any ArcscriptVisitor::visitIdentifier_list(ArcscriptParser::Identifier_listContext *ctx) { - std::vector identifiers; + std::vector identifiers; for (auto *id : ctx->identifier()) { - identifiers.push_back(std::any_cast(visitIdentifier(id))); + identifiers.push_back(std::any_cast(visitIdentifier(id))); } return identifiers; } std::any ArcscriptVisitor::visitIdentifier(ArcscriptParser::IdentifierContext *ctx) { - std::string name; - std::string scope; - if (ctx->IDENTIFIER().size() == 1) { - name = ctx->IDENTIFIER(0)->getText(); - } else { - scope = ctx->IDENTIFIER(0)->getText(); - name = ctx->IDENTIFIER(1)->getText(); - } - IdentifierDef def; - def.name = name; - def.scope = scope; - return def; + auto reference = declarations.resolve(ctx->getText()); + if (!reference) throw RuntimeErrorException("Variable " + ctx->getText() + " not found"); + return *reference; +} + +Variable ArcscriptVisitor::readVariable(const ArcscriptReference& reference) const { + return state->getVarById(reference.variableId); +} + +std::any ArcscriptVisitor::readReference(const ArcscriptReference& reference) const { + return state->getVarValueById(reference.variableId); } std::any ArcscriptVisitor::visitMention(ArcscriptParser::MentionContext *ctx) { diff --git a/Cpp/src/ArcscriptVisitor.h b/Cpp/src/ArcscriptVisitor.h index 7cbe9f6..33691a6 100755 --- a/Cpp/src/ArcscriptVisitor.h +++ b/Cpp/src/ArcscriptVisitor.h @@ -2,10 +2,14 @@ #include "ArcscriptParserBaseVisitor.h" #include "ArcscriptFunctions.h" +#include "ArcscriptContext.h" using namespace Arcweave; class ArcscriptVisitor : public ArcscriptParserBaseVisitor { + const ArcscriptContext& declarations; + std::any readReference(const ArcscriptReference& reference) const; + Variable readVariable(const ArcscriptReference& reference) const; public: struct ConditionalSection { bool clause; @@ -15,7 +19,7 @@ class ArcscriptVisitor : public ArcscriptParserBaseVisitor { ArcscriptState *state; ArcscriptFunctions *functions; - explicit ArcscriptVisitor(ArcscriptState* _state) : state(_state) { + ArcscriptVisitor(ArcscriptState* _state, const ArcscriptContext& context) : declarations(context), state(_state) { functions = new ArcscriptFunctions(state); } ~ArcscriptVisitor() override { diff --git a/TypeScript/src/ArcscriptContext.ts b/TypeScript/src/ArcscriptContext.ts new file mode 100644 index 0000000..43c26aa --- /dev/null +++ b/TypeScript/src/ArcscriptContext.ts @@ -0,0 +1,35 @@ +import { ArcscriptStateDef, VarType } from './types.js'; +import { isGlobalScope } from './scope.js'; + +export type ArcscriptReference = Readonly<{ + kind: 'variable'; + variableId: string; + type: VarType; +}>; + +// A snapshot of declarations, shared by parsing and execution. +export default class ArcscriptContext { + private readonly references = new Map(); + + constructor(variables: ArcscriptStateDef = {}) { + for (const variable of Object.values(variables)) { + const name = isGlobalScope(variable.scope) + ? variable.name + : `${variable.scope}.${variable.name}`; + // Preserve the existing first-match behavior for ordinary variable names. + if (!this.references.has(name)) + this.references.set( + name, + Object.freeze({ + kind: 'variable', + variableId: variable.id, + type: variable.type, + }) + ); + } + } + + resolve(name: string): ArcscriptReference | undefined { + return this.references.get(name); + } +} diff --git a/TypeScript/src/ArcscriptState.ts b/TypeScript/src/ArcscriptState.ts index bf02dfe..4378c98 100644 --- a/TypeScript/src/ArcscriptState.ts +++ b/TypeScript/src/ArcscriptState.ts @@ -122,6 +122,12 @@ export default class ArcscriptState { return variable; } + getVarById(id: string): ArcscriptVariable { + const variable = this.variables[id]; + if (!variable) throw new Error(`Variable ${id} not found`); + return variable; + } + resetVariablesExcept(excludedIds: ReadonlySet): void { Object.values(this.variables).forEach(variable => { if (!excludedIds.has(variable.id)) { diff --git a/TypeScript/src/ArcscriptVisitor.ts b/TypeScript/src/ArcscriptVisitor.ts index dc60200..6cb7c96 100644 --- a/TypeScript/src/ArcscriptVisitor.ts +++ b/TypeScript/src/ArcscriptVisitor.ts @@ -42,13 +42,17 @@ import { } from './Generated/ArcscriptParser.js'; import ArcscriptVariable from './ArcscriptVariable.js'; import ArcscriptParserBase from './Generated/ArcscriptParserBase.js'; +import ArcscriptContext, { ArcscriptReference } from './ArcscriptContext.js'; // eslint-disable-next-line @typescript-eslint/no-explicit-any export default class ArcscriptVisitor extends ArcscriptParserVisitor { private readonly state: ArcscriptState; private readonly functions: ArcscriptFunctions; - constructor(state: ArcscriptState) { + constructor( + state: ArcscriptState, + private readonly declarations: ArcscriptContext + ) { super(); this.state = state; @@ -250,7 +254,7 @@ export default class ArcscriptVisitor extends ArcscriptParserVisitor { }; visitAssignable = (ctx: AssignableContext): ArcscriptVariable => { - return this.visitIdentifier(ctx.identifier()); + return this.readVariable(this.visitIdentifier(ctx.identifier())); }; visitComparisonExpression = (ctx: ComparisonExpressionContext): boolean => { @@ -361,9 +365,7 @@ export default class ArcscriptVisitor extends ArcscriptParserVisitor { }; visitIdentifierExpression = (ctx: IdentifierExpressionContext) => { - const identifier = this.visitIdentifier(ctx.identifier()); - - return identifier.getValue(); + return this.readReference(this.visitIdentifier(ctx.identifier())); }; visitLiteralExpression = (ctx: LiteralExpressionContext) => { @@ -374,22 +376,21 @@ export default class ArcscriptVisitor extends ArcscriptParserVisitor { return this.visitFunction_call(ctx.function_call()); }; - visitIdentifier = (ctx: IdentifierContext): ArcscriptVariable => { - let name: string; - let scope: string | null = null; - if (ctx.IDENTIFIER_list().length === 1) { - name = ctx.IDENTIFIER(0).getText(); - } else { - scope = ctx.IDENTIFIER(0).getText(); - name = ctx.IDENTIFIER(1).getText(); - } - const variableObject = this.state.getVar(name, scope); - if (!variableObject) { - throw new RuntimeError(`Variable ${name} not found`); - } - return variableObject; + visitIdentifier = (ctx: IdentifierContext): ArcscriptReference => { + const reference = this.declarations.resolve(ctx.getText()); + if (!reference) + throw new RuntimeError(`Variable ${ctx.getText()} not found`); + return reference; }; + private readVariable(reference: ArcscriptReference): ArcscriptVariable { + return this.state.getVarById(reference.variableId); + } + + private readReference(reference: ArcscriptReference): VarValue { + return this.readVariable(reference).getValue(); + } + visitLiteral = (ctx: LiteralContext) => { if (ctx.BOOLEAN()) { if (ctx.BOOLEAN().getText() === 'true') { @@ -419,21 +420,26 @@ export default class ArcscriptVisitor extends ArcscriptParserVisitor { argument_list = this.visitArgument_list(ctx.argument_list()); } if (ctx.identifier_list()) { - const variables = this.visitIdentifier_list(ctx.identifier_list()); if ( ArcscriptParserBase.arcscriptFunctionsInfo[function_name].argType === 'variable' ) { - argument_list = variables; + argument_list = this.visitIdentifier_list(ctx.identifier_list()).map( + reference => this.readVariable(reference) + ); } else { - argument_list = variables.map(variable => variable.getValue()); + argument_list = this.visitIdentifier_list(ctx.identifier_list()).map( + reference => this.readReference(reference) + ); } } return this.functions[function_name](...argument_list); }; - visitIdentifier_list = (ctx: Identifier_listContext): ArcscriptVariable[] => { + visitIdentifier_list = ( + ctx: Identifier_listContext + ): ArcscriptReference[] => { return ctx.identifier_list().map(identifier => { return this.visitIdentifier(identifier); }); diff --git a/TypeScript/src/Generated/ArcscriptParserBase.ts b/TypeScript/src/Generated/ArcscriptParserBase.ts index ee6fd66..fa61267 100644 --- a/TypeScript/src/Generated/ArcscriptParserBase.ts +++ b/TypeScript/src/Generated/ArcscriptParserBase.ts @@ -5,11 +5,10 @@ import ArcscriptParser, { IdentifierContext, Mention_attributesContext, } from './ArcscriptParser.js'; -import { ArcscriptStateDef } from '../types.js'; -import { isGlobalScope } from '../scope.js'; +import ArcscriptContext from '../ArcscriptContext.js'; type ArcscriptParserOptions = { - arcscriptVariables: ArcscriptStateDef; + declarations: ArcscriptContext; elementVisits: Record; currentElement: string; }; @@ -48,7 +47,7 @@ export default class ArcscriptParserBase extends Parser { resetVisits: { minArgs: 0, maxArgs: 0, returnType: 'void' }, }; - arcscriptVariableNames: string[] = []; + declarations!: ArcscriptContext; elementVisits: Record = {}; currentElement: string = ''; currentLine: number = 0; @@ -59,15 +58,7 @@ export default class ArcscriptParserBase extends Parser { } setOptions(options: ArcscriptParserOptions) { - const variableNames = Object.values(options.arcscriptVariables).map( - variable => { - if (!isGlobalScope(variable.scope)) { - return `${variable.scope}.${variable.name}`; - } - return variable.name; - } - ); - this.arcscriptVariableNames = variableNames; + this.declarations = options.declarations; this.elementVisits = options.elementVisits; this.currentElement = options.currentElement; } @@ -119,7 +110,7 @@ export default class ArcscriptParserBase extends Parser { assertVariable(identifierCtx: IdentifierContext) { const variableName = identifierCtx.getText(); - if (!this.arcscriptVariableNames.includes(variableName)) { + if (!this.declarations.resolve(variableName)) { this.notifyErrorListeners( `The variable ${variableName} does not exist`, identifierCtx.start, diff --git a/TypeScript/src/antlr4.interpreter.ts b/TypeScript/src/antlr4.interpreter.ts index 7722f60..8f65ee5 100644 --- a/TypeScript/src/antlr4.interpreter.ts +++ b/TypeScript/src/antlr4.interpreter.ts @@ -6,6 +6,7 @@ import ArcscriptVisitor from './ArcscriptVisitor.js'; import ErrorListener from './ErrorListener.js'; import { ParseError } from './errors/index.js'; import { ArcscriptStateDef, VarValue } from './types.js'; +import ArcscriptContext from './ArcscriptContext.js'; import ArcscriptState from './ArcscriptState.js'; import { isGlobalScope } from './scope.js'; import LegacyVariableReferenceRewriter from './LegacyVariableReferenceRewriter.js'; @@ -14,7 +15,7 @@ import type { LegacyVariableRewriteResult, } from './types.js'; -type ArcscriptInterpreterOptions = { +export type ArcscriptInterpreterOptions = { state: ArcscriptStateDef; elementVisits?: Record; currentElement?: string; @@ -48,9 +49,9 @@ export default class Interpreter { this.emit ); - const { tree } = this.parse(code); + const { tree, parser } = this.parse(code); - const visitor = new ArcscriptVisitor(state); + const visitor = new ArcscriptVisitor(state, parser.declarations); state.setVarValues(varValues); @@ -69,9 +70,9 @@ export default class Interpreter { const tokens = new antlr4.CommonTokenStream(lexer); const parser = new ArcscriptParser(tokens); parser.setOptions({ - arcscriptVariables: this.arcscriptVariables, elementVisits: this.elementVisits, currentElement: this.currentElement, + declarations: new ArcscriptContext(this.arcscriptVariables), }); parser.buildParseTrees = true; parser.removeErrorListeners(); @@ -216,10 +217,13 @@ export default class Interpreter { token => tokenTypeNames[token.type] === 'LEGACY_CHARACTER' ); if (legacyToken) { - throw new ParseError(`token recognition error at: '${legacyToken.text}'`, { - line: legacyToken.line, - col: legacyToken.column, - }); + throw new ParseError( + `token recognition error at: '${legacyToken.text}'`, + { + line: legacyToken.line, + col: legacyToken.column, + } + ); } return { From c37111da4225507235db848497220c2e81623d27 Mon Sep 17 00:00:00 2001 From: panayotis_kalaitzoglou Date: Tue, 10 Nov 2026 20:07:09 +0200 Subject: [PATCH 2/8] feat: add enum support across Arcscript interpreters --- .github/workflows/CSharp.yml | 2 + .github/workflows/TypeScript.yml | 2 + .github/workflows/cpp-build-test.yml | 2 + CSharp/EnumTests.cs | 153 ++ CSharp/Interpreter/ArcscriptContext.cs | 69 +- CSharp/Interpreter/ArcscriptEnums.cs | 20 + CSharp/Interpreter/ArcscriptFunctions.cs | 13 +- CSharp/Interpreter/ArcscriptParserBase.cs | 60 + CSharp/Interpreter/ArcscriptTranspiler.cs | 21 +- CSharp/Interpreter/ArcscriptVisitor.cs | 3 +- CSharp/Project/Variable.cs | 1 + CSharp/README.md | 4 + Cpp/CMakeLists.txt | 9 + Cpp/README.md | 4 + Cpp/demo/EnumTests.cpp | 202 ++ Cpp/src/ArcscriptContext.h | 66 +- Cpp/src/ArcscriptEnums.h | 18 + Cpp/src/ArcscriptFunctions.cpp | 12 +- Cpp/src/ArcscriptFunctions.h | 1 + Cpp/src/ArcscriptHelpers.h | 1 + Cpp/src/ArcscriptParserBase.cpp | 71 + Cpp/src/ArcscriptParserBase.h | 2 + Cpp/src/ArcscriptTranspiler.cpp | 14 +- Cpp/src/ArcscriptTranspiler.h | 15 +- Cpp/src/ArcscriptVisitor.cpp | 3 +- README.md | 5 + TypeScript/README.md | 3 + TypeScript/src/ArcscriptContext.ts | 130 +- TypeScript/src/ArcscriptVisitor.ts | 6 +- .../src/Generated/ArcscriptParserBase.ts | 150 +- TypeScript/src/__tests__/enums.test.ts | 171 ++ TypeScript/src/antlr4.interpreter.ts | 14 +- TypeScript/src/index.ts | 10 + TypeScript/src/types.ts | 16 + docs/enums.md | 246 ++ grammar/ArcscriptParser.g4 | 10 +- tests/enums.json | 2065 +++++++++++++++++ 37 files changed, 3539 insertions(+), 55 deletions(-) create mode 100644 CSharp/EnumTests.cs create mode 100644 CSharp/Interpreter/ArcscriptEnums.cs create mode 100644 Cpp/demo/EnumTests.cpp create mode 100644 Cpp/src/ArcscriptEnums.h create mode 100644 TypeScript/src/__tests__/enums.test.ts create mode 100644 docs/enums.md create mode 100644 tests/enums.json diff --git a/.github/workflows/CSharp.yml b/.github/workflows/CSharp.yml index 3436067..9a09c52 100644 --- a/.github/workflows/CSharp.yml +++ b/.github/workflows/CSharp.yml @@ -6,11 +6,13 @@ on: paths: - "CSharp/**" - "grammar/*.g4" + - "tests/**" pull_request: branches: ["main"] paths: - "CSharp/**" - "grammar/*.g4" + - "tests/**" jobs: build-and-test: diff --git a/.github/workflows/TypeScript.yml b/.github/workflows/TypeScript.yml index 19a602a..d044fd7 100644 --- a/.github/workflows/TypeScript.yml +++ b/.github/workflows/TypeScript.yml @@ -10,11 +10,13 @@ on: paths: - "TypeScript/**" - "grammar/*.g4" + - "tests/**" pull_request: branches: ["main"] paths: - "TypeScript/**" - "grammar/*.g4" + - "tests/**" # Allows you to run this workflow manually from the Actions tab workflow_dispatch: diff --git a/.github/workflows/cpp-build-test.yml b/.github/workflows/cpp-build-test.yml index dee3c92..9e37e58 100644 --- a/.github/workflows/cpp-build-test.yml +++ b/.github/workflows/cpp-build-test.yml @@ -6,12 +6,14 @@ on: paths: - "Cpp/**" - "grammar/*.g4" + - "tests/**" - ".github/workflows/cpp-build-test.yml" pull_request: branches: [main] paths: - "Cpp/**" - "grammar/*.g4" + - "tests/**" - ".github/workflows/cpp-build-test.yml" jobs: diff --git a/CSharp/EnumTests.cs b/CSharp/EnumTests.cs new file mode 100644 index 0000000..d9e23f4 --- /dev/null +++ b/CSharp/EnumTests.cs @@ -0,0 +1,153 @@ +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using Arcweave.Interpreter; +using Arcweave.Interpreter.INodes; +using Arcweave.Project; +using Newtonsoft.Json.Linq; +using NUnit.Framework; + +namespace Arcweave +{ + public class EnumTests + { + private static JObject Fixture() => JObject.Parse(File.ReadAllText("../../../../tests/enums.json")); + private static object Value(JToken token) + { + if (token.Type != JTokenType.Integer) return ((JValue)token).Value; + long value = token.Value(); + return value >= int.MinValue && value <= int.MaxValue ? (object)(int)value : value; + } + + private static IEnumerable Cases() => Fixture()["cases"] + .Select(test => new TestCaseData(test).SetName("Enums: " + test["name"])); + + [TestCaseSource(nameof(Cases))] + public void SharedContract(JToken test) + { + var fixture = Fixture(); + var enums = new Dictionary(); + foreach (var entry in (JObject)(test["enums"] ?? fixture["enums"])) + { + var definition = entry.Value; + enums.Add(entry.Key, new EnumDefinition { + Id = (string)definition["id"], Name = (string)definition["name"], Type = (string)definition["type"], + Members = definition["members"].Select(member => new EnumMemberDefinition { + Id = (string)member["id"], Name = (string)member["name"], Value = Value(member["value"]) + }).ToList() + }); + } + var globals = new List(); + var boards = new Dictionary(); + var components = new Dictionary(); + foreach (var entry in (JObject)(test["initialVars"] ?? fixture["initialVars"])) + { + var definition = entry.Value; + var variable = new Variable(entry.Key, (string)definition["name"], Value(definition["defaultValue"])) { + EnumId = (string)definition["enumId"] + }; + if (test["values"]?[entry.Key] != null) variable.Value = Value(test["values"][entry.Key]); + var scope = (string)definition["scope"]; + if (scope == null) globals.Add(variable); + else if ((string)definition["cType"] == "components") + { + if (!components.ContainsKey(scope)) components[scope] = new Component(scope); + components[scope].AddVariable(variable); + } + else + { + if (!boards.ContainsKey(scope)) boards[scope] = new Board(scope, new List(), scope); + boards[scope].AddVariable(variable); + } + } + var project = new Project.Project(boards.Values.ToList(), globals, components.Values.ToList()); + var events = new List(); + var interpreter = new AwInterpreter(project, onEvent: events.Add, enums: enums, + scopeNames: test["scopeNames"]?.Values()); + var original = project.GetAllVariables().ToDictionary(variable => variable.Id, variable => variable.Value); + var code = (string)test["code"]; + if (test["error"] != null) + { + Assert.Throws(() => interpreter.Parse(code)); + Assert.Throws(() => interpreter.RunScript(code)); + Assert.That(project.GetAllVariables().ToDictionary(variable => variable.Id, variable => variable.Value), Is.EquivalentTo(original)); + } + else + { + interpreter.Parse(code); + Assert.That(project.GetAllVariables().ToDictionary(variable => variable.Id, variable => variable.Value), Is.EquivalentTo(original)); + if (test["parseOnly"] == null) + { + var result = interpreter.RunScript(code); + Assert.That(result.Output, Is.EqualTo((string)test["output"] ?? "")); + if (test["result"] != null) Assert.That(result.Result, Is.EqualTo(test["result"].Value())); + if (test["changes"] != null) + Assert.That(result.Changes, Is.EquivalentTo(((JObject)test["changes"]).Properties() + .ToDictionary(property => property.Name, property => Value(property.Value)))); + } + } + Assert.That(events, Is.Empty); + } + private static Dictionary SnapshotEnums() => new Dictionary { + ["quest"] = new EnumDefinition { + Id = "quest", Name = "QuestStatus", Type = "string", + Members = new List { + new EnumMemberDefinition { Id = "inactive", Name = "Inactive", Value = "inactive" }, + new EnumMemberDefinition { Id = "active", Name = "Active", Value = "active" } + } + } + }; + + [Test] + public void ReferencesSnapshotDeclarationIdentityAndType() + { + var enums = SnapshotEnums(); + var variable = new Variable("status", "questStatus", "inactive") { EnumId = "quest" }; + var context = new ArcscriptContext(enums, new[] { variable }); + enums["quest"].Name = "RenamedStatus"; + enums["quest"].Type = "integer"; + enums["quest"].Members[1].Value = 1; + variable.Name = "renamedStatus"; + variable.EnumId = "missing"; + + var binding = context.Resolve("questStatus"); + Assert.That(binding.Kind, Is.EqualTo(ReferenceKind.Variable)); + Assert.That(binding.VariableId, Is.EqualTo("status")); + Assert.That(binding.EnumId, Is.EqualTo("quest")); + Assert.That(binding.Type, Is.EqualTo(typeof(string))); + var member = context.Resolve("QuestStatus.Active"); + Assert.That(member.Kind, Is.EqualTo(ReferenceKind.EnumMember)); + Assert.That(member.EnumId, Is.EqualTo("quest")); + Assert.That(member.MemberId, Is.EqualTo("active")); + Assert.That(member.Type, Is.EqualTo(typeof(string))); + Assert.That(member.Value, Is.EqualTo("active")); + Assert.That(context.EnumType("quest"), Is.EqualTo(typeof(string))); + Assert.That(context.Resolve("RenamedStatus.Active"), Is.Null); + Assert.Throws(() => new ArcscriptContext(enums, new[] { variable })); + } + + [Test] + public void RunKeepsValidatedBindingsAndNextOperationReadsFreshDeclarations() + { + var enums = SnapshotEnums(); + var variable = new Variable("status", "questStatus", "inactive") { EnumId = "quest" }; + var project = new Project.Project(new List(), new List { variable }, new List()); + var interpreter = new AwInterpreter(project, enums: enums, onEvent: _ => { + variable.Name = "renamedStatus"; + enums["quest"].Name = "RenamedStatus"; + enums["quest"].Members[1].Name = "Started"; + enums["quest"].Members[1].Value = "started"; + }); + var result = interpreter.RunScript("
resetVisits()
questStatus = QuestStatus.Active
reset(questStatus)
questStatus = QuestStatus.Active
show(questStatus, QuestStatus.Active)
"); + Assert.That(result.Output, Is.EqualTo("

activeactive

")); + Assert.That(result.Changes, Is.EquivalentTo(new Dictionary { ["status"] = "active" })); + Assert.Throws(() => interpreter.Parse("
questStatus == QuestStatus.Active
")); + var next = interpreter.RunScript("
renamedStatus = RenamedStatus.Started
show(renamedStatus)
"); + Assert.That(next.Output, Is.EqualTo("

started

")); + Assert.That(next.Changes, Is.EquivalentTo(new Dictionary { ["status"] = "started" })); + variable.EnumId = "missing"; + Assert.Throws(() => interpreter.Parse("
true
")); + } + } +} diff --git a/CSharp/Interpreter/ArcscriptContext.cs b/CSharp/Interpreter/ArcscriptContext.cs index d8c2a7b..af576dc 100644 --- a/CSharp/Interpreter/ArcscriptContext.cs +++ b/CSharp/Interpreter/ArcscriptContext.cs @@ -1,45 +1,102 @@ using System; using System.Collections.Generic; using System.Linq; +using System.Text.RegularExpressions; using Arcweave.Project; namespace Arcweave.Interpreter { - public enum ReferenceKind { Variable } + public enum ReferenceKind { Variable, EnumMember } public sealed class ArcscriptReference { public ReferenceKind Kind { get; } public string VariableId { get; } + public string EnumId { get; } + public string MemberId { get; } public Type Type { get; } + public object Value { get; } - internal ArcscriptReference(ReferenceKind kind, Type type, string variableId) + internal ArcscriptReference(ReferenceKind kind, Type type, string variableId = null, + string enumId = null, string memberId = null, object value = null) { Kind = kind; Type = type; VariableId = variableId; + EnumId = enumId; + MemberId = memberId; + Value = value; } } - // A snapshot of declarations, shared by parsing and execution. + // A validated snapshot of declarations, shared by parsing and execution. public sealed class ArcscriptContext { + private static readonly HashSet ReservedNames = new HashSet("abs max min random roll round sqr sqrt visits show resetVisits reset resetAll if else elseif endif and or is not true false abstract as assert async auto await base bool break byte case catch char checked class const constexpr const_cast continue decimal default delegate delete do double dynamic elif enum event explicit export extends extern false final finally fixed float for foreach friend from func get global goto if implicit import in inline int interface internal is lock long match mutable namespace native new noexcept not not_eq null nullptr object operator or or_eq out override params pass private protected public readonly ref register reinterpret_cast return sbyte sealed set short signal signed sizeof stackalloc static static_assert static_cast string struct super switch template this thread_local throw throws trait try typedef typeid typename typeof uint ulong unchecked union unsafe unsigned using ushort var virtual void volatile wchar_t when where while with yield alignas alignof and_eq asm bitand bitor char8_t char16_t char32_t compl concept co_await co_return co_yield consteval constinit decltype dynamic_cast requires xor xor_eq class_name breakpoint preload self PI TAU INF NAN tool onready setget remote master puppet remotesync mastersync puppetsync".Split(' ')); private readonly Dictionary _references = new Dictionary(); + private readonly Dictionary _enumTypes = new Dictionary(); + public bool HasEnums => _enumTypes.Count > 0; - public ArcscriptContext(IEnumerable variables = null) + public ArcscriptContext(IReadOnlyDictionary definitions = null, + IEnumerable variables = null, IEnumerable scopeNames = null) { - foreach (var variable in variables ?? Enumerable.Empty()) + definitions = definitions ?? new Dictionary(); + var variableList = (variables ?? Enumerable.Empty()).ToList(); + var scopes = new HashSet(scopeNames ?? Enumerable.Empty()); + foreach (var variable in variableList) + if (variable.Parent != null) scopes.Add(variable.Parent.CustomId); + var names = new HashSet(); + foreach (var entry in definitions) { + var definition = entry.Value; + AssertName(definition.Name); + if (string.IsNullOrEmpty(entry.Key) || entry.Key != definition.Id || !names.Add(definition.Name)) + throw new ParseException("Enum IDs and names must be unique and match their keys"); + if (scopes.Contains(definition.Name)) + throw new ParseException($"Enum {definition.Name} conflicts with a variable scope"); + if ((definition.Type != "string" && definition.Type != "integer") || definition.Members.Count == 0) + throw new ParseException($"Enum {definition.Name} must have string or integer members"); + var type = definition.Type == "string" ? typeof(string) : typeof(int); + _enumTypes.Add(entry.Key, type); + var memberIds = new HashSet(); + var memberNames = new HashSet(); + var values = new HashSet(); + foreach (var member in definition.Members) + { + AssertName(member.Name); + if (string.IsNullOrEmpty(member.Id) || !memberIds.Add(member.Id) || !memberNames.Add(member.Name) || !values.Add(member.Value)) + throw new ParseException($"Enum {definition.Name} has duplicate or missing members"); + if ((definition.Type == "string" && !(member.Value is string)) || + (definition.Type == "integer" && !(member.Value is int))) + throw new ParseException($"Invalid backing value for {definition.Name}.{member.Name}"); + _references.Add(definition.Name + "." + member.Name, + new ArcscriptReference(ReferenceKind.EnumMember, type, + enumId: entry.Key, memberId: member.Id, value: member.Value)); + } + } + foreach (var variable in variableList) + { + if (variable.EnumId != null && (!_enumTypes.TryGetValue(variable.EnumId, out var type) || type != variable.Type)) + throw new ParseException($"Invalid enum reference for variable {variable.Name}"); var name = variable.Parent == null ? variable.Name : variable.Parent.CustomId + "." + variable.Name; // Preserve the existing first-match behavior for ordinary variable names. if (!_references.ContainsKey(name)) - _references.Add(name, new ArcscriptReference(ReferenceKind.Variable, variable.Type, variable.Id)); + _references.Add(name, new ArcscriptReference(ReferenceKind.Variable, variable.Type, + variableId: variable.Id, enumId: variable.EnumId)); } } + private static void AssertName(string name) + { + if (name == null || !Regex.IsMatch(name, @"\A[A-Za-z][A-Za-z0-9_]*\z") || name.Contains("__") || ReservedNames.Contains(name)) + throw new ParseException($"Invalid or reserved enum identifier {name}"); + } + public ArcscriptReference Resolve(string name) { return _references.TryGetValue(name, out var reference) ? reference : null; } + + public Type EnumType(string id) => _enumTypes[id]; } } diff --git a/CSharp/Interpreter/ArcscriptEnums.cs b/CSharp/Interpreter/ArcscriptEnums.cs new file mode 100644 index 0000000..4516682 --- /dev/null +++ b/CSharp/Interpreter/ArcscriptEnums.cs @@ -0,0 +1,20 @@ +using System.Collections.Generic; + +namespace Arcweave.Interpreter +{ + public sealed class EnumMemberDefinition + { + public string Id { get; set; } + public string Name { get; set; } + public object Value { get; set; } + } + + public sealed class EnumDefinition + { + public string Id { get; set; } + public string Name { get; set; } + public string Type { get; set; } + public List Members { get; set; } = new List(); + } + +} diff --git a/CSharp/Interpreter/ArcscriptFunctions.cs b/CSharp/Interpreter/ArcscriptFunctions.cs index ddf54bf..1f0f299 100644 --- a/CSharp/Interpreter/ArcscriptFunctions.cs +++ b/CSharp/Interpreter/ArcscriptFunctions.cs @@ -20,18 +20,19 @@ public class FunctionDefinition public int? MaxArgs { get; set; } public Type ArgumentsType { get; set; } public Type ReturnType { get; set; } + public bool IsPure { get; set; } } public static Dictionary FunctionDefinitions = new() { - { "abs", new FunctionDefinition { MinArgs=1, MaxArgs=1, ReturnType = typeof(int)} }, - { "max", new FunctionDefinition { MinArgs=2, ReturnType = typeof(double)} }, - { "min", new FunctionDefinition { MinArgs=2, ReturnType = typeof(double)} }, + { "abs", new FunctionDefinition { MinArgs=1, MaxArgs=1, ReturnType = typeof(int), IsPure = true} }, + { "max", new FunctionDefinition { MinArgs=2, ReturnType = typeof(double), IsPure = true} }, + { "min", new FunctionDefinition { MinArgs=2, ReturnType = typeof(double), IsPure = true} }, { "random", new FunctionDefinition { MinArgs=0, MaxArgs=0, ReturnType = typeof(double)} }, { "roll", new FunctionDefinition { MinArgs=1, MaxArgs=2, ReturnType = typeof(int)} }, - { "round", new FunctionDefinition { MinArgs=1, MaxArgs=1, ReturnType = typeof(int)} }, - { "sqr", new FunctionDefinition { MinArgs=1, MaxArgs=1, ReturnType = typeof(double)} }, - { "sqrt", new FunctionDefinition { MinArgs=1, MaxArgs=1, ReturnType = typeof(double)} }, + { "round", new FunctionDefinition { MinArgs=1, MaxArgs=1, ReturnType = typeof(int), IsPure = true} }, + { "sqr", new FunctionDefinition { MinArgs=1, MaxArgs=1, ReturnType = typeof(double), IsPure = true} }, + { "sqrt", new FunctionDefinition { MinArgs=1, MaxArgs=1, ReturnType = typeof(double), IsPure = true} }, { "visits", new FunctionDefinition { MinArgs=0, MaxArgs=1, ReturnType = typeof(int)} }, { "show", new FunctionDefinition { MinArgs=1, ReturnType = typeof(string)} }, { "reset", new FunctionDefinition { MinArgs=1, ArgumentsType = typeof(Variable), ReturnType = typeof(void)} }, diff --git a/CSharp/Interpreter/ArcscriptParserBase.cs b/CSharp/Interpreter/ArcscriptParserBase.cs index 7ee2b96..089b772 100644 --- a/CSharp/Interpreter/ArcscriptParserBase.cs +++ b/CSharp/Interpreter/ArcscriptParserBase.cs @@ -43,6 +43,64 @@ public bool assertVariable(ArcscriptParser.IdentifierContext identifierContext) return true; } + public void assertAssignable(ArcscriptParser.IdentifierContext identifierContext) + { + if (Declarations.Resolve(identifierContext.GetText())?.Kind == ReferenceKind.EnumMember) + throw new ParseException($"Enum member {identifierContext.GetText()} is read-only"); + assertVariable(identifierContext); + } + + private string ExpressionEnum(ArcscriptParser.ExpressionContext context) + { + if (context is ArcscriptParser.ParenthesizedExpressionContext parenthesized) + return ExpressionEnum(parenthesized.expression()); + if (context is ArcscriptParser.IdentifierExpressionContext identifier) + return Declarations.Resolve(identifier.identifier().GetText())?.EnumId; + return null; + } + + private bool IsConstantExpression(ArcscriptParser.ExpressionContext context) + { + if (context is ArcscriptParser.IdentifierExpressionContext identifier) + return Declarations.Resolve(identifier.identifier().GetText())?.Kind == ReferenceKind.EnumMember; + if (context is ArcscriptParser.LiteralExpressionContext) return true; + if (context is ArcscriptParser.FunctionCallExpressionContext function) + { + var call = function.function_call(); + if (!Functions.FunctionDefinitions[call.FNAME().GetText()].IsPure) return false; + if (call.identifier_list() != null) + return call.identifier_list().identifier().All(member => Declarations.Resolve(member.GetText())?.Kind == ReferenceKind.EnumMember); + return call.argument_list()?.argument().All(argument => + argument.expression() != null && IsConstantExpression(argument.expression())) ?? true; + } + return context.GetRuleContexts().All(IsConstantExpression); + } + + public void validateEnums(ParserRuleContext context) + { + if (!Declarations.HasEnums) return; + if (context is ArcscriptParser.Statement_assignmentContext assignment && + Declarations.Resolve(assignment.assignable().GetText())?.EnumId is string enumId && + (assignment.ASSIGN() == null || ExpressionEnum(assignment.expression()) != enumId)) + throw new ParseException("Enum assignment requires a member or variable of the same enum"); + if (context is ArcscriptParser.ComparisonExpressionContext comparison && + comparison.AND() == null && comparison.ANDKEYWORD() == null && + comparison.OR() == null && comparison.ORKEYWORD() == null) + { + var left = ExpressionEnum(comparison.expression(0)); + var right = ExpressionEnum(comparison.expression(1)); + if (left != null && right != null && left != right) + throw new ParseException("Cannot compare different enum types"); + if ((left != null && right == null && IsConstantExpression(comparison.expression(1))) || + (right != null && left == null && IsConstantExpression(comparison.expression(0)))) + throw new ParseException("Enum comparisons with constants require a named member"); + var id = left ?? right; + if (id != null && (comparison.LT() != null || comparison.GT() != null || + comparison.LE() != null || comparison.GE() != null) && Declarations.EnumType(id) != typeof(int)) + throw new ParseException("Only integer enums support ordering"); + } + } + public bool assertMention(IList attrCtxList) { Dictionary attrs = new Dictionary(); foreach ( var attrCtx in attrCtxList ) { @@ -100,6 +158,8 @@ public bool assertFunctionArguments(IToken fname, ArcscriptParser.Identifier_lis var min = Functions.FunctionDefinitions[fname.Text].MinArgs; var max = Functions.FunctionDefinitions[fname.Text].MaxArgs; + if (Functions.FunctionDefinitions[fname.Text].ArgumentsType == typeof(Variable) && identifierListContext != null) + foreach (var identifier in identifierListContext.identifier()) assertAssignable(identifier); if ( ( min != null && identifierListLength < min ) || ( max != null && identifierListLength > max ) ) { throw new RecognitionException("Incorrect number of arguments for function " + fname.Text, this, this.InputStream, this.Context); } diff --git a/CSharp/Interpreter/ArcscriptTranspiler.cs b/CSharp/Interpreter/ArcscriptTranspiler.cs index 527cfff..b0cf28c 100644 --- a/CSharp/Interpreter/ArcscriptTranspiler.cs +++ b/CSharp/Interpreter/ArcscriptTranspiler.cs @@ -1,6 +1,7 @@ #nullable enable using Antlr4.Runtime; using System.Collections.Generic; +using System.Linq; using Arcweave.Interpreter.INodes; namespace Arcweave.Interpreter @@ -11,10 +12,15 @@ public class AwInterpreter private string ElementId { get; set; } private System.Action _emit; + private readonly IReadOnlyDictionary? _enums; + private readonly IEnumerable? _scopeNames; - public AwInterpreter(IProject project, string elementId = "", System.Action? onEvent = null) + public AwInterpreter(IProject project, string elementId = "", System.Action? onEvent = null, + IReadOnlyDictionary? enums = null, IEnumerable? scopeNames = null) { this.Project = project; + _enums = enums; + _scopeNames = scopeNames; this.ElementId = elementId; if (onEvent != null) { @@ -26,7 +32,18 @@ public AwInterpreter(IProject project, string elementId = "", System.Action new ArcscriptContext(Project.GetAllVariables()); + private ArcscriptContext CreateContext() + { +#if GODOT + var scopes = Project.Boards.Values.Select(board => board.CustomId) + .Concat(Project.Components.Values.Select(component => component.CustomId)); +#else + var scopes = Project.Boards.Select(board => board.CustomId) + .Concat(Project.Components.Select(component => component.CustomId)); +#endif + return new ArcscriptContext(_enums, Project.GetAllVariables(), + scopes.Concat(_scopeNames ?? Enumerable.Empty())); + } public ArcscriptParser.InputContext Parse(string code) => ParseWithContext(code).Tree; diff --git a/CSharp/Interpreter/ArcscriptVisitor.cs b/CSharp/Interpreter/ArcscriptVisitor.cs index 0092a1b..70410b4 100644 --- a/CSharp/Interpreter/ArcscriptVisitor.cs +++ b/CSharp/Interpreter/ArcscriptVisitor.cs @@ -414,11 +414,12 @@ public override object VisitIdentifier(ArcscriptParser.IdentifierContext context private Variable ReadVariable(ArcscriptReference reference) { + if (reference.Kind != ReferenceKind.Variable) throw new RuntimeException("Enum members are read-only"); return state.GetVariableById(reference.VariableId); } private object ReadReference(ArcscriptReference reference) => - state.GetVarValueById(reference.VariableId); + reference.Kind == ReferenceKind.EnumMember ? reference.Value : state.GetVarValueById(reference.VariableId); public override object VisitMention([NotNull] ArcscriptParser.MentionContext context) { Dictionary attrs = new Dictionary(); diff --git a/CSharp/Project/Variable.cs b/CSharp/Project/Variable.cs index 4873660..b00b028 100644 --- a/CSharp/Project/Variable.cs +++ b/CSharp/Project/Variable.cs @@ -6,6 +6,7 @@ namespace Arcweave.Project public partial class Variable { public string Name { get; set; } + public string EnumId { get; set; } public string Id { get; } public object Value { get; set; } public object ObjectValue => Value; diff --git a/CSharp/README.md b/CSharp/README.md index 1195668..515ff48 100644 --- a/CSharp/README.md +++ b/CSharp/README.md @@ -2,6 +2,10 @@ The C# interpreter executes Arcscript embedded in the HTML generated by the Arcweave editor. It can evaluate conditions, update global and scoped variables, render output, read visit counts, and emit runtime events. +For enums, set `Variable.EnumId`, pass definitions through the optional `enums` +constructor argument, and use `AwInterpreter.Parse()` for validation without +execution. See the [shared enum contract and API](../docs/enums.md). + ## Prerequisites - .NET 6 SDK or newer diff --git a/Cpp/CMakeLists.txt b/Cpp/CMakeLists.txt index 730c07f..b38d08a 100755 --- a/Cpp/CMakeLists.txt +++ b/Cpp/CMakeLists.txt @@ -62,6 +62,7 @@ target_sources(ArcscriptTranspiler PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/src/Arcscr set(ARCSCRIPT_INCLUDE_HEADERS ${CMAKE_CURRENT_SOURCE_DIR}/src/ArcscriptTranspiler.h ${CMAKE_CURRENT_SOURCE_DIR}/src/ArcscriptHelpers.h + ${CMAKE_CURRENT_SOURCE_DIR}/src/ArcscriptEnums.h ${CMAKE_CURRENT_SOURCE_DIR}/src/ArcscriptErrorExceptions.h ${CMAKE_CURRENT_SOURCE_DIR}/src/ArcscriptOutputs.h ) @@ -136,6 +137,14 @@ if (WITH_TEST) target_link_libraries(ArcscriptTest PRIVATE nlohmann_json::nlohmann_json) target_link_libraries(ArcscriptTest PRIVATE ArcscriptTranspiler) + add_executable(ArcscriptEnumTest ${CMAKE_CURRENT_SOURCE_DIR}/demo/EnumTests.cpp) + target_link_libraries(ArcscriptEnumTest PRIVATE nlohmann_json::nlohmann_json ArcscriptTranspiler) + add_test(NAME Arcscript.Enums COMMAND ArcscriptEnumTest ${CMAKE_CURRENT_SOURCE_DIR}/../tests/enums.json) + set_tests_properties(Arcscript.Enums PROPERTIES LABELS "arcscript;fixtures" TIMEOUT 30) + add_custom_command(TARGET ArcscriptEnumTest POST_BUILD + COMMAND ${CMAKE_COMMAND} -E copy + "$" ${ANTLR4_RUNTIME_LIBRARIES} + "$") if (CMAKE_HOST_UNIX) find_package(Threads REQUIRED) target_link_libraries(ArcscriptTest PRIVATE Threads::Threads) diff --git a/Cpp/README.md b/Cpp/README.md index 78e0abd..9400fd8 100644 --- a/Cpp/README.md +++ b/Cpp/README.md @@ -2,6 +2,10 @@ The C++ interpreter executes Arcscript embedded in the HTML generated by the Arcweave editor. It can evaluate conditions, update variable state, render output, track visits, and emit runtime events. +Enums use `Variable::enumId` and optional definitions on `ArcscriptTranspiler`. +`validate()` checks scripts without execution; `runScriptWithEnumsExport` provides +enum context through the exported bridge. See the [shared enum contract](../docs/enums.md). + ## Prerequisites - CMake 3.10 or newer diff --git a/Cpp/demo/EnumTests.cpp b/Cpp/demo/EnumTests.cpp new file mode 100644 index 0000000..30b9492 --- /dev/null +++ b/Cpp/demo/EnumTests.cpp @@ -0,0 +1,202 @@ +#include +#include +#include +#include +#include +#include "ArcscriptTranspiler.h" +#include "ArcscriptContext.h" + +using namespace Arcweave; +using json = nlohmann::json; + +std::any primitive(const json& value) { + if (value.is_string()) return value.get(); + if (value.is_boolean()) return value.get(); + if (value.is_number_integer()) { + auto number = value.get(); + if (number >= std::numeric_limits::min() && number <= std::numeric_limits::max()) return static_cast(number); + return number; + } + return value.get(); +} +json primitiveJson(const std::any& value) { + if (value.type() == typeid(std::string)) return std::any_cast(value); + if (value.type() == typeid(bool)) return std::any_cast(value); + if (value.type() == typeid(int)) return std::any_cast(value); + if (value.type() == typeid(double)) return std::any_cast(value); + throw std::runtime_error("Expected a primitive runtime value"); +} +void require(bool condition, const std::string& message) { + if (!condition) throw std::runtime_error(message); +} + +void declarationContextTests() { + std::map enums{{"quest", {"quest", "QuestStatus", "string", { + {"inactive", "Inactive", std::string("inactive")}, {"active", "Active", std::string("active")} + }}}}; + std::map variables{{"status", { + "status", "questStatus", AW_STRING, std::string("inactive"), "", std::string("inactive"), "quest" + }}}; + const ArcscriptContext context(enums, variables); + enums.at("quest").name = "RenamedStatus"; + enums.at("quest").type = "integer"; + enums.at("quest").members[1].value = 1; + variables.at("status").name = "renamedStatus"; + variables.at("status").enumId = "missing"; + auto binding = context.resolve("questStatus"); + require(binding && binding->kind == ReferenceKind::Variable && binding->variableId == "status" && + binding->enumId == "quest" && binding->type == AW_STRING, "Variable binding lost its identity"); + auto member = context.resolve("QuestStatus.Active"); + require(member && member->kind == ReferenceKind::EnumMember && member->enumId == "quest" && + member->memberId == "active" && member->type == AW_STRING && primitiveJson(member->value) == "active", + "Enum member binding lost its identity or value"); + require(context.enumType("quest") == AW_STRING && !context.resolve("RenamedStatus.Active"), + "Context observed changes to source declarations"); + bool rejected = false; + try { ArcscriptContext changed(enums, variables); } + catch (const ParseErrorException&) { rejected = true; } + require(rejected, "New context did not validate changed declarations"); +} + +void declarationLifecycleTests() { + std::map enums{{"quest", {"quest", "QuestStatus", "string", { + {"inactive", "Inactive", std::string("inactive")}, {"active", "Active", std::string("active")} + }}}}; + std::map variables{{"status", { + "status", "questStatus", AW_STRING, std::string("inactive"), "", std::string("inactive"), "quest" + }}}; + ArcscriptTranspiler* active = nullptr; + ArcscriptTranspiler interpreter("", variables, {}, [&](const char*) { + active->state.variableValues.at("status").name = "renamedStatus"; + }, enums); + active = &interpreter; + auto result = interpreter.runScript("
resetVisits()
questStatus = QuestStatus.Active
reset(questStatus)
questStatus = QuestStatus.Active
show(questStatus, QuestStatus.Active)
"); + require(result.output == "

activeactive

" && result.changes.size() == 1 && + primitiveJson(result.changes.at("status")) == "active", "Run did not keep its validated bindings"); + bool rejected = false; + try { interpreter.validate("
questStatus == QuestStatus.Active
"); } + catch (const ParseErrorException&) { rejected = true; } + require(rejected, "Next operation did not read renamed variables"); + auto next = interpreter.runScript("
renamedStatus = QuestStatus.Inactive
"); + require(primitiveJson(next.changes.at("status")) == "inactive", "Renamed variable did not resolve by ID"); + interpreter.state.variableValues.at("status").enumId = "missing"; + rejected = false; + try { interpreter.validate("
true
"); } + catch (const ParseErrorException&) { rejected = true; } + require(rejected, "Next operation did not validate updated enum references"); +} + +int main(int argc, char* argv[]) { + if (argc != 2) return 1; + std::ifstream input(argv[1]); + json fixture; + input >> fixture; + int failures = 0; + for (const auto& test : fixture["cases"]) { + try { + auto definitions = test.value("enums", fixture["enums"]); + std::map enums; + for (auto it = definitions.begin(); it != definitions.end(); ++it) { + const auto& definition = it.value(); + EnumDefinition result{definition["id"], definition["name"], definition["type"], {}}; + for (const auto& member : definition["members"]) + result.members.push_back({member["id"], member["name"], primitive(member["value"])}); + enums[it.key()] = result; + } + std::map variables; + auto initialVars = test.value("initialVars", fixture["initialVars"]); + for (auto it = initialVars.begin(); it != initialVars.end(); ++it) { + const auto& definition = it.value(); + Variable variable; + variable.id = it.key(); + variable.name = definition["name"]; + variable.type = definition["type"] == "string" ? AW_STRING : AW_INTEGER; + variable.defaultValue = primitive(definition["defaultValue"]); + variable.value = test.contains("values") && test["values"].contains(it.key()) + ? primitive(test["values"][it.key()]) : variable.defaultValue; + variable.scope = definition.value("scope", ""); + variable.enumId = definition.value("enumId", ""); + variables[it.key()] = variable; + } + int events = 0; + std::unique_ptr interpreter; + std::string code = test["code"]; + bool rejected = false; + try { + interpreter = std::make_unique("", variables, std::map{}, + [&](const char*) { ++events; }, enums, test.value("scopeNames", std::vector{})); + interpreter->validate(code); + } + catch (const ParseErrorException&) { rejected = true; } + require(rejected == test.contains("error"), "Unexpected validation result"); + require((!interpreter || interpreter->state.variableChanges.empty()) && events == 0, "Validation executed script"); + if (rejected) { + if (!interpreter) continue; + bool runRejected = false; + try { interpreter->runScript(code); } + catch (const ParseErrorException&) { runRejected = true; } + require(runRejected && interpreter->state.variableChanges.empty() && events == 0, "Invalid script executed"); + continue; + } + if (test.value("parseOnly", false)) continue; + auto result = interpreter->runScript(code); + require(result.output == test.value("output", ""), "Output mismatch: " + result.output); + if (test.contains("result")) require(primitiveJson(result.result) == test["result"], "Condition mismatch"); + if (test.contains("changes")) { + json changes = json::object(); + for (const auto& [id, value] : result.changes) changes[id] = primitiveJson(value); + require(changes == test["changes"], "Changes mismatch: " + changes.dump()); + } + require(events == 0, "Unexpected event"); + + // The exported bridge must preserve the same metadata and primitive results. + std::vector bridgeVariables; + std::map references; + for (const auto& [id, variable] : variables) { + UVariable bridge; + bridge.id = id.c_str(); + bridge.name = variable.name.c_str(); + bridge.scope = variable.scope.empty() ? nullptr : variable.scope.c_str(); + bridge.type = variable.type; + bridge.has_default_value = true; + if (variable.type == AW_STRING) { + bridge.string_val = std::any_cast(variable.value).c_str(); + bridge.default_string_val = std::any_cast(variable.defaultValue).c_str(); + } else { + bridge.int_val = std::any_cast(variable.value); + bridge.default_int_val = std::any_cast(variable.defaultValue); + } + bridgeVariables.push_back(bridge); + if (!variable.enumId.empty()) references[id] = variable.enumId; + } + auto bridge = runScriptWithEnumsExport(code.c_str(), "", bridgeVariables.data(), bridgeVariables.size(), nullptr, 0, + [&](const char*) { ++events; }, enums, references); + std::string output = bridge->output; + json changes = json::object(); + for (size_t i = 0; i < bridge->changesLen; ++i) { + const auto& change = bridge->changes[i]; + if (change.type == AW_STRING) changes[change.varId] = change.string_result; + else if (change.type == AW_INTEGER) changes[change.varId] = change.int_result; + else if (change.type == AW_DOUBLE) changes[change.varId] = change.double_result; + else if (change.type == AW_BOOLEAN) changes[change.varId] = change.bool_result; + } + bool condition = bridge->conditionResult; + deallocateOutput(bridge); + require(output == result.output, "Bridge output mismatch"); + if (test.contains("changes")) require(changes == test["changes"], "Bridge changes mismatch"); + if (test.contains("result")) require(condition == test["result"], "Bridge condition mismatch"); + } catch (const std::exception& error) { + ++failures; + std::cerr << test["name"] << ": " << error.what() << '\n'; + } + } + for (auto test : {declarationContextTests, declarationLifecycleTests}) { + try { test(); } + catch (const std::exception& error) { + ++failures; + std::cerr << "Declaration context: " << error.what() << '\n'; + } + } + std::cout << fixture["cases"].size() << " enum cases and 2 context tests, " << failures << " failures\n"; + return failures ? 1 : 0; +} diff --git a/Cpp/src/ArcscriptContext.h b/Cpp/src/ArcscriptContext.h index d3f04ba..23bf69e 100644 --- a/Cpp/src/ArcscriptContext.h +++ b/Cpp/src/ArcscriptContext.h @@ -1,24 +1,79 @@ #pragma once +#include "ArcscriptEnums.h" #include "ArcscriptHelpers.h" +#include +#include namespace Arcweave { -enum class ReferenceKind { Variable }; +enum class ReferenceKind { Variable, EnumMember }; struct ArcscriptReference { ReferenceKind kind; VariableType type; std::string variableId; + std::string enumId; + std::string memberId; + std::any value; }; -// A snapshot of declarations, shared by parsing and execution. +// A validated snapshot of declarations, shared by parsing and execution. class ArcscriptContext { std::map references; + std::map enumTypes; + static void assertName(const std::string& name) { + static const std::set reserved = [] { + std::istringstream input("abs max min random roll round sqr sqrt visits show resetVisits reset resetAll if else elseif endif and or is not true false abstract as assert async auto await base bool break byte case catch char checked class const constexpr const_cast continue decimal default delegate delete do double dynamic elif enum event explicit export extends extern false final finally fixed float for foreach friend from func get global goto if implicit import in inline int interface internal is lock long match mutable namespace native new noexcept not not_eq null nullptr object operator or or_eq out override params pass private protected public readonly ref register reinterpret_cast return sbyte sealed set short signal signed sizeof stackalloc static static_assert static_cast string struct super switch template this thread_local throw throws trait try typedef typeid typename typeof uint ulong unchecked union unsafe unsigned using ushort var virtual void volatile wchar_t when where while with yield alignas alignof and_eq asm bitand bitor char8_t char16_t char32_t compl concept co_await co_return co_yield consteval constinit decltype dynamic_cast requires xor xor_eq class_name breakpoint preload self PI TAU INF NAN tool onready setget remote master puppet remotesync mastersync puppetsync"); + std::set result; + for (std::string word; input >> word;) result.insert(word); + return result; + }(); + if (!std::regex_match(name, std::regex("[A-Za-z][A-Za-z0-9_]*")) || name.find("__") != std::string::npos || reserved.count(name)) + throw ParseErrorException("Invalid or reserved enum identifier " + name); + } public: - explicit ArcscriptContext(const std::map& variables = {}) { + explicit ArcscriptContext(const std::map& definitions = {}, + const std::map& variables = {}, const std::vector& scopeNames = {}) { + std::set scopes(scopeNames.begin(), scopeNames.end()); + for (const auto& [id, variable] : variables) + if (!variable.scope.empty()) scopes.insert(variable.scope); + std::set names; + for (const auto& [id, definition] : definitions) { + assertName(definition.name); + if (id.empty() || id != definition.id || !names.insert(definition.name).second) + throw ParseErrorException("Enum IDs and names must be unique and match their keys"); + if ((definition.type != "string" && definition.type != "integer") || definition.members.empty()) + throw ParseErrorException("Enum " + definition.name + " must have string or integer members"); + if (scopes.count(definition.name)) + throw ParseErrorException("Enum " + definition.name + " conflicts with a variable scope"); + auto type = definition.type == "string" ? AW_STRING : AW_INTEGER; + enumTypes[id] = type; + std::set memberIds, memberNames, strings; + std::set integers; + for (const auto& member : definition.members) { + assertName(member.name); + if (member.id.empty() || !memberIds.insert(member.id).second || !memberNames.insert(member.name).second) + throw ParseErrorException("Enum " + definition.name + " has duplicate or missing members"); + if ((definition.type == "string" && member.value.type() != typeid(std::string)) || + (definition.type == "integer" && member.value.type() != typeid(int))) + throw ParseErrorException("Invalid backing value for " + definition.name + "." + member.name); + bool unique = definition.type == "string" + ? strings.insert(std::any_cast(member.value)).second + : integers.insert(std::any_cast(member.value)).second; + if (!unique) throw ParseErrorException("Enum " + definition.name + " has duplicate backing values"); + references[definition.name + "." + member.name] = {ReferenceKind::EnumMember, type, "", id, member.id, member.value}; + } + } for (const auto& [id, variable] : variables) { + if (!variable.enumId.empty()) { + auto type = enumTypes.find(variable.enumId); + if (type == enumTypes.end() || type->second != variable.type) + throw ParseErrorException("Invalid enum reference for variable " + variable.name); + } auto name = variable.scope.empty() ? variable.name : variable.scope + "." + variable.name; + auto existing = resolve(name); + if (existing && existing->kind == ReferenceKind::EnumMember) continue; // Match the existing native name map's last-match behavior. - references[name] = {ReferenceKind::Variable, variable.type, id}; + references[name] = {ReferenceKind::Variable, variable.type, id, variable.enumId, "", {}}; } } @@ -26,5 +81,8 @@ class ArcscriptContext { auto reference = references.find(name); return reference == references.end() ? nullptr : &reference->second; } + + bool hasEnums() const { return !enumTypes.empty(); } + VariableType enumType(const std::string& id) const { return enumTypes.at(id); } }; } diff --git a/Cpp/src/ArcscriptEnums.h b/Cpp/src/ArcscriptEnums.h new file mode 100644 index 0000000..e45b89e --- /dev/null +++ b/Cpp/src/ArcscriptEnums.h @@ -0,0 +1,18 @@ +#pragma once +#include +#include +#include + +namespace Arcweave { +struct EnumMemberDefinition { + std::string id; + std::string name; + std::any value; +}; +struct EnumDefinition { + std::string id; + std::string name; + std::string type; + std::vector members; +}; +} diff --git a/Cpp/src/ArcscriptFunctions.cpp b/Cpp/src/ArcscriptFunctions.cpp index 63f4390..f6cb115 100755 --- a/Cpp/src/ArcscriptFunctions.cpp +++ b/Cpp/src/ArcscriptFunctions.cpp @@ -56,17 +56,17 @@ namespace Arcweave { } std::map ArcscriptFunctions::functions = { - { "abs", { 1, 1 } }, - { "max", { 2, -1 }}, - { "min", { 2, -1 }}, + { "abs", { 1, 1, "", true } }, + { "max", { 2, -1, "", true }}, + { "min", { 2, -1, "", true }}, { "random", { 0, 0 }}, { "reset", { 1, -1, "variable" }}, { "resetAll", { 0, -1, "variable" }}, { "roll", { 1, 2 } }, - { "round", { 1, 1} }, + { "round", { 1, 1, "", true } }, { "show", { 1, -1 } }, - { "sqr", { 1, 1 } }, - { "sqrt", { 1, 1 } }, + { "sqr", { 1, 1, "", true } }, + { "sqrt", { 1, 1, "", true } }, { "visits", { 0, 1 } }, { "resetVisits", { 0, 0 } }, }; diff --git a/Cpp/src/ArcscriptFunctions.h b/Cpp/src/ArcscriptFunctions.h index e1db9d5..9a212fb 100755 --- a/Cpp/src/ArcscriptFunctions.h +++ b/Cpp/src/ArcscriptFunctions.h @@ -14,6 +14,7 @@ class ArcscriptFunctions { int minArgs; int maxArgs; std::string argsType; + bool isPure = false; }; static std::map functions; diff --git a/Cpp/src/ArcscriptHelpers.h b/Cpp/src/ArcscriptHelpers.h index 930dcf2..b16eb85 100755 --- a/Cpp/src/ArcscriptHelpers.h +++ b/Cpp/src/ArcscriptHelpers.h @@ -32,6 +32,7 @@ struct Variable { std::any value; std::string scope; std::any defaultValue; + std::string enumId; }; class ArcscriptState { diff --git a/Cpp/src/ArcscriptParserBase.cpp b/Cpp/src/ArcscriptParserBase.cpp index 2bea360..1ca814e 100755 --- a/Cpp/src/ArcscriptParserBase.cpp +++ b/Cpp/src/ArcscriptParserBase.cpp @@ -15,6 +15,75 @@ bool ArcscriptParserBase::assertVariable(antlr4::ParserRuleContext *identifierCo throw Arcweave::ParseErrorException("Unknown variable \"" + variableName + "\""); } +void ArcscriptParserBase::assertAssignable(ParserRuleContext *identifier) const { + auto reference = _declarations->resolve(identifier->getText()); + if (reference && reference->kind == Arcweave::ReferenceKind::EnumMember) + throw Arcweave::ParseErrorException("Enum member " + identifier->getText() + " is read-only"); + assertVariable(identifier); +} + +namespace { +using Arcweave::ArcscriptParser; +std::string expressionEnum(ArcscriptParser::ExpressionContext *context, const Arcweave::ArcscriptContext& declarations) { + if (auto parenthesized = dynamic_cast(context)) + return expressionEnum(parenthesized->expression(), declarations); + if (auto identifier = dynamic_cast(context)) { + auto reference = declarations.resolve(identifier->identifier()->getText()); + return reference ? reference->enumId : ""; + } + return ""; +} +bool isConstantExpression(ArcscriptParser::ExpressionContext *context, const Arcweave::ArcscriptContext& declarations) { + if (auto identifier = dynamic_cast(context)) { + auto reference = declarations.resolve(identifier->identifier()->getText()); + return reference && reference->kind == Arcweave::ReferenceKind::EnumMember; + } + if (dynamic_cast(context)) return true; + if (auto function = dynamic_cast(context)) { + auto call = function->function_call(); + if (!Arcweave::ArcscriptFunctions::functions.at(call->FNAME()->getText()).isPure) return false; + if (call->identifier_list()) { + for (auto identifier : call->identifier_list()->identifier()) { + auto reference = declarations.resolve(identifier->getText()); + if (!reference || reference->kind != Arcweave::ReferenceKind::EnumMember) return false; + } + } else if (auto arguments = call->argument_list()) { + for (auto argument : arguments->argument()) + if (!argument->expression() || !isConstantExpression(argument->expression(), declarations)) return false; + } + return true; + } + for (auto child : context->getRuleContexts()) + if (!isConstantExpression(child, declarations)) return false; + return true; +} +} + +void ArcscriptParserBase::validateEnums(ParserRuleContext *context) const { + const auto& declarations = *_declarations; + if (!declarations.hasEnums()) return; + if (auto assignment = dynamic_cast(context)) { + auto variable = declarations.resolve(assignment->assignable()->getText()); + if (variable && !variable->enumId.empty() && (!assignment->ASSIGN() || + expressionEnum(assignment->expression(), declarations) != variable->enumId)) + throw Arcweave::ParseErrorException("Enum assignment requires a member or variable of the same enum"); + } + if (auto comparison = dynamic_cast(context)) { + if (comparison->AND() || comparison->ANDKEYWORD() || comparison->OR() || comparison->ORKEYWORD()) return; + auto left = expressionEnum(comparison->expression(0), declarations); + auto right = expressionEnum(comparison->expression(1), declarations); + if (!left.empty() && !right.empty() && left != right) + throw Arcweave::ParseErrorException("Cannot compare different enum types"); + if ((!left.empty() && right.empty() && isConstantExpression(comparison->expression(1), declarations)) || + (!right.empty() && left.empty() && isConstantExpression(comparison->expression(0), declarations))) + throw Arcweave::ParseErrorException("Enum comparisons with constants require a named member"); + auto id = left.empty() ? right : left; + if (!id.empty() && (comparison->LT() || comparison->GT() || comparison->LE() || comparison->GE()) && + declarations.enumType(id) != Arcweave::AW_INTEGER) + throw Arcweave::ParseErrorException("Only integer enums support ordering"); + } +} + inline bool ends_with(std::string const & value, std::string const & ending) { if (ending.size() > value.size()) return false; @@ -83,6 +152,8 @@ bool ArcscriptParserBase::assertFunctionArguments(Token *fname, std::any listCon auto *variableListCtx = std::any_cast(listContext); if (variableListCtx != NULL) { argListLength = static_cast(variableListCtx->identifier().size()); + if (argsType == "variable") + for (auto identifier : variableListCtx->identifier()) assertAssignable(identifier); } } diff --git a/Cpp/src/ArcscriptParserBase.h b/Cpp/src/ArcscriptParserBase.h index f535d71..fdcb236 100755 --- a/Cpp/src/ArcscriptParserBase.h +++ b/Cpp/src/ArcscriptParserBase.h @@ -16,6 +16,8 @@ class ArcscriptParserBase : public antlr4::Parser { _declarations = &declarations; }; bool assertVariable(antlr4::ParserRuleContext *variable) const; + void assertAssignable(antlr4::ParserRuleContext *identifier) const; + void validateEnums(antlr4::ParserRuleContext *context) const; bool assertMention(std::any attrCtxList); bool assertFunctionArguments(antlr4::Token *fname, std::any listContext); void setLineStart(antlr4::Token *token); diff --git a/Cpp/src/ArcscriptTranspiler.cpp b/Cpp/src/ArcscriptTranspiler.cpp index fcd155a..c9d0fd6 100755 --- a/Cpp/src/ArcscriptTranspiler.cpp +++ b/Cpp/src/ArcscriptTranspiler.cpp @@ -24,7 +24,7 @@ void ArcscriptTranspiler::validate(std::string code) { } TranspilerOutput ArcscriptTranspiler::process(std::string code, bool execute) { - const ArcscriptContext declarations(state.variableValues); + const ArcscriptContext declarations(enumDefinitions, state.variableValues, scopeNames); ANTLRInputStream input(code); ArcscriptLexer lexer(&input); @@ -71,6 +71,14 @@ TranspilerOutput ArcscriptTranspiler::process(std::string code, bool execute) { } UTranspilerOutput* runScriptExport(const char* code, const char* elId, UVariable* variables, size_t varLength, UVisit* visits, size_t visitsLength, std::function onEvent) +{ + return runScriptWithEnumsExport(code, elId, variables, varLength, visits, visitsLength, onEvent, {}, {}); +} + +UTranspilerOutput* runScriptWithEnumsExport(const char* code, const char* elId, UVariable* variables, size_t varLength, UVisit* visits, size_t visitsLength, std::function onEvent, + const std::map& enums, + const std::map& variableEnums, + const std::vector& scopeNames) { Arcweave::TranspilerOutput transpilerOutput; @@ -100,6 +108,8 @@ UTranspilerOutput* runScriptExport(const char* code, const char* elId, UVariable var.id = std::string(variables[i].id); var.name = std::string(variables[i].name); var.type = variables[i].type; + auto enumReference = variableEnums.find(var.id); + if (enumReference != variableEnums.end()) var.enumId = enumReference->second; if (variables[i].scope != nullptr) { var.scope = std::string(variables[i].scope); @@ -129,7 +139,7 @@ UTranspilerOutput* runScriptExport(const char* code, const char* elId, UVariable initVisits[std::string(visits[i].elId)] = visits[i].visits; } - Arcweave::ArcscriptTranspiler transpiler(sElId, initVars, initVisits, onEvent); + Arcweave::ArcscriptTranspiler transpiler(sElId, initVars, initVisits, onEvent, enums, scopeNames); transpilerOutput = transpiler.runScript(sCode); UTranspilerOutput* uTranspilerOutput = new UTranspilerOutput(); diff --git a/Cpp/src/ArcscriptTranspiler.h b/Cpp/src/ArcscriptTranspiler.h index 1795fa1..a8b3145 100755 --- a/Cpp/src/ArcscriptTranspiler.h +++ b/Cpp/src/ArcscriptTranspiler.h @@ -1,5 +1,6 @@ #pragma once #include "ArcscriptHelpers.h" +#include "ArcscriptEnums.h" #include "ArcscriptErrorExceptions.h" #if defined _WIN64 @@ -146,11 +147,17 @@ namespace Arcweave */ class ArcscriptTranspiler { TranspilerOutput process(std::string code, bool execute); + std::map enumDefinitions; + std::vector scopeNames; public: ArcscriptState state; - ArcscriptTranspiler(std::string elId, std::map initVars, std::map _visits, std::function onEvent) : state(elId, initVars, _visits, onEvent) { }; + ArcscriptTranspiler(std::string elId, std::map initVars, std::map _visits, std::function onEvent, + std::map enums = {}, std::vector scopes = {}) + : enumDefinitions(std::move(enums)), scopeNames(std::move(scopes)), state(elId, initVars, _visits, onEvent) { }; + + void validate(std::string code); /** * Runs the arcscript code and returns it's results. @@ -159,10 +166,12 @@ namespace Arcweave */ TranspilerOutput runScript(std::string code); - void validate(std::string code); - //ARCSCRIPTTRANSPILER_API UTranspilerOutput URunScript(char* code); }; }; EXPORTED Arcweave::UTranspilerOutput* runScriptExport(const char* code, const char* elId, Arcweave::UVariable* variables, size_t varLength, Arcweave::UVisit* visits, size_t visitsLength, std::function onEvent); +EXPORTED Arcweave::UTranspilerOutput* runScriptWithEnumsExport(const char* code, const char* elId, Arcweave::UVariable* variables, size_t varLength, Arcweave::UVisit* visits, size_t visitsLength, std::function onEvent, + const std::map& enums, + const std::map& variableEnums, + const std::vector& scopeNames = {}); EXPORTED void deallocateOutput(Arcweave::UTranspilerOutput* output); diff --git a/Cpp/src/ArcscriptVisitor.cpp b/Cpp/src/ArcscriptVisitor.cpp index da90618..f3fe7d7 100755 --- a/Cpp/src/ArcscriptVisitor.cpp +++ b/Cpp/src/ArcscriptVisitor.cpp @@ -362,11 +362,12 @@ std::any ArcscriptVisitor::visitIdentifier(ArcscriptParser::IdentifierContext *c } Variable ArcscriptVisitor::readVariable(const ArcscriptReference& reference) const { + if (reference.kind != ReferenceKind::Variable) throw RuntimeErrorException("Enum members are read-only"); return state->getVarById(reference.variableId); } std::any ArcscriptVisitor::readReference(const ArcscriptReference& reference) const { - return state->getVarValueById(reference.variableId); + return reference.kind == ReferenceKind::EnumMember ? reference.value : state->getVarValueById(reference.variableId); } std::any ArcscriptVisitor::visitMention(ArcscriptParser::MentionContext *ctx) { diff --git a/README.md b/README.md index 0f500ee..1f843a0 100644 --- a/README.md +++ b/README.md @@ -108,6 +108,11 @@ On Windows, create `Cpp/build`, run CMake from that directory, and select the Re ## Cross-Language Behavior +All three interpreters support project-wide string and integer enums, read-only +`Enum.Member` constants, and validation of declared enum assignments and +comparisons. See the [enum contract and APIs](docs/enums.md) for definition shapes, +host responsibilities, and the export/native mapping contract. + The interpreters share the Arcscript grammar and maintain parallel fixture categories for: - valid scripts and assignments diff --git a/TypeScript/README.md b/TypeScript/README.md index 4e4bd1d..25342bb 100644 --- a/TypeScript/README.md +++ b/TypeScript/README.md @@ -78,6 +78,7 @@ const interpreter = new Interpreter({ | `defaultValue` | Yes | Initial value and the value restored by `reset()`. | | `value` | No | Current value that overrides `defaultValue` during initialization. | | `scope` | No | Scope qualifier. Omitted, `undefined`, or `null` means unscoped/global. | +| `enumId` | No | Declared enum ID. Keep `type` and values primitive; see the [enum contract](../docs/enums.md). | Any string is treated as a named scope. In particular, `scope: "global"` defines a literal scope named `global`; it does not define an unscoped variable. @@ -194,6 +195,8 @@ Creates an interpreter. Calling `new Interpreter()` is valid and creates an inte | Option | Description | | --- | --- | | `state` | Variable definitions keyed by ID. Required when an options object is supplied. | +| `enums` | Enum definitions keyed by stable ID; members resolve to string/integer constants. | +| `scopeNames` | All board/component custom IDs, including scopes with no variables, for enum namespace validation. | | `elementVisits` | Visit counts used by the `visits()` function. | | `currentElement` | Current element ID used by element-aware functions. | | `eventHandler` | Callback for interpreter events, such as `resetVisits`. | diff --git a/TypeScript/src/ArcscriptContext.ts b/TypeScript/src/ArcscriptContext.ts index 43c26aa..b5cac43 100644 --- a/TypeScript/src/ArcscriptContext.ts +++ b/TypeScript/src/ArcscriptContext.ts @@ -1,18 +1,113 @@ -import { ArcscriptStateDef, VarType } from './types.js'; +import { ParseError } from './errors/index.js'; +import { ArcscriptEnumDefs, ArcscriptStateDef, VarType } from './types.js'; import { isGlobalScope } from './scope.js'; -export type ArcscriptReference = Readonly<{ - kind: 'variable'; - variableId: string; - type: VarType; -}>; +// Portable enum identifiers; ordinary Arcscript variable names are unchanged. +const reservedNames = new Set( + 'abs max min random roll round sqr sqrt visits show resetVisits reset resetAll if else elseif endif and or is not true false abstract as assert async auto await base bool break byte case catch char checked class const constexpr const_cast continue decimal default delegate delete do double dynamic elif enum event explicit export extends extern false final finally fixed float for foreach friend from func get global goto if implicit import in inline int interface internal is lock long match mutable namespace native new noexcept not not_eq null nullptr object operator or or_eq out override params pass private protected public readonly ref register reinterpret_cast return sbyte sealed set short signal signed sizeof stackalloc static static_assert static_cast string struct super switch template this thread_local throw throws trait try typedef typeid typename typeof uint ulong unchecked union unsafe unsigned using ushort var virtual void volatile wchar_t when where while with yield alignas alignof and_eq asm bitand bitor char8_t char16_t char32_t compl concept co_await co_return co_yield consteval constinit decltype dynamic_cast requires xor xor_eq class_name breakpoint preload self PI TAU INF NAN tool onready setget remote master puppet remotesync mastersync puppetsync'.split( + ' ' + ) +); -// A snapshot of declarations, shared by parsing and execution. +export type ArcscriptReference = Readonly< + | { kind: 'variable'; variableId: string; type: VarType; enumId?: string } + | { + kind: 'enumMember'; + enumId: string; + memberId: string; + type: 'string' | 'integer'; + value: string | number; + } +>; + +// A validated snapshot of declarations, shared by parsing and execution. export default class ArcscriptContext { private readonly references = new Map(); + private readonly enumTypes = new Map(); - constructor(variables: ArcscriptStateDef = {}) { + constructor( + definitions: ArcscriptEnumDefs = {}, + variables: ArcscriptStateDef = {}, + scopeNames: readonly string[] = [] + ) { + const scopes = new Set(scopeNames); + Object.values(variables).forEach(variable => { + if (!isGlobalScope(variable.scope)) scopes.add(variable.scope!); + }); + const names = new Set(); + for (const [id, definition] of Object.entries(definitions)) { + this.assertName(definition.name); + if (!id || id !== definition.id || names.has(definition.name)) { + throw new ParseError( + 'Enum IDs and names must be unique and match their keys' + ); + } + if (scopes.has(definition.name)) { + throw new ParseError( + `Enum ${definition.name} conflicts with a variable scope` + ); + } + names.add(definition.name); + if ( + !['string', 'integer'].includes(definition.type) || + !definition.members.length + ) { + throw new ParseError( + `Enum ${definition.name} must have string or integer members` + ); + } + this.enumTypes.set(id, definition.type); + const memberIds = new Set(); + const memberNames = new Set(); + const values = new Set(); + for (const member of definition.members) { + this.assertName(member.name); + if ( + !member.id || + memberIds.has(member.id) || + memberNames.has(member.name) || + values.has(member.value) + ) { + throw new ParseError( + `Enum ${definition.name} has duplicate or missing members` + ); + } + if ( + (definition.type === 'string' && typeof member.value !== 'string') || + (definition.type === 'integer' && + (typeof member.value !== 'number' || + !Number.isInteger(member.value) || + member.value < -2147483648 || + member.value > 2147483647)) + ) { + throw new ParseError( + `Invalid backing value for ${definition.name}.${member.name}` + ); + } + memberIds.add(member.id); + memberNames.add(member.name); + values.add(member.value); + this.references.set( + `${definition.name}.${member.name}`, + Object.freeze({ + kind: 'enumMember', + enumId: id, + memberId: member.id, + type: definition.type, + value: member.value, + }) + ); + } + } for (const variable of Object.values(variables)) { + if ( + variable.enumId !== undefined && + this.enumTypes.get(variable.enumId) !== variable.type + ) { + throw new ParseError( + `Invalid enum reference for variable ${variable.name}` + ); + } const name = isGlobalScope(variable.scope) ? variable.name : `${variable.scope}.${variable.name}`; @@ -24,12 +119,31 @@ export default class ArcscriptContext { kind: 'variable', variableId: variable.id, type: variable.type, + enumId: variable.enumId, }) ); } } + private assertName(name: string) { + if ( + !/^[A-Za-z][A-Za-z0-9_]*$/.test(name) || + name.includes('__') || + reservedNames.has(name) + ) { + throw new ParseError(`Invalid or reserved enum identifier ${name}`); + } + } + resolve(name: string): ArcscriptReference | undefined { return this.references.get(name); } + + get hasEnums(): boolean { + return this.enumTypes.size > 0; + } + + enumType(id: string): 'string' | 'integer' | undefined { + return this.enumTypes.get(id); + } } diff --git a/TypeScript/src/ArcscriptVisitor.ts b/TypeScript/src/ArcscriptVisitor.ts index 6cb7c96..f24df3d 100644 --- a/TypeScript/src/ArcscriptVisitor.ts +++ b/TypeScript/src/ArcscriptVisitor.ts @@ -384,11 +384,15 @@ export default class ArcscriptVisitor extends ArcscriptParserVisitor { }; private readVariable(reference: ArcscriptReference): ArcscriptVariable { + if (reference.kind !== 'variable') + throw new RuntimeError('Enum members are read-only'); return this.state.getVarById(reference.variableId); } private readReference(reference: ArcscriptReference): VarValue { - return this.readVariable(reference).getValue(); + return reference.kind === 'enumMember' + ? reference.value + : this.readVariable(reference).getValue(); } visitLiteral = (ctx: LiteralContext) => { diff --git a/TypeScript/src/Generated/ArcscriptParserBase.ts b/TypeScript/src/Generated/ArcscriptParserBase.ts index fa61267..e9cd2c9 100644 --- a/TypeScript/src/Generated/ArcscriptParserBase.ts +++ b/TypeScript/src/Generated/ArcscriptParserBase.ts @@ -1,16 +1,29 @@ -import { Parser, TerminalNode, Token, TokenStream } from 'antlr4'; +import { + Parser, + ParserRuleContext, + TerminalNode, + Token, + TokenStream, +} from 'antlr4'; import ArcscriptParser, { Argument_listContext, Identifier_listContext, IdentifierContext, Mention_attributesContext, + Statement_assignmentContext, + ComparisonExpressionContext, + ExpressionContext, + ParenthesizedExpressionContext, + IdentifierExpressionContext, + LiteralExpressionContext, + FunctionCallExpressionContext, } from './ArcscriptParser.js'; import ArcscriptContext from '../ArcscriptContext.js'; type ArcscriptParserOptions = { - declarations: ArcscriptContext; elementVisits: Record; currentElement: string; + declarations: ArcscriptContext; }; type ArcscriptFunctionInfo = { @@ -18,18 +31,19 @@ type ArcscriptFunctionInfo = { maxArgs: number | null; returnType?: 'number' | 'void'; argType?: 'number' | 'variable' | 'mention'; + pure?: boolean; }; export default class ArcscriptParserBase extends Parser { static arcscriptFunctionsInfo: Record = { - abs: { minArgs: 1, maxArgs: 1, returnType: 'number' }, - max: { minArgs: 2, maxArgs: null, returnType: 'number' }, - min: { minArgs: 2, maxArgs: null, returnType: 'number' }, + abs: { minArgs: 1, maxArgs: 1, returnType: 'number', pure: true }, + max: { minArgs: 2, maxArgs: null, returnType: 'number', pure: true }, + min: { minArgs: 2, maxArgs: null, returnType: 'number', pure: true }, random: { minArgs: 0, maxArgs: 0, returnType: 'number' }, roll: { minArgs: 1, maxArgs: 2, returnType: 'number' }, - round: { minArgs: 1, maxArgs: 1, returnType: 'number' }, - sqr: { minArgs: 1, maxArgs: 1, returnType: 'number' }, - sqrt: { minArgs: 1, maxArgs: 1, returnType: 'number' }, + round: { minArgs: 1, maxArgs: 1, returnType: 'number', pure: true }, + sqr: { minArgs: 1, maxArgs: 1, returnType: 'number', pure: true }, + sqrt: { minArgs: 1, maxArgs: 1, returnType: 'number', pure: true }, visits: { minArgs: 0, maxArgs: 1, returnType: 'number' }, show: { minArgs: 1, maxArgs: null, returnType: 'void' }, reset: { @@ -104,6 +118,11 @@ export default class ArcscriptParserBase extends Parser { undefined ); } + if (argListCtx instanceof Identifier_listContext) { + argListCtx + .identifier_list() + .forEach(identifier => this.assertAssignable(identifier)); + } } } } @@ -119,6 +138,121 @@ export default class ArcscriptParserBase extends Parser { } } + assertAssignable(identifierCtx: IdentifierContext) { + if ( + this.declarations.resolve(identifierCtx.getText())?.kind === 'enumMember' + ) { + this.notifyErrorListeners( + `Enum member ${identifierCtx.getText()} is read-only`, + identifierCtx.start, + undefined + ); + } + this.assertVariable(identifierCtx); + } + + private expressionEnum(ctx: ExpressionContext): string | undefined { + if (ctx instanceof ParenthesizedExpressionContext) + return this.expressionEnum(ctx.expression()); + if (ctx instanceof IdentifierExpressionContext) + return this.declarations.resolve(ctx.identifier().getText())?.enumId; + return undefined; + } + + private isConstantExpression(ctx: ExpressionContext): boolean { + if (ctx instanceof IdentifierExpressionContext) + return ( + this.declarations.resolve(ctx.identifier().getText())?.kind === + 'enumMember' + ); + if (ctx instanceof LiteralExpressionContext) return true; + if (ctx instanceof FunctionCallExpressionContext) { + const call = ctx.function_call(); + if ( + !ArcscriptParserBase.arcscriptFunctionsInfo[call.FNAME().getText()].pure + ) + return false; + if (call.identifier_list()) { + return call + .identifier_list() + .identifier_list() + .every( + identifier => + this.declarations.resolve(identifier.getText())?.kind === + 'enumMember' + ); + } + return ( + call + .argument_list() + ?.argument_list() + .every(argument => { + const expression = argument.expression(); + return !!expression && this.isConstantExpression(expression); + }) ?? true + ); + } + return ctx + .getTypedRuleContexts(ExpressionContext) + .every(child => this.isConstantExpression(child)); + } + + // Called as assignments/comparisons are parsed, including unreachable branches. + validateEnums(ctx: ParserRuleContext) { + if (!this.declarations.hasEnums) return; + if (ctx instanceof Statement_assignmentContext) { + const enumId = this.declarations.resolve( + ctx.assignable().getText() + )?.enumId; + if ( + enumId && + (!ctx.ASSIGN() || this.expressionEnum(ctx.expression()) !== enumId) + ) { + this.notifyErrorListeners( + 'Enum assignment requires a member or variable of the same enum', + ctx.start, + undefined + ); + } + } + if ( + ctx instanceof ComparisonExpressionContext && + !(ctx.AND() || ctx.ANDKEYWORD() || ctx.OR() || ctx.ORKEYWORD()) + ) { + const left = this.expressionEnum(ctx.expression(0)); + const right = this.expressionEnum(ctx.expression(1)); + if (left && right && left !== right) { + this.notifyErrorListeners( + 'Cannot compare different enum types', + ctx.start, + undefined + ); + } + if ( + (left && !right && this.isConstantExpression(ctx.expression(1))) || + (right && !left && this.isConstantExpression(ctx.expression(0))) + ) { + this.notifyErrorListeners( + 'Enum comparisons with constants require a named member', + ctx.start, + undefined + ); + } + const enumId = left ?? right; + if ( + enumId && + (ctx.LT() || ctx.GT() || ctx.LE() || ctx.GE()) && + this.declarations.enumType(enumId) !== 'integer' + ) { + this.notifyErrorListeners( + 'Only integer enums support ordering', + ctx.start, + undefined + ); + } + } + } + assertMention(attrListCtx: Mention_attributesContext[]) { const attrs: Record< string, diff --git a/TypeScript/src/__tests__/enums.test.ts b/TypeScript/src/__tests__/enums.test.ts new file mode 100644 index 0000000..fab9e47 --- /dev/null +++ b/TypeScript/src/__tests__/enums.test.ts @@ -0,0 +1,171 @@ +import { describe, expect, test, vi } from 'vitest'; +import { Interpreter, ParseError } from '../index.js'; +import type { + ArcscriptEnumDefs, + ArcscriptStateDef, + VarValue, +} from '../index.js'; +import fixture from '../../../tests/enums.json'; +import ArcscriptContext from '../ArcscriptContext.js'; + +type EnumCase = { + name: string; + code: string; + changes?: Record; + output?: string; + values?: Record; + result?: boolean; + error?: string; + parseOnly?: boolean; + enums?: ArcscriptEnumDefs; + initialVars?: ArcscriptStateDef; + scopeNames?: string[]; +}; + +describe('shared enum contract', () => { + test.each(fixture.cases as EnumCase[])('$name', testCase => { + const state = structuredClone( + testCase.initialVars ?? fixture.initialVars + ) as ArcscriptStateDef; + for (const [id, value] of Object.entries(testCase.values ?? {})) + state[id].value = value; + const eventHandler = vi.fn(); + const interpreter = new Interpreter({ + state, + enums: testCase.enums ?? (fixture.enums as ArcscriptEnumDefs), + scopeNames: testCase.scopeNames, + eventHandler, + }); + const original = structuredClone(state); + if (testCase.error) { + expect(() => interpreter.parse(testCase.code)).toThrow(ParseError); + expect(() => interpreter.runScript(testCase.code)).toThrow(ParseError); + } else { + interpreter.parse(testCase.code); + if (!testCase.parseOnly) { + const result = interpreter.runScript(testCase.code); + expect(result.output).toBe(testCase.output ?? ''); + if (testCase.changes) expect(result.changes).toEqual(testCase.changes); + if (testCase.result !== undefined) + expect(result.result.condition).toBe(testCase.result); + } + } + expect(state).toEqual(original); + expect(eventHandler).not.toHaveBeenCalled(); + }); + + test('returned changes can be restored as primitive overrides', () => { + const interpreter = new Interpreter({ + state: fixture.initialVars as ArcscriptStateDef, + enums: fixture.enums as ArcscriptEnumDefs, + }); + const first = interpreter.runScript( + '
questStatus = QuestStatus.Active
' + ); + const next = interpreter.runScript( + '
show(questStatus)
', + first.changes + ); + expect(next.output).toBe('

active

'); + expect(next.changes).toEqual({ status: 'active' }); + }); + + test('enum validation errors identify the offending code block', () => { + const interpreter = new Interpreter({ + state: fixture.initialVars as ArcscriptStateDef, + enums: fixture.enums as ArcscriptEnumDefs, + }); + expect(() => + interpreter.parse( + '
questStatus = "active"
show(1)
' + ) + ).toThrow('at line 1, col 0'); + }); + + test('variable and scope rewriting leave enum constants alone', () => { + const interpreter = new Interpreter({ + state: fixture.initialVars as ArcscriptStateDef, + enums: fixture.enums as ArcscriptEnumDefs, + }); + const code = + '
Board.questStatus = QuestStatus.Active
'; + expect( + interpreter.replaceVariables(code, { + scoped: 'status', + QuestStatus: 'renamed', + }) + ).toBe('
Board.status = QuestStatus.Active
'); + expect(interpreter.replaceScope(code, 'Board', 'OtherBoard')).toBe( + '
OtherBoard.questStatus = QuestStatus.Active
' + ); + }); +}); + +describe('declaration contexts', () => { + test('resolved references retain identity and type when source declarations change', () => { + const enums = structuredClone(fixture.enums) as ArcscriptEnumDefs; + const variables = structuredClone(fixture.initialVars) as ArcscriptStateDef; + const context = new ArcscriptContext(enums, variables); + enums.quest.name = 'RenamedStatus'; + enums.quest.type = 'integer'; + enums.quest.members[1].value = 1; + variables.status.name = 'renamedStatus'; + variables.status.enumId = 'door'; + + expect(context.resolve('questStatus')).toEqual({ + kind: 'variable', + variableId: 'status', + type: 'string', + enumId: 'quest', + }); + expect(context.resolve('Board.questStatus')).toMatchObject({ + kind: 'variable', + variableId: 'scoped', + enumId: 'quest', + }); + expect(context.resolve('QuestStatus.Active')).toEqual({ + kind: 'enumMember', + enumId: 'quest', + memberId: 'active', + type: 'string', + value: 'active', + }); + expect(context.enumType('quest')).toBe('string'); + expect(context.resolve('RenamedStatus.Active')).toBeUndefined(); + expect(() => new ArcscriptContext(enums, variables)).toThrow(ParseError); + }); + + test('a run keeps validated bindings and the next operation reads fresh declarations', () => { + const enums = structuredClone(fixture.enums) as ArcscriptEnumDefs; + const state = structuredClone(fixture.initialVars) as ArcscriptStateDef; + const interpreter = new Interpreter({ + state, + enums, + eventHandler: () => { + state.status.name = 'renamedStatus'; + enums.quest.name = 'RenamedStatus'; + enums.quest.members[1].name = 'Started'; + enums.quest.members[1].value = 'started'; + }, + }); + const result = interpreter.runScript( + '
resetVisits()
questStatus = QuestStatus.Active
reset(questStatus)
questStatus = QuestStatus.Active
show(questStatus, QuestStatus.Active)
' + ); + expect(result.output).toBe('

activeactive

'); + expect(result.changes).toEqual({ status: 'active' }); + expect(() => + interpreter.parse( + '
questStatus == QuestStatus.Active
' + ) + ).toThrow(ParseError); + const next = interpreter.runScript( + '
renamedStatus = RenamedStatus.Started
show(renamedStatus)
' + ); + expect(next.output).toBe('

started

'); + expect(next.changes).toEqual({ status: 'started' }); + state.status.enumId = 'missing'; + expect(() => interpreter.parse('
true
')).toThrow( + ParseError + ); + }); +}); diff --git a/TypeScript/src/antlr4.interpreter.ts b/TypeScript/src/antlr4.interpreter.ts index 8f65ee5..2356a78 100644 --- a/TypeScript/src/antlr4.interpreter.ts +++ b/TypeScript/src/antlr4.interpreter.ts @@ -5,7 +5,7 @@ import ArcscriptParser from './Generated/ArcscriptParser.js'; import ArcscriptVisitor from './ArcscriptVisitor.js'; import ErrorListener from './ErrorListener.js'; import { ParseError } from './errors/index.js'; -import { ArcscriptStateDef, VarValue } from './types.js'; +import { ArcscriptEnumDefs, ArcscriptStateDef, VarValue } from './types.js'; import ArcscriptContext from './ArcscriptContext.js'; import ArcscriptState from './ArcscriptState.js'; import { isGlobalScope } from './scope.js'; @@ -17,6 +17,8 @@ import type { export type ArcscriptInterpreterOptions = { state: ArcscriptStateDef; + enums?: ArcscriptEnumDefs; + scopeNames?: readonly string[]; elementVisits?: Record; currentElement?: string; eventHandler?: (event: string, data?: unknown) => void; @@ -33,9 +35,13 @@ export default class Interpreter { private readonly elementVisits: Record; private readonly currentElement: string; private readonly emit: (event: string, data?: unknown) => void; + private readonly enumDefinitions: ArcscriptEnumDefs; + private readonly scopeNames: readonly string[]; constructor(options: ArcscriptInterpreterOptions = { state: {} }) { this.arcscriptVariables = options.state; + this.enumDefinitions = options.enums ?? {}; + this.scopeNames = options.scopeNames ?? []; this.elementVisits = options.elementVisits ?? {}; this.currentElement = options.currentElement ?? ''; this.emit = options.eventHandler ?? (() => {}); @@ -72,7 +78,11 @@ export default class Interpreter { parser.setOptions({ elementVisits: this.elementVisits, currentElement: this.currentElement, - declarations: new ArcscriptContext(this.arcscriptVariables), + declarations: new ArcscriptContext( + this.enumDefinitions, + this.arcscriptVariables, + this.scopeNames + ), }); parser.buildParseTrees = true; parser.removeErrorListeners(); diff --git a/TypeScript/src/index.ts b/TypeScript/src/index.ts index a2416cd..755e0ab 100644 --- a/TypeScript/src/index.ts +++ b/TypeScript/src/index.ts @@ -7,3 +7,13 @@ import type { export { Interpreter, RuntimeError, ParseError, FatalError }; export type { LegacyVariableRewriteOptions, LegacyVariableRewriteResult }; +export type { ArcscriptInterpreterOptions } from './antlr4.interpreter.js'; +export type { + ArcscriptEnumDefs, + EnumDef, + EnumMemberDef, + ArcscriptStateDef, + VarDef, + VarType, + VarValue, +} from './types.js'; diff --git a/TypeScript/src/types.ts b/TypeScript/src/types.ts index 0b6079f..87d8523 100644 --- a/TypeScript/src/types.ts +++ b/TypeScript/src/types.ts @@ -1,6 +1,21 @@ export type VarValue = string | number | boolean; export type VarType = 'string' | 'integer' | 'float' | 'boolean'; +export type EnumMemberDef = { + id: string; + name: string; + value: string | number; +}; + +export type EnumDef = { + id: string; + name: string; + type: 'string' | 'integer'; + members: EnumMemberDef[]; +}; + +export type ArcscriptEnumDefs = Record; + export type VarDef = { id: string; name: string; @@ -8,6 +23,7 @@ export type VarDef = { defaultValue: VarValue; value?: VarValue; scope?: string | null; + enumId?: string; }; export type MentionResult = { diff --git a/docs/enums.md b/docs/enums.md new file mode 100644 index 0000000..715cd19 --- /dev/null +++ b/docs/enums.md @@ -0,0 +1,246 @@ +# Arcscript enum contract + +This implements interpreter stage 1 of Arcweave's `docs/arcscript-enums-plan.md`. +TypeScript, C#, and C++ share the grammar and [enum fixtures](../tests/enums.json). +Application persistence, editors, exports, native enum generation, plugin distribution, +and package publishing are separate integration/release work. + +## Definitions and declarations + +Enum definitions are project-wide and keyed by stable enum ID. Members are an +ordered array with stable IDs, script names, and primitive backing values: + +```json +{ + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { "id": "inactive", "name": "Inactive", "value": "inactive" }, + { "id": "active", "name": "Active", "value": "active" } + ] + } +} +``` + +Each definition has at least one member and one backing type: `string` or +`integer`. Integers use the signed 32-bit range, −2147483648 through 2147483647, +matching C# `int` and the supported C++ targets' `int`. Member IDs, member names, +and backing values must be unique within a definition. Definition IDs must match +their collection keys; definition names must be unique across the project. +Reordering members does not change their values or identity. + +Enum and member names use the portable subset `[A-Za-z][A-Za-z0-9_]*`. Arcscript +keywords/functions and C#, C++, and GDScript reserved words are rejected. Leading +underscores, consecutive underscores (including C#'s reserved `value__` member), +and `$` are excluded from this subset. Ordinary variable identifiers +keep their existing rules. Enum names cannot match board/component **custom IDs** +(the script scope names). A global variable may share an enum's name because +unqualified variable lookup and qualified member lookup are distinct. + +Supply every board/component scope through `scopeNames`, including scopes with no +variables. All runtimes also discover scopes on their variable definitions; C# +also discovers board/component custom IDs from its project. The host must check +these collisions when creating or renaming either side of the namespace. + +An enum variable retains its backing primitive type and adds an `enumId`: + +```json +{ + "id": "status", + "name": "questStatus", + "type": "string", + "enumId": "quest", + "defaultValue": "inactive" +} +``` + +Definitions and variable references are validated before execution. Missing enum +references and incompatible declared backing types are parse errors. Selected +member IDs belong to authoring storage/export metadata, not runtime values. + +## Script rules + +| Operation | Behavior | +| --- | --- | +| `questStatus = QuestStatus.Active` | Assigns the backing string `"active"`. | +| `questStatus = otherStatus` | Valid when both variables declare the same enum ID. | +| `Board.questStatus = Component.questStatus` | Uses the same rules as globals. | +| `questStatus = (QuestStatus.Active)` | Parentheses preserve the declared enum. | +| `questStatus = "active"` | Parse error, even when the literal is a member value. | +| `difficulty = Difficulty.Easy + 1` | Parse error: computed assignments are deferred. | +| `difficulty += Difficulty.Easy` | Parse error: compound assignments are deferred. | +| `QuestStatus.Active = ...` | Parse error: enum members are read-only. | +| `reset(QuestStatus.Active)` / `resetAll(QuestStatus.Active)` | Parse error: these functions accept mutable variables. | +| `questStatus == QuestStatus.Active` | Ordinary primitive equality. `!=`, `is`, and `is not` also work. | +| `questStatus == DoorStatus.Active` | Parse error, even if backing strings match. | +| `difficulty >= Difficulty.Normal` | Integer ordering is supported. String-enum ordering is rejected. | +| `difficulty == 2` | Parse error: comparisons with constant expressions require a named member. | +| `show(QuestStatus.Active)` | Displays `active`, with no enum wrapper or label. | +| `number = Difficulty.Hard + 1` | Ordinary variables and expression operators retain primitive behavior. | + +Only a direct member/declared variable reference, optionally parenthesized, carries +an enum type during semantic validation. Computed expressions produce ordinary +primitive values. Direct enum comparisons reject differing enum IDs and raw or +computed constant expressions on the other side. Calls to `abs`, `max`, `min`, +`round`, `sqr`, and `sqrt` are constant expressions when every argument is +constant, including nested calls and enum members. Calls that depend on variables, +randomness, or visit counts remain dynamic. Classification never executes a function. +Ordinary variable operands are allowed; their values have no tracked enum origin. +Logical operators retain their +primitive truthiness behavior. These rules do not add general static typing to +Arcscript. + +Validation checks every assignment and comparison while parsing, without evaluating expressions, invoking +functions, writing state, or emitting events. It rejects invalid assignments and +comparisons in unreachable branches and short-circuited expressions too. Runtime +execution begins only after validation succeeds. + +## Declaration context + +Each parse/validation or execution operation builds one `ArcscriptContext` from +the supplied declarations. Parsing and execution share that context. Its resolver +distinguishes mutable variables from enum members and records stable variable, +enum, and member IDs together with their backing types. Member bindings also hold +their primitive constant values. + +The context snapshots declaration metadata. Changing source declarations does +not alter bindings in an active operation; subsequent operations rebuild and +validate the context. TypeScript and C# read their supplied definitions on each +operation. C++ owns its enum definitions and rebuilds the context from those +definitions and its current variable declarations. + +Visitors read and write variables by resolved ID. Mutable runtime state holds +variable values and changes separately from enum declarations. The parser's +existing semantic hooks use the same resolver for existence, mutability, enum +assignment, and comparison checks, preserving validation at the offending source +location. + +## State and host boundaries + +Defaults, current values, overrides, resets, returned changes, and saved runtime +state remain primitive. Enum constants never appear in variable changes or resets. +`reset` and `resetAll` restore the host-supplied primitive defaults using each +runtime's existing state lifecycle. + +The application/plugin must resolve stored member IDs and validate membership +when supplying defaults, debugger/API writes, plugin setters, or restored values. +The interpreters do not evaluate or validate incoming runtime-value membership. +Static same-enum assignment checks assume those boundaries supplied valid values. +Unknown values from old saves must remain available to recovery APIs, but the host +must block script execution until they have been repaired or reset. A typed getter +must report an unknown value instead of choosing a member silently. + +## Interpreter APIs + +### TypeScript + +```ts +import { Interpreter, type ArcscriptEnumDefs } from '@arcweave/arcscript'; + +const enums: ArcscriptEnumDefs = { + quest: { + id: 'quest', name: 'QuestStatus', type: 'string', + members: [ + { id: 'inactive', name: 'Inactive', value: 'inactive' }, + { id: 'active', name: 'Active', value: 'active' }, + ], + }, +}; +const interpreter = new Interpreter({ + enums, + scopeNames: ['Board', 'Component'], + state: { + status: { + id: 'status', name: 'questStatus', type: 'string', enumId: 'quest', + defaultValue: 'inactive', + }, + }, +}); +interpreter.parse('
questStatus = QuestStatus.Active
'); +const { changes } = interpreter.runScript( + '
questStatus = QuestStatus.Active
' +); +// changes: { status: 'active' } +``` + +`enums` and `scopeNames` are optional. Public definition and option types are +exported from the package. Existing variable/scope rewriting leaves enum +references intact; enum rename/conversion rewriting belongs to the lifecycle stage. + +### C# + +Use `EnumDefinition` / `EnumMemberDefinition` from `Arcweave.Interpreter`, with +`Type` set to `"string"` or `"integer"` and member `Value` boxed as `string` or +`int`. Set `Variable.EnumId` on global and scoped variables. Supply definitions +as the optional `enums` argument to `AwInterpreter`: + +```csharp +var interpreter = new AwInterpreter(project, enums: definitions); +interpreter.Parse("
questStatus = QuestStatus.Active
"); +var result = interpreter.RunScript( + "
questStatus = QuestStatus.Active
"); +// result.Changes["status"] is the string "active". +``` + +`Parse` is the public validation-only API. JSON adapters must convert integer +member values to `int`; libraries that default JSON integers to `long` must +range-check before conversion. Existing constructor calls remain valid. + +### C++ + +Use `EnumDefinition` / `EnumMemberDefinition` from `ArcscriptEnums.h`, with `type` +set to `"string"` or `"integer"` and `std::any` values containing `std::string` +or `int`. Set `Variable::enumId` and pass the definition map as the optional fifth +argument to `ArcscriptTranspiler`; `scopeNames` is the optional sixth argument. + +```cpp +Arcweave::ArcscriptTranspiler interpreter("", variables, visits, onEvent, enums); +interpreter.validate("
questStatus = QuestStatus.Active
"); +auto result = interpreter.runScript( + "
questStatus = QuestStatus.Active
"); +// result.changes["status"] contains std::string("active"). +``` + +The exported bridge adds `runScriptWithEnumsExport`, taking the existing bridge +arguments followed by definitions, a variable-ID-to-enum-ID map, and optional +scope names. `UVariable`, the existing `runScriptExport` signature, and primitive +`UTranspilerOutput` layout are unchanged. Native C++ callers must rebuild against +the updated headers/library because the native `Variable`/state classes grow. + +## Export and native mapping contract for integration + +Export a root-level, ID-keyed `enums` collection in plain JSON and each engine +format. Export global variables with primitive `type` and resolved `value`, plus +`enumId` and selected `memberId`. Scoped variable attributes retain their envelope: +`attribute.value.type`, `attribute.value.data`, `attribute.value.enumId`, and +`attribute.value.memberId`; string-backed attributes also use `plain: true`. +Importers check that both primitive fields agree with the referenced member. + +Native generation is an editor/import-time operation. Integer native members use +their explicit backing values. String native members use nonnegative signed +32-bit codes from a persisted mapping manifest keyed by stable enum/member IDs, +plus a generated native-code-to-string map. On first import, allocate codes in +member-ID order; subsequent imports allocate from a retained high-water mark. +Keep deleted codes reserved. Commit/retain this manifest with generated files; +regeneration must never derive codes from display order or reuse deleted codes. +A missing manifest for an existing generated mapping requires explicit recovery, +not automatic renumbering. The manifest is plugin metadata, not runtime state. + +This base contract does not promise Unreal Blueprint exposure: signed 32-bit +enums cannot generally be exposed as Blueprint `uint8` enums. A Blueprint subset +and compatible native generation policy must be agreed in the plugin stage. + +Generated typed accessors validate the requested enum ID and backing membership, +including the variable's scope. Provide checked setters and `TryGetEnum` recovery +for unknown saved values. Compare runtime definition IDs/types/member mappings +against compiled mappings before execution. Renames require regeneration; +deletions and backing-value/type edits require an explicit compatibility/migration +policy. Runtime downloads cannot introduce new compiled native types. + +The application/plugin release must select format versions, minimum compatible +plugin releases, and save-migration behavior before shipping enum exports. Older +interpreters cannot execute `Enum.Member` merely because exported values remain +primitive. These rollout policies, Unity/Godot/Unreal builds, and their generated +code are outside this interpreter change. diff --git a/grammar/ArcscriptParser.g4 b/grammar/ArcscriptParser.g4 index b7559f2..610dc28 100644 --- a/grammar/ArcscriptParser.g4 +++ b/grammar/ArcscriptParser.g4 @@ -66,9 +66,9 @@ statement_assignment: | ASSIGNDIV | ASSIGNMOD | ASSIGN - ) expression; + ) expression {this.validateEnums($ctx);}; -assignable: identifier {this.assertVariable($identifier.ctx);}; +assignable: identifier {this.assertAssignable($identifier.ctx);}; identifier_list: identifier {this.assertVariable($identifier.ctx);} ( @@ -91,8 +91,8 @@ expression: | SUB expression # UnaryExpression | expression (MUL | DIV | MOD) expression # MultiplicativeExpression | expression (ADD | SUB) expression # AdditiveExpression - | expression (LT | GT | LE | GE) expression # ComparisonExpression - | expression (EQ | NE | (ISKEYWORD NOTKEYWORD) | ISKEYWORD) expression # ComparisonExpression + | expression (LT | GT | LE | GE) expression {this.validateEnums($ctx);} # ComparisonExpression + | expression (EQ | NE | (ISKEYWORD NOTKEYWORD) | ISKEYWORD) expression {this.validateEnums($ctx);} # ComparisonExpression | expression (AND | ANDKEYWORD) expression # ComparisonExpression | expression (OR | ORKEYWORD) expression # ComparisonExpression | identifier {this.assertVariable($identifier.ctx);} # IdentifierExpression @@ -110,4 +110,4 @@ function_call: FNAME LPAREN identifier_list? RPAREN {this.assertFunctionArguments($FNAME, $identifier_list.ctx); } | FNAME LPAREN argument_list? RPAREN {this.assertFunctionArguments($FNAME, $argument_list.ctx);} - ; \ No newline at end of file + ; diff --git a/tests/enums.json b/tests/enums.json new file mode 100644 index 0000000..b1b61bf --- /dev/null +++ b/tests/enums.json @@ -0,0 +1,2065 @@ +{ + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + }, + "door": { + "id": "door", + "name": "DoorStatus", + "type": "string", + "members": [ + { + "id": "closed", + "name": "Closed", + "value": "closed" + }, + { + "id": "open", + "name": "Active", + "value": "active" + } + ] + }, + "difficulty": { + "id": "difficulty", + "name": "Difficulty", + "type": "integer", + "members": [ + { + "id": "easy", + "name": "Easy", + "value": 1 + }, + { + "id": "normal", + "name": "Normal", + "value": 2 + }, + { + "id": "hard", + "name": "Hard", + "value": 3 + }, + { + "id": "zero", + "name": "Zero", + "value": 0 + }, + { + "id": "low", + "name": "Lowest", + "value": -2147483648 + }, + { + "id": "high", + "name": "Highest", + "value": 2147483647 + } + ] + }, + "rank": { + "id": "rank", + "name": "Rank", + "type": "integer", + "members": [ + { + "id": "normal", + "name": "Normal", + "value": 2 + } + ] + }, + "weather": { + "id": "weather", + "name": "Weather", + "type": "string", + "members": [ + { + "id": "rain", + "name": "HeavyRain", + "value": "heavy rain" + }, + { + "id": "empty", + "name": "Empty", + "value": "" + } + ] + } + }, + "initialVars": { + "status": { + "id": "status", + "name": "questStatus", + "type": "string", + "defaultValue": "inactive", + "enumId": "quest" + }, + "other": { + "id": "other", + "name": "otherStatus", + "type": "string", + "defaultValue": "active", + "enumId": "quest" + }, + "door": { + "id": "door", + "name": "doorStatus", + "type": "string", + "defaultValue": "active", + "enumId": "door" + }, + "difficulty": { + "id": "difficulty", + "name": "difficulty", + "type": "integer", + "defaultValue": 2, + "enumId": "difficulty" + }, + "rank": { + "id": "rank", + "name": "rank", + "type": "integer", + "defaultValue": 2, + "enumId": "rank" + }, + "scoped": { + "id": "scoped", + "name": "questStatus", + "type": "string", + "defaultValue": "inactive", + "enumId": "quest", + "scope": "Board", + "cType": "boards" + }, + "component": { + "id": "component", + "name": "questStatus", + "type": "string", + "defaultValue": "active", + "enumId": "quest", + "scope": "Component", + "cType": "components" + }, + "text": { + "id": "text", + "name": "text", + "type": "string", + "defaultValue": "active" + }, + "number": { + "id": "number", + "name": "number", + "type": "integer", + "defaultValue": 2 + }, + "QuestStatus": { + "id": "QuestStatus", + "name": "QuestStatus", + "type": "integer", + "defaultValue": 5 + } + }, + "cases": [ + { + "name": "string assignment and display", + "code": "
questStatus = QuestStatus.Active
show(questStatus)
", + "changes": { + "status": "active" + }, + "output": "

active

" + }, + { + "name": "same enum assignment", + "code": "
questStatus = otherStatus
", + "changes": { + "status": "active" + } + }, + { + "name": "parenthesized assignment", + "code": "
questStatus = ((QuestStatus.Complete))
", + "changes": { + "status": "complete" + } + }, + { + "name": "scoped assignment", + "code": "
Board.questStatus = Component.questStatus
questStatus = Board.questStatus
", + "changes": { + "scoped": "active", + "status": "active" + } + }, + { + "name": "integer assignment", + "code": "
difficulty = Difficulty.Hard
show(difficulty)
", + "changes": { + "difficulty": 3 + }, + "output": "

3

" + }, + { + "name": "constant-only function arguments", + "code": "
show(QuestStatus.Active, Difficulty.Hard)
", + "output": "

active3

", + "changes": {} + }, + { + "name": "expression function arguments", + "code": "
show((Weather.HeavyRain), \":\", Difficulty.Normal + 1)
", + "output": "

heavy rain:3

" + }, + { + "name": "zero constant in identifier arguments", + "code": "
show(Difficulty.Zero)
", + "output": "

0

" + }, + { + "name": "empty constant in identifier arguments", + "code": "
show(Weather.Empty)
", + "output": "

" + }, + { + "name": "numeric functions", + "code": "
number = max(Difficulty.Easy, Difficulty.Hard)
", + "changes": { + "number": 3 + } + }, + { + "name": "ordinary assignments remain primitive", + "code": "
text = QuestStatus.Active
number += Difficulty.Hard
", + "changes": { + "text": "active", + "number": 5 + } + }, + { + "name": "runtime identity is erased", + "code": "
text = QuestStatus.Active
if text == DoorStatus.Active
show(\"equal\")
endif
", + "changes": { + "text": "active" + }, + "output": "

equal

" + }, + { + "name": "global name can match enum", + "code": "
number = QuestStatus + Difficulty.Normal
", + "changes": { + "number": 7 + } + }, + { + "name": "reset enum variables", + "code": "
questStatus = QuestStatus.Active
difficulty = Difficulty.Hard
reset(questStatus, difficulty)
", + "changes": { + "status": "inactive", + "difficulty": 2 + } + }, + { + "name": "resetAll exclusion", + "code": "
questStatus = QuestStatus.Active
resetAll(questStatus)
", + "changes": { + "other": "active", + "door": "active", + "difficulty": 2, + "rank": 2, + "scoped": "inactive", + "component": "active", + "text": "active", + "number": 2, + "QuestStatus": 5, + "status": "active" + } + }, + { + "name": "primitive current values", + "code": "
show(questStatus, Board.questStatus)
", + "values": { + "status": "complete", + "scoped": "active" + }, + "output": "

completeactive

" + }, + { + "name": "reset uses default not current", + "code": "
reset(questStatus)
", + "values": { + "status": "complete" + }, + "changes": { + "status": "inactive" + } + }, + { + "name": "member equality", + "code": "
questStatus == QuestStatus.Inactive
", + "result": true + }, + { + "name": "member inequality", + "code": "
questStatus != QuestStatus.Active
", + "result": true + }, + { + "name": "is keyword", + "code": "
questStatus is QuestStatus.Inactive
", + "result": true + }, + { + "name": "is not keyword", + "code": "
questStatus is not QuestStatus.Active
", + "result": true + }, + { + "name": "same enum variables", + "code": "
questStatus == otherStatus
", + "result": false + }, + { + "name": "numeric ordering", + "code": "
difficulty >= Difficulty.Normal
", + "result": true + }, + { + "name": "numeric less than", + "code": "
Difficulty.Easy < difficulty
", + "result": true + }, + { + "name": "numeric less or equal", + "code": "
difficulty <= Difficulty.Normal
", + "result": true + }, + { + "name": "numeric greater than", + "code": "
Difficulty.Hard > difficulty
", + "result": true + }, + { + "name": "parenthesized comparison", + "code": "
((difficulty)) == ((Difficulty.Normal))
", + "result": true + }, + { + "name": "primitive variable comparison", + "code": "
text == QuestStatus.Active
", + "result": true + }, + { + "name": "computed values retain primitives", + "code": "
Difficulty.Easy + 1 == 2
", + "result": true + }, + { + "name": "logical operators are primitive", + "code": "
Difficulty.Zero or QuestStatus.Active
", + "result": true + }, + { + "name": "lowest integer", + "code": "
Difficulty.Lowest < Difficulty.Highest
", + "result": true + }, + { + "name": "raw string assignment", + "code": "
questStatus = \"active\"
", + "error": "parse" + }, + { + "name": "raw integer assignment", + "code": "
difficulty = 2
", + "error": "parse" + }, + { + "name": "ordinary variable assignment", + "code": "
questStatus = text
", + "error": "parse" + }, + { + "name": "computed assignment", + "code": "
difficulty = Difficulty.Easy + 1
", + "error": "parse" + }, + { + "name": "function assignment", + "code": "
difficulty = max(Difficulty.Easy, Difficulty.Normal)
", + "error": "parse" + }, + { + "name": "unary assignment", + "code": "
difficulty = +Difficulty.Normal
", + "error": "parse" + }, + { + "name": "cross enum assignment", + "code": "
questStatus = DoorStatus.Active
", + "error": "parse" + }, + { + "name": "cross enum variable assignment", + "code": "
questStatus = doorStatus
", + "error": "parse" + }, + { + "name": "unknown enum", + "code": "
questStatus = Unknown.Active
", + "error": "parse" + }, + { + "name": "unknown member", + "code": "
questStatus = QuestStatus.Unknown
", + "error": "parse" + }, + { + "name": "bare enum", + "code": "
show(DoorStatus)
", + "error": "parse" + }, + { + "name": "cross enum comparison", + "code": "
questStatus == DoorStatus.Active
", + "error": "parse" + }, + { + "name": "cross enum member comparison", + "code": "
QuestStatus.Active == DoorStatus.Active
", + "error": "parse" + }, + { + "name": "cross enum variable comparison", + "code": "
otherStatus != doorStatus
", + "error": "parse" + }, + { + "name": "cross integer comparison", + "code": "
difficulty >= Rank.Normal
", + "error": "parse" + }, + { + "name": "raw string comparison", + "code": "
questStatus == \"inactive\"
", + "error": "parse" + }, + { + "name": "raw integer comparison", + "code": "
difficulty == 2
", + "error": "parse" + }, + { + "name": "reversed raw comparison", + "code": "
2 <= difficulty
", + "error": "parse" + }, + { + "name": "computed constant comparison", + "code": "
difficulty == 1 + 1
", + "error": "parse" + }, + { + "name": "parenthesized raw comparison", + "code": "
((questStatus)) is (\"inactive\")
", + "error": "parse" + }, + { + "name": "string ordering", + "code": "
questStatus < QuestStatus.Complete
", + "error": "parse" + }, + { + "name": "string member ordering", + "code": "
QuestStatus.Active >= QuestStatus.Complete
", + "error": "parse" + }, + { + "name": "member reset", + "code": "
reset(QuestStatus.Active)
", + "error": "parse" + }, + { + "name": "member resetAll exclusion", + "code": "
resetAll(Difficulty.Hard)
", + "error": "parse" + }, + { + "name": "mixed reset arguments", + "code": "
reset(questStatus, QuestStatus.Active)
", + "error": "parse" + }, + { + "name": "parenthesized reset", + "code": "
reset((QuestStatus.Active))
", + "error": "parse" + }, + { + "name": "unreachable bad assignment", + "code": "
if false
questStatus = \"active\"
endif
", + "error": "parse" + }, + { + "name": "unreachable comparison", + "code": "
true or questStatus == DoorStatus.Active
", + "error": "parse" + }, + { + "name": "no partial execution", + "code": "
number = 99
questStatus = \"active\"
", + "error": "parse" + }, + { + "name": "read-only member =", + "code": "
Difficulty.Normal = Difficulty.Hard
", + "error": "parse" + }, + { + "name": "read-only member +=", + "code": "
Difficulty.Normal += Difficulty.Hard
", + "error": "parse" + }, + { + "name": "enum compound +=", + "code": "
difficulty += Difficulty.Hard
", + "error": "parse" + }, + { + "name": "read-only member -=", + "code": "
Difficulty.Normal -= Difficulty.Hard
", + "error": "parse" + }, + { + "name": "enum compound -=", + "code": "
difficulty -= Difficulty.Hard
", + "error": "parse" + }, + { + "name": "read-only member *=", + "code": "
Difficulty.Normal *= Difficulty.Hard
", + "error": "parse" + }, + { + "name": "enum compound *=", + "code": "
difficulty *= Difficulty.Hard
", + "error": "parse" + }, + { + "name": "read-only member /=", + "code": "
Difficulty.Normal /= Difficulty.Hard
", + "error": "parse" + }, + { + "name": "enum compound /=", + "code": "
difficulty /= Difficulty.Hard
", + "error": "parse" + }, + { + "name": "read-only member %=", + "code": "
Difficulty.Normal %= Difficulty.Hard
", + "error": "parse" + }, + { + "name": "enum compound %=", + "code": "
difficulty %= Difficulty.Hard
", + "error": "parse" + }, + { + "name": "parse never executes functions", + "code": "
show(1 / 0)
", + "parseOnly": true + }, + { + "name": "parse never emits events", + "code": "
resetVisits()
", + "parseOnly": true + }, + { + "name": "context rejects mismatched enum ID", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "different", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects empty enum", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects float backing type", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "float", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects enum name class", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "class", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects enum name for", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "for", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects enum name match", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "match", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects enum name show", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "show", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects enum name and", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "and", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects enum name await", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "await", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects enum name bad-name", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "bad-name", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects enum name with space", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "with space", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects enum name $Enum", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "$Enum", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects enum name _Reserved", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "_Reserved", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects enum name 123Enum", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "123Enum", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects enum name \u00c9num", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "\u00c9num", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects member name true", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "true", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects member name return", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "return", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects member name func", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "func", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects member name $Member", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "$Member", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects member name bad.member", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "bad.member", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects duplicate member names", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Inactive", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects duplicate member IDs", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "inactive", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects duplicate backing values", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "inactive" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects missing member ID", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects mixed types", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": 1 + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects integer backing 1.5", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "integer", + "members": [ + { + "id": "one", + "name": "One", + "value": 1.5 + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects integer backing 2147483648", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "integer", + "members": [ + { + "id": "one", + "name": "One", + "value": 2147483648 + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects integer backing -2147483649", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "integer", + "members": [ + { + "id": "one", + "name": "One", + "value": -2147483649 + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects integer backing True", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "integer", + "members": [ + { + "id": "one", + "name": "One", + "value": true + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects integer backing 1", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "integer", + "members": [ + { + "id": "one", + "name": "One", + "value": "1" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects duplicate enum names", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + }, + "other": { + "id": "other", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects empty scope collision", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "scopeNames": [ + "QuestStatus" + ], + "error": "parse" + }, + { + "name": "context rejects used scope collision", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": { + "x": { + "id": "x", + "name": "x", + "type": "string", + "defaultValue": "inactive", + "scope": "QuestStatus", + "cType": "boards" + } + }, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects unknown variable enum", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": { + "x": { + "id": "x", + "name": "x", + "type": "string", + "defaultValue": "inactive", + "enumId": "unknown" + } + }, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context rejects variable backing mismatch", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": { + "x": { + "id": "x", + "name": "x", + "type": "integer", + "defaultValue": 1, + "enumId": "quest" + } + }, + "parseOnly": true, + "error": "parse" + }, + { + "name": "context permits unrelated scopes", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "parseOnly": true, + "scopeNames": [ + "OtherBoard" + ] + }, + { + "name": "member order does not change values", + "code": "
questStatus = QuestStatus.Active
", + "enums": { + "quest": { + "id": "quest", + "name": "QuestStatus", + "type": "string", + "members": [ + { + "id": "complete", + "name": "Complete", + "value": "complete" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + } + ] + }, + "door": { + "id": "door", + "name": "DoorStatus", + "type": "string", + "members": [ + { + "id": "closed", + "name": "Closed", + "value": "closed" + }, + { + "id": "open", + "name": "Active", + "value": "active" + } + ] + }, + "difficulty": { + "id": "difficulty", + "name": "Difficulty", + "type": "integer", + "members": [ + { + "id": "easy", + "name": "Easy", + "value": 1 + }, + { + "id": "normal", + "name": "Normal", + "value": 2 + }, + { + "id": "hard", + "name": "Hard", + "value": 3 + }, + { + "id": "zero", + "name": "Zero", + "value": 0 + }, + { + "id": "low", + "name": "Lowest", + "value": -2147483648 + }, + { + "id": "high", + "name": "Highest", + "value": 2147483647 + } + ] + }, + "rank": { + "id": "rank", + "name": "Rank", + "type": "integer", + "members": [ + { + "id": "normal", + "name": "Normal", + "value": 2 + } + ] + }, + "weather": { + "id": "weather", + "name": "Weather", + "type": "string", + "members": [ + { + "id": "rain", + "name": "HeavyRain", + "value": "heavy rain" + }, + { + "id": "empty", + "name": "Empty", + "value": "" + } + ] + } + }, + "changes": { + "status": "active" + } + }, + { + "name": "context rejects C++ auto keyword", + "code": "
show(1)
", + "enums": { + "quest": { + "id": "quest", + "name": "auto", + "type": "string", + "members": [ + { + "id": "inactive", + "name": "Inactive", + "value": "inactive" + }, + { + "id": "active", + "name": "Active", + "value": "active" + }, + { + "id": "complete", + "name": "Complete", + "value": "complete" + } + ] + } + }, + "initialVars": {}, + "error": "parse" + }, + { + "name": "constant pure function comparison abs(2)", + "code": "
difficulty == abs(2)
", + "error": "parse" + }, + { + "name": "constant pure function comparison max(1, 2)", + "code": "
difficulty == max(1, 2)
", + "error": "parse" + }, + { + "name": "constant pure function comparison min(2, 3)", + "code": "
difficulty == min(2, 3)
", + "error": "parse" + }, + { + "name": "constant pure function comparison round(2)", + "code": "
difficulty == round(2)
", + "error": "parse" + }, + { + "name": "constant pure function comparison sqr(2)", + "code": "
difficulty == sqr(2)
", + "error": "parse" + }, + { + "name": "constant pure function comparison sqrt(4)", + "code": "
difficulty == sqrt(4)
", + "error": "parse" + }, + { + "name": "constant pure function comparison max(abs(1), min(2, 3))", + "code": "
difficulty == max(abs(1), min(2, 3))
", + "error": "parse" + }, + { + "name": "constant pure function comparison max(Difficulty.Easy, Difficulty.Normal)", + "code": "
difficulty == max(Difficulty.Easy, Difficulty.Normal)
", + "error": "parse" + }, + { + "name": "constant pure function comparison abs(Difficulty.Normal)", + "code": "
difficulty == abs(Difficulty.Normal)
", + "error": "parse" + }, + { + "name": "constant pure function comparison abs(1 / 0)", + "code": "
difficulty == abs(1 / 0)
", + "error": "parse" + }, + { + "name": "constant pure function comparison sqrt(-1)", + "code": "
difficulty == sqrt(-1)
", + "error": "parse" + }, + { + "name": "constant pure function on left", + "code": "
max(1, 2) <= difficulty
", + "error": "parse" + }, + { + "name": "constant pure function nested in arithmetic", + "code": "
difficulty == 1 + abs(1)
", + "error": "parse" + }, + { + "name": "constant pure function in unreachable comparison", + "code": "
true or difficulty == max(1, 2)
", + "error": "parse" + }, + { + "name": "pure function of variable abs(number)", + "code": "
difficulty == abs(number)
", + "result": true + }, + { + "name": "pure function of variable max(number, Difficulty.Normal)", + "code": "
difficulty == max(number, Difficulty.Normal)
", + "result": true + }, + { + "name": "pure function of variable abs(abs(number))", + "code": "
difficulty == abs(abs(number))
", + "result": true + }, + { + "name": "pure function with computed variable argument", + "code": "
difficulty == max(Difficulty.Normal, number + 1)
", + "result": false + }, + { + "name": "dynamic function comparison random()", + "code": "
difficulty == random()
", + "parseOnly": true + }, + { + "name": "dynamic function comparison roll(2)", + "code": "
difficulty == roll(2)
", + "parseOnly": true + }, + { + "name": "dynamic function comparison visits()", + "code": "
difficulty == visits()
", + "parseOnly": true + }, + { + "name": "dynamic function comparison abs(random())", + "code": "
difficulty == abs(random())
", + "parseOnly": true + }, + { + "name": "dynamic function comparison round(roll(2))", + "code": "
difficulty == round(roll(2))
", + "parseOnly": true + }, + { + "name": "dynamic function comparison max(1, visits())", + "code": "
difficulty == max(1, visits())
", + "parseOnly": true + }, + { + "name": "ordinary variable may compare with constant pure function", + "code": "
number == abs(2)
", + "result": true + }, + { + "name": "native reserved name Status.value__", + "code": "
show(1)
", + "enums": { + "e": { + "id": "e", + "name": "Status", + "type": "integer", + "members": [ + { + "id": "m", + "name": "value__", + "value": 1 + } + ] + } + }, + "initialVars": {}, + "error": "parse" + }, + { + "name": "native reserved name Status.Bad__Name", + "code": "
show(1)
", + "enums": { + "e": { + "id": "e", + "name": "Status", + "type": "integer", + "members": [ + { + "id": "m", + "name": "Bad__Name", + "value": 1 + } + ] + } + }, + "initialVars": {}, + "error": "parse" + }, + { + "name": "native reserved name Bad__Name.Active", + "code": "
show(1)
", + "enums": { + "e": { + "id": "e", + "name": "Bad__Name", + "type": "integer", + "members": [ + { + "id": "m", + "name": "Active", + "value": 1 + } + ] + } + }, + "initialVars": {}, + "error": "parse" + }, + { + "name": "portable single underscores remain valid", + "code": "
show(Quest_Status.In_Progress_)
", + "enums": { + "e": { + "id": "e", + "name": "Quest_Status", + "type": "integer", + "members": [ + { + "id": "m", + "name": "In_Progress_", + "value": 1 + } + ] + } + }, + "initialVars": {}, + "output": "

1

" + }, + { + "name": "ordinary variable double underscores remain valid", + "code": "
show(legacy__value)
", + "initialVars": { + "legacy": { + "id": "legacy", + "name": "legacy__value", + "type": "integer", + "defaultValue": 42 + } + }, + "output": "

42

" + }, + { + "name": "empty pure function arguments report parse errors", + "code": "
difficulty == max()
", + "error": "parse" + } + ] +} From 0cdc5dc807095b4fd4b071fcca04e11d8d56c751 Mon Sep 17 00:00:00 2001 From: panayotis_kalaitzoglou Date: Wed, 11 Nov 2026 08:50:02 +0200 Subject: [PATCH 3/8] fix: preserve enum declaration lookup and parse diagnostics Separate scope/name keys, normalize absent enum IDs, and validate declarations before legacy rewriting. Preserve syntax failures and locate enum diagnostics, refresh native name-based lookups, and reuse the identifier regex. Add shared and runtime-specific regressions for the review findings. --- CSharp/EnumTests.cs | 61 +++++- CSharp/Interpreter/ArcscriptContext.cs | 10 +- CSharp/Interpreter/ArcscriptExceptions.cs | 9 + CSharp/Interpreter/ArcscriptParserBase.cs | 17 +- CSharp/Interpreter/ArcscriptTranspiler.cs | 52 ++--- Cpp/demo/EnumTests.cpp | 80 +++++++- Cpp/src/ArcscriptContext.h | 21 +- Cpp/src/ArcscriptHelpers.h | 18 +- Cpp/src/ArcscriptParserBase.cpp | 16 +- Cpp/src/ArcscriptParserBase.h | 3 +- TypeScript/src/ArcscriptContext.ts | 21 +- TypeScript/src/__tests__/enums.test.ts | 45 ++++- TypeScript/src/antlr4.interpreter.ts | 25 ++- TypeScript/src/types.ts | 2 +- docs/enums.md | 21 +- tests/enums.json | 223 ++++++++++++++++++++++ 16 files changed, 539 insertions(+), 85 deletions(-) diff --git a/CSharp/EnumTests.cs b/CSharp/EnumTests.cs index d9e23f4..7e029e7 100644 --- a/CSharp/EnumTests.cs +++ b/CSharp/EnumTests.cs @@ -69,8 +69,19 @@ public void SharedContract(JToken test) var code = (string)test["code"]; if (test["error"] != null) { - Assert.Throws(() => interpreter.Parse(code)); - Assert.Throws(() => interpreter.RunScript(code)); + foreach (TestDelegate operation in new TestDelegate[] { + () => interpreter.Parse(code), () => interpreter.RunScript(code) + }) + { + var error = Assert.Throws(operation); + if (test["errorContains"] != null) + Assert.That(error.Message, Does.Contain((string)test["errorContains"])); + if (test["errorLocation"] != null) + { + Assert.That(error.Line, Is.EqualTo((int)test["errorLocation"]["line"])); + Assert.That(error.Column, Is.EqualTo((int)test["errorLocation"]["col"])); + } + } Assert.That(project.GetAllVariables().ToDictionary(variable => variable.Id, variable => variable.Value), Is.EquivalentTo(original)); } else @@ -99,6 +110,52 @@ public void SharedContract(JToken test) } }; + [TestCase("questStatus == ")] + [TestCase("questStatus = ")] + [TestCase("questStatus = @ \"active\"")] + public void SyntaxErrorsTakePrecedenceOverEnumValidation(string expression) + { + var variable = new Variable("status", "questStatus", "inactive") { EnumId = "quest" }; + var project = new Project.Project(new List(), new List { variable }, new List()); + var interpreter = new AwInterpreter(project, enums: SnapshotEnums()); + var code = "
" + expression + "
"; + foreach (TestDelegate operation in new TestDelegate[] { + () => interpreter.Parse(code), () => interpreter.RunScript(code) + }) + { + var error = Assert.Throws(operation); + Assert.That(error.Message, Does.Contain("errors:").And.Not.Contain("Enum")); + } + Assert.That(variable.Value, Is.EqualTo("inactive")); + } + + [TestCase("label", typeof(KeyNotFoundException))] + [TestCase("label", typeof(ArgumentException))] + public void ParseAndRunNormalizeMalformedMentionErrors(string mention, Type innerType) + { + var project = new Project.Project(new List(), new List(), new List()); + var interpreter = new AwInterpreter(project); + var code = "
visits(" + mention + ")
"; + foreach (TestDelegate operation in new TestDelegate[] { + () => interpreter.Parse(code), () => interpreter.RunScript(code) + }) + { + var error = Assert.Throws(operation); + Assert.That(error.InnerException, Is.TypeOf(innerType)); + } + } + + [Test] + public void EmptyParseIsInvalidWhileEmptyRunRemainsANoOp() + { + var project = new Project.Project(new List(), new List(), new List()); + var interpreter = new AwInterpreter(project); + Assert.Throws(() => interpreter.Parse("")); + var result = interpreter.RunScript(""); + Assert.That(result.Output, Is.Empty); + Assert.That(result.Changes, Is.Empty); + } + [Test] public void ReferencesSnapshotDeclarationIdentityAndType() { diff --git a/CSharp/Interpreter/ArcscriptContext.cs b/CSharp/Interpreter/ArcscriptContext.cs index af576dc..77af754 100644 --- a/CSharp/Interpreter/ArcscriptContext.cs +++ b/CSharp/Interpreter/ArcscriptContext.cs @@ -33,7 +33,7 @@ internal ArcscriptReference(ReferenceKind kind, Type type, string variableId = n public sealed class ArcscriptContext { private static readonly HashSet ReservedNames = new HashSet("abs max min random roll round sqr sqrt visits show resetVisits reset resetAll if else elseif endif and or is not true false abstract as assert async auto await base bool break byte case catch char checked class const constexpr const_cast continue decimal default delegate delete do double dynamic elif enum event explicit export extends extern false final finally fixed float for foreach friend from func get global goto if implicit import in inline int interface internal is lock long match mutable namespace native new noexcept not not_eq null nullptr object operator or or_eq out override params pass private protected public readonly ref register reinterpret_cast return sbyte sealed set short signal signed sizeof stackalloc static static_assert static_cast string struct super switch template this thread_local throw throws trait try typedef typeid typename typeof uint ulong unchecked union unsafe unsigned using ushort var virtual void volatile wchar_t when where while with yield alignas alignof and_eq asm bitand bitor char8_t char16_t char32_t compl concept co_await co_return co_yield consteval constinit decltype dynamic_cast requires xor xor_eq class_name breakpoint preload self PI TAU INF NAN tool onready setget remote master puppet remotesync mastersync puppetsync".Split(' ')); - private readonly Dictionary _references = new Dictionary(); + private readonly Dictionary<(string Scope, string Name), ArcscriptReference> _references = new Dictionary<(string, string), ArcscriptReference>(); private readonly Dictionary _enumTypes = new Dictionary(); public bool HasEnums => _enumTypes.Count > 0; @@ -69,7 +69,7 @@ public ArcscriptContext(IReadOnlyDictionary definitions if ((definition.Type == "string" && !(member.Value is string)) || (definition.Type == "integer" && !(member.Value is int))) throw new ParseException($"Invalid backing value for {definition.Name}.{member.Name}"); - _references.Add(definition.Name + "." + member.Name, + _references.Add((definition.Name, member.Name), new ArcscriptReference(ReferenceKind.EnumMember, type, enumId: entry.Key, memberId: member.Id, value: member.Value)); } @@ -78,7 +78,7 @@ public ArcscriptContext(IReadOnlyDictionary definitions { if (variable.EnumId != null && (!_enumTypes.TryGetValue(variable.EnumId, out var type) || type != variable.Type)) throw new ParseException($"Invalid enum reference for variable {variable.Name}"); - var name = variable.Parent == null ? variable.Name : variable.Parent.CustomId + "." + variable.Name; + var name = (variable.Parent?.CustomId, variable.Name); // Preserve the existing first-match behavior for ordinary variable names. if (!_references.ContainsKey(name)) _references.Add(name, new ArcscriptReference(ReferenceKind.Variable, variable.Type, @@ -94,7 +94,9 @@ private static void AssertName(string name) public ArcscriptReference Resolve(string name) { - return _references.TryGetValue(name, out var reference) ? reference : null; + var dot = name.IndexOf('.'); + var key = dot < 0 ? (null, name) : (name.Substring(0, dot), name.Substring(dot + 1)); + return _references.TryGetValue(key, out var reference) ? reference : null; } public Type EnumType(string id) => _enumTypes[id]; diff --git a/CSharp/Interpreter/ArcscriptExceptions.cs b/CSharp/Interpreter/ArcscriptExceptions.cs index acea2c9..171a2d0 100644 --- a/CSharp/Interpreter/ArcscriptExceptions.cs +++ b/CSharp/Interpreter/ArcscriptExceptions.cs @@ -13,6 +13,9 @@ public RuntimeException(string message, System.Exception innerException) : base( public class ParseException : System.Exception { + public int? Line { get; } + public int? Column { get; } + public ParseException(string message) : base(message) { } @@ -20,6 +23,12 @@ public ParseException(string message) : base(message) public ParseException(string message, System.Exception innerException) : base(message, innerException) { } + + public ParseException(string message, int line, int column) : base($"line {line}:{column} {message}") + { + Line = line; + Column = column; + } } } diff --git a/CSharp/Interpreter/ArcscriptParserBase.cs b/CSharp/Interpreter/ArcscriptParserBase.cs index 089b772..a8dc709 100644 --- a/CSharp/Interpreter/ArcscriptParserBase.cs +++ b/CSharp/Interpreter/ArcscriptParserBase.cs @@ -35,18 +35,21 @@ public void SetProject(IProject project, ArcscriptContext declarations = null) { public override string GrammarFileName => throw new System.NotImplementedException(); + private ParseException Error(string message, ParserRuleContext context) => + new ParseException(message, currentLine, context.Start.StartIndex - openTagEndPos); + public bool assertVariable(ArcscriptParser.IdentifierContext identifierContext) { var variableName = identifierContext.GetText(); if (Declarations.Resolve(variableName) == null) - throw new ParseException($"The variable {variableName} does not exist"); + throw Error($"The variable {variableName} does not exist", identifierContext); return true; } public void assertAssignable(ArcscriptParser.IdentifierContext identifierContext) { if (Declarations.Resolve(identifierContext.GetText())?.Kind == ReferenceKind.EnumMember) - throw new ParseException($"Enum member {identifierContext.GetText()} is read-only"); + throw Error($"Enum member {identifierContext.GetText()} is read-only", identifierContext); assertVariable(identifierContext); } @@ -78,11 +81,11 @@ private bool IsConstantExpression(ArcscriptParser.ExpressionContext context) public void validateEnums(ParserRuleContext context) { - if (!Declarations.HasEnums) return; + if (!Declarations.HasEnums || NumberOfSyntaxErrors > 0) return; if (context is ArcscriptParser.Statement_assignmentContext assignment && Declarations.Resolve(assignment.assignable().GetText())?.EnumId is string enumId && (assignment.ASSIGN() == null || ExpressionEnum(assignment.expression()) != enumId)) - throw new ParseException("Enum assignment requires a member or variable of the same enum"); + throw Error("Enum assignment requires a member or variable of the same enum", context); if (context is ArcscriptParser.ComparisonExpressionContext comparison && comparison.AND() == null && comparison.ANDKEYWORD() == null && comparison.OR() == null && comparison.ORKEYWORD() == null) @@ -90,14 +93,14 @@ public void validateEnums(ParserRuleContext context) var left = ExpressionEnum(comparison.expression(0)); var right = ExpressionEnum(comparison.expression(1)); if (left != null && right != null && left != right) - throw new ParseException("Cannot compare different enum types"); + throw Error("Cannot compare different enum types", context); if ((left != null && right == null && IsConstantExpression(comparison.expression(1))) || (right != null && left == null && IsConstantExpression(comparison.expression(0)))) - throw new ParseException("Enum comparisons with constants require a named member"); + throw Error("Enum comparisons with constants require a named member", context); var id = left ?? right; if (id != null && (comparison.LT() != null || comparison.GT() != null || comparison.LE() != null || comparison.GE() != null) && Declarations.EnumType(id) != typeof(int)) - throw new ParseException("Only integer enums support ordering"); + throw Error("Only integer enums support ordering", context); } } diff --git a/CSharp/Interpreter/ArcscriptTranspiler.cs b/CSharp/Interpreter/ArcscriptTranspiler.cs index b0cf28c..2259a36 100644 --- a/CSharp/Interpreter/ArcscriptTranspiler.cs +++ b/CSharp/Interpreter/ArcscriptTranspiler.cs @@ -49,28 +49,40 @@ private ArcscriptContext CreateContext() private (ArcscriptParser.InputContext Tree, ArcscriptContext Declarations) ParseWithContext(string code) { - var declarations = CreateContext(); - ICharStream stream = CharStreams.fromString(code); - ArcscriptLexer lexer = new ArcscriptLexer(stream); var lexerErrorListener = new ErrorListener(); - lexer.AddErrorListener(lexerErrorListener); - ITokenStream tokens = new CommonTokenStream(lexer); var parserErrorListener = new ErrorListener(); - ArcscriptParser parser = new ArcscriptParser(tokens); - parser.AddErrorListener(parserErrorListener); - parser.SetProject(Project, declarations); - ArcscriptParser.InputContext tree = parser.input(); - - if (lexerErrorListener.HasErrors) + void ThrowSyntaxErrors(System.Exception? inner = null) { - throw new ParseException("Lexing errors:\n" + string.Join("\n", lexerErrorListener.Errors)); + if (lexerErrorListener.HasErrors) + throw new ParseException("Lexing errors:\n" + string.Join("\n", lexerErrorListener.Errors), inner); + if (parserErrorListener.HasErrors) + throw new ParseException("Parsing errors:\n" + string.Join("\n", parserErrorListener.Errors), inner); } - if (parserErrorListener.HasErrors) + + ArcscriptContext declarations; + ArcscriptParser.InputContext tree; + try { - throw new ParseException("Parsing errors:\n" + string.Join("\n", parserErrorListener.Errors)); + declarations = CreateContext(); + ICharStream stream = CharStreams.fromString(code); + ArcscriptLexer lexer = new ArcscriptLexer(stream); + lexer.AddErrorListener(lexerErrorListener); + ITokenStream tokens = new CommonTokenStream(lexer); + ArcscriptParser parser = new ArcscriptParser(tokens); + parser.AddErrorListener(parserErrorListener); + parser.SetProject(Project, declarations); + tree = parser.input(); } - + catch (System.Exception e) + { + // Recovery callbacks must not obscure an earlier syntax error. + ThrowSyntaxErrors(e); + if (e is ParseException) throw; + throw new ParseException(e.Message, e); + } + + ThrowSyntaxErrors(); return (tree, declarations); } @@ -81,15 +93,7 @@ public TranspilerOutput RunScript(string code) return new TranspilerOutput(); } - (ArcscriptParser.InputContext Tree, ArcscriptContext Declarations) parsed; - try - { - parsed = ParseWithContext(code); - } - catch (System.Exception e) - { - throw new ParseException(e.Message, e); - } + var parsed = ParseWithContext(code); var tree = parsed.Tree; ArcscriptVisitor visitor = new ArcscriptVisitor(this.ElementId, this.Project, _emit, diff --git a/Cpp/demo/EnumTests.cpp b/Cpp/demo/EnumTests.cpp index 30b9492..3c3a8a4 100644 --- a/Cpp/demo/EnumTests.cpp +++ b/Cpp/demo/EnumTests.cpp @@ -86,6 +86,63 @@ void declarationLifecycleTests() { require(rejected, "Next operation did not validate updated enum references"); } +void currentNameLookupTests() { + std::map variables{ + {"a_scoped", {"a_scoped", "score", AW_INTEGER, 2, "Board", 2}}, + {"z_legacy", {"z_legacy", "Board.score", AW_INTEGER, 100, "", 100}} + }; + ArcscriptTranspiler interpreter("", variables, {}, [](const char*) {}); + auto& state = interpreter.state; + require(std::any_cast(state.getVarValue({"score", "Board"})) == 2, + "Dotted global name shadowed the scoped getter"); + require(std::any_cast(state.getVarValue({"Board.score", ""})) == 100, + "Host getter lost access to the legacy global declaration"); + state.variableValues.at("a_scoped").name = "renamed"; + state.variableValues.at("a_scoped").scope = "OtherBoard"; + require(state.getVar({"renamed", "OtherBoard"}).id == "a_scoped", + "Host declaration lookup did not observe renamed metadata"); + state.setVarValue({"renamed", "OtherBoard"}, 7); + require(std::any_cast(state.getVarValue({"renamed", "OtherBoard"})) == 7 && + std::any_cast(state.getVarValueById("a_scoped")) == 7, + "Name and ID helpers disagree after rename"); + auto result = interpreter.runScript("
OtherBoard.renamed += 1
"); + require(std::any_cast(result.changes.at("a_scoped")) == 8 && + std::any_cast(state.getVarValue({"renamed", "OtherBoard"})) == 8, + "Interpreter and host helpers disagree after rename"); + bool rejected = false; + try { state.getVarValue({"score", "Board"}); } + catch (const std::out_of_range&) { rejected = true; } + require(rejected && state.variableValues.size() == 2 && state.variableChanges.size() == 1, + "Unknown names should fail without inserting variables"); +} + +void bridgeEnumReferenceTests() { + UVariable variable{}; + variable.id = "score"; + variable.name = "score"; + variable.type = AW_INTEGER; + variable.int_val = variable.default_int_val = 1; + variable.has_default_value = true; + const char* code = "
score = 999
"; + for (bool withDefinitions : {false, true}) { + std::map enums; + if (withDefinitions) enums["rank"] = {"rank", "Rank", "integer", {{"one", "One", 1}}}; + auto result = runScriptWithEnumsExport(code, "", &variable, 1, nullptr, 0, + [](const char*) {}, enums, {}); + bool accepted = result->changesLen == 1 && result->changes[0].int_result == 999; + deallocateOutput(result); + require(accepted, "Absent bridge enum reference changed primitive assignment"); + bool rejected = false; + try { + auto invalid = runScriptWithEnumsExport(code, "", &variable, 1, nullptr, 0, + [](const char*) {}, enums, {{"score", ""}}); + deallocateOutput(invalid); + } + catch (const ParseErrorException&) { rejected = true; } + require(rejected, "Explicit empty bridge enum reference was accepted"); + } +} + int main(int argc, char* argv[]) { if (argc != 2) return 1; std::ifstream input(argv[1]); @@ -115,7 +172,8 @@ int main(int argc, char* argv[]) { variable.value = test.contains("values") && test["values"].contains(it.key()) ? primitive(test["values"][it.key()]) : variable.defaultValue; variable.scope = definition.value("scope", ""); - variable.enumId = definition.value("enumId", ""); + if (definition.contains("enumId") && !definition["enumId"].is_null()) + variable.enumId = definition["enumId"].get(); variables[it.key()] = variable; } int events = 0; @@ -127,7 +185,15 @@ int main(int argc, char* argv[]) { [&](const char*) { ++events; }, enums, test.value("scopeNames", std::vector{})); interpreter->validate(code); } - catch (const ParseErrorException&) { rejected = true; } + catch (const ParseErrorException& error) { + rejected = true; + if (test.contains("errorContains")) + require(error.message.find(test["errorContains"].get()) != std::string::npos, + "Unexpected validation error: " + error.message); + if (test.contains("errorLocation")) + require(error.line == test["errorLocation"]["line"] && error.charPositionInLine == test["errorLocation"]["col"], + "Validation error did not identify the offending code block and column"); + } require(rejected == test.contains("error"), "Unexpected validation result"); require((!interpreter || interpreter->state.variableChanges.empty()) && events == 0, "Validation executed script"); if (rejected) { @@ -167,7 +233,7 @@ int main(int argc, char* argv[]) { bridge.default_int_val = std::any_cast(variable.defaultValue); } bridgeVariables.push_back(bridge); - if (!variable.enumId.empty()) references[id] = variable.enumId; + if (variable.enumId) references[id] = *variable.enumId; } auto bridge = runScriptWithEnumsExport(code.c_str(), "", bridgeVariables.data(), bridgeVariables.size(), nullptr, 0, [&](const char*) { ++events; }, enums, references); @@ -190,13 +256,15 @@ int main(int argc, char* argv[]) { std::cerr << test["name"] << ": " << error.what() << '\n'; } } - for (auto test : {declarationContextTests, declarationLifecycleTests}) { + const auto additionalTests = {declarationContextTests, declarationLifecycleTests, + currentNameLookupTests, bridgeEnumReferenceTests}; + for (auto test : additionalTests) { try { test(); } catch (const std::exception& error) { ++failures; - std::cerr << "Declaration context: " << error.what() << '\n'; + std::cerr << "Native regression: " << error.what() << '\n'; } } - std::cout << fixture["cases"].size() << " enum cases and 2 context tests, " << failures << " failures\n"; + std::cout << fixture["cases"].size() << " enum cases and " << additionalTests.size() << " native regressions, " << failures << " failures\n"; return failures ? 1 : 0; } diff --git a/Cpp/src/ArcscriptContext.h b/Cpp/src/ArcscriptContext.h index 23bf69e..ac9fb2c 100644 --- a/Cpp/src/ArcscriptContext.h +++ b/Cpp/src/ArcscriptContext.h @@ -18,7 +18,7 @@ struct ArcscriptReference { // A validated snapshot of declarations, shared by parsing and execution. class ArcscriptContext { - std::map references; + std::map, ArcscriptReference> references; std::map enumTypes; static void assertName(const std::string& name) { static const std::set reserved = [] { @@ -27,7 +27,8 @@ class ArcscriptContext { for (std::string word; input >> word;) result.insert(word); return result; }(); - if (!std::regex_match(name, std::regex("[A-Za-z][A-Za-z0-9_]*")) || name.find("__") != std::string::npos || reserved.count(name)) + static const std::regex identifierPattern("[A-Za-z][A-Za-z0-9_]*"); + if (!std::regex_match(name, identifierPattern) || name.find("__") != std::string::npos || reserved.count(name)) throw ParseErrorException("Invalid or reserved enum identifier " + name); } public: @@ -60,25 +61,25 @@ class ArcscriptContext { ? strings.insert(std::any_cast(member.value)).second : integers.insert(std::any_cast(member.value)).second; if (!unique) throw ParseErrorException("Enum " + definition.name + " has duplicate backing values"); - references[definition.name + "." + member.name] = {ReferenceKind::EnumMember, type, "", id, member.id, member.value}; + references[{definition.name, member.name}] = {ReferenceKind::EnumMember, type, "", id, member.id, member.value}; } } for (const auto& [id, variable] : variables) { - if (!variable.enumId.empty()) { - auto type = enumTypes.find(variable.enumId); + if (variable.enumId) { + auto type = enumTypes.find(*variable.enumId); if (type == enumTypes.end() || type->second != variable.type) throw ParseErrorException("Invalid enum reference for variable " + variable.name); } - auto name = variable.scope.empty() ? variable.name : variable.scope + "." + variable.name; - auto existing = resolve(name); - if (existing && existing->kind == ReferenceKind::EnumMember) continue; // Match the existing native name map's last-match behavior. - references[name] = {ReferenceKind::Variable, variable.type, id, variable.enumId, "", {}}; + references[{variable.scope, variable.name}] = {ReferenceKind::Variable, variable.type, id, variable.enumId.value_or(""), "", {}}; } } const ArcscriptReference* resolve(const std::string& name) const { - auto reference = references.find(name); + auto dot = name.find('.'); + auto key = dot == std::string::npos ? std::make_pair(std::string{}, name) + : std::make_pair(name.substr(0, dot), name.substr(dot + 1)); + auto reference = references.find(key); return reference == references.end() ? nullptr : &reference->second; } diff --git a/Cpp/src/ArcscriptHelpers.h b/Cpp/src/ArcscriptHelpers.h index b16eb85..fd78466 100755 --- a/Cpp/src/ArcscriptHelpers.h +++ b/Cpp/src/ArcscriptHelpers.h @@ -6,6 +6,8 @@ #include #include #include +#include +#include #include "ArcscriptOutputs.h" #include "ArcscriptErrorExceptions.h" @@ -32,13 +34,21 @@ struct Variable { std::any value; std::string scope; std::any defaultValue; - std::string enumId; + std::optional enumId; }; class ArcscriptState { + const std::string& getVarId(const IdentifierDef& identifier) const { + // Metadata is mutable; resolve current names and preserve last-match behavior. + for (auto it = variableValues.rbegin(); it != variableValues.rend(); ++it) + if (it->second.name == identifier.name && it->second.scope == identifier.scope) + return it->first; + throw std::out_of_range("Unknown variable " + getVarFullName(identifier)); + } public: std::map variableChanges; std::map variableValues; + // Legacy constructor snapshot; name-based helpers resolve current metadata. std::map varNameToID; ArcscriptOutputs outputs; std::string currentElement; @@ -78,15 +88,15 @@ class ArcscriptState { } inline std::any getVarValue(IdentifierDef identifier) { - return getVarValueById(varNameToID.at(getVarFullName(identifier))); + return getVarValueById(getVarId(identifier)); } inline Variable getVar(IdentifierDef identifier) { - return getVarById(varNameToID.at(getVarFullName(identifier))); + return getVarById(getVarId(identifier)); } inline void setVarValue(IdentifierDef identifier, std::any value) { - setVarValueById(varNameToID.at(getVarFullName(identifier)), std::move(value)); + setVarValueById(getVarId(identifier), std::move(value)); } inline std::any getVarValueById(const std::string& id) const { diff --git a/Cpp/src/ArcscriptParserBase.cpp b/Cpp/src/ArcscriptParserBase.cpp index 1ca814e..8ab8168 100755 --- a/Cpp/src/ArcscriptParserBase.cpp +++ b/Cpp/src/ArcscriptParserBase.cpp @@ -7,18 +7,22 @@ using namespace antlr4; +Arcweave::ParseErrorException ArcscriptParserBase::error(const std::string& message, ParserRuleContext* context) const { + return Arcweave::ParseErrorException(message, currentLine, context->getStart()->getStartIndex() - openTagEndPos); +} + bool ArcscriptParserBase::assertVariable(antlr4::ParserRuleContext *identifierContext) const { std::string variableName = identifierContext->getText(); if (_declarations->resolve(variableName)) { return true; } - throw Arcweave::ParseErrorException("Unknown variable \"" + variableName + "\""); + throw error("Unknown variable \"" + variableName + "\"", identifierContext); } void ArcscriptParserBase::assertAssignable(ParserRuleContext *identifier) const { auto reference = _declarations->resolve(identifier->getText()); if (reference && reference->kind == Arcweave::ReferenceKind::EnumMember) - throw Arcweave::ParseErrorException("Enum member " + identifier->getText() + " is read-only"); + throw error("Enum member " + identifier->getText() + " is read-only", identifier); assertVariable(identifier); } @@ -66,21 +70,21 @@ void ArcscriptParserBase::validateEnums(ParserRuleContext *context) const { auto variable = declarations.resolve(assignment->assignable()->getText()); if (variable && !variable->enumId.empty() && (!assignment->ASSIGN() || expressionEnum(assignment->expression(), declarations) != variable->enumId)) - throw Arcweave::ParseErrorException("Enum assignment requires a member or variable of the same enum"); + throw error("Enum assignment requires a member or variable of the same enum", context); } if (auto comparison = dynamic_cast(context)) { if (comparison->AND() || comparison->ANDKEYWORD() || comparison->OR() || comparison->ORKEYWORD()) return; auto left = expressionEnum(comparison->expression(0), declarations); auto right = expressionEnum(comparison->expression(1), declarations); if (!left.empty() && !right.empty() && left != right) - throw Arcweave::ParseErrorException("Cannot compare different enum types"); + throw error("Cannot compare different enum types", context); if ((!left.empty() && right.empty() && isConstantExpression(comparison->expression(1), declarations)) || (!right.empty() && left.empty() && isConstantExpression(comparison->expression(0), declarations))) - throw Arcweave::ParseErrorException("Enum comparisons with constants require a named member"); + throw error("Enum comparisons with constants require a named member", context); auto id = left.empty() ? right : left; if (!id.empty() && (comparison->LT() || comparison->GT() || comparison->LE() || comparison->GE()) && declarations.enumType(id) != Arcweave::AW_INTEGER) - throw Arcweave::ParseErrorException("Only integer enums support ordering"); + throw error("Only integer enums support ordering", context); } } diff --git a/Cpp/src/ArcscriptParserBase.h b/Cpp/src/ArcscriptParserBase.h index fdcb236..08556bf 100755 --- a/Cpp/src/ArcscriptParserBase.h +++ b/Cpp/src/ArcscriptParserBase.h @@ -7,7 +7,8 @@ class ArcscriptParserBase : public antlr4::Parser { private: Arcweave::ArcscriptState* _state; const Arcweave::ArcscriptContext* _declarations; - size_t openTagEndPos; + size_t openTagEndPos = 0; + Arcweave::ParseErrorException error(const std::string& message, antlr4::ParserRuleContext* context) const; public: int currentLine = 0; ArcscriptParserBase(antlr4::TokenStream *input) : Parser(input) { } diff --git a/TypeScript/src/ArcscriptContext.ts b/TypeScript/src/ArcscriptContext.ts index b5cac43..f7dea1e 100644 --- a/TypeScript/src/ArcscriptContext.ts +++ b/TypeScript/src/ArcscriptContext.ts @@ -88,7 +88,7 @@ export default class ArcscriptContext { memberNames.add(member.name); values.add(member.value); this.references.set( - `${definition.name}.${member.name}`, + this.referenceKey(member.name, definition.name), Object.freeze({ kind: 'enumMember', enumId: id, @@ -101,16 +101,14 @@ export default class ArcscriptContext { } for (const variable of Object.values(variables)) { if ( - variable.enumId !== undefined && + variable.enumId != null && this.enumTypes.get(variable.enumId) !== variable.type ) { throw new ParseError( `Invalid enum reference for variable ${variable.name}` ); } - const name = isGlobalScope(variable.scope) - ? variable.name - : `${variable.scope}.${variable.name}`; + const name = this.referenceKey(variable.name, variable.scope); // Preserve the existing first-match behavior for ordinary variable names. if (!this.references.has(name)) this.references.set( @@ -119,7 +117,7 @@ export default class ArcscriptContext { kind: 'variable', variableId: variable.id, type: variable.type, - enumId: variable.enumId, + enumId: variable.enumId ?? undefined, }) ); } @@ -136,7 +134,16 @@ export default class ArcscriptContext { } resolve(name: string): ArcscriptReference | undefined { - return this.references.get(name); + const dot = name.indexOf('.'); + const key = + dot < 0 + ? this.referenceKey(name) + : this.referenceKey(name.slice(dot + 1), name.slice(0, dot)); + return this.references.get(key); + } + + private referenceKey(name: string, scope?: string | null): string { + return JSON.stringify([isGlobalScope(scope) ? null : scope, name]); } get hasEnums(): boolean { diff --git a/TypeScript/src/__tests__/enums.test.ts b/TypeScript/src/__tests__/enums.test.ts index fab9e47..b9cca29 100644 --- a/TypeScript/src/__tests__/enums.test.ts +++ b/TypeScript/src/__tests__/enums.test.ts @@ -16,6 +16,8 @@ type EnumCase = { values?: Record; result?: boolean; error?: string; + errorContains?: string; + errorLocation?: { line: number; col: number }; parseOnly?: boolean; enums?: ArcscriptEnumDefs; initialVars?: ArcscriptStateDef; @@ -38,8 +40,18 @@ describe('shared enum contract', () => { }); const original = structuredClone(state); if (testCase.error) { - expect(() => interpreter.parse(testCase.code)).toThrow(ParseError); - expect(() => interpreter.runScript(testCase.code)).toThrow(ParseError); + for (const operation of [ + () => interpreter.parse(testCase.code), + () => interpreter.runScript(testCase.code), + ]) { + expect(operation).toThrow(ParseError); + if (testCase.errorContains) + expect(operation).toThrow(testCase.errorContains); + if (testCase.errorLocation) { + const { line, col } = testCase.errorLocation; + expect(operation).toThrow(`at line ${line}, col ${col}`); + } + } } else { interpreter.parse(testCase.code); if (!testCase.parseOnly) { @@ -102,6 +114,35 @@ describe('shared enum contract', () => { }); describe('declaration contexts', () => { + test.each(['invalid definition', 'unknown enum', 'scope collision'])( + 'legacy rewriting reports %s instead of misclassifying valid code', + problem => { + const state: ArcscriptStateDef = { + score: { id: 'score', name: 'score', type: 'integer', defaultValue: 1 }, + padded: { + id: 'padded', + name: 'score ', + type: 'integer', + defaultValue: 2, + }, + }; + const enums = structuredClone(fixture.enums) as ArcscriptEnumDefs; + const scopeNames: string[] = []; + const interpreter = new Interpreter({ state, enums, scopeNames }); + const rewrite = () => + interpreter.rewriteLegacyVariableReferences( + '
score + 1
', + { padded: 'renamed' } + ); + expect(rewrite().blockedVariableIds).toEqual(['padded']); + + if (problem === 'invalid definition') enums.quest.members = []; + else if (problem === 'unknown enum') state.score.enumId = 'missing'; + else scopeNames.push('QuestStatus'); + expect(rewrite).toThrow(ParseError); + } + ); + test('resolved references retain identity and type when source declarations change', () => { const enums = structuredClone(fixture.enums) as ArcscriptEnumDefs; const variables = structuredClone(fixture.initialVars) as ArcscriptStateDef; diff --git a/TypeScript/src/antlr4.interpreter.ts b/TypeScript/src/antlr4.interpreter.ts index 2356a78..c5d0760 100644 --- a/TypeScript/src/antlr4.interpreter.ts +++ b/TypeScript/src/antlr4.interpreter.ts @@ -72,17 +72,25 @@ export default class Interpreter { } parse(code: string) { + return this.parseWithContext(code, this.createContext()); + } + + private createContext() { + return new ArcscriptContext( + this.enumDefinitions, + this.arcscriptVariables, + this.scopeNames + ); + } + + private parseWithContext(code: string, declarations: ArcscriptContext) { const { chars, lexer, errorListener } = this.createLexer(code); const tokens = new antlr4.CommonTokenStream(lexer); const parser = new ArcscriptParser(tokens); parser.setOptions({ elementVisits: this.elementVisits, currentElement: this.currentElement, - declarations: new ArcscriptContext( - this.enumDefinitions, - this.arcscriptVariables, - this.scopeNames - ), + declarations, }); parser.buildParseTrees = true; parser.removeErrorListeners(); @@ -156,9 +164,10 @@ export default class Interpreter { variables: Record, options: LegacyVariableRewriteOptions = {} ): LegacyVariableRewriteResult { + const declarations = this.createContext(); return new LegacyVariableReferenceRewriter( this.arcscriptVariables, - legacyName => this.parsesAsArcscript(legacyName) + legacyName => this.parsesAsArcscript(legacyName, declarations) ).rewrite(code, variables, options); } @@ -242,7 +251,7 @@ export default class Interpreter { }; } - private parsesAsArcscript(code: string) { + private parsesAsArcscript(code: string, declarations: ArcscriptContext) { const scripts = [ `
${code}
`, `
${code}

endif
`, @@ -251,7 +260,7 @@ export default class Interpreter { for (const script of scripts) { try { - this.parse(script); + this.parseWithContext(script, declarations); return true; } catch (error) { diff --git a/TypeScript/src/types.ts b/TypeScript/src/types.ts index 87d8523..dcf1d88 100644 --- a/TypeScript/src/types.ts +++ b/TypeScript/src/types.ts @@ -23,7 +23,7 @@ export type VarDef = { defaultValue: VarValue; value?: VarValue; scope?: string | null; - enumId?: string; + enumId?: string | null; }; export type MentionResult = { diff --git a/docs/enums.md b/docs/enums.md index 715cd19..ff94742 100644 --- a/docs/enums.md +++ b/docs/enums.md @@ -56,8 +56,9 @@ An enum variable retains its backing primitive type and adds an `enumId`: } ``` -Definitions and variable references are validated before execution. Missing enum -references and incompatible declared backing types are parse errors. Selected +Definitions and variable references are validated before execution. An omitted or +`null` enum ID declares an ordinary variable; an explicit empty string, unknown +enum ID, or incompatible declared backing type is a parse error. Selected member IDs belong to authoring storage/export metadata, not runtime values. ## Script rules @@ -105,6 +106,9 @@ distinguishes mutable variables from enum members and records stable variable, enum, and member IDs together with their backing types. Member bindings also hold their primitive constant values. +Scope and name are separate lookup keys. A legacy global declaration named +`Board.score` cannot shadow the scoped variable `score` on `Board`. + The context snapshots declaration metadata. Changing source declarations does not alter bindings in an active operation; subsequent operations rebuild and validate the context. TypeScript and C# read their supplied definitions on each @@ -168,6 +172,8 @@ const { changes } = interpreter.runScript( `enums` and `scopeNames` are optional. Public definition and option types are exported from the package. Existing variable/scope rewriting leaves enum references intact; enum rename/conversion rewriting belongs to the lifecycle stage. +Legacy rewriting validates declarations once before testing candidate syntax, so +invalid enum metadata is reported as a parse error. ### C# @@ -184,7 +190,11 @@ var result = interpreter.RunScript( // result.Changes["status"] is the string "active". ``` -`Parse` is the public validation-only API. JSON adapters must convert integer +`Parse` is the public validation-only API and reports parse failures as +`ParseException`, as does the parsing phase of `RunScript`. Enum usage errors +include the logical code-block line and column (`Line` and `Column`). An empty +script is invalid for `Parse`; `RunScript("")` retains its existing no-op behavior. +JSON adapters must convert integer member values to `int`; libraries that default JSON integers to `long` must range-check before conversion. Existing constructor calls remain valid. @@ -194,6 +204,8 @@ Use `EnumDefinition` / `EnumMemberDefinition` from `ArcscriptEnums.h`, with `typ set to `"string"` or `"integer"` and `std::any` values containing `std::string` or `int`. Set `Variable::enumId` and pass the definition map as the optional fifth argument to `ArcscriptTranspiler`; `scopeNames` is the optional sixth argument. +`Variable::enumId` is a `std::optional`: leave it disengaged (or set +`std::nullopt`) for ordinary variables. Setting it to `""` is an invalid reference. ```cpp Arcweave::ArcscriptTranspiler interpreter("", variables, visits, onEvent, enums); @@ -208,6 +220,9 @@ arguments followed by definitions, a variable-ID-to-enum-ID map, and optional scope names. `UVariable`, the existing `runScriptExport` signature, and primitive `UTranspilerOutput` layout are unchanged. Native C++ callers must rebuild against the updated headers/library because the native `Variable`/state classes grow. +Omit ordinary variables from the bridge's enum-reference map; an entry with an +empty enum ID is rejected. Name-based state helpers read current variable metadata +after renames, while `varNameToID` remains a legacy constructor snapshot. ## Export and native mapping contract for integration diff --git a/tests/enums.json b/tests/enums.json index b1b61bf..8645783 100644 --- a/tests/enums.json +++ b/tests/enums.json @@ -2060,6 +2060,229 @@ "name": "empty pure function arguments report parse errors", "code": "
difficulty == max()
", "error": "parse" + }, + { + "name": "missing enum ID with no definitions", + "code": "
score = 999
", + "initialVars": { + "score": { + "id": "score", + "name": "score", + "type": "integer", + "defaultValue": 1 + } + }, + "enums": {}, + "changes": { + "score": 999 + } + }, + { + "name": "null enum ID with no definitions", + "code": "
score = 999
", + "initialVars": { + "score": { + "id": "score", + "name": "score", + "type": "integer", + "defaultValue": 1, + "enumId": null + } + }, + "enums": {}, + "changes": { + "score": 999 + } + }, + { + "name": "empty enum ID with no definitions", + "code": "
score = 999
", + "initialVars": { + "score": { + "id": "score", + "name": "score", + "type": "integer", + "defaultValue": 1, + "enumId": "" + } + }, + "enums": {}, + "error": "Invalid enum reference" + }, + { + "name": "missing enum ID with definitions", + "code": "
score = 999
", + "initialVars": { + "score": { + "id": "score", + "name": "score", + "type": "integer", + "defaultValue": 1 + } + }, + "changes": { + "score": 999 + } + }, + { + "name": "null enum ID with definitions", + "code": "
score = 999
", + "initialVars": { + "score": { + "id": "score", + "name": "score", + "type": "integer", + "defaultValue": 1, + "enumId": null + } + }, + "changes": { + "score": 999 + } + }, + { + "name": "empty enum ID with definitions", + "code": "
score = 999
", + "initialVars": { + "score": { + "id": "score", + "name": "score", + "type": "integer", + "defaultValue": 1, + "enumId": "" + } + }, + "error": "Invalid enum reference" + }, + { + "name": "Dotted global names do not shadow scoped ordinary variables", + "initialVars": { + "z_legacy": { + "id": "z_legacy", + "name": "Board.score", + "type": "integer", + "defaultValue": 100 + }, + "a_scoped": { + "id": "a_scoped", + "name": "score", + "scope": "Board", + "type": "integer", + "defaultValue": 2 + } + }, + "code": "
Board.score += 1
show(Board.score)
", + "changes": { + "a_scoped": 3 + }, + "output": "

3

" + }, + { + "name": "Dotted global names do not shadow scoped enum variables", + "initialVars": { + "z_legacy": { + "id": "z_legacy", + "name": "Board.score", + "type": "integer", + "defaultValue": 100 + }, + "a_scoped": { + "id": "a_scoped", + "name": "score", + "scope": "Board", + "type": "integer", + "defaultValue": 2, + "enumId": "difficulty" + } + }, + "code": "
Board.score = Difficulty.Hard
show(Board.score)
", + "changes": { + "a_scoped": 3 + }, + "output": "

3

" + }, + { + "name": "A dotted global name does not create a scoped declaration", + "initialVars": { + "legacy": { + "id": "legacy", + "name": "Board.score", + "type": "integer", + "defaultValue": 100 + } + }, + "code": "
show(Board.score)
", + "error": "Unknown variable" + }, + { + "name": "assignment error identifies the third code block and column", + "code": "
show(1)
show(2)
  questStatus = \"active\"
", + "error": "Enum assignment requires", + "errorLocation": { + "line": 3, + "col": 2 + }, + "errorContains": "Enum assignment requires" + }, + { + "name": "member mutation error identifies the third code block and column", + "code": "
show(1)
show(2)
  QuestStatus.Active = \"active\"
", + "error": "is read-only", + "errorLocation": { + "line": 3, + "col": 2 + }, + "errorContains": "is read-only" + }, + { + "name": "member reset error identifies the third code block and column", + "code": "
show(1)
show(2)
  reset(QuestStatus.Active)
", + "error": "is read-only", + "errorLocation": { + "line": 3, + "col": 8 + }, + "errorContains": "is read-only" + }, + { + "name": "cross-enum comparison error identifies the third code block and column", + "code": "
show(1)
show(2)
  show(questStatus == doorStatus)
", + "error": "Cannot compare different enum types", + "errorLocation": { + "line": 3, + "col": 7 + }, + "errorContains": "Cannot compare different enum types" + }, + { + "name": "constant comparison error identifies the third code block and column", + "code": "
show(1)
show(2)
  show(questStatus == \"active\")
", + "error": "require a named member", + "errorLocation": { + "line": 3, + "col": 7 + }, + "errorContains": "require a named member" + }, + { + "name": "string enum ordering error identifies the third code block and column", + "code": "
show(1)
show(2)
  show(questStatus < QuestStatus.Active)
", + "error": "Only integer enums support ordering", + "errorLocation": { + "line": 3, + "col": 7 + }, + "errorContains": "Only integer enums support ordering" + }, + { + "name": "unknown member error identifies the third code block and column", + "code": "
show(1)
show(2)
  show(QuestStatus.Missing)
", + "error": "variable", + "errorLocation": { + "line": 3, + "col": 7 + }, + "errorContains": "variable" } ] } From dc491157d8966bf3e8d63a670666d0be9347469a Mon Sep 17 00:00:00 2001 From: panayotis_kalaitzoglou Date: Wed, 11 Nov 2026 09:00:30 +0200 Subject: [PATCH 4/8] chore: share portable VS Code CMake settings --- .vscode/settings.json | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..2cca82e --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "cmake.sourceDirectory": "${workspaceFolder}/Cpp" +} From e0e3b6f16efafd002ec2e7587529d79d890a912f Mon Sep 17 00:00:00 2001 From: panayotis_kalaitzoglou Date: Wed, 11 Nov 2026 18:35:12 +0200 Subject: [PATCH 5/8] fix: correct enum scope boundaries and diagnostics Keep unnamed C# container variables scoped and report enum/reference columns as UTF-16 block offsets. Reuse owned native exception messages, create legacy rewrite contexts only for ambiguity probes, and preserve dotted-name helper compatibility after exact lookup. Cover Unicode and multiline diagnostics, null scopes, lazy rewriting, and native error/helper behavior. --- CSharp/EnumTests.cs | 32 ++++++ CSharp/Interpreter/ArcscriptContext.cs | 8 +- CSharp/Interpreter/ArcscriptParserBase.cs | 12 ++- Cpp/demo/EnumTests.cpp | 32 +++++- Cpp/src/ArcscriptErrorExceptions.h | 18 ++-- Cpp/src/ArcscriptHelpers.h | 4 + Cpp/src/ArcscriptParserBase.cpp | 15 ++- TypeScript/src/ErrorListener.ts | 4 +- .../src/Generated/ArcscriptParserBase.ts | 2 +- TypeScript/src/__tests__/enums.test.ts | 45 ++++++++ TypeScript/src/antlr4.interpreter.ts | 7 +- docs/enums.md | 16 ++- tests/enums.json | 100 ++++++++++++++++++ 13 files changed, 266 insertions(+), 29 deletions(-) diff --git a/CSharp/EnumTests.cs b/CSharp/EnumTests.cs index 7e029e7..72e1d87 100644 --- a/CSharp/EnumTests.cs +++ b/CSharp/EnumTests.cs @@ -184,6 +184,38 @@ public void ReferencesSnapshotDeclarationIdentityAndType() Assert.Throws(() => new ArcscriptContext(enums, new[] { variable })); } + [TestCase(true)] + [TestCase(false)] + public void ContainersWithoutCustomIdsDoNotExposeGlobalVariables(bool useBoard) + { + var scoped = new Variable("scoped", "score", 5); + var board = new Board("board", new List()); + var component = new Component(); + if (useBoard) board.AddVariable(scoped); + else component.AddVariable(scoped); + var globals = new List(); + var project = new Project.Project(new List { board }, globals, new List { component }); + var interpreter = new AwInterpreter(project); + var code = "
score += 1
"; + + Assert.That(project.GetVariable("score"), Is.Null); + Assert.Throws(() => interpreter.Parse(code)); + Assert.Throws(() => interpreter.RunScript(code)); + Assert.That(scoped.Value, Is.EqualTo(5)); + + var global = new Variable("global", "score", 100); + globals.Add(global); + Assert.That(interpreter.RunScript(code).Changes, + Is.EquivalentTo(new Dictionary { ["global"] = 101 })); + foreach (var variables in new[] { new[] { scoped, global }, new[] { global, scoped } }) + Assert.That(new ArcscriptContext(variables: variables).Resolve("score").VariableId, Is.EqualTo("global")); + + // Unnamed containers remain valid and their variables still participate in resets. + scoped.Value = 9; + Assert.That(interpreter.RunScript("
resetAll(score)
").Changes, + Is.EquivalentTo(new Dictionary { ["scoped"] = 5 })); + } + [Test] public void RunKeepsValidatedBindingsAndNextOperationReadsFreshDeclarations() { diff --git a/CSharp/Interpreter/ArcscriptContext.cs b/CSharp/Interpreter/ArcscriptContext.cs index 77af754..885bcf9 100644 --- a/CSharp/Interpreter/ArcscriptContext.cs +++ b/CSharp/Interpreter/ArcscriptContext.cs @@ -33,7 +33,7 @@ internal ArcscriptReference(ReferenceKind kind, Type type, string variableId = n public sealed class ArcscriptContext { private static readonly HashSet ReservedNames = new HashSet("abs max min random roll round sqr sqrt visits show resetVisits reset resetAll if else elseif endif and or is not true false abstract as assert async auto await base bool break byte case catch char checked class const constexpr const_cast continue decimal default delegate delete do double dynamic elif enum event explicit export extends extern false final finally fixed float for foreach friend from func get global goto if implicit import in inline int interface internal is lock long match mutable namespace native new noexcept not not_eq null nullptr object operator or or_eq out override params pass private protected public readonly ref register reinterpret_cast return sbyte sealed set short signal signed sizeof stackalloc static static_assert static_cast string struct super switch template this thread_local throw throws trait try typedef typeid typename typeof uint ulong unchecked union unsafe unsigned using ushort var virtual void volatile wchar_t when where while with yield alignas alignof and_eq asm bitand bitor char8_t char16_t char32_t compl concept co_await co_return co_yield consteval constinit decltype dynamic_cast requires xor xor_eq class_name breakpoint preload self PI TAU INF NAN tool onready setget remote master puppet remotesync mastersync puppetsync".Split(' ')); - private readonly Dictionary<(string Scope, string Name), ArcscriptReference> _references = new Dictionary<(string, string), ArcscriptReference>(); + private readonly Dictionary<(bool IsGlobal, string Scope, string Name), ArcscriptReference> _references = new Dictionary<(bool, string, string), ArcscriptReference>(); private readonly Dictionary _enumTypes = new Dictionary(); public bool HasEnums => _enumTypes.Count > 0; @@ -69,7 +69,7 @@ public ArcscriptContext(IReadOnlyDictionary definitions if ((definition.Type == "string" && !(member.Value is string)) || (definition.Type == "integer" && !(member.Value is int))) throw new ParseException($"Invalid backing value for {definition.Name}.{member.Name}"); - _references.Add((definition.Name, member.Name), + _references.Add((false, definition.Name, member.Name), new ArcscriptReference(ReferenceKind.EnumMember, type, enumId: entry.Key, memberId: member.Id, value: member.Value)); } @@ -78,7 +78,7 @@ public ArcscriptContext(IReadOnlyDictionary definitions { if (variable.EnumId != null && (!_enumTypes.TryGetValue(variable.EnumId, out var type) || type != variable.Type)) throw new ParseException($"Invalid enum reference for variable {variable.Name}"); - var name = (variable.Parent?.CustomId, variable.Name); + var name = (variable.Parent == null, variable.Parent?.CustomId, variable.Name); // Preserve the existing first-match behavior for ordinary variable names. if (!_references.ContainsKey(name)) _references.Add(name, new ArcscriptReference(ReferenceKind.Variable, variable.Type, @@ -95,7 +95,7 @@ private static void AssertName(string name) public ArcscriptReference Resolve(string name) { var dot = name.IndexOf('.'); - var key = dot < 0 ? (null, name) : (name.Substring(0, dot), name.Substring(dot + 1)); + var key = dot < 0 ? (true, null, name) : (false, name.Substring(0, dot), name.Substring(dot + 1)); return _references.TryGetValue(key, out var reference) ? reference : null; } diff --git a/CSharp/Interpreter/ArcscriptParserBase.cs b/CSharp/Interpreter/ArcscriptParserBase.cs index a8dc709..37a137c 100644 --- a/CSharp/Interpreter/ArcscriptParserBase.cs +++ b/CSharp/Interpreter/ArcscriptParserBase.cs @@ -35,8 +35,14 @@ public void SetProject(IProject project, ArcscriptContext declarations = null) { public override string GrammarFileName => throw new System.NotImplementedException(); - private ParseException Error(string message, ParserRuleContext context) => - new ParseException(message, currentLine, context.Start.StartIndex - openTagEndPos); + private ParseException Error(string message, ParserRuleContext context) + { + // ANTLR indexes code points; editor columns are UTF-16 offsets within the block. + var start = context.Start.StartIndex; + var column = start <= openTagEndPos ? 0 : context.Start.InputStream.GetText( + Antlr4.Runtime.Misc.Interval.Of(openTagEndPos, start - 1)).Length; + return new ParseException(message, currentLine, column); + } public bool assertVariable(ArcscriptParser.IdentifierContext identifierContext) { var variableName = identifierContext.GetText(); @@ -172,7 +178,7 @@ public bool assertFunctionArguments(IToken fname, ArcscriptParser.Identifier_lis internal void setLineStart(IToken token) { - openTagEndPos = token.StartIndex + token.Text.Length; + openTagEndPos = token.StopIndex + 1; } } diff --git a/Cpp/demo/EnumTests.cpp b/Cpp/demo/EnumTests.cpp index 3c3a8a4..427abaf 100644 --- a/Cpp/demo/EnumTests.cpp +++ b/Cpp/demo/EnumTests.cpp @@ -101,8 +101,11 @@ void currentNameLookupTests() { state.variableValues.at("a_scoped").scope = "OtherBoard"; require(state.getVar({"renamed", "OtherBoard"}).id == "a_scoped", "Host declaration lookup did not observe renamed metadata"); - state.setVarValue({"renamed", "OtherBoard"}, 7); + require(state.getVar({"OtherBoard.renamed", ""}).id == "a_scoped", + "Dotted declaration shorthand did not observe renamed metadata"); + state.setVarValue({"OtherBoard.renamed", ""}, 7); require(std::any_cast(state.getVarValue({"renamed", "OtherBoard"})) == 7 && + std::any_cast(state.getVarValue({"OtherBoard.renamed", ""})) == 7 && std::any_cast(state.getVarValueById("a_scoped")) == 7, "Name and ID helpers disagree after rename"); auto result = interpreter.runScript("
OtherBoard.renamed += 1
"); @@ -114,6 +117,31 @@ void currentNameLookupTests() { catch (const std::out_of_range&) { rejected = true; } require(rejected && state.variableValues.size() == 2 && state.variableChanges.size() == 1, "Unknown names should fail without inserting variables"); + for (auto identifier : {IdentifierDef{"OtherBoard.missing", ""}, IdentifierDef{".Board.score", ""}, + IdentifierDef{"OtherBoard.renamed", "Board"}}) { + rejected = false; + try { state.setVarValue(identifier, 999); } + catch (const std::out_of_range&) { rejected = true; } + require(rejected && state.variableValues.size() == 2 && state.variableChanges.size() == 1, + "Invalid shorthand should fail without changing state"); + } +} + +template +void checkExceptionMessage() { + Error located("message", 3, 2); + const char* text = located.what(); + require(std::string(text) == "line 3:2 message", "Located error has incorrect formatting"); + require(located.what() == text, "Repeated what() calls must reuse the owned message"); + Error copy = located; + require(std::string(copy.what()) == text, "Copied exception lost its message"); + Error plain("message"); + require(std::string(plain.what()) == "message", "Location-free error changed formatting"); +} + +void exceptionMessageTests() { + checkExceptionMessage(); + checkExceptionMessage(); } void bridgeEnumReferenceTests() { @@ -257,7 +285,7 @@ int main(int argc, char* argv[]) { } } const auto additionalTests = {declarationContextTests, declarationLifecycleTests, - currentNameLookupTests, bridgeEnumReferenceTests}; + currentNameLookupTests, bridgeEnumReferenceTests, exceptionMessageTests}; for (auto test : additionalTests) { try { test(); } catch (const std::exception& error) { diff --git a/Cpp/src/ArcscriptErrorExceptions.h b/Cpp/src/ArcscriptErrorExceptions.h index f08b087..cdf89e7 100755 --- a/Cpp/src/ArcscriptErrorExceptions.h +++ b/Cpp/src/ArcscriptErrorExceptions.h @@ -12,6 +12,7 @@ namespace Arcweave { class RuntimeErrorException : public std::exception { + std::string formattedMessage; public: std::string message; size_t line = 0; @@ -23,18 +24,15 @@ namespace Arcweave { message = msg; line = _line; charPositionInLine = _charPositionInLine; + formattedMessage = "line " + std::to_string(line) + ":" + std::to_string(charPositionInLine) + " " + message; }; char const* what() const noexcept override { - if (line > 0) { - std::ostringstream oss; - oss << "line " << line << ":" << charPositionInLine << " " << message << std::endl; - return strdup(oss.str().c_str()); - } - return message.c_str(); + return line > 0 ? formattedMessage.c_str() : message.c_str(); } }; class ParseErrorException : public std::exception { + std::string formattedMessage; public: std::string message; size_t line = 0; @@ -46,14 +44,10 @@ namespace Arcweave { message = msg; line = _line; charPositionInLine = _charPositionInLine; + formattedMessage = "line " + std::to_string(line) + ":" + std::to_string(charPositionInLine) + " " + message; }; char const* what() const noexcept override { - if (line > 0) { - std::ostringstream oss; - oss << "line " << line << ":" << charPositionInLine << " " << message << std::endl; - return strdup(oss.str().c_str()); - } - return message.c_str(); + return line > 0 ? formattedMessage.c_str() : message.c_str(); } }; } diff --git a/Cpp/src/ArcscriptHelpers.h b/Cpp/src/ArcscriptHelpers.h index fd78466..cc0a9f5 100755 --- a/Cpp/src/ArcscriptHelpers.h +++ b/Cpp/src/ArcscriptHelpers.h @@ -43,6 +43,10 @@ class ArcscriptState { for (auto it = variableValues.rbegin(); it != variableValues.rend(); ++it) if (it->second.name == identifier.name && it->second.scope == identifier.scope) return it->first; + // Preserve the public helpers' dotted shorthand, after an exact scope/name lookup. + auto dot = identifier.name.find('.'); + if (identifier.scope.empty() && dot != std::string::npos && dot > 0) + return getVarId({identifier.name.substr(dot + 1), identifier.name.substr(0, dot)}); throw std::out_of_range("Unknown variable " + getVarFullName(identifier)); } public: diff --git a/Cpp/src/ArcscriptParserBase.cpp b/Cpp/src/ArcscriptParserBase.cpp index 8ab8168..134bdd7 100755 --- a/Cpp/src/ArcscriptParserBase.cpp +++ b/Cpp/src/ArcscriptParserBase.cpp @@ -8,7 +8,18 @@ using namespace antlr4; Arcweave::ParseErrorException ArcscriptParserBase::error(const std::string& message, ParserRuleContext* context) const { - return Arcweave::ParseErrorException(message, currentLine, context->getStart()->getStartIndex() - openTagEndPos); + auto token = context->getStart(); + auto start = token->getStartIndex(); + size_t column = 0; + if (start > openTagEndPos) { + auto prefix = token->getInputStream()->getText(misc::Interval(openTagEndPos, start - 1)); + // Count UTF-16 units in ANTLR's UTF-8 text to match editor offsets. + for (unsigned char byte : prefix) { + if ((byte & 0xc0) != 0x80) ++column; + if (byte >= 0xf0) ++column; + } + } + return Arcweave::ParseErrorException(message, currentLine, column); } bool ArcscriptParserBase::assertVariable(antlr4::ParserRuleContext *identifierContext) const { @@ -174,5 +185,5 @@ bool ArcscriptParserBase::assertFunctionArguments(Token *fname, std::any listCon void ArcscriptParserBase::setLineStart(antlr4::Token* token) { - openTagEndPos = token->getStartIndex() + token->getText().length(); + openTagEndPos = token->getStopIndex() + 1; } diff --git a/TypeScript/src/ErrorListener.ts b/TypeScript/src/ErrorListener.ts index 701dc13..625a2db 100644 --- a/TypeScript/src/ErrorListener.ts +++ b/TypeScript/src/ErrorListener.ts @@ -20,7 +20,9 @@ export default class ErrorListener extends BaseErrorListener { e: RecognitionException | undefined ): void { if (recognizer instanceof ArcscriptParser) { - column = column - recognizer.openTagEndPos; + if (offendingSymbol instanceof Token) { + column = offendingSymbol.start - recognizer.openTagEndPos; + } line = recognizer.currentLine; } diff --git a/TypeScript/src/Generated/ArcscriptParserBase.ts b/TypeScript/src/Generated/ArcscriptParserBase.ts index e9cd2c9..e2b8f59 100644 --- a/TypeScript/src/Generated/ArcscriptParserBase.ts +++ b/TypeScript/src/Generated/ArcscriptParserBase.ts @@ -78,7 +78,7 @@ export default class ArcscriptParserBase extends Parser { } setLineStart(token: Token) { - this.openTagEndPos = token.start + token.text.length; + this.openTagEndPos = token.stop + 1; } assertFunctionArguments( diff --git a/TypeScript/src/__tests__/enums.test.ts b/TypeScript/src/__tests__/enums.test.ts index b9cca29..cfc3262 100644 --- a/TypeScript/src/__tests__/enums.test.ts +++ b/TypeScript/src/__tests__/enums.test.ts @@ -114,6 +114,51 @@ describe('shared enum contract', () => { }); describe('declaration contexts', () => { + test.each<{ + code: string; + replacements: Record; + expected: string; + }>([ + { + code: '

unchanged

', + replacements: {}, + expected: '

unchanged

', + }, + { + code: '

unchanged

', + replacements: { legacy: 'renamed' }, + expected: '

unchanged

', + }, + { + code: '
old value
', + replacements: { legacy: 'renamed' }, + expected: '
renamed
', + }, + ])( + 'legacy rewriting without an ambiguity probe ignores unrelated declarations: $code', + ({ code, replacements, expected }) => { + const enums = structuredClone(fixture.enums) as ArcscriptEnumDefs; + enums.quest.members = []; + const interpreter = new Interpreter({ + state: { + legacy: { + id: 'legacy', + name: 'old value', + type: 'integer', + defaultValue: 1, + }, + }, + enums, + }); + expect( + interpreter.rewriteLegacyVariableReferences(code, replacements) + ).toEqual({ + code: expected, + blockedVariableIds: [], + }); + } + ); + test.each(['invalid definition', 'unknown enum', 'scope collision'])( 'legacy rewriting reports %s instead of misclassifying valid code', problem => { diff --git a/TypeScript/src/antlr4.interpreter.ts b/TypeScript/src/antlr4.interpreter.ts index c5d0760..105bbff 100644 --- a/TypeScript/src/antlr4.interpreter.ts +++ b/TypeScript/src/antlr4.interpreter.ts @@ -164,10 +164,13 @@ export default class Interpreter { variables: Record, options: LegacyVariableRewriteOptions = {} ): LegacyVariableRewriteResult { - const declarations = this.createContext(); + let declarations: ArcscriptContext | undefined; return new LegacyVariableReferenceRewriter( this.arcscriptVariables, - legacyName => this.parsesAsArcscript(legacyName, declarations) + legacyName => { + declarations ??= this.createContext(); + return this.parsesAsArcscript(legacyName, declarations); + } ).rewrite(code, variables, options); } diff --git a/docs/enums.md b/docs/enums.md index ff94742..b4dec21 100644 --- a/docs/enums.md +++ b/docs/enums.md @@ -108,6 +108,8 @@ their primitive constant values. Scope and name are separate lookup keys. A legacy global declaration named `Board.score` cannot shadow the scoped variable `score` on `Board`. +C# variables whose parent has no custom ID remain scoped and cannot be referenced +as globals; they still participate in variable resets. The context snapshots declaration metadata. Changing source declarations does not alter bindings in an active operation; subsequent operations rebuild and @@ -120,6 +122,9 @@ variable values and changes separately from enum declarations. The parser's existing semantic hooks use the same resolver for existence, mutability, enum assignment, and comparison checks, preserving validation at the offending source location. +Enum and variable-reference diagnostics use the logical block line and a +zero-based UTF-16 offset from the end of the opening code tag. This offset includes +whitespace and newlines inside the block and matches JavaScript editor offsets. ## State and host boundaries @@ -172,8 +177,9 @@ const { changes } = interpreter.runScript( `enums` and `scopeNames` are optional. Public definition and option types are exported from the package. Existing variable/scope rewriting leaves enum references intact; enum rename/conversion rewriting belongs to the lifecycle stage. -Legacy rewriting validates declarations once before testing candidate syntax, so -invalid enum metadata is reported as a parse error. +Legacy rewriting validates declarations once, when it first needs to test candidate +syntax. Invalid enum metadata is reported as a parse error from that point; rewrites +that need no ambiguity probe can proceed without valid enum declarations. ### C# @@ -197,6 +203,9 @@ script is invalid for `Parse`; `RunScript("")` retains its existing no-op behavi JSON adapters must convert integer member values to `int`; libraries that default JSON integers to `long` must range-check before conversion. Existing constructor calls remain valid. +Hosts driving the C# parser and visitor directly must pass the same +`ArcscriptContext` with enum definitions to both; their default contexts support +ordinary variables, and `IProject` does not supply enum definitions. ### C++ @@ -223,6 +232,9 @@ the updated headers/library because the native `Variable`/state classes grow. Omit ordinary variables from the bridge's enum-reference map; an entry with an empty enum ID is rejected. Name-based state helpers read current variable metadata after renames, while `varNameToID` remains a legacy constructor snapshot. +The helpers also accept `{"Board.score", ""}` as shorthand for `{"score", "Board"}` +when no global is literally named `Board.score`. Explicit scope/name lookup takes +priority, and unknown names throw without inserting variables. ## Export and native mapping contract for integration diff --git a/tests/enums.json b/tests/enums.json index 8645783..e028d12 100644 --- a/tests/enums.json +++ b/tests/enums.json @@ -2283,6 +2283,106 @@ "col": 7 }, "errorContains": "variable" + }, + { + "name": "Astral character in pre attributes preserves diagnostic offsets", + "code": "
questStatus == \"active\"
", + "error": "parse", + "errorContains": "require a named member", + "errorLocation": { + "line": 1, + "col": 0 + } + }, + { + "name": "BMP character in pre attributes preserves diagnostic offsets", + "code": "
questStatus == \"active\"
", + "error": "parse", + "errorContains": "require a named member", + "errorLocation": { + "line": 1, + "col": 0 + } + }, + { + "name": "Astral character in code attributes preserves diagnostic offsets", + "code": "
  questStatus = \"active\"
", + "error": "parse", + "errorContains": "Enum assignment requires", + "errorLocation": { + "line": 1, + "col": 2 + } + }, + { + "name": "Newline before code block preserves diagnostic offsets", + "code": "

a

\n
  questStatus = \"active\"
", + "error": "parse", + "errorContains": "Enum assignment requires", + "errorLocation": { + "line": 2, + "col": 2 + } + }, + { + "name": "Unicode paragraph and multiline opening tag preserves diagnostic offsets", + "code": "

\ud83d\ude00

\r\n questStatus = \"active\"", + "error": "parse", + "errorContains": "Enum assignment requires", + "errorLocation": { + "line": 2, + "col": 2 + } + }, + { + "name": "Newline inside code block preserves diagnostic offsets", + "code": "
\n  questStatus = \"active\"
", + "error": "parse", + "errorContains": "Enum assignment requires", + "errorLocation": { + "line": 1, + "col": 3 + } + }, + { + "name": "Astral character before comparison preserves diagnostic offsets", + "code": "
show(\"\ud83d\ude00\", questStatus == \"active\")
", + "error": "parse", + "errorContains": "require a named member", + "errorLocation": { + "line": 1, + "col": 11 + } + }, + { + "name": "Unicode tag and expression in later block preserves diagnostic offsets", + "code": "
show(1)
\n
show(\"\u00e9\ud83d\ude00\", questStatus == \"active\")
", + "error": "parse", + "errorContains": "require a named member", + "errorLocation": { + "line": 2, + "col": 12 + } + }, + { + "name": "Astral character before unknown member preserves diagnostic offsets", + "code": "
show(\"\ud83d\ude00\", QuestStatus.Unknown)
", + "error": "parse", + "errorContains": "variable", + "errorLocation": { + "line": 1, + "col": 11 + } + }, + { + "name": "Astral character before member mutation preserves diagnostic offsets", + "code": "
show(\"\ud83d\ude00\", reset(QuestStatus.Active))
", + "error": "parse", + "errorContains": "is read-only", + "errorLocation": { + "line": 1, + "col": 17 + } } ] } From 0ed9699aa42b39bf0e4b5544e8ba0d4199c1f32f Mon Sep 17 00:00:00 2001 From: panayotis_kalaitzoglou Date: Wed, 11 Nov 2026 22:01:31 +0200 Subject: [PATCH 6/8] fix: preserve enum references and mutable exception diagnostics Protect enum namespaces during legacy rewrites without losing inferred or supplied scopes. Refresh owned exception messages after public field edits, keep what() noexcept under allocation failure, and remove unused public-header dependencies. Assert complete TypeScript error locations and clarify raw HTML offsets and scoped export requirements. --- Cpp/demo/EnumTests.cpp | 20 +++++ Cpp/src/ArcscriptErrorExceptions.h | 58 ++++++++----- Cpp/src/ArcscriptTranspiler.cpp | 1 + .../src/LegacyVariableReferenceRewriter.ts | 16 ++-- TypeScript/src/__tests__/enums.test.ts | 82 ++++++++++++++++++- TypeScript/src/antlr4.interpreter.ts | 8 +- docs/enums.md | 14 +++- 7 files changed, 168 insertions(+), 31 deletions(-) diff --git a/Cpp/demo/EnumTests.cpp b/Cpp/demo/EnumTests.cpp index 427abaf..14a86ca 100644 --- a/Cpp/demo/EnumTests.cpp +++ b/Cpp/demo/EnumTests.cpp @@ -137,6 +137,26 @@ void checkExceptionMessage() { require(std::string(copy.what()) == text, "Copied exception lost its message"); Error plain("message"); require(std::string(plain.what()) == "message", "Location-free error changed formatting"); + plain.line = 3; + plain.charPositionInLine = 2; + require(std::string(plain.what()) == "line 3:2 message", "Adding a location lost the error message"); + located.message = "edited"; + require(std::string(located.what()) == "line 3:2 edited", "Edited message was not reflected"); + located.line = 4; + require(std::string(located.what()) == "line 4:2 edited", "Edited line was not reflected"); + located.charPositionInLine = 9; + require(std::string(located.what()) == "line 4:9 edited", "Edited column was not reflected"); + text = located.what(); + require(located.what() == text, "Unchanged fields should reuse the refreshed message"); + require(std::string(copy.what()) == "line 3:2 message", "Editing an exception changed its copy"); + located.line = 0; + require(std::string(located.what()) == "edited", "Removing a location retained its prefix"); + located.message = "a longer message whose formatting requires an allocation"; + located.line = 5; + Error changedCopy = located; + Error moved = std::move(changedCopy); + require(std::string(moved.what()) == "line 5:9 " + located.message, + "Copying and moving after field edits retained stale formatting"); } void exceptionMessageTests() { diff --git a/Cpp/src/ArcscriptErrorExceptions.h b/Cpp/src/ArcscriptErrorExceptions.h index cdf89e7..c0bf5c0 100755 --- a/Cpp/src/ArcscriptErrorExceptions.h +++ b/Cpp/src/ArcscriptErrorExceptions.h @@ -1,53 +1,73 @@ #pragma once -#include +#include #include -#include -#include #include -#ifdef _WIN64 -#define strdup _strdup -#endif - namespace Arcweave { + namespace detail { + class ExceptionMessageCache { + mutable std::string formattedMessage; + mutable std::string cachedMessage; + mutable std::size_t cachedLine = 0; + mutable std::size_t cachedColumn = 0; + public: + const char* get(const std::string& message, std::size_t line, std::size_t column) const noexcept { + if (line == 0) return message.c_str(); + try { + if (formattedMessage.empty() || cachedMessage != message || cachedLine != line || cachedColumn != column) { + auto formatted = "line " + std::to_string(line) + ":" + std::to_string(column) + " " + message; + auto currentMessage = message; + // Publish the cache only after every allocation succeeds. + formattedMessage.swap(formatted); + cachedMessage.swap(currentMessage); + cachedLine = line; + cachedColumn = column; + } + return formattedMessage.c_str(); + } catch (...) { + // what() must still return useful text if formatting cannot allocate. + return message.c_str(); + } + } + }; + } + class RuntimeErrorException : public std::exception { - std::string formattedMessage; + detail::ExceptionMessageCache messageCache; public: std::string message; - size_t line = 0; - size_t charPositionInLine = 0; + std::size_t line = 0; + std::size_t charPositionInLine = 0; RuntimeErrorException(std::string msg) { message = msg; }; - RuntimeErrorException(std::string msg, size_t _line, size_t _charPositionInLine) { + RuntimeErrorException(std::string msg, std::size_t _line, std::size_t _charPositionInLine) { message = msg; line = _line; charPositionInLine = _charPositionInLine; - formattedMessage = "line " + std::to_string(line) + ":" + std::to_string(charPositionInLine) + " " + message; }; char const* what() const noexcept override { - return line > 0 ? formattedMessage.c_str() : message.c_str(); + return messageCache.get(message, line, charPositionInLine); } }; class ParseErrorException : public std::exception { - std::string formattedMessage; + detail::ExceptionMessageCache messageCache; public: std::string message; - size_t line = 0; - size_t charPositionInLine = 0; + std::size_t line = 0; + std::size_t charPositionInLine = 0; ParseErrorException(std::string msg) { message = msg; }; - ParseErrorException(std::string msg, size_t _line, size_t _charPositionInLine) { + ParseErrorException(std::string msg, std::size_t _line, std::size_t _charPositionInLine) { message = msg; line = _line; charPositionInLine = _charPositionInLine; - formattedMessage = "line " + std::to_string(line) + ":" + std::to_string(charPositionInLine) + " " + message; }; char const* what() const noexcept override { - return line > 0 ? formattedMessage.c_str() : message.c_str(); + return messageCache.get(message, line, charPositionInLine); } }; } diff --git a/Cpp/src/ArcscriptTranspiler.cpp b/Cpp/src/ArcscriptTranspiler.cpp index c9d0fd6..ebd9b6e 100755 --- a/Cpp/src/ArcscriptTranspiler.cpp +++ b/Cpp/src/ArcscriptTranspiler.cpp @@ -5,6 +5,7 @@ #include "ArcscriptLexer.h" #include "ArcscriptParser.h" #include +#include #define _CRT_SECURE_NO_WARNINGS diff --git a/TypeScript/src/LegacyVariableReferenceRewriter.ts b/TypeScript/src/LegacyVariableReferenceRewriter.ts index 24de4be..d71506a 100644 --- a/TypeScript/src/LegacyVariableReferenceRewriter.ts +++ b/TypeScript/src/LegacyVariableReferenceRewriter.ts @@ -138,7 +138,8 @@ const IDENTIFIER_PART_PATTERN = /^[\p{L}\p{N}\p{M}_$]$/u; export default class LegacyVariableReferenceRewriter { constructor( private readonly state: ArcscriptStateDef, - private readonly parsesAsArcscript: (code: string) => boolean + private readonly parsesAsArcscript: (code: string) => boolean, + private readonly additionalNamespaces: ReadonlySet = new Set() ) {} rewrite( @@ -390,12 +391,13 @@ export default class LegacyVariableReferenceRewriter { return !CALLABLE_RESERVED_NAMES.has(candidate.oldName); } if (candidate.scope === null && candidate.oldName.includes('.')) { - const scopeNames = new Set( - options.scopeNames ?? - Object.values(this.state) - .map(variable => variable.scope) - .filter((value): value is string => !isGlobalScope(value)) - ); + const scopeNames = new Set([ + ...Object.values(this.state) + .map(variable => variable.scope) + .filter((value): value is string => !isGlobalScope(value)), + ...(options.scopeNames ?? []), + ...this.additionalNamespaces, + ]); const dotIndex = tokens.tokenNames.indexOf('DOT'); const scope = dotIndex > 0 ? tokens.tokens[dotIndex - 1].text : ''; if (scope.length === 0 || scopeNames.has(scope)) { diff --git a/TypeScript/src/__tests__/enums.test.ts b/TypeScript/src/__tests__/enums.test.ts index cfc3262..677caaa 100644 --- a/TypeScript/src/__tests__/enums.test.ts +++ b/TypeScript/src/__tests__/enums.test.ts @@ -49,7 +49,9 @@ describe('shared enum contract', () => { expect(operation).toThrow(testCase.errorContains); if (testCase.errorLocation) { const { line, col } = testCase.errorLocation; - expect(operation).toThrow(`at line ${line}, col ${col}`); + expect(operation).toThrow( + new RegExp(` at line ${line}, col ${col}$`) + ); } } } else { @@ -91,7 +93,7 @@ describe('shared enum contract', () => { interpreter.parse( '
questStatus = "active"
show(1)
' ) - ).toThrow('at line 1, col 0'); + ).toThrow(/ at line 1, col 0$/); }); test('variable and scope rewriting leave enum constants alone', () => { @@ -114,6 +116,82 @@ describe('shared enum contract', () => { }); describe('declaration contexts', () => { + test.each([ + { label: 'default scopes', scopeNames: undefined }, + { label: 'empty scopes', scopeNames: [] }, + { label: 'explicit scopes', scopeNames: ['OtherBoard'] }, + ])( + 'legacy rewriting preserves enum constants with $label', + ({ scopeNames }) => { + const state: ArcscriptStateDef = { + legacy: { + id: 'legacy', + name: 'QuestStatus.Active', + type: 'integer', + defaultValue: 7, + }, + }; + const interpreter = new Interpreter({ + state, + enums: fixture.enums as ArcscriptEnumDefs, + }); + const code = '
show(QuestStatus.Active)
'; + const rewrite = interpreter.rewriteLegacyVariableReferences( + code, + { legacy: 'renamed' }, + { scopeNames } + ); + expect(rewrite).toEqual({ code, blockedVariableIds: ['legacy'] }); + expect(interpreter.runScript(code).output).toBe('

active

'); + state.legacy.name = 'renamed'; + expect(interpreter.runScript(rewrite.code).output).toBe('

active

'); + } + ); + + test('legacy rewriting protects enum, inferred, constructor, and supplied namespaces together', () => { + const state: ArcscriptStateDef = {}; + for (const [id, name] of Object.entries({ + enumAlias: 'QuestStatus.Active', + inferred: 'Board.score', + constructorScope: 'EmptyBoard.score', + supplied: 'SuppliedBoard.score', + unqualifiedLegacy: 'Other.score', + })) + state[id] = { id, name, type: 'integer', defaultValue: 7 }; + state.scoped = { + id: 'scoped', + name: 'score', + scope: 'Board', + type: 'integer', + defaultValue: 1, + }; + const interpreter = new Interpreter({ + state, + enums: fixture.enums as ArcscriptEnumDefs, + scopeNames: ['EmptyBoard'], + }); + const rewrite = interpreter.rewriteLegacyVariableReferences( + '
show(QuestStatus.Active, Board.score, EmptyBoard.score, SuppliedBoard.score, Other.score)
', + { + enumAlias: 'enumRenamed', + inferred: 'boardRenamed', + constructorScope: 'emptyRenamed', + supplied: 'suppliedRenamed', + unqualifiedLegacy: 'renamed', + }, + { scopeNames: ['SuppliedBoard'] } + ); + expect(rewrite).toEqual({ + code: '
show(QuestStatus.Active, Board.score, EmptyBoard.score, SuppliedBoard.score, renamed)
', + blockedVariableIds: [ + 'constructorScope', + 'enumAlias', + 'inferred', + 'supplied', + ], + }); + }); + test.each<{ code: string; replacements: Record; diff --git a/TypeScript/src/antlr4.interpreter.ts b/TypeScript/src/antlr4.interpreter.ts index 105bbff..f5f70a7 100644 --- a/TypeScript/src/antlr4.interpreter.ts +++ b/TypeScript/src/antlr4.interpreter.ts @@ -170,7 +170,13 @@ export default class Interpreter { legacyName => { declarations ??= this.createContext(); return this.parsesAsArcscript(legacyName, declarations); - } + }, + new Set([ + ...this.scopeNames, + ...Object.values(this.enumDefinitions).map( + definition => definition.name + ), + ]) ).rewrite(code, variables, options); } diff --git a/docs/enums.md b/docs/enums.md index b4dec21..848fadb 100644 --- a/docs/enums.md +++ b/docs/enums.md @@ -43,6 +43,9 @@ Supply every board/component scope through `scopeNames`, including scopes with n variables. All runtimes also discover scopes on their variable definitions; C# also discovers board/component custom IDs from its project. The host must check these collisions when creating or renaming either side of the namespace. +Host adapters must provide a nonempty custom ID when exporting scoped variables. +Do not encode an unnamed container as `scope: null` in TypeScript or an empty +scope in C++: those representations explicitly declare global variables. An enum variable retains its backing primitive type and adds an `enumId`: @@ -123,8 +126,10 @@ existing semantic hooks use the same resolver for existence, mutability, enum assignment, and comparison checks, preserving validation at the offending source location. Enum and variable-reference diagnostics use the logical block line and a -zero-based UTF-16 offset from the end of the opening code tag. This offset includes -whitespace and newlines inside the block and matches JavaScript editor offsets. +zero-based UTF-16 offset into the raw HTML source, measured from the end of the +opening code tag. Entity spellings such as `>` and both characters of CRLF count +toward this offset. Hosts displaying decoded or normalized text must map the +source offset to that text before placing an editor marker. ## State and host boundaries @@ -180,6 +185,9 @@ references intact; enum rename/conversion rewriting belongs to the lifecycle sta Legacy rewriting validates declarations once, when it first needs to test candidate syntax. Invalid enum metadata is reported as a parse error from that point; rewrites that need no ambiguity probe can proceed without valid enum declarations. +Enum names remain protected namespaces during legacy rewriting, including when +explicit scope options are supplied. A legacy global named `QuestStatus.Active` +is reported as ambiguous rather than replacing an enum member reference. ### C# @@ -235,6 +243,8 @@ after renames, while `varNameToID` remains a legacy constructor snapshot. The helpers also accept `{"Board.score", ""}` as shorthand for `{"score", "Board"}` when no global is literally named `Board.score`. Explicit scope/name lookup takes priority, and unknown names throw without inserting variables. +Name-based lookups use current declarations and may bind differently after a +rename. Use stable variable-ID accessors for references retained across renames. ## Export and native mapping contract for integration From 9ccdd533bd5a299a3b83bcad070ea151fe7f942f Mon Sep 17 00:00:00 2001 From: panayotis_kalaitzoglou Date: Thu, 12 Nov 2026 19:43:08 +0200 Subject: [PATCH 7/8] fix: synchronize exception diagnostics and rewrite scope checks Serialize native diagnostic cache access while preserving field edits, copy and move behavior. Share rewrite namespace checks and retain duplicate scopes from constructor and per-call declarations. Cover concurrent diagnostics, no-argument enum resets, and raw HTML entity/CRLF offsets; document native header compatibility. --- Cpp/CMakeLists.txt | 7 +- Cpp/demo/EnumTests.cpp | 60 +++++++++++++ Cpp/src/ArcscriptErrorExceptions.h | 8 ++ TypeScript/README.md | 5 +- .../src/LegacyVariableReferenceRewriter.ts | 64 ++++++++------ TypeScript/src/__tests__/enums.test.ts | 85 +++++++++++++++++++ TypeScript/src/antlr4.interpreter.ts | 8 +- docs/enums.md | 7 ++ tests/enums.json | 72 ++++++++++++++++ 9 files changed, 276 insertions(+), 40 deletions(-) diff --git a/Cpp/CMakeLists.txt b/Cpp/CMakeLists.txt index b38d08a..e1825f2 100755 --- a/Cpp/CMakeLists.txt +++ b/Cpp/CMakeLists.txt @@ -75,7 +75,8 @@ elseif(CMAKE_CXX_COMPILER_ID STREQUAL "MSVC") target_compile_definitions(ArcscriptTranspiler PRIVATE WIN_EXPORT) endif() -target_link_libraries(ArcscriptTranspiler PRIVATE antlr4_shared) +find_package(Threads REQUIRED) +target_link_libraries(ArcscriptTranspiler PRIVATE antlr4_shared PUBLIC Threads::Threads) if (WIN32 OR WIN64) set(LIBRARY_NAME "${PROJECT_NAME}.lib") @@ -145,10 +146,6 @@ if (WITH_TEST) COMMAND ${CMAKE_COMMAND} -E copy "$" ${ANTLR4_RUNTIME_LIBRARIES} "$") - if (CMAKE_HOST_UNIX) - find_package(Threads REQUIRED) - target_link_libraries(ArcscriptTest PRIVATE Threads::Threads) - endif() set_target_properties(ArcscriptTest PROPERTIES LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/demo/${PLATFORM}" diff --git a/Cpp/demo/EnumTests.cpp b/Cpp/demo/EnumTests.cpp index 14a86ca..4992045 100644 --- a/Cpp/demo/EnumTests.cpp +++ b/Cpp/demo/EnumTests.cpp @@ -2,6 +2,9 @@ #include #include #include +#include +#include +#include #include #include "ArcscriptTranspiler.h" #include "ArcscriptContext.h" @@ -157,11 +160,68 @@ void checkExceptionMessage() { Error moved = std::move(changedCopy); require(std::string(moved.what()) == "line 5:9 " + located.message, "Copying and moving after field edits retained stale formatting"); + Error assigned("old", 1, 1); + assigned.what(); + assigned = moved; + require(std::string(assigned.what()) == moved.what(), "Copy assignment retained the destination's old message"); + Error moveAssigned("old", 1, 1); + moveAssigned.what(); + moveAssigned = std::move(assigned); + require(std::string(moveAssigned.what()) == moved.what(), "Move assignment retained the destination's old message"); +} + +template +void checkConcurrentExceptionMessage() { + for (int iteration = 0; iteration < 32; ++iteration) { + std::exception_ptr exception; + try { throw Error(std::string(10000, 'x'), 3, 2); } + catch (...) { exception = std::current_exception(); } + for (bool edited : {false, true}) { + const std::string message(10000, edited ? 'y' : 'x'); + const std::string expected = (edited ? "line 9:4 " : "line 3:2 ") + message; + if (edited) { + try { std::rethrow_exception(exception); } + catch (Error& error) { + error.message = message; + error.line = 9; + error.charPositionInLine = 4; + } + } + std::atomic ready{0}; + std::atomic go{false}; + std::array pointers{}; + std::array correct{}; + std::vector threads; + for (std::size_t index = 0; index < pointers.size(); ++index) { + threads.emplace_back([&, index] { + try { std::rethrow_exception(exception); } + catch (const std::exception& error) { + ++ready; + while (!go.load()) std::this_thread::yield(); + pointers[index] = error.what(); + correct[index] = std::string(pointers[index]) == expected; + for (int read = 0; read < 10; ++read) + correct[index] = correct[index] && error.what() == pointers[index] && std::string(error.what()) == expected; + Error copy = static_cast(error); + correct[index] = correct[index] && std::string(copy.what()) == expected; + } + }); + } + while (ready.load() != static_cast(pointers.size())) std::this_thread::yield(); + go = true; + for (auto& thread : threads) thread.join(); + for (std::size_t index = 0; index < pointers.size(); ++index) + require(correct[index] && pointers[index] == pointers[0], + "Concurrent exception reads must share one stable, current message"); + } + } } void exceptionMessageTests() { checkExceptionMessage(); checkExceptionMessage(); + checkConcurrentExceptionMessage(); + checkConcurrentExceptionMessage(); } void bridgeEnumReferenceTests() { diff --git a/Cpp/src/ArcscriptErrorExceptions.h b/Cpp/src/ArcscriptErrorExceptions.h index c0bf5c0..fd203e7 100755 --- a/Cpp/src/ArcscriptErrorExceptions.h +++ b/Cpp/src/ArcscriptErrorExceptions.h @@ -3,18 +3,26 @@ #include #include #include +#include namespace Arcweave { namespace detail { class ExceptionMessageCache { + mutable std::mutex mutex; mutable std::string formattedMessage; mutable std::string cachedMessage; mutable std::size_t cachedLine = 0; mutable std::size_t cachedColumn = 0; public: + ExceptionMessageCache() = default; + // The cache is derived from public exception fields. Copies start fresh; + // assignment keeps the destination cache, which get() checks for changes. + ExceptionMessageCache(const ExceptionMessageCache&) noexcept {} + ExceptionMessageCache& operator=(const ExceptionMessageCache&) noexcept { return *this; } const char* get(const std::string& message, std::size_t line, std::size_t column) const noexcept { if (line == 0) return message.c_str(); try { + std::lock_guard lock(mutex); if (formattedMessage.empty() || cachedMessage != message || cachedLine != line || cachedColumn != column) { auto formatted = "line " + std::to_string(line) + ":" + std::to_string(column) + " " + message; auto currentMessage = message; diff --git a/TypeScript/README.md b/TypeScript/README.md index 25342bb..8f8bd2d 100644 --- a/TypeScript/README.md +++ b/TypeScript/README.md @@ -260,7 +260,10 @@ console.log(result.blockedVariableIds); ``` `scopeNames` should contain every board/component scope name, including -duplicates. Variables are reported in `blockedVariableIds` and left unchanged +duplicates. Constructor and per-call scope lists both contribute to rewrite +safety checks. A duplicate within either list marks that scope as ambiguous; +the same scope appearing once in each list does not. +Variables are reported in `blockedVariableIds` and left unchanged when their references could instead be Arcscript syntax, when their name is duplicated within a scope, when a scoped qualifier is invalid or ambiguous, or when the requested replacement is not a non-reserved Arcscript identifier. diff --git a/TypeScript/src/LegacyVariableReferenceRewriter.ts b/TypeScript/src/LegacyVariableReferenceRewriter.ts index d71506a..594fe20 100644 --- a/TypeScript/src/LegacyVariableReferenceRewriter.ts +++ b/TypeScript/src/LegacyVariableReferenceRewriter.ts @@ -44,6 +44,11 @@ type SourceReplacement = { text: string; }; +type NamespaceInfo = { + names: ReadonlySet; + duplicateScopes: ReadonlySet; +}; + const CALLABLE_RESERVED_NAMES = new Set([ 'sqr', 'sqrt', @@ -139,7 +144,8 @@ export default class LegacyVariableReferenceRewriter { constructor( private readonly state: ArcscriptStateDef, private readonly parsesAsArcscript: (code: string) => boolean, - private readonly additionalNamespaces: ReadonlySet = new Set() + private readonly scopeNames: readonly string[] = [], + private readonly enumNames: readonly string[] = [] ) {} rewrite( @@ -157,7 +163,11 @@ export default class LegacyVariableReferenceRewriter { ? null : (variable.scope as string), })); - const blocked = this.inherentlyBlockedCandidates(candidates, options); + const namespaces = this.namespaces(options); + const blocked = this.inherentlyBlockedCandidates( + candidates, + namespaces.duplicateScopes + ); const decoded = this.decodeSource(code); const possibleMatches = candidates .filter(candidate => !blocked.has(candidate.id)) @@ -199,7 +209,7 @@ export default class LegacyVariableReferenceRewriter { for (const candidate of candidates) { if ( (matchesByCandidate.get(candidate.id)?.length ?? 0) > 0 && - this.isAmbiguous(candidate, options) + this.isAmbiguous(candidate, namespaces.names) ) { blocked.add(candidate.id); } @@ -219,22 +229,30 @@ export default class LegacyVariableReferenceRewriter { }; } + private namespaces(options: LegacyVariableRewriteOptions): NamespaceInfo { + const names = new Set(this.enumNames); + for (const variable of Object.values(this.state)) { + if (!isGlobalScope(variable.scope)) names.add(variable.scope as string); + } + const duplicateScopes = new Set(); + // Each list describes containers independently. A scope appearing once in + // both lists (or on several variables) does not imply duplicate containers. + for (const scopes of [this.scopeNames, options.scopeNames ?? []]) { + const seen = new Set(); + for (const scope of scopes) { + names.add(scope); + if (seen.has(scope)) duplicateScopes.add(scope); + seen.add(scope); + } + } + return { names, duplicateScopes }; + } + private inherentlyBlockedCandidates( candidates: Candidate[], - options: LegacyVariableRewriteOptions + duplicateScopes: ReadonlySet ) { const blocked = new Set(); - const scopeNames = options.scopeNames ?? [ - ...new Set( - Object.values(this.state) - .map(variable => variable.scope) - .filter((scope): scope is string => !isGlobalScope(scope)) - ), - ]; - const scopeCounts = new Map(); - for (const scope of scopeNames) { - scopeCounts.set(scope, (scopeCounts.get(scope) ?? 0) + 1); - } for (const candidate of candidates) { if ( @@ -246,7 +264,7 @@ export default class LegacyVariableReferenceRewriter { (candidate.scope !== null && (!this.isValidIdentifier(candidate.scope) || RESERVED_NAMES.has(candidate.scope) || - (scopeCounts.get(candidate.scope) ?? 0) > 1)) + duplicateScopes.has(candidate.scope))) ) { blocked.add(candidate.id); } @@ -366,10 +384,7 @@ export default class LegacyVariableReferenceRewriter { return outside; } - private isAmbiguous( - candidate: Candidate, - options: LegacyVariableRewriteOptions - ) { + private isAmbiguous(candidate: Candidate, namespaces: ReadonlySet) { const name = candidate.oldName.trim(); const tokens = this.tokensForCode(name); if ( @@ -391,16 +406,9 @@ export default class LegacyVariableReferenceRewriter { return !CALLABLE_RESERVED_NAMES.has(candidate.oldName); } if (candidate.scope === null && candidate.oldName.includes('.')) { - const scopeNames = new Set([ - ...Object.values(this.state) - .map(variable => variable.scope) - .filter((value): value is string => !isGlobalScope(value)), - ...(options.scopeNames ?? []), - ...this.additionalNamespaces, - ]); const dotIndex = tokens.tokenNames.indexOf('DOT'); const scope = dotIndex > 0 ? tokens.tokens[dotIndex - 1].text : ''; - if (scope.length === 0 || scopeNames.has(scope)) { + if (scope.length === 0 || namespaces.has(scope)) { return true; } } diff --git a/TypeScript/src/__tests__/enums.test.ts b/TypeScript/src/__tests__/enums.test.ts index 677caaa..352ca96 100644 --- a/TypeScript/src/__tests__/enums.test.ts +++ b/TypeScript/src/__tests__/enums.test.ts @@ -116,6 +116,91 @@ describe('shared enum contract', () => { }); describe('declaration contexts', () => { + test.each([ + { + label: 'constructor duplicates', + constructorScopes: ['Board', 'Board'], + blocked: true, + }, + { + label: 'constructor duplicates with empty options', + constructorScopes: ['Board', 'Board'], + suppliedScopes: [], + blocked: true, + }, + { + label: 'constructor duplicates with unique options', + constructorScopes: ['Board', 'Board'], + suppliedScopes: ['Board'], + blocked: true, + }, + { + label: 'per-call duplicates', + constructorScopes: [], + suppliedScopes: ['Board', 'Board'], + blocked: true, + }, + { + label: 'per-call duplicates with unique constructor scopes', + constructorScopes: ['Board'], + suppliedScopes: ['Board', 'Board'], + blocked: true, + }, + { + label: 'same scope in both lists', + constructorScopes: ['Board'], + suppliedScopes: ['Board'], + blocked: false, + }, + { + label: 'several variables in an inferred scope', + constructorScopes: [], + blocked: false, + }, + { + label: 'duplicates in another scope', + constructorScopes: ['Other', 'Other'], + suppliedScopes: ['Board'], + blocked: false, + }, + ])( + 'legacy rewriting handles $label', + ({ constructorScopes, suppliedScopes, blocked }) => { + const interpreter = new Interpreter({ + scopeNames: constructorScopes, + state: { + legacy: { + id: 'legacy', + name: 'health points', + scope: 'Board', + type: 'integer', + defaultValue: 7, + }, + other: { + id: 'other', + name: 'score', + scope: 'Board', + type: 'integer', + defaultValue: 1, + }, + }, + }); + const code = '
show(Board.health points)
'; + expect( + interpreter.rewriteLegacyVariableReferences( + code, + { legacy: 'healthPoints' }, + { scopeNames: suppliedScopes } + ) + ).toEqual({ + code: blocked + ? code + : '
show(Board.healthPoints)
', + blockedVariableIds: blocked ? ['legacy'] : [], + }); + } + ); + test.each([ { label: 'default scopes', scopeNames: undefined }, { label: 'empty scopes', scopeNames: [] }, diff --git a/TypeScript/src/antlr4.interpreter.ts b/TypeScript/src/antlr4.interpreter.ts index f5f70a7..7a0b68c 100644 --- a/TypeScript/src/antlr4.interpreter.ts +++ b/TypeScript/src/antlr4.interpreter.ts @@ -171,12 +171,8 @@ export default class Interpreter { declarations ??= this.createContext(); return this.parsesAsArcscript(legacyName, declarations); }, - new Set([ - ...this.scopeNames, - ...Object.values(this.enumDefinitions).map( - definition => definition.name - ), - ]) + this.scopeNames, + Object.values(this.enumDefinitions).map(definition => definition.name) ).rewrite(code, variables, options); } diff --git a/docs/enums.md b/docs/enums.md index 848fadb..043f916 100644 --- a/docs/enums.md +++ b/docs/enums.md @@ -237,6 +237,13 @@ arguments followed by definitions, a variable-ID-to-enum-ID map, and optional scope names. `UVariable`, the existing `runScriptExport` signature, and primitive `UTranspilerOutput` layout are unchanged. Native C++ callers must rebuild against the updated headers/library because the native `Variable`/state classes grow. +The public exception header no longer supplies ``, ``, +``, or a Win64 `strdup` macro transitively. Native integrations using +those facilities must include their dependencies and supply any platform mapping +directly. +Concurrent `what()` calls on one exception are supported. Public exception-field +edits and assignments must be synchronized with readers. Copy returned text if +it must survive later changes to the exception or its destruction. Omit ordinary variables from the bridge's enum-reference map; an entry with an empty enum ID is rejected. Name-based state helpers read current variable metadata after renames, while `varNameToID` remains a legacy constructor snapshot. diff --git a/tests/enums.json b/tests/enums.json index e028d12..60e8be4 100644 --- a/tests/enums.json +++ b/tests/enums.json @@ -293,6 +293,48 @@ "status": "active" } }, + { + "name": "resetAll without arguments restores supplied ordinary and enum values", + "values": { + "status": "complete", + "difficulty": 3, + "scoped": "active", + "component": "inactive", + "text": "changed", + "number": 9 + }, + "code": "
resetAll()
show(questStatus, \":\", difficulty, \":\", Board.questStatus, \":\", Component.questStatus, \":\", text, \":\", number, \":\", QuestStatus.Active, Difficulty.Hard)
", + "changes": { + "status": "inactive", + "other": "active", + "door": "active", + "difficulty": 2, + "rank": 2, + "scoped": "inactive", + "component": "active", + "text": "active", + "number": 2, + "QuestStatus": 5 + }, + "output": "

inactive:2:inactive:active:active:2:active3

" + }, + { + "name": "resetAll without arguments restores values assigned in the script", + "code": "
questStatus = QuestStatus.Active
difficulty = Difficulty.Hard
Board.questStatus = QuestStatus.Active
Component.questStatus = QuestStatus.Inactive
text = \"changed\"
number = 9
resetAll()
show(questStatus, \":\", difficulty, \":\", Board.questStatus, \":\", Component.questStatus, \":\", text, \":\", number, \":\", QuestStatus.Active, Difficulty.Hard)
", + "changes": { + "status": "inactive", + "other": "active", + "door": "active", + "difficulty": 2, + "rank": 2, + "scoped": "inactive", + "component": "active", + "text": "active", + "number": 2, + "QuestStatus": 5 + }, + "output": "

inactive:2:inactive:active:active:2:active3

" + }, { "name": "primitive current values", "code": "
show(questStatus, Board.questStatus)
", @@ -2383,6 +2425,36 @@ "line": 1, "col": 17 } + }, + { + "name": "Entity spelling before an enum error counts toward the raw source offset", + "code": "
show(1 > 0,  questStatus == \"active\")
", + "error": "parse", + "errorContains": "require a named member", + "errorLocation": { + "line": 1, + "col": 16 + } + }, + { + "name": "CRLF before an enum error counts both characters toward the source offset", + "code": "
show(1,\r\n  questStatus == \"active\")
", + "error": "parse", + "errorContains": "require a named member", + "errorLocation": { + "line": 1, + "col": 11 + } + }, + { + "name": "Entity and CRLF before an enum error retain the raw source offset", + "code": "
show(1 > 0,\r\n  questStatus == \"active\")
", + "error": "parse", + "errorContains": "require a named member", + "errorLocation": { + "line": 1, + "col": 18 + } } ] } From 8a0c46c474af4cf7ba9d13dca11c02a1962db753 Mon Sep 17 00:00:00 2001 From: panayotis_kalaitzoglou Date: Thu, 12 Nov 2026 19:47:33 +0200 Subject: [PATCH 8/8] test: share exception instances directly across threads Avoid assuming rethrow_exception preserves object identity, which is not guaranteed on MSVC. Exercise concurrent diagnostic reads and later field edits on the same exception on every platform. --- Cpp/demo/EnumTests.cpp | 34 ++++++++++++++-------------------- 1 file changed, 14 insertions(+), 20 deletions(-) diff --git a/Cpp/demo/EnumTests.cpp b/Cpp/demo/EnumTests.cpp index 4992045..d118aa4 100644 --- a/Cpp/demo/EnumTests.cpp +++ b/Cpp/demo/EnumTests.cpp @@ -173,19 +173,16 @@ void checkExceptionMessage() { template void checkConcurrentExceptionMessage() { for (int iteration = 0; iteration < 32; ++iteration) { - std::exception_ptr exception; - try { throw Error(std::string(10000, 'x'), 3, 2); } - catch (...) { exception = std::current_exception(); } + Error error(std::string(10000, 'x'), 3, 2); + // Share the object directly: rethrow_exception may copy it on some runtimes. + const std::exception& diagnostic = error; for (bool edited : {false, true}) { const std::string message(10000, edited ? 'y' : 'x'); const std::string expected = (edited ? "line 9:4 " : "line 3:2 ") + message; if (edited) { - try { std::rethrow_exception(exception); } - catch (Error& error) { - error.message = message; - error.line = 9; - error.charPositionInLine = 4; - } + error.message = message; + error.line = 9; + error.charPositionInLine = 4; } std::atomic ready{0}; std::atomic go{false}; @@ -194,17 +191,14 @@ void checkConcurrentExceptionMessage() { std::vector threads; for (std::size_t index = 0; index < pointers.size(); ++index) { threads.emplace_back([&, index] { - try { std::rethrow_exception(exception); } - catch (const std::exception& error) { - ++ready; - while (!go.load()) std::this_thread::yield(); - pointers[index] = error.what(); - correct[index] = std::string(pointers[index]) == expected; - for (int read = 0; read < 10; ++read) - correct[index] = correct[index] && error.what() == pointers[index] && std::string(error.what()) == expected; - Error copy = static_cast(error); - correct[index] = correct[index] && std::string(copy.what()) == expected; - } + ++ready; + while (!go.load()) std::this_thread::yield(); + pointers[index] = diagnostic.what(); + correct[index] = std::string(pointers[index]) == expected; + for (int read = 0; read < 10; ++read) + correct[index] = correct[index] && diagnostic.what() == pointers[index] && std::string(diagnostic.what()) == expected; + Error copy = error; + correct[index] = correct[index] && std::string(copy.what()) == expected; }); } while (ready.load() != static_cast(pointers.size())) std::this_thread::yield();