view release on metacpan or  search on metacpan

lib/JSON/Lines.pm  view on Meta::CPAN

	my $jsonl = JSON::Lines->new(
		success_cb => sub { if ($_[0] eq 'encode') { ... } },
		error_cb => sub { if ($_[0] eq 'decode') { ... } },
		canonical => 1,
		utf8 => 1,
		pretty => 1,
		parse_headers => 1
	);

=head3 success_cb

Callback called on successfull encode or decode of an item.

=head3 error_cb

Callback called on unsucessfull encode or decode of an item.

=head3 canonical

Print in canonical order.

=head3 utf8

utf8 encode/decode

=head3 pretty

Pretty print.

=head3 parse_headers

Parse the first line of the stream as headers.

All of the above options can also be get/set dynamically via accessor methods:

	# Get current value
	my $is_pretty = $jsonl->pretty;

	# Set value (returns $self for chaining)
	$jsonl->pretty(1)->canonical(1);

	# Set callbacks
	$jsonl->error_cb(sub { warn "Error: $_[1]" });
	$jsonl->success_cb(sub { print "Processed: $_[1]" });

=head2 encode

Encode a perl struct into a json lines string.

	$jsonl->encode( $data );

=head2 encode_file

Encode a perl struct into a json lines file.

	$jsonl->encode_file($file, $data);

=head2 decode

Decode a json lines string into a perl struct. Handles multiple JSON objects
per line (e.g., from streaming output that concatenates objects without newlines).
The decoder is string-aware, correctly handling unbalanced braces within JSON
string values (e.g., code snippets containing C<{> or C<}>).

	$jsonl->decode( $string );

	# Handles multiple objects on one line:
	my @data = $jsonl->decode('{"a":1}{"b":2}');
	# Returns: ({ a => 1 }, { b => 2 })

	# Handles code in strings:
	my @data = $jsonl->decode('{"code":"sub foo { }"}');
	# Correctly parses as single object

Supports chunked/streaming input - incomplete JSON is buffered and combined
with subsequent calls. Use C<remaining()> to check buffer state and
C<clear_buffer()> to reset.

=head2 decode_file

Decode a json lines file into a perl struct.

	$jsonl->decode_file( $file );

=head2 remaining

Returns any incomplete JSON data buffered from previous decode() calls.
Useful for debugging chunked input scenarios.

	my $buffered = $jsonl->remaining;
	if (length $buffered) {
		warn "Incomplete JSON in buffer: $buffered";
	}

=head2 clear_buffer

Clears the internal buffer used for chunked input. Call this to reset
state between unrelated decode operations on the same instance.

	$jsonl->clear_buffer;
	# Fresh state for new input
	my @data = $jsonl->decode($new_input);

=head2 add_line

Add a new line to the current JSON::Lines stream.

	$jsonl->add_line($line);

	$jsonl->add_line($line, $fh);

=head2 get_line

Decode a json lines file, one object at a time. If a line contains multiple
JSON objects, they are buffered and returned one at a time on subsequent calls.

	open my $fh, "<", $file or die "$file: $!";
	while (my $obj = $jsonl->get_line($fh)) {
		print $obj->{id}, "\n";
	}
	close $fh;

=head2 get_lines

Decode a json lines file, 'n' lines at a time.

	open my $fh, "<", $file or die "$file: $!";
	my @lines = $jsonl->get_lines($fh, 100);
	close $fh;

=head2 clear_stream

Clear the current JSON::Lines stream.

	$jsonl->clear_stream;