JSON-JSONFold

 view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# JSON::JSONFold

Readable, compact JSON formatting for Perl.

JSON::JSONFold is a streaming JSON formatter that produces compact,
human-readable output by selectively folding small arrays and objects.


## Installation

```sh
cpanm JSON::JSONFold
```

## Example

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

}

sub bytes_in  { $_[0]{bytes_in}  }
sub bytes_out { $_[0]{bytes_out} }
sub lines_in  { $_[0]{lines_in}  }
sub lines_out { $_[0]{lines_out} }

sub as_hash { return %{ $_[0] } }

# -------------------------------------------------------------------------
# Internal package: streaming folding filter/writer
# -------------------------------------------------------------------------

package JSON::JSONFold::Writer;
use strict;
use warnings;

BEGIN {
    JSON::JSONFold::Line->import() ;
    JSON::JSONFold::Frame->import() ;
    JSON::JSONFold::Config->import() ;

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

sub _add_to_frame {
    my ($self, $frame, $line) = @_;

    if (!$frame->is_empty) {
        return if $line->[L_CAN_PACK] && $self->_try_pack($frame, $line);
        return if $line->[L_CAN_JOIN] && $self->_try_join($frame, $line);

        # If frame is empty, may be it's in "streaming" mode, which
        # mean that lines that can not be packed/joined can be sent
        # directly to the output:
    } elsif (!$frame->[F_FOLD_OK] && !$line->[L_CAN_PACK] && !$line->[L_CAN_JOIN]) {
        $self->_write_line($line);
        return;
    }

    push @{ $frame->[F_LINES] }, $line;

    if ( $frame->[F_FOLD_OK] && $line->width > $self->[W_CFG][C_WIDTH] ) {

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

=item *

A functional API.

=item *

An object-oriented formatter.

=item *

A streaming post-processor.

=item *

A drop-in replacement for C<encode_json> and C<to_json>.

=back

=head1 EXPORTED FUNCTIONS

The following functions are exported by default:

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

    my $text = $fmt->encode($data);

Alias for C<format>, provided for compatibility with JSON-style APIs.

=head1 STREAMING INTERFACE

=head2 create_formatter

    my $formatter = create_formatter($fh, $width, $config, %overrides);

Creates a streaming formatter around an existing filehandle.

The C<$config> parameter may be a preset name or a
L<JSON::JSONFold::Config> object.


The returned object accepts pretty-printed JSON text incrementally and writes
folded JSON to C<$fh>. This allows JSONFold to be used as a streaming
post-processor without buffering the entire document in memory.

    my $formatter = create_formatter(\*STDOUT, 100, 'default');

    $formatter->write("{\n");
    $formatter->write(qq(  "name": "Alice"\n));
    $formatter->write("}\n");

    $formatter->finish;
    $formatter->flush;

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

The returned object is a L<JSON::JSONFold::Writer> and supports:

    write($text)
    finish()
    flush()
    close()
    stats()

Normally, users should prefer C<format_json>, C<write_json>, or the object
interface. C<create_formatter> is intended for advanced use cases and
integration with existing serializers and streaming APIs.

=head1 JSON-COMPATIBLE FUNCTIONS

=head2 encode_json

This function may be used as a drop-in replacement for C<JSON::encode_json>.
The optional second argument controls JSONFold formatting.

    my $text = encode_json($data);

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

package JSON::JSONFold::Writer;

1;

__END__

=head1 NAME

JSON::JSONFold::Writer - streaming formatter for JSON::JSONFold

=head1 SYNOPSIS

    use JSON::JSONFold;

    my $formatter = create_formatter(
        \*STDOUT,
        100,
        'default'
    );

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

    $formatter->write("}\n");

    $formatter->finish;
    $formatter->flush;

=head1 DESCRIPTION

C<JSON::JSONFold::Writer> incrementally processes pretty-printed JSON text and
writes a folded representation to an underlying filehandle.

This allows JSONFold to be used as a streaming post-processor without
buffering the entire document in memory.

Normally users should prefer the higher-level interfaces in
L<JSON::JSONFold>, such as C<format_json>, C<write_json>, or the object
interface.

=head1 CONSTRUCTOR

=head2 new

    my $formatter = JSON::JSONFold::Writer->new(
        $fh,
        $config,
        $close_fp
    );

Creates a streaming formatter around an existing filehandle.

Parameters:

=over

=item * C<$fh>

Destination filehandle.

=item * C<$config>