JSON export/import in generate-bindings.pl

Source/bindings/scripts/JSONSerializer.pm

+# Copyright (C) 2013 Google Inc. All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+# Library to convert the Perl Intermediate Representation (IR) of IDLs

[dominicc (has gone to gerrit), 2013/06/12 04:39:33]

"Perl Intermediate Representation (IR)" could be better.

Abstractly, there is one intermediate representation of IDLs. And that is being
realized in Perl objects or JSON. The Perl objects and the JSON should be
isomorphic; there isn't a "Perl IR" and a "JSON IR."

The other thing I don't like about using "intermediate representation" so much
is that the JSON data are themselves intermediate between the Perl and Python.
It is vaguely confusing.

I would write this:

# Converts the intermediate representation of IDLs between Perl objects
# and JSON.

Your two points about why are nice context--work them in.

Once you have a high-level comment like this I think the file can use "IR" less.

For that matter, this isn't really a generic JSON serializer. Maybe this package
should be called "IDLSerializer." That way you can have something with a
parallel name on the Python side to give readers a clue how the pieces fit
together.

[Nils Barth (inactive), 2013/06/12 09:15:27]

Rewritten, and renamed to remove redundant "IR" throughout.

Yeah, "IR" got a bit tedious; it's really just changing representation
(serialization/deserialization of a single data structure).
The "decoded JSON" (back to Perl hashes, before rebuilding the Perl objects) is
in a messy half-way state, so hard to give a good name (hence earlier "raw IR").
Renamed.
Yeah, it's properly "Serialize/Deserialize Perl IR of IDLs to/from JSON";
IDLSerializer seems clear enough.

+# to and from JSON, for:
+# 1. Modularity between frontend parser and backend code generator;
+# 2. Porting to Python, so can connect Perl scripts and Python scripts.
+
+package JSONSerializer;
+
+use strict;
+use warnings;
+
+require Exporter;
+use vars qw(@ISA @EXPORT);
+@ISA = qw(Exporter);
+@EXPORT = qw(serializeJSON deserializeJSON);

[haraken, 2013/06/12 04:46:31]

Do you need these exports?

[Nils Barth (inactive), 2013/06/12 09:15:27]

If it's a package, yes.
I've removed "package" and thus exports for brevity.

