NAME

PerlHash - Encapsulate a perl HASH in JavaScript space

Perl HASH references are seen in javascript as PerlHash instances.

JAVASCRIPT INTERFACE

When a perl HASH enters javascript you'll get an instance of PerlHash. These objects will behave just like common javascript objects.

For example, you can use them in for...in or for each...in javascript statements or access its properties with hash.foo or hash['foo'] expressions.

These objects have two important characteristics:

• They are connected to their perl counterpart. Changes to this objects will be observable on the original perl HASH. If the hash has perl magic, for example if it is tied, any access from javascript to the hash will invoke the associated magic in perl.

  For example you can expose the program arguments to javascript:

      $ctx->bind_value(Env => \%ENV); 

• Every perl HASH has a single javascript PerlHash instance. No matter how the perl HASH enters javascript: passed as an argument to a javascript function, returned by a subroutine, binded from perl to a global object property, etc.... No matter how many times the same perl HASH enters javascript. It will always get the same (== and ===-wise) PerlHash instance.

Constructor

    phash = new PerlHash(...);

You can create new perl HASHes in javascript.

The arguments, if any, are taken as KEY/VALUE pairs to populate the HASH.

    var ahash = new PerlHash('foo', 1, 'bar', 'hi');

When those objects land in perl space they will be normal (without any "magic") perl HASHes, nobody can distinguish its origin.

Common javascript objects will be seen in perl as HASHes too, but can be perl code that needs a HASH without any magic. To convert a javascript object to a PerlHash you can use something like:

    function Object2PH(obj) {
        // A simple "one level deep copy"
        var ph = new PerlHash();
        for(var key in obj) {
            ph[key] = obj[key];
        }
        return ph;
    }

    perl_func_that_need_a_real_hash_ref(
        Object2PH( {foo: 1, bar: 'hi'} )
    );

Properties

Every key in the associated perl HASH becomes an own property in the PerlHash. As you can expect, the value of the property is the value of that key in the perl HASH.

When you add a new property, you are adding a new key => value pair to the associated perl HASH.

When you delete a property, you are deleting it from the perl HASH.

Methods

If the perl HASH has a subroutine reference stored in some key, it will be called if the corresponding property is used as a method call. Instances of PerlHash originally don't have any methods by themselves.

PerlHash instances inherit the following methods from PerlHash.prototype:

toSource ( )

Returns a string that when evaluated recreated the PerlHash.

    // Assuming 'ahash' is defined above
    say(ahash.toSource()); // prints "new PerlHash('foo',1,'bar','hi')"

As with all javascript objects you can change its constructor's prototype object (PerlHash.prototype) to make changes to all PerlHash instances.

PERL INTERFACE

PACKAGE VARIABLES

$construct_blessed

When you set the variable $JSPL::PerlHash::construct_blessed to a TRUE value, you are turning on the Claes's JavaScript compatibility mode. This affects the behavior of the javascript PerlHash constructor.

This feature can be removed at any time. I strongly recommend against using it. Read "Migrating from JavaScript.txt" for the details.