/ 
JSON-JSONFold-0.1.7
/ JSON::JSONFold

NAME

JSON::JSONFold - compact, readable JSON formatting

SYNOPSIS

use JSON::JSONFold;

# Functional interface

my $text = format_json($data, 100, 'default');

write_json($data, \*STDOUT, 100, 'default');

my $folded = fold_text($pretty_json, 100, 'default');

# Object interface

my $fmt = JSON::JSONFold->new(
    width  => 100,
    config => 'default',
);

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

# JSON-compatible interface

my $text = encode_json($data, {
    width   => 100,
    compact => 'default',
});

# Streaming interface

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

$formatter->write($text);
$formatter->finish;

DESCRIPTION

JSON::JSONFold formats JSON using a regular pretty-printer and then folds the output into a more compact layout.

It is intended to preserve readability while reducing unnecessary vertical space in arrays, objects, and simple nested structures.

JSONFold may be used as:

  • A functional API.

  • An object-oriented formatter.

  • A streaming post-processor.

  • A drop-in replacement for encode_json and to_json.

EXPORTED FUNCTIONS

The following functions are exported by default:

format_json
write_json
fold_text
encode_json
to_json

The following functions are exported on request:

jsonfold_config
create_formatter

FUNCTIONAL INTERFACE

jsonfold_config

my $config = jsonfold_config($preset, $width, %overrides);

Creates a JSONFold configuration object.

$preset may be a preset name or an existing configuration object. Additional named arguments override individual configuration settings.

format_json

my $text = format_json($data, $width, $config, %overrides);

Formats a Perl data structure as folded JSON and returns the resulting text.

write_json

my $stats = write_json($data, $fh, $width, $config, %overrides);

Formats a Perl data structure and writes the folded JSON to $fh.

Returns formatting statistics.

fold_text

my $text = fold_text($pretty_json, $width, $config);

Folds existing pretty-printed JSON text and returns the folded result.

OBJECT INTERFACE

new

my $fmt = JSON::JSONFold->new(
    width     => 100,
    config    => 'default',
    indent    => 2,
    sort_keys => 1,
);

Creates a formatter object.

Recognized options include:

width
    Target line width.

config
    Preset name or configuration object.

indent
    Pretty-print indentation width.

sort_keys
    Sort object keys before formatting.

gold
    Use JSONFold reference formatting (indent=2, space_before=0, space_after=1). default = true

json
    Custom JSON encoder object.

do_close
    Close the underlying filehandle when writing finishes.

If json is not supplied, a default pretty-printing JSON encoder is created.

format

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

Formats a Perl data structure and returns folded JSON text.

fold

my $text = $fmt->fold($pretty_json);

Folds existing pretty-printed JSON text.

write

my $stats = $fmt->write($data, $fh);

Formats a Perl data structure and writes the result to $fh.

Returns formatting statistics.

encode

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

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

STREAMING INTERFACE

create_formatter

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

Creates a streaming formatter around an existing filehandle.

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

The returned object accepts pretty-printed JSON text incrementally and writes folded JSON to $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;

The returned object is a JSON::JSONFold::Writer and supports:

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

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

JSON-COMPATIBLE FUNCTIONS

encode_json

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

my $text = encode_json($data);

my $text = encode_json($data, {
    width   => 100,
    compact => 'default',
});

Encodes $data as folded JSON.

When called without a second argument, encode_json is compatible with JSON::encode_json and uses the default JSONFold settings.

The optional second argument is a hash reference containing JSONFold options.

JSONFold-specific options:

  • width

    Target output width.

  • compact

    Preset name or configuration object.

to_json

This function may be used as a drop-in replacement for JSON::to_json. The optional second argument controls JSONFold formatting. It will ignore other legacy JSON options (canonical, etc).

my $text = to_json($data);

my $text = to_json($data, {
    canonical => 1,
    pretty    => 1,
});

my $text = to_json($data, {
    width     => 100,
    compact   => 'high',
    canonical => 1,
});

Compatibility wrapper similar to JSON::to_json.

When called without a second argument, to_json behaves like JSON::to_json followed by JSONFold formatting using the default settings.

The optional hash reference may contain both JSON options and JSONFold options. JSONFold-specific options are removed before the remaining options are forwarded to JSON::to_json.

JSONFold-specific options:

  • width

    Target output width.

  • compact

    Preset name or configuration object.

SEE ALSO

JSON, JSON::PP, JSON::JSONFold::Config, JSON::JSONFold::Writer

AUTHOR

Yair Lenga

COPYRIGHT AND LICENSE

See the distribution license.