기술 문서

HotXLS로 Delphi에서 두 엑셀 워크북 diff 하기

같은 분기 워크북의 사본 두 개가 D2 셀에 똑같이 1,250.00을 보여 주면서도 그 셀의 정체는 서로 다를 수 있습니다. 한쪽은 직접 입력한 리터럴이고 다른 한쪽은 =SUM(A2:C2)입니다. 파일을 오가며 검토하는 사람에게는 두 화면이 완전히 같아 보입니다. 두 .xlsx 패키지를 바이트 단위로 비교하면 반대로 거의 모든 게 다르다고 나오는데, zip 아카이브는 두 번 썼다고 바이트까지 같아지는 경우가 드물기 때문입니다. 어느 쪽 검사도 검토 라운드 뒤에 사람들이 실제로 묻는 질문, 즉 어떤 셀과 수식과 시트가 바뀌었는지는 답해 주지 못합니다

이 질문이 튀어 나오는 지점은 몇 군데로 정해져 있습니다. 재무 워크북이 검토를 마치고 돌아오거나, 코드 변경 뒤에 야간 내보내기가 다시 생성되거나, 두 부서가 하나의 템플릿을 각자 편집해서 돌려보내는 경우입니다. 나란히 펼쳐 보고 비교하는 방식은 시트 하나에는 통하지만 스무 개에는 무력하며, 지친 눈이 놓치는 것이 바로 위의 수식 대 리터럴 뒤바뀜입니다

Delphi에서 HotXLS 워크북 비교 개요 다이어그램: baseline.xlsx와 reviewed.xlsx가 TXLSXWorkbookCompare에 공급되고, 이가 이름으로 시트를 짝짓고, 저장된 셀을 순회하며, 구조화된 차이 레코드와 읽을 수 있는 리포트를 방출
TXLSXWorkbookCompare는 로드된 두 HotXLS 워크북을 로직용 구조화된 diff 목록 하나와 검토자용 읽을 수 있는 보고서 하나로 바꿉니다

TXLSXWorkbookCompare로 두 워크북 비교하기

HotXLS는 lxCompare 유닛의 TXLSXWorkbookCompare로 워크북을 비교합니다. Compare(Left, Right)는 로드된 TXLSXWorkbook 객체 둘을 받아 발견된 차이의 개수를 반환합니다. 차이 목록은 이후 Diff(I)와 Count로 인덱스로 접근할 수 있고, Report는 차이마다 읽기 쉬운 한 줄씩 아무 TStrings에나 덧붙입니다. 어느 시점에도 Excel이 개입하지 않습니다. 비교는 HotXLS가 이미 로드한 객체 모델 위에서 돌아가므로, 콘솔 잡이나 서비스, C++Builder 애플리케이션에서도 똑같이 동작합니다

uses
  SysUtils, Classes, lxHandleX, lxCompare;

var
  Left, Right: TXLSXWorkbook;
  Cmp: TXLSXWorkbookCompare;
  Lines: TStringList;
begin
  Left := TXLSXWorkbook.Create;
  Right := TXLSXWorkbook.Create;
  Cmp := TXLSXWorkbookCompare.Create;
  Lines := TStringList.Create;
  try
    // Open은 성공 시 1을 반환하고, 실패한 열기는 여기서 멈춰야
    // 아니면 빈 워크북끼리 비교되어 결과가 아무 의미 없어짐
    if Left.Open('baseline.xlsx') <> 1 then
      raise Exception.Create('cannot open baseline.xlsx');
    if Right.Open('reviewed.xlsx') <> 1 then
      raise Exception.Create('cannot open reviewed.xlsx');

    if Cmp.Compare(Left, Right) = 0 then
      Writeln('workbooks are equivalent')
    else
    begin
      Cmp.Report(Lines);              // 차이마다 읽기 쉬운 한 줄
      Lines.SaveToFile('workbook-diff.txt');
      Writeln(Format('%d difference(s) written', [Cmp.Count]));
    end;
  finally
    Lines.Free;
    Cmp.Free;
    Right.Free;
    Left.Free;
  end;
