Formel-Token und benutzerdefinierte Funktionen
HotXLS legt vom Aufrufer verwaltete Formel-Token-Streams für verlustfreie Prüfung und geschützten Rückschrieb in beiden Arbeitsmappen-Engines offen, zusätzlich zu hierarchischen Registern für benutzerdefinierte Funktionen zur benutzerdefinierten Berechnung
Token-Modell
TXLSFormulaTokenClass, TXLSFormulaTokenKind und TXLSFormulaTokenSource klassifizieren jedes TXLSFormulaToken und zeichnen auf, ob es aus geparstem Text, klassischen BIFF-Bytes oder einer anderen unterstützten Quelle stammt
| TXLSFormulaToken | Kind, Opcode, BaseOpcode, TokenClass, RawBytes, TextValue, NumberValue, IntegerValue, ArgumentCount, FunctionIndex, ExternSheetIndex, Row1, Col1, Row2, Col2, Row1Relative, Col1Relative, Row2Relative, Col2Relative, ReferenceUsesOffsets, Supported, ArrayRows, ArrayCols, ArrayValueCount und ArrayValues |
| TXLSFormulaTokenStream | DecodeBiff, Clone, CloneSyntaxTree, BindContext, CanCompileFor, CanWriteBiffAt, ReplaceReference, Count, Items, Source, FormulaText, FullyDecoded, Rgce, RgbExtra, BiffWritable und BiffVersion |
| TXLSCompiledFormula | CreateTokenStream gibt einen vom Aufrufer verwalteten Klon des kompilierten Formel-Token-Streams zurück |
| TXLSFormula | ArrayFormulaMode, FormulaLocale, MaxRow, MaxCol, FuncNamebyPtg, FuncArgsCntByPtg, GetCompiled, GetCompiledPreservingUnknownNames, GetCompiledR1C1, GetTokenStream, GetTranslated, GetStoreData, GetStoreDataExt, CanStoreData, BindUserDefinedFunctions, GetTExpData, SetMode, IsKnownFunction, GetFunctionNames und FunctionArgumentClass |
Jede Arbeitsmappen-Engine kompiliert und übersetzt Formeln über eine gemeinsame TXLSFormula-Instanz: GetCompiled parst A1-Text in einen Syntaxbaum, GetCompiledR1C1 löst R1C1-Verweise gegen die Koordinaten der Zelle auf, in der die Formel liegt, GetTranslated baut einen Baum aus klassischen BIFF-Bytes wieder auf, und die GetStoreData-Familie schreibt die Token-Bytes für die Speicherung wieder heraus. MaxRow und MaxCol begrenzen das Referenzraster, das der Compiler akzeptiert — die XLSX-Engine hebt sie von den BIFF8-Defaults auf das XLSX-Raster an, und Verweise, die nicht in BIFF8 passen, haben keine ptg-Form, sodass die BIFF8-Writer sie als nicht kodierbar melden
ArrayFormulaMode ist gesetzt, während die rgce eines ARRAY-Datensatzes (eine Array-Formel) geschrieben wird: Wertklassen-Verweise und Array-Konstanten serialisieren dann als Array-Klasse (tAreaA / tArrayA), so wie Excel selbst sie schreibt. Mit Wertklassen-Operanden wertet Excel die Array-Formel mit impliziter Schnittmenge aus, statt sie als echte Array-Formel zu behandeln — deshalb setzen die Engines das Flag für die eigene rgce des ARRAY-Datensatzes
Begrenzte Inspektion eines einfachen gespeicherten Blatts
TXLSCompiledFormula.ReadSimpleLeafInfo(ExpectedOwner, MaxBytes, MaxTextCharacters, AllowUnboundBiff) untersucht den Haupt-Syntaxbaum und jeden zurückgehaltenen Token-Stream an Ort und Stelle, ohne Tokens oder Arrays zu klonen, zu dekompilieren, auszuwerten oder zu materialisieren; das Standard-AllowUnboundBiff ist False
Die unterstützten Formen sind ein absolutes REF3D- oder RANGE3D-Blatt und ein String-Literal, mit genau einem kohärenten Token, wenn ein Stream zurückgehalten wird; Ausdrücke, relative oder Offset-Verweise, Arrays, externe Array-Daten, unbekannte Tokens, nicht zusammenpassende Haupt- und zurückgehaltene Blätter sowie fremde gebundene Owner liefern fslkUnsupported, ohne Cache-Werte oder Berechnungszustand zu ändern
| TXLSFormulaSimpleLeafKind | fslkUnsupported, fslkRange oder fslkLiteral; vor der Nutzung der anderen Ergebnisfelder Kind prüfen |
| TXLSFormulaLeafOwnerState | flosNoRetainedStream meldet keine Token-Stream-Herkunft, flosUnboundStream meldet importierten ungebundenen BIFF, flosSameOwner meldet eine exakte Übereinstimmung des gebundenen Owners, und flosForeignOwner weist einen anderen gebundenen Owner zurück |
| TXLSFormulaSimpleLeafInfo | Ein stringfreier Wertedatensatz mit Kind, OwnerState, RangeType, ExternId, FirstRow, FirstCol, LastRow, LastCol, TextCharacters, StoredTextCharacters, ReadBytes, SyntaxNodes und TokenCount |
| Range coordinates and identity | Koordinaten sind nullbasiert; ExternId ist die logische 1-basierte Syntaxbaum-ID, nicht der BIFF-Wire-Index; der Aufrufer muss sie über die angepinnte Arbeitsmappe auflösen und externe Mappen, Blattspannen, fehlende Blätter oder Koordinaten außerhalb des unterstützten Erfassungsbereichs zurückweisen |
| Source costs | TextCharacters ist die literale Ausgabelänge in UTF-16-Codeeinheiten, oder null für einen Bereich; StoredTextCharacters summiert zurückgehaltenen Quelltext, Token-Text und untersuchten Syntaxtext; ReadBytes summiert deren Zwei-Byte-Textkosten und zurückgehaltene Rohbytelängen, einschließlich separat zurückgehaltener Repräsentationen; diese Zähler beschreiben die begrenzten Inspektionseingaben und nicht die gesamte Heap-Nutzung |
| Syntax and token counts | SyntaxNodes ist eins für ein einfaches kompiliertes Blatt oder zwei, wenn Haupt- und zurückgehaltenes Blatt geprüft werden; TokenCount ist null ohne Stream oder eins mit einem unterstützten kohärenten zurückgehaltenen Stream |
| TXLSFormulaTokenStream.ReadSimpleLeafInfo | Die untere Schicht nimmt denselben Owner und dieselben Quotas, ein optionales ComparedLeaf und einen optionalen ReferenceContext; sie prüft den privaten Syntax-, Token- und Rohbytebestand des Streams direkt; ComparedLeaf ergänzt Kohärenzprüfungen des Hauptblatts, während ReferenceContext serialisierte Textformel-Extern-Indizes ohne Kopieren auflöst |
| TXLSCompiledFormula.ReadSimpleLiteral | Nimmt dieselben Argumente, wiederholt die Blattprüfungen und liefert einen aufrufereigenen WideString erst, wenn die verbleibenden Byte- und Zeichen-Quotas auch seine Ausgabe abdecken; nicht unterstützte Blätter oder unzureichende Restkapazität lösen EInvalidOperation aus |
ExpectedOwner muss der exakte Calculator sein, der an die konsumierende Quelle gebunden ist, und muss während der gesamten Inspektion und Literal-Extraktion am Leben und stabil bleiben; ein fehlender Owner löst EArgumentException aus, negative Quotas EArgumentOutOfRangeException, und überdimensionierte zurückgehaltene Quelleingaben lösen EInvalidOperation aus, noch bevor Inhaltsvergleiche oder Ausgabekopien erfolgen
Ein einfaches Blatt ohne zurückgehaltenen Stream begründet keinen ursprünglichen Owner; ein ungebundener importierter Stream trägt ebenfalls keine Arbeitsmappen-Identität, daher ist explizites AllowUnboundBiff=True nur angemessen, wenn der Aufrufer den Quell-Calculator bereits angepinnt hat und die lokale Blattidentität vor dem Lesen von Zellen validiert; die Inspektion importierter Referenzen akzeptiert derzeit BIFF8-Referenzen und weist die unterschiedliche BIFF5-Extern-Repräsentation zurück
Die Legacy-Syntaxfelder namens FFirstRowRel, FFirstColRel, FLastRowRel und FLastColRel sind für absolute Koordinaten true; der Helper prüft auch die unabhängigen Token-Relative-Flags und die Offset-Repräsentation, sodass Konsumenten absolute Koordinaten nicht aus diesen historischen Namen ableiten müssen
Syntaxbaum
CloneSyntaxTree gibt einen vom Aufrufer verwalteten, geparsten Baum aus TXLSSyntaxItem-Knoten für die strukturelle Inspektion zurück: Jeder Knoten meldet seinen ItemType, seine Literal-Payload (Value, IntValue, DecValue), führende Spaces, seine Baumverweise (Parent, Child, ChildCount), das Referenz-Blatt als TXLSRangeItem über Range sowie die Daten von Array-Konstanten (ArrayRows, ArrayCols, ArrayValueCount und die TXLSArraySerVal-Einträge in ArrayValues). Der Baum ist eine losgelöste Kopie — ein Durchlauf berührt also nie die kompilierten Formeln der Arbeitsmappe. Die Mutations-Member (AddChild, PushChild, CopyObject, OffsetCopyReferences, AdjustForShift sowie TXLSRangeItem.CopyObject / AdjustForShift) gibt es für Tools, die einen geklonten Baum vor dem Rekompilieren umschreiben
Einstiegspunkte der Arbeitsmappe
Tokens := Worksheet.ParseFormulaTokens('SUM(A1:A4)', 1, 1);
try
if Tokens.ReplaceReference(OldRef, NewRef) then
Worksheet.SetFormulaTokens(1, 1, Tokens);
finally
Tokens.Free;
end;
ParseFormulaTokens, GetFormulaTokens, FormulaTokensToText und SetFormulaTokens halten die Verwaltung explizit und validieren Kontext, BIFF-Version, Token-Unterstützung, Array-Verwaltung und Referenzgrenzen, bevor eine Zelle geändert wird
Register für benutzerdefinierte Funktionen
TXLSUserFunctionResolver und TXLSUserFunctionRegistry bieten das Nachschlagen nach Namen über RegisterHandler, UnregisterHandler, Clear, Contains, TryGetHandler und Count
Workbook.RegisterUserFunction('NETMARGIN', CalculateNetMargin);
Workbook.RegisterGlobalUserFunction('FISCALYEAR', CalculateFiscalYear);
try
Workbook.Calculate;
finally
Workbook.UnregisterUserFunction('NETMARGIN');
Workbook.UnregisterGlobalUserFunction('FISCALYEAR');
end;
IXLSWorkbook, TXLSWorkbook und TXLSXWorkbook legen RegisterUserFunction, UnregisterUserFunction, ClearUserFunctions, RegisteredUserFunctionCount, RegisterGlobalUserFunction, UnregisterGlobalUserFunction, ClearGlobalUserFunctions und RegisteredGlobalUserFunctionCount offen
Die entsprechenden Einstiegspunkte auf Unit-Ebene sind XLSRegisterGlobalUserFunction, XLSUnregisterGlobalUserFunction, XLSClearGlobalUserFunctions, XLSRegisteredGlobalUserFunctionCount und XLSGlobalUserFunctionRegistered
TXLSCalculator.OnUserFunctionResolve wirkt vor dem Ereignis-Fallback der älteren Version, und Registry-Handler werden außerhalb der Registry-Sperre aufgerufen, sodass sich ein Handler sicher selbst abmelden kann
Gefährliche externe und makroartige Funktionsnamen werden blockiert, bevor Argumente ausgewertet und Handler nachgeschlagen werden — es sei denn, AllowUnsafeFormulaCallbacks ist für die Arbeitsmappe oder die einzelne kontextbezogene Auswertung explizit aktiviert; gewöhnliche Benutzerfunktionsnamen bleiben standardmäßig verfügbar
Formeldiagnose
TXLSXFormulaIssueKind, TXLSXFormulaLocation und TXLSXFormulaIssue werden von TXLSXWorkbook.AnalyzeFormulaIssues für fehlende Funktionen, externe Verweise und Komponenten zyklischer Abhängigkeiten zurückgegeben
Prüfung von Makroblättern
TXLSSheetKind unterscheidet Arbeitsblatt-, Makroblatt-, Diagrammblatt-, VBA-Modul- und unbekannte Blattdatensätze über TXLSWorksheet.SheetKind; TXLSMacroRisk, TXLSMacroCommandInfo und TXLSMacroCommandArray beschreiben die typisierten Ergebnisse von TXLSWorksheet.ScanMacroCommands
Zusammengeführte AutoFit- und Sortiertypen
TXLSMergedAutoFitStrategy und TXLSXMergedAutoFitStrategy wählen erstes, letztes oder ausgeglichenes Wachstum für zusammengeführte Bereiche, während TXLSSortOrientation, TXLSSortFormulaMode und TXLSSortCompareEvent vertikales oder horizontales stabiles Sortieren und die Formelverschiebung steuern