NAME

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

STATUS

SYNOPSIS

      use JSON::Slurper qw(slurp_json spurt_json);
    
      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');
    
      # ".json" is added ad the file extension if no file extension is present.
      # This saves to people.json
      spurt_json @people, 'people';
    
      # This reads from people.json
      my @people_from_file = slurp_json 'people';

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. You
    can also pass along extra options to "read_text" in File::Slurper and
    "write_text" in File::Slurper, which are the two methods used by this
    module to read and write JSON.

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

 slurp_json

    slurp_json [$json_encoder], $filename, [@args for
    File::Slurper::read_text]

      # 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 JSON::PP->new->ascii->pretty, 'ref.json';
    
      # You can pass options to File::Slurper::read_text
      my $ref = slurp_json 'ref.json', $encoding, $crlf;
    
      # If no extension is provided, ".json" will be used.
      # Reads from "ref.json";
      my $ref = slurp_json 'ref';

    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 first argument, as long as it is blessed
    and has encode and decode methods. You may also pass extra arguments at
    the end that will be passed on to "read_text" in File::Slurper. By
    default, no additional arguments are passed to "read_text" in
    File::Slurper. If no extension is present on the filename, .ext will be
    added.

 spurt_json

    spurt_json [$json_encoder], $data, $filename, [@args for
    File::Slurper::write_text]

      # values can be passed as refs
      spurt_json \@array, 'ref.json';
    
      # or as an array or hash (still passed as refs using prototypes)
      spurt_json @array, 'array.json';
    
      spurt_json %hash, 'hash.json';
    
      # You can pass your own JSON encoder
      spurt_json JSON::PP->new->ascii->pretty, $ref, 'ref.json';
    
      # You can pass options to File::Slurper::write_text
      spurt_json $ref, 'ref.json', $encoding, $crlf;
    
      # If no extension is provided, ".json" will be used.
      # Writes to "ref.json";
      spurt_json $ref, 'ref';

    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 first argument, as long as it is blessed
    and has encode and decode methods. You may also pass extra arguments at
    the end that will be passed on to "write_text" in File::Slurper. By
    default, no additional arguments are passed to "write_text" in
    File::Slurper. If no extension is present on the filename, .ext will be
    added.

OBJECT-ORIENTED INTERFACE

 new

      my $json_slurper = JSON::Slurper->new;
    
      # or pass in your own JSON encoder/decoder
      my $json_slurper = JSON::Slurper->new(JSON::PP->new->ascii->pretty);

    "new" creates a JSON::Slurper object that allows you to use the
    "OBJECT-ORIENTED INTERFACE" and call "slurp" and "spurt". You may pass
    in your own JSON encoder/decoder as long as it has encode and decode
    methods, like JSON::PP or Cpanel::JSON::XS, and this encoder will be
    used instead of the default one when calling "slurp" and "spurt".

 slurp

    slurp($filename, [@args for File::Slurper::read_text])

      # 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');
    
      # You can pass options to File::Slurper::read_text
      my $ref = $json_slurper->slurp('ref.json', $encoding, $crlf);
    
      # If no extension is provided, ".json" will be used.
      # Reads from "ref.json";
      my $ref = $json_slurper->slurp('ref');

    This reads in JSON from a file and returns it as a Perl data structure
    (a reference, an array, or a hash). You may pass extra arguments at the
    end that will be passed on to "read_text" in File::Slurper. By default,
    no additional arguments are passed to "read_text" in File::Slurper. If
    no extension is present on the filename, .ext will be added.

 spurt

    spurt($data, $filename, [@args for File::Slurper::write_text])

      $json_slurper->spurt(\@array, 'array.json');
    
      $json_slurper->spurt(\%hash, 'hash.json');
    
      # You can pass options to File::Slurper::write_text
      $json_slurper->spurt($ref, 'ref.json', $encoding, $crlf);
    
      # If no extension is provided, ".json" will be used.
      # Writes to "ref.json";
      $json_slurper->spurt($ref, 'ref');

    This reads in JSON from a file and returns it as a Perl data structure
    (a reference, an array, or a hash). You may pass extra arguments at the
    end that will be passed on to "write_text" in File::Slurper. By
    default, no additional arguments are passed to "write_text" in
    File::Slurper. If no extension is present on the filename, .ext will be
    added.

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

