NAME

    JSON::Slurper - Convenient file slurping and spurting of data using
    JSON

STATUS

SYNOPSIS

      use JSON::Slurper qw(slurp_json spurt_json);
      # or
      use JSON::Slurper -std;
    
      my @people = (
        {
            name => 'Ralph',
            age => 19,
            favorite_food => 'Pizza',
        },
        {
            name => 'Sally',
            age => 23,
            favorite_food => 'French Fries',
        },
      );
    
      spurt_json \@people, 'people.json';
    
      my @people_from_file = slurp_json 'people.json';
    
      # or get as a reference
      my $people_from_file = slurp_json 'people.json';
    
      # Same as above with Object-Oriented interface
      my $json_slurper = JSON::Slurper->new;
    
      $json_slurper->spurt(\@people, 'people.json');
    
      my @people_from_file = $json_slurper->slurp('people.json');
    
      # or get as a reference
      my $people_from_file = $json_slurper->slurp('people.json');
    
      # use the -auto_ext flag so that ".json" is added as the
      # file extension if no file extension is present.
      use JSON::Slurper qw(-auto_ext slurp_json spurt_json);
      # or
      use JSON::Slurper -std_auto;
    
      # This saves to people.json
      spurt_json \@people, 'people';
    
      # This reads from people.json
      my @people_from_file = slurp_json 'people';
    
      # auto_ext can also be passed when using the object-oriented interface:
      my $json_slurper = JSON::Slurper->new(auto_ext => 1);
    
    
      # provide an encoder on import to use with spurt_json and slurp_json
      use JSON::Slurper -encoder => JSON::PP->new->pretty, qw(slurp_json spurt_json);
    
      # use encoder passed in above
      spurt_json \@people, 'people.json';
    
      my @people_from_file = slurp_json 'people.json';

DESCRIPTION

    JSON::Slurper is a convenient way to slurp/spurt (read/write) Perl data
    structures to and from JSON files. It tries to do what you mean, and
    allows you to provide your own JSON encoder/decoder if necessary.

DEFAULT ENCODER

    Both the "FUNCTIONAL INTERFACE" and the "OBJECT-ORIENTED INTERFACE" use
    the same default encoders. You can provide your own encoder whether you
    use the "FUNCTIONAL INTERFACE" or the "OBJECT-ORIENTED INTERFACE".

 Cpanel::JSON::XS

    If you have the recommended Cpanel::JSON::XS installed, this is the
    default used:

      Cpanel::JSON::XS->new
                      ->utf8
                      ->pretty
                      ->canonical
                      ->allow_nonref
                      ->allow_blessed
                      ->convert_blessed
                      ->escape_slash
                      ->stringify_infnan

 JSON::PP

    If you are using JSON::PP, this is the default used:

      JSON::PP->new
              ->utf8
              ->pretty
              ->canonical
              ->allow_nonref
              ->allow_blessed
              ->convert_blessed
              ->escape_slash

