Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

JE::Object
Base class for all JavaScript objects

JE::Object - Base class for all JavaScript objects


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->{property1} = $new_value;       # or use it as a hash

  $obj->{property1};                    # ref like this

  $obj->keys; # returns a list of the names of enumerable property

  keys %$obj;

  $obj->delete('property_name');

  delete $obj->{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

  0+$obj"; #  nan -- same as $obj->to_number->value

  # etc.


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).

JE::Object objects can be used in Perl as a number, string or boolean. The result will be the same as in JavaScript. The %{} (hashref) operator is also overloaded and returns a hash that can be used to modify the object. See USING AN OBJECT AS A HASH.

See also the JE::Types manpage 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.

$obj->new_function($name, sub { ... })
$obj->new_function(sub { ... })
This creates and returns a new function object. If $name is given, it will become a property of the object. The function is enumerable, like alert et al. in web browsers.

For more ways to create functions, see the JE::Object::Function manpage.

$obj->new_method($name, sub { ... })
$obj->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, and that the property created will not be enumerable. This allows one to add methods to Object.prototype, for instance, without making every for-in loop list that method.

For more ways to create functions, see the JE::Object::Function manpage.

$obj->prop( $name )
$obj->prop( $name => $value )
$obj->prop({ ... })
See JE::Types for the first two uses.

When the prop method is called with a hash ref as its argument, the prototype chain is not searched. The elements of the hash are as follows:


  name      property name

  value     new value

  dontenum  whether this property is unenumerable

  dontdel   whether this property is undeletable

  readonly  whether this property is read-only

  fetch     subroutine called when the property is fetched

  store     subroutine called when the property is set

  autoload  see below

If dontenum, dontdel or readonly is given, the attribute in question will be set. If value is given, the value of the property will be set, regardless of the attributes.

fetch and store, if specified, must be subroutines for fetching/setting the value of the property. The 'fetch' subroutine will be called with ($object, $storage_space) as the arguments, where $storage_space is a hash key inside the object that the two subroutines can use for storing the value (they can ignore it if they like). The 'store' subroutine will be call with ($object, $new_value, $storage_space) as the arguments. Values assigned to the storage space from within these routines are not upgraded, neither is the return value of fetch. fetch and store do not necessarily have to go together. If you only specify fetch, then the value will be set as usual, but fetch will be able to mangle the value when it is retrieved. Likewise, if you only specify store, the value will be retrieved the usual way, so you can use this for validating or normalising the assigned value, for instance. Note: Currently, a simple scalar or unblessed coderef in the storage space will cause autoloading, but that is subject to change.

autoload can be a string or a coderef. It will be called/evalled the first time the property is accessed (accessing it with a hash ref as described here does not count). If it is a string, it will be evaluated in a scope that has a variable name $global, containing a reference to the global object. The result will become the property's value. The value returned is not currently upgraded. The behaviour when a simple scalar or unblessed reference is returned is undefined. autoload will be ignored completely if value or fetch is also given.

This hash ref calling convention does not work on Array objects when the property name is length or an array index (a non-negative integer below 4294967295). It does not work on String objects if the property name is length.

$obj->delete($property_name, $even_if_it's_undeletable)
Deletes the property named $name, if it is deletable. If the property did not exist or it was deletable, then true is returned. If the property exists and could not be deleted, false is returned.

If the second argument is given and is true, the property will be deleted even if it is marked is undeletable, if the object supports it.

$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. This is a copy of the object's properties. Modifying it does not modify the object itself.


USING AN OBJECT AS A HASH

Note first of all that \%$obj is not the same as $obj->value. The value method creates a new hash containing just the enumerable properties of the object and its prototypes. It's just a plain hash--no ties, no magic. %$obj, on the other hand, is another creature...

%$obj returns a magic hash which only lists enumerable properties when you write keys %$obj, but still provides access to the rest.

Using exists on this hash will check to see whether it is the object's own property, and not a prototype's.

Assignment to the hash itself currently throws an error:


  %$obj = (); # no good!

This is simply because I have not yet figured out what it should do. If anyone has any ideas, please let me know.

Autovivification works, so you can write


  $obj->{a}{b} = 3;

and the 'a' element will be created if did not already exist. Note that, if the property did exist but was undefined (from JS's point of view), this throws an error.


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

the JE::Types manpage

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy