decoder and docs

diff --git a/lib/JSON/Diffable.pm b/lib/JSON/Diffable.pm
index 7530d9c..b24a219 100644 (file)
--- a/lib/JSON/Diffable.pm
+++ b/lib/JSON/Diffable.pm
@@ -5,15 +5,23 @@ package JSON::Diffable;
 use JSON ();
 use Exporter 'import';
 
-my $real = JSON->new->allow_nonref->utf8;
+our $VERSION = '0.000001';
+$VERSION = eval $VERSION;
 
-our @EXPORT_OK = qw( encode_json );
+my $real = JSON->new->relaxed->allow_nonref->utf8;
+
+our @EXPORT_OK = qw( encode_json decode_json );
 
 sub encode_json {
     my $data = shift;
     return _encode($data, 0);
 }
 
+sub decode_json {
+    my $str = shift;
+    return $real->decode($str);
+}
+
 sub _indent {
     my $str = shift;
     $str =~ s{^}{  }gm;
@@ -46,3 +54,50 @@ sub _encode {
 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+JSON::Diffable - A relaxed and easy diffable JSON variant
+
+=head1 SYNOPSIS
+
+    use JSON::Diffable qw( encode_json decode_json );
+
+    $json = encode_json $data;
+    $data = decode_json $json;
+
+=head1 DESCRIPTION
+
+This module allows to create a JSON variant that is suitable for easy
+diffing. This means:
+
+=over
+
+=item * Commas after each hash or array element.
+
+=item * Consistent indentation
+
+=item * One line per entry
+
+=back
+
+The data can be read again by a relaxed L<JSON> parser or the exported
+L</decode_json> function.
+
+=head1 EXPORTS
+
+=head2 encode_json
+
+    my $json = encode_json($data);
+
+Turns a Perl data structure into relaxed JSON.
+
+=head2 decode_json
+
+    my $data = decode_json($json);
+
+Turns relaxed JSON into a Perl data structure.
+
+=cut