NAME

JSPL::Object - Reference to a JavaScript Object

DESCRIPTION

Besides primitives everything else in JavaScript is an object. This class (or one of its subclasses) encapsulate a reference to them.

    $adate = $ctx->eval(' new Date() ');
    print ref $adate;                       # 'JSPL::Object'
    print $adate->toString;                 # Today date

SIMPLE INTERFACE

Objects in JavaScript resemble perl HASHes. By default and for transparency to unaware perl code, for the most simple JavaScript objects, you won't see the JSPL::Object instance wrapper. Instead the JSPL::Object instance will be converted, via "tie" in perlfunc, into perl HASHes and returned as HASH-references. So to access or modify the object properties you use the regular perl HASH operations and functions.

By "most simple" in the last paragraph we're referring to all those objects which its constructor is Object.

    ...
    $obj = $ctx->eval('v = { foo:4, bar:{}, baz:true }; v;');

    print $obj->{foo};      # 4
    print ref $obj->{bar};  # 'HASH'

    print keys %$obj;               # foo bar baz
    print exists $obj->{bar}{fob};  # FALSE

All those HASHes are alive, thats it, they refer to the original JavaScript object, so if you modify them on one side, you are modifying both sides.

    $obj->{bar}{fob} = 'hi';
    print $ctx->eval( 'say(v.bar.fob);' ); # 'hi'

    $ctx->eval( 'delete v.baz' );
    print keys %$obj;                # foo bar

But as the HASH is a plain perl one, you can't use it to call methods on $obj.

    $obj->toString(...);  # Throws an error.

You need to use:

    my $func = $obj->{toString};
    $func->call(...);              # $func isa JSPL::Function

The automatic conversion of JSPL::Object instances into HASH references can be controled per context, via the "AutoTie" in JSPL::Context option.

When AutoTie is TRUE, the default, and you obtained a HASH reference, but you need the underlaying JSPL::Object instance, you can get it using "tied" in perlfunc.

    my $jsobj = tied %$obj;
    print ref $jsobj;               # 'JSPL::Object'

In fact, tied is the only way to distinguish the HASH reference as a JSPL::Object.

INSTANCE METHODS

To avoid name clashes with the methods defined for an object in JavaScript, instances of JSPL::Object only define a minimum of methods, all in UPPERCASE, so any other method called will be proxied to the original JavaScript object.

FETCH ( PROP )

  my $value = $jsobj->FETCH('foo');

Get the property named PROP from the object.

Remember that by JavaScript rules, the value returned not necessarily is an own property of the object, it may come from the prototype chain. Also, if in JavaScript the object has any getter associated with that name, the getter will be called.

Because overloading, you don't need to call the FETCH method, you can just say $jsobj->{foo}.

STORE ( PROP, VALUE )

  $jsobj->STORE('baz', $value);

Set the property named PROP to VALUE in the object.

If the JavaScript object has any setter associated with that name, the setter will be called, as expected.

Because overloading, you don't need to call the STORE method, you can just say $jsobj->{baz} = $value;

DELETE ( PROP )

  $jsobj->DELETE('foo');

Delete the property named PROP from the object.

Because overloading, you can just say delete $jsobj->{foo}

EXISTS ( PROP )

  if($jsobj->EXISTS('foo')) { ... }

Returns a TRUE value if a property named PROP exists in object or, by JavaScript rules, in any object in the prototype chain of the object. Otherwise it returns FALSE.

Because overloading, you can just say if(exists $jsobj->{foo}) { ... }

Because the prototype based nature of JavaScript, if you need to known if the object contains the specified property as a direct property and not inherited through the prototype chain you must use the JavaScript function hasOwnProperty

    if( $jsobj->hasOwnProperty('foo') ) { ... }

CLASS_NAME

Returns the native class name of the object

HASH_REF

Returns a HASH reference, tied to the underlaying JSPL::Object.

The reference is cached, so every time you call HASH_REF, you obtain the same reference. This reference is the same used for the "SIMPLE INTERFACE" above and for "OVERLOADED OPERATIONS" below, so you seldom need to call this method.

foo ( ARGS )

    $jsobj->foo(@someargs);

Any other method foo results in a call to the object's method of the same name.

OVERLOADED OPERATIONS

Instances of this class overload the "%{}" operator, so when you use a JSPL::Object instance in a context that expect a HASH reference, the operation just work.