gitpan / json-maybexs Goto Github PK

NAME
    JSON::MaybeXS - Use Cpanel::JSON::XS with a fallback to JSON::XS and
    JSON::PP

SYNOPSIS
      use JSON::MaybeXS;

      my $data_structure = decode_json($json_input);

      my $json_output = encode_json($data_structure);

      my $json = JSON->new;

      my $json_with_args = JSON::MaybeXS->new(utf8 => 1); # or { utf8 => 1 }

DESCRIPTION
    This module first checks to see if either Cpanel::JSON::XS or JSON::XS
    is already loaded, in which case it uses that module. Otherwise it tries
    to load Cpanel::JSON::XS, then JSON::XS, then JSON::PP in order, and
    either uses the first module it finds or throws an error.

    It then exports the "encode_json" and "decode_json" functions from the
    loaded module, along with a "JSON" constant that returns the class name
    for calling "new" on.

    If you're writing fresh code rather than replacing JSON.pm usage, you
    might want to pass options as constructor args rather than calling
    mutators, so we provide our own "new" method that supports that.

EXPORTS
    "encode_json", "decode_json" and "JSON" are exported by default;
    "is_bool" is exported on request.

    To import only some symbols, specify them on the "use" line:

      use JSON::MaybeXS qw(encode_json decode_json is_bool); # functions only

      use JSON::MaybeXS qw(JSON); # JSON constant only

    To import all available sensible symbols ("encode_json", "decode_json",
    and "is_bool"), use ":all":

      use JSON::MaybeXS ':all';

    To import all symbols including those needed by legacy apps that use
    JSON::PP:

      use JSON::MaybeXS ':legacy';

    This imports the "to_json" and "from_json" symbols as well as everything
    in ":all". NOTE: This is to support legacy code that makes extensive use
    of "to_json" and "from_json" which you are not yet in a position to
    refactor. DO NOT use this import tag in new code, in order to avoid the
    crawling horrors of getting UTF8 support subtly wrong. See the
    documentation for JSON for further details.

  encode_json
    This is the "encode_json" function provided by the selected
    implementation module, and takes a perl data structure which is
    serialised to JSON text.

      my $json_text = encode_json($data_structure);

  decode_json
    This is the "decode_json" function provided by the selected
    implementation module, and takes a string of JSON text to deserialise to
    a perl data structure.

      my $data_structure = decode_json($json_text);

  to_json, from_json
    See JSON for details. These are included to support legacy code only.

  JSON
    The "JSON" constant returns the selected implementation module's name
    for use as a class name - so:

      my $json_obj = JSON->new; # returns a Cpanel::JSON::XS or JSON::PP object

    and that object can then be used normally:

      my $data_structure = $json_obj->decode($json_text); # etc.

  is_bool
      $is_boolean = is_bool($scalar)

    Returns true if the passed scalar represents either "true" or "false",
    two constants that act like 1 and 0, respectively and are used to
    represent JSON "true" and "false" values in Perl.

    Since this is a bare sub in the various backend classes, it cannot be
    called as a class method like the other interfaces; it must be called as
    a function, with no invocant. It supports the representation used in all
    JSON backends.

CONSTRUCTOR
  new
    With JSON::PP, JSON::XS and Cpanel::JSON::XS you are required to call
    mutators to set options, such as:

      my $json = $class->new->utf8(1)->pretty(1);

    Since this is a trifle irritating and noticeably un-perlish, we also
    offer:

      my $json = JSON::MaybeXS->new(utf8 => 1, pretty => 1);

    which works equivalently to the above (and in the usual tradition will
    accept a hashref instead of a hash, should you so desire).

BOOLEANS
    To include JSON-aware booleans ("true", "false") in your data, just do:

        use JSON::MaybeXS;
        my $true = JSON->true;
        my $false = JSON->false;

AUTHOR
    mst - Matt S. Trout (cpan:MSTROUT) <[email protected]>

CONTRIBUTORS
    *   Clinton Gormley <[email protected]>

    *   Karen Etheridge <[email protected]>

    *   Kieren Diment <[email protected]>

COPYRIGHT
    Copyright (c) 2013 the "JSON::MaybeXS" "AUTHOR" and "CONTRIBUTORS" as
    listed above.

LICENSE
    This library is free software and may be distributed under the same
    terms as perl itself.