end;

명시적인 열기 검사는 보이는 것보다 중요합니다. 인자 하나라도 nil이면 Compare는 0을 반환하고 목록을 지우며, 빈 워크북 둘도 같은 것으로 비교됩니다. 따라서 0이라는 결과는 두 파일이 실제로 로드됐을 때만 "동등함"을 뜻합니다. workbook-diff.txt의 전형적인 줄은 value changed: Data!A2: 10 -> 99처럼 읽힙니다

기본값으로는 무엇이 차이로 잡히는가?

옵션을 하나도 켜지 않으면 TXLSXWorkbookCompare는 여덟 종류의 차이를 보고합니다. 시트 추가 또는 제거, 셀 추가 또는 제거, 값 변경, 수식 변경, 병합 범위 추가 또는 제거입니다. 열거형 값은 lckSheetAdded, lckSheetRemoved, lckCellAdded, lckCellRemoved, lckValueChanged, lckFormulaChanged, lckMergeAdded, lckMergeRemoved입니다. 모든 차이는 왼쪽 워크북을 기준선으로 삼아 측정되므로, 추가된 항목은 오른쪽에만, 제거된 항목은 왼쪽에만 존재합니다

여덟 가지 HotXLS 워크북 차이 종류 다이어그램: 시트, 셀, 병합 수준으로 묶이고 각각 왼쪽 워크북을 기준선으로 측정되며, 0 행과 0 열은 시트 수준과 병합 수준 항목을 표시
HotXLS는 기본값으로 세 수준에 걸쳐 여덟 종류의 차이를 보고하며 모두 왼쪽 워크북 기준이므로, 시트 재배열은 아무것도 보고하지 않습니다

시트는 이름으로 짝지어지고 매칭은 대소문자를 무시하므로, 왼쪽의 Data는 오른쪽의 DATA와 짝이 됩니다. 따라서 탭을 새 위치로 드래그해도 항목이 하나도 생기지 않습니다. 시트 이름을 바꾸는 것은 사정이 다릅니다. Q3을 Q3 Final로 바꾸면 sheet removed 한 줄과 sheet added 한 줄로 나타나는데, 둘이 같은 시트라는 사실을 파일 어디에도 기록해 두지 않기 때문입니다. 한쪽에만 존재하는 시트는 내부의 셀마다 한 줄씩이 아니라 시트 수준 항목 하나로 보고되므로, 두 워크북의 구조가 다를 때도 리포트는 읽을 만하게 유지됩니다

셀은 위치로 짝지어집니다. 비교는 짝지어진 각 시트의 저장된 셀을 순회하는데, 여기에는 서식만 담고 있는 셀도 포함됩니다. 왼쪽에만 있고 오른쪽에 없는 서식만 있는 빈 셀은 cell removed: Data!C4 was (blank)로 보고됩니다. 병합 범위는 A1 텍스트로 비교하므로, A1:D1이 A1:E1으로 넓어지면 merge removed 하나와 merge added 하나가 나옵니다

같은 숫자의 수식과 리터럴은 왜 변경으로 보고되는가?

수식이 곧 작성된 콘텐츠이기 때문입니다. 셀 짝의 어느 한쪽이 수식을 담고 있으면 TXLSXWorkbookCompare는 수식 텍스트를 비교하고, 한쪽은 수식이고 다른 쪽은 리터럴인 경우 두 셀이 모두 1,250을 표시하더라도 lckFormulaChanged 항목이 됩니다. 도입부 예제의 리포트 줄은 formula changed: Data!D2: 1250 -> =SUM(A2:C2)이고, 레코드는 LeftKind = lcvNumber와 RightKind = lcvFormula를 갖습니다. 수식 텍스트는 저장된 그대로 비교되며, 표시할 때만 앞에 등호를 붙입니다

