Tokens de fórmula y funciones de usuario

HotXLS expone flujos de tokens de fórmula propiedad del llamador para inspección sin pérdidas y escritura controlada en ambos motores de libro, además de registros jerárquicos de funciones de usuario para cálculo personalizado

Modelo de tokens

TXLSFormulaTokenClass, TXLSFormulaTokenKindy TXLSFormulaTokenSource clasifican cada TXLSFormulaToken y registran si provino de texto analizado, bytes BIFF clásicos u otra fuente admitida

Cada motor de libro compila y traduce fórmulas a través de una única instancia compartida de TXLSFormula: GetCompiled analiza texto estilo A1 en un árbol de sintaxis, GetCompiledR1C1 resuelve referencias R1C1 contra las coordenadas de la celda donde vive la fórmula, GetTranslated reconstruye un árbol a partir de bytes BIFF clásicos, y la familia GetStoreData vuelve a escribir los bytes de los tokens para almacenarlos. MaxRow y MaxCol acotan la cuadrícula de referencias que acepta el compilador — el motor XLSX los eleva de los valores predeterminados de BIFF8 a la cuadrícula de XLSX, y las referencias que no caben en BIFF8 no tienen forma ptg, así que los escritores BIFF8 las reportan como no codificables

ArrayFormulaMode se activa mientras se escribe el rgce de un registro ARRAY (una fórmula de matriz): las referencias de clase valor y las constantes de matriz se serializan entonces como clase matriz (tAreaA / tArrayA), de la forma en que el propio Excel las escribe. Con operandos de clase valor, Excel evalúa la fórmula de matriz con intersección implícita en lugar de tratarla como una fórmula de matriz verdadera, razón por la que los motores activan la bandera para el rgce del propio registro ARRAY

Inspección acotada de una hoja almacenada sencilla

TXLSCompiledFormula.ReadSimpleLeafInfo(ExpectedOwner, MaxBytes, MaxTextCharacters, AllowUnboundBiff) inspecciona en el sitio el árbol de sintaxis principal y cualquier flujo de tokens retenido, sin clonar, descompilar, evaluar ni materializar tokens o arreglos; el AllowUnboundBiff por defecto es False

Las formas soportadas son una hoja REF3D o RANGE3D absoluta y un literal de cadena, con exactamente un token coherente cuando se retiene un flujo; las expresiones, las referencias relativas o por desplazamiento, los arreglos, los datos externos de arreglos, los tokens desconocidos, las hojas principal y retenida que no coinciden y los propietarios vinculados ajenos devuelven fslkUnsupported sin cambiar los valores en caché ni el estado de cálculo

ExpectedOwner debe ser la calculadora exacta adjunta al origen consumidor y debe permanecer viva y estable durante toda la inspección y la extracción del literal; un propietario ausente lanza EArgumentException, las cuotas negativas lanzan EArgumentOutOfRangeException y las entradas de origen retenidas demasiado grandes lanzan EInvalidOperation antes de comparar contenido o copiar salida

Una hoja sencilla sin flujo retenido no establece su propietario original; un flujo importado sin vincular tampoco carga identidad de libro, así que un AllowUnboundBiff=True explícito solo procede cuando quien llama ya fijó la calculadora de origen y validará la identidad de la hoja local antes de leer celdas; la inspección de referencias importadas actualmente acepta referencias BIFF8 y rechaza la representación externa distinta de BIFF5

Los campos heredados de sintaxis llamados FFirstRowRel, FFirstColRel, FLastRowRel y FLastColRel son True para coordenadas absolutas; el helper también comprueba los flags independientes de relatividad de los tokens y la representación por desplazamiento, de modo que los consumidores no necesitan deducir coordenadas absolutas a partir de estos nombres históricos

Árbol de sintaxis

CloneSyntaxTree devuelve un árbol analizado propiedad del llamador, formado por nodos TXLSSyntaxItem para inspección estructural: cada nodo expone su ItemType, la carga útil literal (Value, IntValue, DecValue), los Spacesiniciales, los enlaces del árbol (Parent, Child, ChildCount), la hoja de referencia como TXLSRangeItem a través de Range, y los datos de constantes de matriz (ArrayRows, ArrayCols, ArrayValueCounty las entradas TXLSArraySerVal de ArrayValues). El árbol es una copia desvinculada, de modo que recorrerlo nunca toca las fórmulas compiladas del libro de trabajo; los miembros de mutación (AddChild, PushChild, CopyObject, OffsetCopyReferences, AdjustForShifty TXLSRangeItem.CopyObject / AdjustForShift) existen para las herramientas que reescriben un árbol clonado antes de recompilar

Puntos de entrada del libro

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, FormulaTokensToTexty SetFormulaTokens mantienen la propiedad explícita y validan el contexto, la versión de BIFF, la compatibilidad de tokens, la propiedad de matrices y los límites de referencias antes de modificar una celda

Registros de funciones de usuario

TXLSUserFunctionResolver y TXLSUserFunctionRegistry proporcionan búsqueda por nombre mediante RegisterHandler, UnregisterHandler, Clear, Contains, TryGetHandlery Count

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

IXLSWorkbook, TXLSWorkbooky TXLSXWorkbook exponen RegisterUserFunction, UnregisterUserFunction, ClearUserFunctions, RegisteredUserFunctionCount, RegisterGlobalUserFunction, UnregisterGlobalUserFunction, ClearGlobalUserFunctionsy RegisteredGlobalUserFunctionCount

Los puntos de entrada equivalentes a nivel de unidad son XLSRegisterGlobalUserFunction, XLSUnregisterGlobalUserFunction, XLSClearGlobalUserFunctions, XLSRegisteredGlobalUserFunctionCounty XLSGlobalUserFunctionRegistered

TXLSCalculator.OnUserFunctionResolve participa antes del respaldo del evento heredado, y los controladores del registro se invocan fuera del bloqueo del registro para que un controlador pueda cancelar su propio registro de forma segura

Los nombres de funciones peligrosos de tipo externo o macro se bloquean antes de evaluar los argumentos y de buscar los manejadores, salvo que AllowUnsafeFormulaCallbacks se habilite explícitamente para el libro de trabajo o para la evaluación contextual individual; los nombres de funciones de usuario ordinarias siguen estando disponibles de forma predeterminada

Diagnósticos de fórmulas

TXLSXFormulaIssueKind, TXLSXFormulaLocationy TXLSXFormulaIssue son devueltos por TXLSXWorkbook.AnalyzeFormulaIssues para funciones faltantes, referencias externas y componentes de dependencia circular

Inspección de hojas de macros

TXLSSheetKind distingue hojas de cálculo, hojas de macros, hojas de gráficos, módulos VBA y registros de hoja desconocidos mediante TXLSWorksheet.SheetKind; TXLSMacroRisk, TXLSMacroCommandInfoy TXLSMacroCommandArray describen los resultados con tipos de TXLSWorksheet.ScanMacroCommands

Tipos de AutoFit y ordenación combinados

TXLSMergedAutoFitStrategy y TXLSXMergedAutoFitStrategy eligen crecimiento primero, último o equilibrado para rangos combinados, mientras TXLSSortOrientation, TXLSSortFormulaModey TXLSSortCompareEvent controlan la ordenación estable vertical u horizontal y el movimiento de fórmulas

Véase también

• Motor de cálculo de Excel
• Trazado y auditoría de fórmulas
• Flujos de trabajo avanzados de libros