NAME

Module::Generic::JSON - A thin and reliable wrapper around JSON

SYNOPSIS

            

              
              
use Module::Generic::JSON;
my $j = Module::Generic::JSON->new(
    utf8         => 1,
    pretty       => 1,
    canonical    => 1,
    relaxed      => 1,
    allow_nonref => 1,
) || die( Module::Generic::JSON->error );
$j->encode( $some_ref ) || die( $j->error );
            
          

Or

            

              
              
my $j = Module::Generic::JSON->new;
$j->utf8->pretty->canonical->relaxed->allow_nonref->encode( $some_ref ) ||
    die( $j->error );
            
          

Or, even simpler:

            

              
              
use Module::Generic::JSON qw( new_json );
my $j = new_json(
    utf8         => 1,
    pretty       => 1,
    canonical    => 1,
    relaxed      => 1,
    allow_nonref => 1,
) || die( Module::Generic::JSON->error );
$j->encode( $some_ref ) || die( $j->error );
            
          

VERSION

            

              
              
v0.1.0
            
          

DESCRIPTION

This is a thin and reliable wrapper around the otherwise excellent JSON class. Its added value is:

• Allow the setting of all the JSON properties upon object instantiation

  As mentioned in the synopsis, you can do:

  
              
  
                
                
  my $j = Module::Generic::JSON->new(
      utf8         => 1,
      pretty       => 1,
      canonical    => 1,
      relaxed      => 1,
      allow_nonref => 1,
  ) || die( Module::Generic::JSON->error );
              
            

  instead of:

  
              
  
                
                
  my $j = Module::Generic::JSON->new;
  $j = $j->utf8->pretty->canonical->relaxed->allow_nonref;
              
            

• No fatal exception that would kill your process inadvertently.

  This is important in a web application where you do not want some module killing your process, but rather you want the exception to be handled gracefully.

  Thus, instead of having to do:

  
              
  
                
                
  local $@;
  my $ref = eval{ $j->decode( $payload ) };
  if( $@ )
  {
      # Like returning a 500 or maybe 400 HTTP error
      bailout_gracefully( $@ );
  }
              
            

  you can simply do:

  
              
  
                
                
  my $ref = $j->decode( $payload ) || bailout_gracefully( $j->error );
              
            

• Upon error, it returns an exception object

• All methods calls are passed through to JSON, and any exception is caught, and handled properly for you.

For class functions too, you can execute them safely and catch error, if any, by calling Module::Generic::JSON->error, so for example:

            

              
              
decode_json( $some_data ) || die( Module::Generic::JSON->error );
            
          

CONSTRUCTOR

new

This takes an hash or an hash reference of options and it returns a new Module::Generic::JSON object.

The options provided must be supported by JSON.

Upon error, this sets an error object, and returns undef in scalar context, or an empty list in list context.

METHODS

See the documentation for the module JSON for more information, but below are the known methods supported by JSON

allow_blessed

allow_nonref

allow_tags

allow_unknown

ascii

backend

boolean

boolean_values

canonical

convert_blessed

decode

decode_prefix

encode

filter_json_object

filter_json_single_key_object

indent

is_pp

is_xs

latin1

max_depth

max_size

pretty

property

relaxed

space_after

space_before

utf8

CLASS FUNCTIONS

decode_json

encode_json

from_json

to_json

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

JSON, Module::Generic::Exception

COPYRIGHT & LICENSE

Copyright(c) 2025 DEGUEST Pte. Ltd.

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Module::Generic

perl -MCPAN -e shell
install Module::Generic