view release on metacpan or  search on metacpan

lib/File/Raw/JSON.pm  view on Meta::CPAN

package File::Raw::JSON;

use 5.010;
use strict;
use warnings;

our $VERSION = '0.04';

use File::Raw;
use Tie::OrderedHash;

require XSLoader;
XSLoader::load('File::Raw::JSON', $VERSION);

1;

__END__

=head1 NAME

File::Raw::JSON - Fast JSON / JSONL plugin for File::Raw

=head1 VERSION

Version 0.03

=head1 SYNOPSIS

Loading the module registers two plugins (C<json>, C<jsonl>) with
File::Raw at BOOT time. Use them via File::Raw's standard plugin tail:

    use File::Raw qw(slurp spew each_line);
    use File::Raw::JSON;     # registers json + jsonl plugins

    # Single JSON document
    my $config = file_slurp("config.json", plugin => 'json');

    # Pretty-printed write
    file_spew("out.json", $payload, plugin => 'json',
              pretty => 1, sort_keys => 1);

    # JSON Lines / NDJSON streaming (line-by-line, RSS bounded)
    file_each_line("events.jsonl",
        sub { my $event = $_[0]; ... },
        plugin => 'jsonl');

    # Whole-file JSONL into AoV
    my $events = file_slurp("events.jsonl", plugin => 'jsonl');

For in-memory bytes <-> structure work (no path, no syscalls), import
the direct codec:

    use File::Raw::JSON qw(file_json_decode file_json_encode);

    my $val   = file_json_decode($json_bytes);
    my $bytes = file_json_encode($val, pretty => 1, sort_keys => 1);

    # JSONL via the same entry points
    my $rows  = file_json_decode($jsonl_bytes, mode => 'lines');
    my $out   = file_json_encode(\@rows,       mode => 'lines');

=head1 DESCRIPTION

Fast JSON I/O integrated with the L<File::Raw> plugin pipeline. One
syscall path through File::Raw, then a direct call into
L<yyjson|https://github.com/ibireme/yyjson> (vendored, MIT).

Two plugins are registered:

=over 4

=item B<json>

One JSON value per file. C<slurp> returns the parsed structure
(hashref / arrayref / scalar / undef); C<spew> serialises any Perl
value back to JSON bytes. C<each_line> with this plugin croaks with
a "use 'jsonl'" message - single documents don't decompose into
records.

=item B<jsonl>

JSONL / NDJSON / concatenated JSON values. C<slurp> returns an AoV;
C<spew> takes an AoV and writes one record per line; C<each_line>
streams records via callback (memory-bounded).

JSONL parsing uses brace-balancing rather than newline-splitting,
mirroring L<JSON::Lines>'s C<$LINES> regex. This means:

=over 4

=item * Pretty-printed JSONL works (records can span multiple lines).

=item * Multiple records on one line work (C<{"a":1}{"b":2}> = 2 records).

=item * Braces inside string fields don't break parsing.

=item * Chunked input is buffered and re-assembled across reads.

=back

=back