리터럴 값은 입력된 타입 그대로 비교됩니다. 숫자는 숫자와, 텍스트는 텍스트와 비교되고, 숫자 10과 텍스트 "10"은 두 셀이 같은 문자를 출력하더라도 변경입니다. 종류가 다르면 리포트에 타입 레이블이 붙습니다. value changed: Data!B7: [number] 10 -> [text] 10 같은 식입니다. 이런 사례는 CSV 왕복이나 사용자 복사-붙여넣기를 거친 파일에서 흔하고, 나중에 조회 수식을 깨뜨리는 바로 그 사례입니다

텍스트가 바뀌지 않은 수식은 캐시된 결과가 달라지더라도 기본값으로는 아무것도 보고하지 않습니다. 작성된 콘텐츠를 검토하는 관점에서는 올바른 동작입니다. 그러나 생성기를 회귀 테스트할 때는 너무 관대한데, 입력 시트가 바뀌면 수식 하나도 건드리지 않고 모든 합계가 움직일 수 있기 때문입니다. Options에 lcoFormulaCachedResults를 켜면 캐시된 결과가 다를 때마다, 또는 한쪽에만 캐시 값이 있고 다른 쪽에 없을 때((missing cache)로 보고) lckFormulaCacheChanged 항목이 추가됩니다. 생성기 회귀 테스트라면 이 옵션을 켜세요. 수식은 그대로인데 합계가 흘러가는 것이 바로 그런 테스트가 잡으려는 실패입니다

캐시된 결과는 마지막 계산 시점만큼만 새것이므로, 질문이 "이 수식들이 오늘 무엇을 만들어 내는가"라면 두 워크북을 먼저 재계산하세요. TXLSXWorkbook.Recalculate는 성공 시 lxOk를 반환하고, 반복 계산이 꺼져 있으면 참조 순환이 lxErrorRef를 돌려줍니다. 거짓 경보의 또 다른 원천은 부동소수점 노이즈인데, SetNumericTolerance(AbsoluteTolerance, RelativeTolerance)가 숫자 리터럴과 캐시된 결과를 한꺼번에 처리해 줍니다:

uses
  SysUtils, lxCalc, lxHandleX, lxCompare;

function CompareGeneratedReport(Expected, Actual: TXLSXWorkbook;
  Cmp: TXLSXWorkbookCompare): Integer;
begin
  // 결과를 비교하기 전에 두 캐시를 모두 최신으로
  if (Expected.Recalculate <> lxOk) or (Actual.Recalculate <> lxOk) then
    raise Exception.Create('recalculation failed');

  Cmp.Options := [lcoFormulaCachedResults];
  // 절대 1e-9 또는 상대 1e-12; 두 값 모두 유한하고 음수가 아니어야 하며
  // 아니면 EArgumentException이 발생하고 어느 값도 바뀌지 않음
  Cmp.SetNumericTolerance(1e-9, 1e-12);

  Result := Cmp.Compare(Expected, Actual);
end;

허용 오차의 기본값은 0이며, 이는 정확 비교를 뜻합니다. 오차는 숫자에만 적용됩니다. 날짜와 행/열 기하 정보, 스타일은 항상 정확히 비교되므로, 통화 반올림에 맞춘 오차가 1초 어긋난 날짜를 숨기는 일은 없습니다

구조화된 차이로 로직 구동하기

각 TlxCompareDiff 레코드는 Kind, Sheet, 1 기반 Row와 Col, A1 Ref, LeftText, RightText를 노출하고, 셀 항목에는 LeftKind와 RightKind가 붙습니다. 시트 수준과 병합 수준 항목은 Row와 Col에 0을 담습니다. 선택적 검사를 켜면 행 기하 항목은 행만, 열 기하 항목은 열만 담고, 정의된 이름 같은 워크북 기능 항목은 둘 다 비워 두므로, 0 좌표가 아니라 Kind로 분기하세요:

