NAME

Data::Hash::Diff::Smart - Smart structural diff for Perl data structures

SYNOPSIS

use Data::Hash::Diff::Smart qw(diff diff_text diff_json diff_yaml diff_test2);

my $changes = diff($old, $new);

print diff_text($old, $new);

my $json = diff_json($old, $new);

my $yaml = diff_yaml($old, $new);

diag diff_test2($old, $new);

DESCRIPTION

Data::Hash::Diff::Smart provides a modern, recursive, configurable diff engine for Perl data structures. It understands nested hashes, arrays, scalars, objects, and supports ignore rules, custom comparators, and multiple array diffing strategies.

The diff engine produces a stable, structured list of change operations, which can be rendered as text, JSON, YAML, or Test2 diagnostics.

FUNCTIONS

diff($old, $new, %opts)

Compute a structural diff between two Perl data structures.

Returns an arrayref of change operations:

[
    { op => 'change', path => '/user/name', from => 'Nigel', to => 'N. Horne' },
    { op => 'add',    path => '/tags/2',    value => 'admin' },
    { op => 'remove', path => '/debug',     from  => 1 },
]

Options

• ignore => [ '/path', qr{^/debug}, '/foo/*/bar' ]

  Ignore specific paths. Supports exact paths, regexes, and wildcard segments.

• compare => { '/price' => sub { abs($_[0] - $_[1]) < 0.01 } }

  Custom comparator callbacks for specific paths.

• array_mode => 'index' | 'lcs' | 'unordered'

  Choose how arrays are diffed:

  • index - compare by index (default)
  • lcs - minimal diff using Longest Common Subsequence
  • unordered - treat arrays as multisets (order ignored)

diff_text($old, $new, %opts)

Render the diff as a human-readable text format.

diff_json($old, $new, %opts)

Render the diff as JSON using JSON::MaybeXS.

diff_yaml($old, $new, %opts)

Render the diff as YAML using YAML::XS.

diff_test2($old, $new, %opts)

Render the diff as Test2 diagnostics suitable for diag.

INTERNALS

The diff engine lives in Data::Hash::Diff::Smart::Engine.

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

REPOSITORY

https://github.com/nigelhorne/Data-Hash-Diff-Smart

SUPPORT

This module is provided as-is without any warranty.

Please report any bugs or feature requests to bug-data-hash-diff-smart at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-Hash-Diff-Smart. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

You can find documentation for this module with the perldoc command.

perldoc Data::Hash::Diff::Smart

You can also look for information at:

• MetaCPAN

  https://metacpan.org/dist/Data-Hash-Diff-Smart

• RT: CPAN's request tracker

  https://rt.cpan.org/NoAuth/Bugs.html?Dist=Data-Hash-Diff-Smart

• CPAN Testers' Matrix

  http://matrix.cpantesters.org/?dist=Data-Hash-Diff-Smart

• CPAN Testers Dependencies

  http://deps.cpantesters.org/?module=Data::Hash::Diff::Smart

LICENCE AND COPYRIGHT

Copyright 2026 Nigel Horne.

Usage is subject to licence terms.

The licence terms of this software are as follows:

• Personal single user, single computer use: GPL2
• All other users (including Commercial, Charity, Educational, Government) must apply in writing for a licence for use from Nigel Horne at the above e-mail.