=head1 NAME

PerlHash - Encapsulate a perl HASH in JavaScript space

Perl HASH references are seen in javascript as C<PerlHash> instances. 

=head1 JAVASCRIPT INTERFACE

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

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

These objects have two important characteristics:

=over 4

=item *

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 C<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); 


=item *

Every perl HASH has a single javascript C<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 I<same> (C<==> and C<===>-wise) C<PerlHash> instance.

=back


=head2 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 I<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'} )
    );

=head2 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 C<< key => value >> pair to the
associated perl HASH.

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

=head2 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
C<PerlHash> originally don't have any methods by themselves. 

C<PerlHash> instances inherit the following methods from C<PerlHash.prototype>:

=over 4

=item 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')"

=back

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

=head1 PERL INTERFACE

=head2 PACKAGE VARIABLES

=over 4

=item $construct_blessed

When you set the variable I<$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 C<PerlHash> constructor.

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

=back