var
  I, FormulaEdits: Integer;
  D: TlxCompareDiff;
begin
  FormulaEdits := 0;
  for I := 0 to Cmp.Count - 1 do
  begin
    D := Cmp.Diff(I);
    case D.Kind of
      lckFormulaChanged:
        begin
          Inc(FormulaEdits);
          Writeln(Format('%s!%s: %s => %s',
            [D.Sheet, D.Ref, D.LeftText, D.RightText]));
        end;
      lckValueChanged:
        if D.LeftKind <> D.RightKind then
          Writeln('type change: ' + D.Describe);
      lckSheetAdded, lckSheetRemoved:
        Writeln('structure: ' + D.Describe);
      lckMergeAdded, lckMergeRemoved:
        Writeln('layout: ' + D.Describe);
    end;
  end;

  // 수식 편집만 차단하는 검토 정책
  if FormulaEdits > 0 then
    raise Exception.CreateFmt(
      '%d formula change(s) need sign-off', [FormulaEdits]);
end;

목록의 순서는 고정되어 있습니다. Compare는 차이를 시트 이름, 그다음 행, 열, 종류, 참조 순으로 정렬하므로, 같은 파일 쌍에 두 번 돌려도 리포트 텍스트가 줄 단위로 동일하게 나옵니다. 시트 이름은 탭 위치가 아니라 서수 문자열 비교로 정렬되고, 행이 0인 항목은 각 시트 그룹 안에서 맨 앞에 옵니다. 덕분에 리포트 텍스트는 회귀 테스트의 골든 파일로 손색이 없습니다. 기대되는 workbook-diff.txt를 커밋해 두고, 새 결과가 다르면 빌드를 실패시키면 됩니다. 정책 판단에는 레코드 필드를 직접 읽고, 사람이 읽을 설명 줄은 그 용도로 남겨 두세요

서식, 레이아웃, 객체 검사는 직접 켜기

기본 집합은 데이터 비교이므로, 숫자 서식이 General에서 Currency로 바뀐 셀은 기본 집합 아래에서 아무것도 보고하지 않습니다. Options 속성은 비교를 한 번에 한 범주씩 넓힙니다. lcoCellStyles는 짝지어진 각 셀의 확정된 스타일을 비교하고, lcoBlankStyleRegions는 저장된 셀이 없는 서식 영역에 대해 같은 비교를 하면서 인접한 차이를 LastRow와 LastCol에 먼 코너를 둔 사각형으로 병합합니다. lcoAxisGeometry는 행 높이와 열 너비를 숨김, 개요 수준, 축소 상태와 함께 비교합니다. lcoRichTextRuns는 텍스트 셀 안의 서식 지정 런을 비교합니다

객체 수준 콘텐츠에는 자체 스위치가 있습니다. lcoDefinedNames, lcoDataValidations, lcoConditionalFormats, lcoTables, lcoDrawings(셀 안 이미지도 포함), lcoPivotTables, lcoPivotCaches, lcoSlicerState, lcoTimelineState입니다. 이런 항목들은 기능의 키를 Ref에 넣고, 추가되었는지 제거되었는지 변경되었는지는 Change로 알려 줍니다. 정의된 이름, 피벗 캐시, 워크북 수준 슬라이서·타임라인 캐시는 빈 Sheet를 갖습니다

이 검사들의 출력은 기대치를 바로잡고 읽어야 합니다. 스타일, 리치 텍스트, 기능 항목은 정규화된 정의의 SHA-256 다이제스트를 LeftText와 RightText에 담으므로, 리포트는 C5 셀의 스타일이 바뀌었다고 말해 줘도 어느 속성이 바뀌었는지는 말해 주지 않습니다. 기하 항목은 읽을 수 있어서 size=15; hidden=0; outline=0; collapsed=0 같은 식이고, 명시적 높이가 없는 행은 시트 표준 높이로 비교되므로 표준 높이도 15라면 명시적인 15포인트 행과 설정 없는 행이 같게 됩니다. 콘텐츠 검토에서는 lcoCellStyles를 끄세요. 큰 워크북에서 이 옵션은 다시 서식을 입은 모든 열을 해시의 벽으로 바꿔 놓아, 검토자에게 승인을 요청받은 세 셀 편집을 가려 버립니다

