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 the Object 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 when value is omitted, undef, undefined or null.

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, call new in the package through which new_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., without new in JavaScript; using the call method from Perl). If this is omitted, the function will simply return undefined.

\&prototype_init (prototype initialiser), if present, will be called by the new_constructor with a prototype object as its only argument. It is expected to add the default properties to the prototype (except for the constructor 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 if new_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.

SEE ALSO

JE

JE::Types