رموز الصيغ والدوال المخصصة

تكشف HotXLS عن تيارات رموز الصيغ المملوكة للمتصل للفحص دون فقدان والكتابة المحمية في محركَي المصنف، بالإضافة إلى سجلات دوال مخصصة هرمية للحساب المخصص

نموذج الرمز

تصنّف TXLSFormulaTokenClass وTXLSFormulaTokenKind وTXLSFormulaTokenSource كل TXLSFormulaToken وتسجّل ما إذا كان مصدره نصًا محلَّلًا أو بايتات BIFF كلاسيكية أو مصدرًا مدعومًا آخر

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` و`ArrayValues`
TXLSFormulaTokenStream	`DecodeBiff` و`Clone` و`CloneSyntaxTree` و`BindContext` و`CanCompileFor` و`CanWriteBiffAt` و`ReplaceReference` و`Count` و`Items` و`Source` و`FormulaText` و`FullyDecoded` و`Rgce` و`RgbExtra` و`BiffWritable` و`BiffVersion`
TXLSCompiledFormula	يعيد `CreateTokenStream` نسخة مملوكة للمتصل من تيار رموز الصيغة المُجمَّعة
TXLSFormula	`ArrayFormulaMode` و`FormulaLocale` و`MaxRow` و`MaxCol` و`FuncNamebyPtg` و`FuncArgsCntByPtg` و`GetCompiled` و`GetCompiledPreservingUnknownNames` و`GetCompiledR1C1` و`GetTokenStream` و`GetTranslated` و`GetStoreData` و`GetStoreDataExt` و`CanStoreData` و`BindUserDefinedFunctions` و`GetTExpData` و`SetMode` و`IsKnownFunction` و`GetFunctionNames` و`FunctionArgumentClass`

يجمّع كل محرك مصنف الصيغَ ويترجمها عبر نسخة TXLSFormula واحدة مشتركة: يحلل GetCompiled النص بنمط A1 إلى شجرة بنية، ويحل GetCompiledR1C1 مراجع R1C1 مقابل إحداثيات الخلية التي تسكن فيها الصيغة، ويعيد GetTranslated بناء شجرة من بايتات BIFF الكلاسيكية، وتكتب عائلة GetStoreData بايتات الرموز مجددًا لتخزينها. ويحدّ MaxRow وMaxCol شبكةَ المراجع التي يقبلها المجمّع — يرفعهما محرك XLSX من الافتراضات في BIFF8 إلى شبكة XLSX، والمراجع التي لا تتسع لـ BIFF8 لا شكل ptg لها، فيبلّغ عنها كتّاب BIFF8 بأنها غير قابلة للترميز

يُضبط ArrayFormulaMode أثناء كتابة rgce لسجل ARRAY (صيغة مصفوفة): تُتسلسل حينها مراجع الفئة القيمية وثوابت المصفوفات بوصفها فئة مصفوفة (tAreaA / tArrayA)، كما يكتبها Excel نفسه. ومع معاملات الفئة القيمية يقيّم Excel صيغة المصفوفة بتقاطع ضمني بدل معاملتها بوصفها صيغة مصفوفة حقيقية، ولهذا يرفع المحركان الراية لـ rgce سجل ARRAY نفسه

فحص محود لورقة مخزنة بسيطة

يفحص TXLSCompiledFormula.ReadSimpleLeafInfo(ExpectedOwner, MaxBytes, MaxTextCharacters, AllowUnboundBiff) شجرةَ البنية الرئيسية وأي تيار رموز محتفظ به في مكانه، دون استنساخ أو تفكيك أو تقييم أو تجسيد رموز أو مصفوفات؛ وافتراض AllowUnboundBiff هو False

الأشكال المدعومة هي ورقة REF3D أو RANGE3D مطلقة واحدة وحرفية نصية واحدة، برمز متماسك واحد بالضبط عندما يُحتفظ بتيار؛ وتعيد التعبيرات والمراجع النسبية أو ذات الإزاحات والمصفوفات وبيانات المصفوفات الخارجية والرموز المجهولة والأوراق غير المتطابقة بين الرئيسي والمحتفظ به والمالِكين المرتبطين الأجانب قيمةَ fslkUnsupported دون تغيير القيم المخزنة أو حالة الحساب

TXLSFormulaSimpleLeafKind	`fslkUnsupported` أو `fslkRange` أو `fslkLiteral`؛ افحص `Kind` قبل استخدام حقول النتيجة الأخرى
TXLSFormulaLeafOwnerState	يبلّغ `flosNoRetainedStream` عن غياب منشأ تيار رموز، ويبلّغ `flosUnboundStream` عن BIFF مستورد غير مرتبط، ويبلّغ `flosSameOwner` عن تطابق تام للمالك المرتبط، ويرفض `flosForeignOwner` مالكًا مرتبطًا مختلفًا
TXLSFormulaSimpleLeafInfo	سجل قيم خالٍ من السلاسل يحتوي `Kind` و `OwnerState` و `RangeType` و `ExternId` و `FirstRow` و `FirstCol` و `LastRow` و `LastCol` و `TextCharacters` و `StoredTextCharacters` و `ReadBytes` و `SyntaxNodes` و `TokenCount`
Range coordinates and identity	الإحداثيات ذات أساس صفري؛ و `ExternId` هو المعرف المنطقي ذو الأساس 1 لشجرة البنية لا فهرس BIFF السلكي؛ وعلى المستدعي حلّه عبر المصنف المثبت ورفض المصنفات الخارجية وامتدادات الأوراق والأوراق المفقودة والإحداثيات خارج مجال الالتقاط المدعوم لديه
Source costs	قيمة `TextCharacters` هي طول الإخراج الحرفي بوحدات كود UTF-16 أو صفر لنطاق؛ و `StoredTextCharacters` يجمع نص المصدر المحتفظ به ونص الرموز والنص المفحوص للبنية؛ و `ReadBytes` يجمع كلفتها النصية ثنائية البايت وأطوال البايتات الخام المحتفظ بها، بما يشمل التمثيلات المحتفظ بها على حدة؛ وتصف هذه العدادات مدخلات الفحص المحود لا إجمالي استخدام الكومة
Syntax and token counts	قيمة `SyntaxNodes` هي 1 لورقة مجمَّعة عادية أو 2 عندما تُفحص الورقتان الرئيسية والمحتفظ به معًا؛ و `TokenCount` صفر بلا تيار أو 1 مع تيار محتفظ متماسك مدعوم
TXLSFormulaTokenStream.ReadSimpleLeafInfo	تأخذ الطبقة الدنيا المالك والحصص نفسهما و `ComparedLeaf` و `ReferenceContext` اختياريين؛ وتفحص بنية التيار الخاصة ورموزه وبايتاته الخام مباشرة؛ ويضيف `ComparedLeaf` فحوصات تماسك الورقة الرئيسية، بينما يخطّط `ReferenceContext` فهارس extern لصيغ النص المسلسلة دون نسخ
TXLSCompiledFormula.ReadSimpleLiteral	تأخذ الوسائط نفسها وتكرر فحوصات الورقة وتعيد `WideString` مملوكًا للمستدعي فقط بعد أن تغطي حصتا البايتات والمحارف المتبقيتان مخرجه أيضًا؛ وترفع الأوراق غير المدعومة أو السعة المتبقية غير الكافية استثناءً `EInvalidOperation`

يجب أن يكون ExpectedOwner الحاسبة الدقيقة المرفقة بالمصدر المستهلك، ويجب أن يبقى حيًا ومستقرًا طوال الفحص واستخلاص الحرفية؛ ويرفع المالك المفقود استثناءً EArgumentException، وترفع الحصص السالبة استثناءً EArgumentOutOfRangeException، وترفع مدخلات المصدر المحتفظ به الزائدة عن الحد استثناءً EInvalidOperation قبل مقارنات المحتوى أو نسخ المخرجات

لا تثبت الورقة العادية بلا تيار محتفظ به مالكَها الأصلي؛ والتيار المستورد غير المرتبط أيضًا يحمل بلا هوية مصنف، لذا فالتمرير الصريح لـ AllowUnboundBiff=True ملائم فقط عندما يكون المستدعي قد ثبّت حاسبة المصدر بالفعل وسيتحقق من هوية الورقة المحلية قبل قراءة الخلايا؛ ويقبل فحص المراجع المستوردة حاليًا مراجع BIFF8 ويرفض تمثيل extern المختلف في BIFF5

حقول البنية القديمة المسماة FFirstRowRel و FFirstColRel و FLastRowRel و FLastColRel تكون صائبة للإحداثيات المطلقة؛ ويفحص المساعد أيضًا أعلام الـ token النسبية المستقلة وتمثيل الإزاحات، فلا يحتاج المستهلكون إلى استنتاج الإحداثيات المطلقة من هذه الأسماء التاريخية

شجرة البنية

يعيد CloneSyntaxTree شجرة محلَّلة مملوكة للمتصل من عقد TXLSSyntaxItem للفحص البنيوي: تبلّغ كل عقدة عن ItemType وحمولتها الحرفية (Value وIntValue وDecValue) وSpaces البادئة وروابط الشجرة (Parent وChild وChildCount) وورقة المرجع بصيغة TXLSRangeItem عبر Range وبيانات ثوابت المصفوفات (ArrayRows وArrayCols وArrayValueCount وإدخالات TXLSArraySerVal في ArrayValues). الشجرة نسخة منفصلة، فتجوّلها لا يلمس صيغ المصنف المجمَّعة إطلاقاً، وأعضاء التعديل (AddChild وPushChild وCopyObject وOffsetCopyReferences وAdjustForShift وTXLSRangeItem.CopyObject / AdjustForShift) موجودة للأدوات التي تعيد كتابة شجرة مستنسخة قبل إعادة التجميع

نقاط دخول المصنف

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 وSetFormulaTokens الملكية صريحة وتتحقق من السياق وإصدار BIFF ودعم الرموز وملكية المصفوفة وحدود المراجع قبل تغيير الخلية

سجلات الدوال المخصصة

توفر TXLSUserFunctionResolver وTXLSUserFunctionRegistry بحثًا بالاسم عبر RegisterHandler وUnregisterHandler وClear وContains وTryGetHandler وCount

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

تكشف IXLSWorkbook وTXLSWorkbook وTXLSXWorkbook عن RegisterUserFunction وUnregisterUserFunction وClearUserFunctions وRegisteredUserFunctionCount وRegisterGlobalUserFunction وUnregisterGlobalUserFunction وClearGlobalUserFunctions وRegisteredGlobalUserFunctionCount

نقاط الدخول المكافئة على مستوى الوحدة هي XLSRegisterGlobalUserFunction وXLSUnregisterGlobalUserFunction وXLSClearGlobalUserFunctions وXLSRegisteredGlobalUserFunctionCount وXLSGlobalUserFunctionRegistered

يشارك TXLSCalculator.OnUserFunctionResolve قبل التراجع القديم عن الأحداث، ويتم استدعاء معالجات السجل خارج قفل السجل بحيث يمكن للمعالج إلغاء تسجيل نفسه بأمان

تُحجب أسماء الدوال الخارجية الخطرة وأسماء الدوال بأسلوب الماكرو قبل تقييم الوسائط والبحث عن المعالج، ما لم تُمكَّن AllowUnsafeFormulaCallbacks صراحةً للمصنف أو لتقييم السياق الفردي؛ وتظل أسماء الدوال المخصصة العادية متاحة افتراضياً

تشخيص الصيغ

يتم إرجاع TXLSXFormulaIssueKind وTXLSXFormulaLocation وTXLSXFormulaIssue بواسطة TXLSXWorkbook.AnalyzeFormulaIssues للدوال المفقودة والمراجع الخارجية ومكونات التبعية الدائرية

فحص ورقة الماكرو

يميّز TXLSSheetKind بين ورقة العمل وورقة الماكرو وورقة المخطط ووحدة VBA وسجلات الأوراق غير المعروفة عبر TXLSWorksheet.SheetKind؛ تصف TXLSMacroRisk وTXLSMacroCommandInfo وTXLSMacroCommandArray النتائج المكتوبة التي يعيدها TXLSWorksheet.ScanMacroCommands

أنواع الضبط التلقائي المدمج والفرز

يختار TXLSMergedAutoFitStrategy وTXLSXMergedAutoFitStrategy النمو الأول أو الأخير أو المتوازن للامتدادات المدمجة، بينما يتحكم TXLSSortOrientation وTXLSSortFormulaMode وTXLSSortCompareEvent في الفرز الثابت العمودي أو الأفقي ونقل الصيغ