NAME
JE::Object - Base class for all JavaScript objects
SYNOPSIS
use JE;
use JE::Object;
$j = new JE;
$obj = new JE::Object $j;
$obj->prop('property1', $new_value); # sets the property
$obj->prop('property1'); # returns $new_value;
$obj->keys; # 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 )
- $obj = JE::Object->new( $global_obj, $value )
- $obj = JE::Object->new( $global_obj, \%options )
-
This class method constructs and returns a new JavaScript object, unless
$value
is already a JS object, in which case it just returns it. The behaviour is the same as theObject
constructor in JavaScript.The <%options> are as follows:
prototype the object to be used as the prototype for this object (Object.prototype is the default) value the value to be turned into an object
prototype
only applies whenvalue
is omitted,undef
,undefined
ornull
.To convert a hash into an object, you can use the hash ref syntax like this:
new JE::Object $j, { value => \%hash }
Though it may be easier to write:
$j->upgrade(\%hash)
The former is what
upgrade
itself uses. - $j->new_function($name, sub { ... })
- $j->new_function(sub { ... })
-
This creates and returns a new function object. If $name is given, it will become a property of the object. As with built-in JS functions, the property will not be enumerable.
For more ways to create functions, see JE::Object::Function.
- $j->new_method($name, sub { ... })
- $j->new_method(sub { ... })
-
This is the same as
new_function
, except that the subroutine's first argument will be the object with which the function is called.For more ways to create functions, see JE::Object::Function.
- $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: I am going to delete this method since its interface is very convoluted and it is insufficient for too many cases. Just consider it a private method that you don't know about.
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.