// 레이아웃 검토: geometry, 병합, 조건부 서식만
Cmp.Options := [lcoAxisGeometry, lcoConditionalFormats, lcoDataValidations];
// 객체 검사가 담을 수 있는 상한: 32 MiB, 50만 개 항목
Cmp.SetFeatureLimits(32 * 1024 * 1024, 500000);
try
  Cmp.Compare(Left, Right);
except
  on E: EXLSXSemanticBudget do
    Writeln('workbooks too large for this check: ' + E.Message);
end;

객체 검사는 비교에 앞서 정의를 담아 두며, SetFeatureLimits가 그 담기 상한을 정합니다. 기본값은 67,108,864바이트와 1,000,000개 항목이고, 하나라도 넘어서면 EXLSXSemanticBudget이 발생합니다. Compare가 예외를 던졌을 때 이전 성공 호출의 차이 목록은 그대로 남아 있으므로, 예외를 잡은 호출자가 실패한 실행의 결과로 Count를 읽어서는 안 됩니다

날짜, 삽입된 행, 그리고 diff가 빛을 발하는 지점

워크북이 날짜로 보관하는 셀은 날짜로, 정확하게 비교되고, 밑에 깔린 날짜 숫자 값을 date(...) 형태로 출력합니다. 한쪽은 날짜인데 다른 쪽은 평범한 숫자인 경우 종류 레이블이 붙는데, 이는 어떤 도구를 거치며 열의 날짜 서식을 잃었다는 전형적인 신호입니다. 여기서의 함정은 섞인 날짜 체계입니다. 1904 날짜 체계 워크북과 1900 체계 워크북은 같은 달력 날짜를 1,462 차이 나는 일련번호로 저장하므로, 날짜 변경 목록을 믿기 전에 양쪽의 Date1904를 확인하세요. 배경은 날짜 일련번호와 1904 체계에 있습니다

위치 기반 짝짓기에는 미리 계획해 둘 만한 결과가 하나 있습니다. 시트 위쪽에 행을 삽입하면 그 아래의 모든 셀이 이동하므로, 비교는 시트를 따라 변경, 추가, 제거된 셀의 행렬을 보고하고, 삽입이 참조를 다시 쓴 수식들은 변경으로 보고됩니다. 파이프라인을 통제할 수 있다면 구조 편집 전에 한 번, 후에 한 번 비교를 돌려서 각 리포트가 한 종류의 변경만 다루게 하세요. 다시 쓰기 규칙은 삽입과 삭제 시의 수식 참조 조정에서 다룹니다

세 가지 작업은 이 기능을 붙일 명분이 됩니다. 리포트 생성기 회귀 테스트: 정상 동작이 확인된 워크북을 보관하고, 다시 생성하고, 캐시 결과를 켠 채 비교해서 차이가 하나라도 있으면 실패시킵니다. 변경 검토: 파일 두 개 대신 정렬된 리포트를 검토자에게 건넵니다. 마이그레이션 검증: 레거시 워크북 묶음을 변환한 뒤 각 결과를 원본과 비교하고, 이어서 워크북 감사 및 변환 워크벤치의 인벤토리 패스로 양쪽의 서식과 객체 기능 개수를 셉니다

비교, 재계산, 변환은 Delphi와 C++Builder용 HotXLS에서 하나의 엔진을 공유하며, HotXLS Delphi 스프레드시트 컴포넌트 페이지에 그 엔진이 읽고 쓰는 나머지 것들이 정리되어 있습니다