Formuletokens en gebruikersfuncties

HotXLS stelt door de aanroeper beheerde formuletokenstromen beschikbaar voor verliesvrije inspectie en bewaakte terugschrijving in beide werkmapengines, plus hiërarchische registers voor gebruikersfuncties voor aangepaste berekening

Tokenmodel

TXLSFormulaTokenClass, TXLSFormulaTokenKind en TXLSFormulaTokenSource classificeren elke TXLSFormulaToken en registreren of deze afkomstig is van geparste tekst, klassieke BIFF-bytes of een andere ondersteunde bron

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` en `ArrayValues`
TXLSFormulaTokenStream	`DecodeBiff`, `Clone`, `CloneSyntaxTree`, `BindContext`, `CanCompileFor`, `CanWriteBiffAt`, `ReplaceReference`, `Count`, `Items`, `Source`, `FormulaText`, `FullyDecoded`, `Rgce`, `RgbExtra`, `BiffWritable` en `BiffVersion`
TXLSCompiledFormula	`CreateTokenStream` retourneert een door de aanroeper beheerde kloon van de gecompileerde formuletokenstroom
TXLSFormula	`ArrayFormulaMode`, `FormulaLocale`, `MaxRow`, `MaxCol`, `FuncNamebyPtg`, `FuncArgsCntByPtg`, `GetCompiled`, `GetCompiledPreservingUnknownNames`, `GetCompiledR1C1`, `GetTokenStream`, `GetTranslated`, `GetStoreData`, `GetStoreDataExt`, `CanStoreData`, `BindUserDefinedFunctions`, `GetTExpData`, `SetMode`, `IsKnownFunction`, `GetFunctionNames` en `FunctionArgumentClass`

Elke werkmap-engine compileert en vertaalt formules via één gedeelde TXLSFormula-instantie: GetCompiled parseert A1-stijl tekst tot een syntaxisboom, GetCompiledR1C1 lost R1C1-referenties op tegen de coördinaten van de cel waarin de formule staat, GetTranslated bouwt een boom op uit klassieke BIFF-bytes, en de GetStoreData-familie schrijft de tokenbytes terug voor opslag. MaxRow en MaxCol begrenzen het referentieraster dat de compiler accepteert — de XLSX-engine verhoogt ze van de BIFF8-standaardwaarden naar het XLSX-raster, en referenties die niet in BIFF8 passen hebben geen ptg-vorm, dus de BIFF8-writers melden ze als niet codeerbaar

ArrayFormulaMode wordt gezet terwijl de rgce van een ARRAY-record (een matrixformule) wordt weggeschreven: referenties van de waardeklasse en arrayconstanten serialiseren dan als arrayklasse (tAreaA / tArrayA), precies zoals Excel ze zelf schrijft. Met operanden van de waardeklasse evalueert Excel de matrixformule met impliciete intersectie in plaats van haar als een echte matrixformule te behandelen — daarom zetten de engines de vlag voor de eigen rgce van het ARRAY-record

Begrensde inspectie van een eenvoudig opgeslagen blad

TXLSCompiledFormula.ReadSimpleLeafInfo(ExpectedOwner, MaxBytes, MaxTextCharacters, AllowUnboundBiff) inspecteert de hoofdsyntaxisboom en eventuele bewaarde tokenstroom in place, zonder te klonen, decompileren, evalueren of tokens of arrays te materialiseren; de standaard AllowUnboundBiff is False

De ondersteunde vormen zijn één absolute REF3D- of RANGE3D-blad en één stringliteral, met exact één samenhangend token wanneer er een stroom wordt bewaard; expressies, relatieve of offsetverwijzingen, arrays, externe arraygegevens, onbekende tokens, niet-matchende hoofd- en bewaarde bladen en vreemde gebonden eigenaars geven fslkUnsupported terug zonder gecachte waarden of berekeningsstatus te wijzigen

TXLSFormulaSimpleLeafKind	`fslkUnsupported`, `fslkRange` of `fslkLiteral`; inspecteer `Kind` voordat je de andere resultaatinvoeren gebruikt
TXLSFormulaLeafOwnerState	`flosNoRetainedStream` meldt geen tokenstroom-proveniëntie, `flosUnboundStream` meldt geïmporteerde ongebruikte BIFF, `flosSameOwner` meldt een exacte gebonden eigenaarmatch en `flosForeignOwner` wijst een andere gebonden eigenaar af
TXLSFormulaSimpleLeafInfo	Een waarde-record zonder strings met `Kind`, `OwnerState`, `RangeType`, `ExternId`, `FirstRow`, `FirstCol`, `LastRow`, `LastCol`, `TextCharacters`, `StoredTextCharacters`, `ReadBytes`, `SyntaxNodes` en `TokenCount`
Range coordinates and identity	Coördinaten zijn nulgebaseerd; `ExternId` is de logische 1-based syntaxisboom-ID, niet de BIFF-wire-index; de aanroeper moet die herleiden via de vastgepinde werkmap en externe werkmappen, bladoverspanningen, ontbrekende bladen of coördinaten buiten het ondersteunde capture-bereik afwijzen
Source costs	`TextCharacters` is de letterlijke uitvoerlengte in UTF-16-code-eenheden, of nul voor een bereik; `StoredTextCharacters` somt bewaarde brontekst, tokentekst en geïnspecteerde syntaxistekst op; `ReadBytes` somt hun tweetekstbyte-kosten en bewaarde rauwe bytelengtes op, inclusief apart bewaarde representaties; deze tellers beschrijven de begrensde inspectie-invoer in plaats van het totale heapgebruik
Syntax and token counts	`SyntaxNodes` is één voor een gewone gecompileerd blad of twee wanneer zowel hoofd- als bewaard blad worden gecontroleerd; `TokenCount` is nul zonder stroom of één met een ondersteunde samenhangende bewaarde stroom
TXLSFormulaTokenStream.ReadSimpleLeafInfo	De onderste laag neemt dezelfde eigenaar en quota, een optionele `ComparedLeaf` en een optionele `ReferenceContext`; hij controleert de eigen privé-syntax, tokens en rauwe bytes van de stroom rechtstreeks; `ComparedLeaf` voegt coherentiecontroles van het hoofdblad toe, terwijl `ReferenceContext` extern-indexes van geserialiseerde tekstformules mapt zonder te kopiëren
TXLSCompiledFormula.ReadSimpleLiteral	Neemt dezelfde argumenten, herhaalt de bladcontroles en geeft pas een door de aanroeper beheerde `WideString` terug nadat de resterende byte- en tekenquota ook zijn uitvoer dekken; niet-ondersteunde bladen of onvoldoende resterende capaciteit geven `EInvalidOperation`

ExpectedOwner moet de exacte calculator zijn die aan de consumerende bron is gekoppeld, en moet heel en stabiel blijven tijdens de inspectie en letterlijke extractie; een ontbrekende eigenaar geeft EArgumentException, negatieve quota's geven EArgumentOutOfRangeException en te grote bewaarde broninvoer geven EInvalidOperation vóór inhoudsvergelijkingen of uitvoerkopiëring

Een gewone blad zonder bewaarde stroom legt zijn oorspronkelijke eigenaar niet vast; een ongebruikte geïmporteerde stroom draagt ook geen werkmapidentiteit, dus expliciete AllowUnboundBiff=True is alleen passend wanneer de aanroeper de broncalculator al heeft vastgepind en de lokale bladidentiteit zal valideren voordat cellen worden gelezen; geïmporteerde referentie-inspectie accepteert momenteel BIFF8-verwijzingen en wijst de andere BIFF5-externrepresentatie af

De legacysyntaxisvelden met de namen FFirstRowRel, FFirstColRel, FLastRowRel en FLastColRel zijn true voor absolute coördinaten; de helper controleert ook de onafhankelijke relatieve vlaggen van het token en de offsetrepresentatie, zodat consumenten absolute coördinaten niet uit deze historische namen hoeven af te leiden

Syntaxisboom

CloneSyntaxTree geeft een door de aanroeper beheerde geparsede boom van TXLSSyntaxItem-knooppunten terug voor structurele inspectie: elk knooppunt rapporteert zijn ItemType, letterlijke payload (Value, IntValue, DecValue), voorloop-Spaces, boomverwijzingen (Parent, Child, ChildCount), het referentieblad als een TXLSRangeItem via Range en de data van arrayconstanten (ArrayRows, ArrayCols, ArrayValueCount en de TXLSArraySerVal-items in ArrayValues). De boom is een losse kopie, dus het doorlopen ervan raakt nooit de gecompileerde formules van de werkmap aan, en de mutatieleden (AddChild, PushChild, CopyObject, OffsetCopyReferences, AdjustForShift en TXLSRangeItem.CopyObject / AdjustForShift) bestaan voor tools die een gekloonde boom herschrijven vóór hercompilatie

Toegangspunten van de werkmap

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 en SetFormulaTokens houden het eigendom expliciet en valideren context, BIFF-versie, tokenondersteuning, array-eigendom en referentiegrenzen voordat een cel wordt gewijzigd

Registers voor gebruikersfuncties

TXLSUserFunctionResolver en TXLSUserFunctionRegistry bieden op naam gebaseerde opzoeking via RegisterHandler, UnregisterHandler, Clear, Contains, TryGetHandler en Count

Workbook.RegisterUserFunction('NETMARGIN', CalculateNetMargin);
Workbook.RegisterGlobalUserFunction('FISCALYEAR', CalculateFiscalYear);
try
  Workbook.Calculate;
finally
  Workbook.UnregisterUserFunction('NETMARGIN');
  Workbook.UnregisterGlobalUserFunction('FISCALYEAR');
end;

IXLSWorkbook, TXLSWorkbook en TXLSXWorkbook stellen RegisterUserFunction, UnregisterUserFunction, ClearUserFunctions, RegisteredUserFunctionCount, RegisterGlobalUserFunction, UnregisterGlobalUserFunction, ClearGlobalUserFunctions en RegisteredGlobalUserFunctionCount beschikbaar

De equivalente toegangspunten op eenheidsniveau zijn XLSRegisterGlobalUserFunction, XLSUnregisterGlobalUserFunction, XLSClearGlobalUserFunctions, XLSRegisteredGlobalUserFunctionCount en XLSGlobalUserFunctionRegistered

TXLSCalculator.OnUserFunctionResolve neemt deel vóór de verouderde event-fallback, en registerhandlers worden buiten de registervergrendeling aangeroepen, zodat een handler zichzelf veilig kan uitschrijven

Gevaarlijke externe functienamen en functienamen in macro-stijl worden geblokkeerd vóór de evaluatie van argumenten en het opzoeken van handlers, tenzij AllowUnsafeFormulaCallbacks expliciet is ingeschakeld voor de werkmap of de afzonderlijke contextuele evaluatie; gewone namen voor gebruikersfuncties blijven standaard beschikbaar

Formulediagnostiek

TXLSXFormulaIssueKind, TXLSXFormulaLocation en TXLSXFormulaIssue worden geretourneerd door TXLSXWorkbook.AnalyzeFormulaIssues voor ontbrekende functies, externe verwijzingen en circulaire-afhankelijkheidscomponenten

Inspectie van macrobladen

TXLSSheetKind onderscheidt werkblad-, macroblad-, grafiekblad-, VBA-module- en onbekende bladrecords via TXLSWorksheet.SheetKind; TXLSMacroRisk, TXLSMacroCommandInfo en TXLSMacroCommandArray beschrijven de getypeerde resultaten van TXLSWorksheet.ScanMacroCommands

Samengevoegde AutoFit- en sorteertypen

TXLSMergedAutoFitStrategy en TXLSXMergedAutoFitStrategy kiezen eerste, laatste of gebalanceerde groei voor samengevoegde bereiken, terwijl TXLSSortOrientation, TXLSSortFormulaMode en TXLSSortCompareEvent verticale of horizontale stabiele sortering en formuleverplaatsing aansturen