Toby Inkster > JSON-JOM > JSON::JOM

Download:
JSON-JOM-0.501.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

New  1
Open  1
View/Report Bugs
Module Version: 0.501   Source  

NAME ^

JSON::JOM - the JSON Object Model

SYNOPSIS ^

 # from_json and to_json compatible with the JSON module
 # but build JSON::JOM::Object and JSON::JOM::Array objects
 use JSON::JOM qw[from_json to_json]; 
 my $object = from_json('{ ...some json... }');
 
 # JOM objects are blessed hashrefs and arrayrefs
 # So you can read from them like this...
 my $thingy = $object->{'foo'}{'bar'}[0]{'quux'};
 
 # But look at this:
 my $array = $thingy->parentNode->parentNode;
 print $array->nodePath;  # $['foo']['bar']

DESCRIPTION ^

JSON::JOM provides a DOM-like API for working with JSON.

While JSON represents JSON arrays as Perl arrayrefs and JSON objects as Perl hashrefs, JSON::JOM represents each as a blessed object.

Internally, JSON::JOM::Object and JSON::JOM::Array store their data as a hashref or arrayref, so you can still use this pattern of working:

  my $data = JSON::JOM::from_json(<<'JSON');
  {
    "foo": {
      "bar": [
        { "quux" : 0 },
        { "quux" : 1 },
        { "quux" : 2 },
      ]
    }
  }
  JSON
  
  foreach my $obj (@{ $data->{foo}{bar} })
  {
    printf("The quux of the matter is: %d\n", $obj->{quux})
  }

But all arrays and objects provide various methods to make working with them a bit easier. See JSON::JOM::Object and JSON::JOM::Array for descriptions of these methods.

Values that the JSON module would represent as a Perl scalar, are represented as a JSON::JOM::Value in JOM. This uses overload to act like a scalar.

Note that if you use the arrayref/hashref way of working, things are not always completely intuitive:

  $root  = to_jom({});
  $child = [ 1,2,3 ];
  
  # Add $child to our JOM structure:
  $root->{list} = $child;
  
  print $root->{list}->count . "\n";  # prints '3'
  
  # Now modify $child
  push @$child, 4;
  
  print $root->{list}->count . "\n";  # still '3'!

This is because the $child arrayref isn't just placed blindly into the JOM structure, but "imported" into it. Compare the above with:

  $root  = to_jom({});
  $child = [ 1,2,3 ];
  
  # Add $child to our JOM structure, and this time,
  # set $child to point to the imported list.
  $child = $root->{list} = $child;
  
  print $root->{list}->count . "\n";  # prints '3'
  
  # Now modify $child
  push @$child, 4;
  
  print $root->{list}->count . "\n";  # prints '4'

FUNCTIONS ^

This modules provides the following functions. None of them are exported by default.

  use JSON::JOM;              # export nothing
  use JSON::JOM ':standard';  # export first three
  use JSON::JOM ':all;        # export everything
  use JSON::JOM 'to_jom';     # export a particular function

from_json($string, \%options)

JSON parser compatible with JSON::from_json.

to_json($jom, \%options)

JSON serialiser mostly compatible with JSON::to_json.

to_jom($data)

Converts a Perl hashref/arrayref structure to its JOM equivalent.

BUGS ^

Please report any bugs to http://rt.cpan.org/.

SEE ALSO ^

The real guts of JOM are in JSON::JOM::Object, JSON::JOM::Array and JSON::JOM::Value.

JSON::JOM::Plugins.

JSON.

AUTHOR ^

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT ^

Copyright 2010-2011 Toby Inkster

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

DISCLAIMER OF WARRANTIES ^

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

syntax highlighting: