NAME
JE::Object - Base class for all JavaScript objects
SYNOPSIS
use JE;
use JE::Object;
$j = new JE;
$obj = new JE::Object $j,
property1 => $obj1,
property2 => $obj2;
$obj->prop('property1'); # returns $obj1;
$obj->prop('property1', $new_value); # sets the property
$obj->props; # returns a list of the names of enumerable property
$obj->delete('property_name');
$obj->method('method_name', 'arg1', 'arg2');
# calls a method with the given arguments
$obj->value ; # returns a value useful in Perl (a hashref)
"$obj"; # "[object Object]"
# same as $obj->to_string->value
DESCRIPTION
This module implements JavaScript objects for JE. It serves as a base class for all other JavaScript objects.
A JavaScript object is an associative array, the elements of which are its properties. A method is a property that happens to be an instance of the Function
class (JE::Object::Function
).
This class overrides the stringification operator by calling $obj->method('toString')
. The %{}
(hashref) operator is also overloaded and returns a hash of enumerable properties.
See also JE::Types for descriptions of most of the methods. Only what is specific to JE::Object is explained here.
METHODS
- $obj = JE::Object->new( $global_obj, LIST )
-
This class method constructs and returns a new object. LIST is a hash-style list of keys and values. If the values are not blessed references, they will be upgraded. (See "'UPGRADING VALUES'" in JE::Types.)
- $obj->typeof
-
This returns the string 'object'.
- $obj->class
-
Returns the string 'Object'.
- $obj->value
-
This returns a hash ref of the object's enumerable properties.
- Class->new_constructor( $global, \&function, \&prototype_init );
-
Warning: This method is still subject to change.
You should not call this method--or read its description--unless you are subclassing JE::Object.
This class method creates and returns a constructor function (JE::Object::Function object), which when its
construct
method is invoked, callnew
in the package through whichnew_constructor
is invoked, using the same arguments, but with the package name prepended to the argument list (as though<package name>->new
had been called.\&function
, if present, will be the subroutine called when the constructor function is called as a regular function (i.e., withoutnew
in JavaScript; using thecall
method from Perl). If this is omitted, the function will simply return undefined.\&prototype_init
(prototype initialiser), if present, will be called by thenew_constructor
with a prototype object as its only argument. It is expected to add the default properties to the prototype (except for theconstructor
property, which will be there already), and to bless the it into the appropriate Perl class, if necessary (it will be a JE::Object by default).For both coderefs, the scope will be passed as the first argument.
Here is an example of how you might set up the constructor function and add methods to the prototype:
package MyObject; require JE::Object; our @ISA = 'JE::Object'; sub new_constructor { shift->SUPER::new_constructor(shift, sub { __PACKAGE__->new(@_); }, sub { my $proto = shift; my $global = $$proto->{global}; $proto->prop({ name => 'toString', value => JE::Object::Function->new({ scope => $global, name => 'toString', length => 1, function_args => ['this'], function => sub { # ... } }), dontenum => 1, }); # ... # put other properties here }, ); }
And then you can add it to a global object like this:
$j->prop({ name => 'MyObject', value => MyObject->new_constructor, readonly => 1, dontenum => 1, dontdel => 1, });
You can, of course, create your own constructor function with
new JE::Object::Function
ifnew_constructor
does not do what you want.To do: Make this exportable, for classes that don't feel like inheriting from JE::Object (maybe this is not necessary, since one can say
__PACKAGE__->JE::Object::new_constructor
).
INNARDS
Each JE::Object
instance is a blessed reference to a hash ref. The contents of the hash are as follows:
$$self->{global} a reference to the global object
$$self->{props} a hash ref of properties, the values being
JavaScript objects
$$self->{prop_readonly} a hash ref with property names for the keys
and booleans (that indicate whether prop-
erties are read-only) for the values
$$self->{prop_dontdel} a hash ref in the same format as
prop_readonly that indicates whether proper-
ties are undeletable
$$self->{keys} an array of the names of enumerable
properties
$$self->{prototype} a reference to this object's prototype
In derived classes, if you need to store extra information, begin the hash keys with an underscore or use at least one capital letter in each key. Such keys will never be used by the classes that come with the JE distribution.