+
+use Class::Struct;
+use JSON -convert_blessed_universally;  # IR contains objects (blessed references)
+
+
+sub serializeJSON
+{
+    my $document = shift;
+    my $json = JSON->new->utf8;
+    # JSON.pm defaults to barfing on objects (blessed references) and returning keys in indeterminate order; set options to change this:

[dominicc (has gone to gerrit), 2013/06/12 04:39:33]

Be consistent--you don't wrap here but do on line 57

[Nils Barth (inactive), 2013/06/12 09:15:27]

Done.
(Consistently wrap multi-line.)

+    # allow_blessed: don't barf when encounter blessed (but default to return null)
+    # convert_blessed: convert blessed reference as if unblessed (rather than returning null)
+    # canonical: sort keys when writing JSON, so JSON always in same order,
+    #            so can compare output between runs or between Perl and Python

[haraken, 2013/06/12 04:46:31]

Regarding comments here and there, please use more formal English for
readability.

e.g. By default JSON.pm outputs keys of blessed references in an indetermininate
order. We set options to change the default behavior.

(I don't know detailed syntax issues. You must be familiar with correct
English:-)

[Nils Barth (inactive), 2013/06/12 09:15:27]

(Reworded to change "barf" to "die", usual Perl term.)
?
I don't see anything especially casual here, other than "barf",
which is following the docs:
http://search.cpan.org/~makamaka/JSON-2.59/lib/JSON.pm#allow_blessed

Please always feel free to request clearer comments!
(I don't intentionally use slang or idioms, but your take is v. helpful in
finding out what's unclear.)

+    $json = $json->allow_blessed->convert_blessed->canonical();
+    return $json->encode($document);
+}
+
+sub deserializeJSON
+{
+    my $jsonText = shift;
+    my $json = JSON->new->utf8;
+    my $jsonIR = $json->decode($jsonText);
+    return jsonIRToPerlIR($jsonIR);

[dominicc (has gone to gerrit), 2013/06/12 04:39:33]

Maybe $json should be $jsonDecoder or something? Ditto for line 52--jsonEncoder.
This object is not JSON in any real sense.

[Nils Barth (inactive), 2013/06/12 09:15:27]

I'm following usage in docs, which calls this object $json.
We could call it $jsonEncoderDecoder, though that's a bit long.
http://search.cpan.org/~makamaka/JSON-2.59/lib/JSON.pm#SYNOPSIS

+}
+
+sub jsonIRToPerlIR
+{
+    my $jsonIR = shift;
+    if (ref $jsonIR eq "ARRAY") {
+        my $perlIR = [];
+        foreach my $element (@$jsonIR) {
+            push(@$perlIR, jsonIRToPerlIR($element));
+        }
+        return $perlIR;
+    }
+    if (ref $jsonIR eq "HASH") {
+        if (!scalar %{$jsonIR}) {

[haraken, 2013/06/12 04:46:31]

my @keys = keys %$jsonIR;
return {} if @keys == 0;

[Nils Barth (inactive), 2013/06/12 09:15:27]

(>.<) Good point (changed here and below).

+            return {};
+        }
+        # Detect objects as hashes where all keys are of form CLASS::KEY
+        # One exception: overloadedIndex is not part of domFunction struct,
+        # (just a hash key, not an object member), so need to special case
+        my $firstKey = (keys %{$jsonIR})[0];

[haraken, 2013/06/12 04:46:31]

$keys[0]

[Nils Barth (inactive), 2013/06/12 09:15:27]

Done.

+        $firstKey = (keys %{$jsonIR})[1] if $firstKey eq "overloadedIndex";

[dominicc (has gone to gerrit), 2013/06/12 04:39:33]

Suggestion: Make a method to get the class name for a hash. Return false for
non-objects. This will make the intent clearer, the surrounding code clearer,
and may let you write a shorter comment.

[haraken, 2013/06/12 04:46:31]

$keys[1]

[Nils Barth (inactive), 2013/06/12 09:15:27]

Done.

+        my $isObject = $firstKey =~ /::/;

[dominicc (has gone to gerrit), 2013/06/12 04:39:33]

Nice use of explaining variable.

[Nils Barth (inactive), 2013/06/12 09:15:27]

Thanks!

+
+        if ($isObject) {
+            my $class = (split('::', $firstKey))[0];
+            return jsonHashToPerlObject($jsonIR, $class);
+        } else {  # just hash
+            my $hashRef = {};
+            foreach my $key (keys %{$jsonIR}) {

[haraken, 2013/06/12 04:46:31]

foreach my $key (@keys)

[Nils Barth (inactive), 2013/06/12 09:15:27]

Done.

+                $hashRef->{$key} = jsonIRToPerlIR($jsonIR->{$key});
+            }
+            return $hashRef;
+        }
+    }
+    die "Unexpected reference type: " . ref $jsonIR . "\n" if ref $jsonIR;
+    return $jsonIR;
+}
+
+sub jsonHashToPerlObject
+{
+    # JSON.pm serializes hash objects of class CLASS as a hash with keys CLASS::KEY1, CLASS::KEY2, etc.
+    # When deserializing, need to rebuild objects by stripping prefix and calling the constructor
+    my $jsonHash = shift;
+    my $class = shift;
+
+    my %keysValues = ();
+    foreach my $classAndKey (keys %{$jsonHash}) {
+        next if $classAndKey eq "overloadedIndex";
+        my $key = (split('::', $classAndKey))[1];
+        $keysValues{$key} = jsonIRToPerlIR($jsonHash->{$classAndKey});
+    }
+    my $object = $class->new(%keysValues);  # Build object
+    # overloadedIndex not part of constructor; add separately
+    $object->{overloadedIndex} = $jsonHash->{overloadedIndex} if exists $jsonHash->{overloadedIndex};
+    return $object;
+}
+
+1;