FUNCTIONAL INTERFACE

 -auto_ext

    Passing the -auto_ext flag with the imports causes .json to be added to
    filenames when they have no extension.

      use JSON::Slurper qw(-auto_ext slurp_json spurt_json);
    
      # or
    
      use JSON::Slurper -std_auto;
    
      # Reads from "ref.json";
      my $ref = slurp_json 'ref';
    
      # If no extension is provided, ".json" will be used.
      # Writes to "ref.json";
      spurt_json $ref, 'ref';
    
      # If an extension is present, ".json" will not be added.
      # Writes to "ref.txt";
      spurt_json $ref, 'ref.txt';

 -encoder

    You can use -encoder at import time to pass the encoder that will be
    used with "slurp_json" and "spurt_json". If you provide an encoder to
    the function call, it will override any encoder passed in at import
    time.

      use JSON::Slurper -encoder => JSON::PP->new->pretty, 'spurt_json';
    
      # uses encoder passed in above
      spurt_json \@people, 'people.json';
    
      # use the encoder passed in below to spurt_json instead of the one passed in on import
      spurt_json \@people, 'people.json', JSON::PP->new->ascii;

 slurp_json

    slurp_json $filename, [$json_encoder]

      # values can be returned as refs
      my $ref = slurp_json 'ref.json';
    
      # or as an array or hash
      my @array = slurp_json 'array.json';
    
      my %hash = slurp_json 'hash.json';
    
      # You can pass your own JSON encoder
      my $ref = slurp_json 'ref.json', JSON::PP->new->ascii->pretty;

    This reads in JSON from a file and returns it as a Perl data structure
    (a reference, an array, or a hash). You can pass in your own JSON
    encoder/decoder as an optional argument, as long as it is blessed and
    has encode and decode methods. Any encoder passed in will override an
    encoder provided during import via "-encoder".

 spurt_json

    spurt_json $data, $filename, [$json_encoder]

      # data must be passed as references or scalars
      spurt_json \@array, 'ref.json';
    
      spurt_json 'string', 'ref.json';
    
      # pass anonymous array or hash refs
      spurt_json [1, 2, 3], 'ref.json';
    
      spurt_json {key => 'value'}, 'ref.json';
    
      # You can pass your own JSON encoder
      spurt_json $ref, 'ref.json', JSON::PP->new->ascii->pretty;

    This reads in JSON from a file and returns it as a Perl data structure
    (a reference, an array, or a hash). You can pass in your own JSON
    encoder/decoder as an optional argument, as long as it is blessed and
    has encode and decode methods. Any encoder passed in will override an
    encoder provided during import via "-encoder".

 Export Tags

  -std

    This tag is the same as explicitly importing "slurp_json" and
    "spurt_json":

      use JSON::Slurper -std;
    
      # same as
    
      use JSON::Slurper qw(slurp_json spurt_json);

  -std_auto

    This tag is the same as explicitly importing "slurp_json" and
    "spurt_json" and including the "-auto_ext" flag:

      use JSON::Slurper -std_auto;
    
      # same as
    
      use JSON::Slurper qw(-auto_ext slurp_json spurt_json);

  -slurp_auto

    This tag is the same as explicitly importing "slurp_json" and including
    the "-auto_ext" flag:

      use JSON::Slurper -slurp_auto;
    
      # same as
    
      use JSON::Slurper qw(-auto_ext slurp_json);

  -spurt_auto

    This tag is the same as explicitly importing "spurt_json" and including
    the "-auto_ext" flag:

      use JSON::Slurper -spurt_auto;
    
      # same as
    
      use JSON::Slurper qw(-auto_ext spurt_json);

 Shiny Importing

    JSON::Slurper uses Exporter::Shiny for its exporting of subroutines.
    This allows for fancy importing, such as renaming imported subroutines:

      use JSON::Slurper
        'slurp_json' => { -as => 'slurp_plz' },
        'spurt_json' => { -as => 'spurt_plz' };
    
      spurt_plz $ref, 'ref.json';
      my $ref_from_file = slurp_plz 'ref.json';

    See Exporter::Tiny::Manual::Importing for much more.

OBJECT-ORIENTED INTERFACE

 new

      my $json_slurper = JSON::Slurper->new;
    
      # pass in your own JSON encoder/decoder
      my $json_slurper = JSON::Slurper->new(encoder => JSON::PP->new->ascii->pretty);
    
      # add ".json" to filenames that do not have an extension
      my $json_slurper = JSON::Slurper->new(auto_ext => 1);

    "new" creates a JSON::Slurper object that allows you to use the
    "OBJECT-ORIENTED INTERFACE" and call "slurp" and "spurt".

  encoder

    You may provide your own encoder instead of the "DEFAULT ENCODER" as
    long as it is blessed and has encode and decode methods, like JSON::PP
    or Cpanel::JSON::XS. This encoder will be used instead of the default
    one when calling "slurp" and "spurt".

      my $json_slurper = JSON::Slurper->new(encoder => JSON::PP->new->ascii->pretty);

  auto_ext

    Passing auto_ext with a true value causes .json to be added to
    filenames when they have no extension.

      my $json_slurper = JSON::Slurper->new(auto_ext => 1)
    
      # Reads from "ref.json";
      my $ref = $json_slurper->slurp('ref');
    
      # If no extension is provided, ".json" will be used.
      # Writes to "ref.json";
      $json_slurper->spurt($ref, 'ref');
    
      # If an extension is present, ".json" will not be added.
      # Writes to "ref.txt";
      $json_slurper->spurt($ref, 'ref.txt');

 slurp

    slurp($filename)

      # values can be returned as refs
      my $ref = $json_slurper->slurp('ref.json');
    
      # or as an array or hash
      my @array = $json_slurper->slurp('array.json');
    
      my %hash = $json_slurper->slurp('hash.json');

    This reads in JSON from a file and returns it as a Perl data structure
    (a reference, an array, or a hash).

 spurt

    spurt($data, $filename)

      $json_slurper->spurt(\@array, 'array.json');
    
      $json_slurper->spurt(\%hash, 'hash.json');

    This reads in JSON from a file and returns it as a Perl data structure
    (a reference, an array, or a hash).

TODO

    More testing required.

AUTHOR

    Adam Hopkins <srchulo@cpan.org>

COPYRIGHT

    Copyright 2019- Adam Hopkins

LICENSE

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

SEE ALSO

      * File::Slurper

      * JSON::PP

      * Cpanel::JSON::XS

      * Exporter::Tiny::Manual::Importing