oracular (3) JE::Object.3pm.gz

Provided by: libje-perl_0.066-4_all bug

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

       $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 JE::Object::Function.

       $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 JE::Object::Function.

       $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 the calling package (see warning below), in a scope that has a variable named $global
           that refers 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.  Warning: The
           'calling package' may not be what you think it is if a subclass overrides "prop".  It may be the
           subclass in such cases.  To be on the safe side, always begin the string of code with an explicit
           "package" statement.  (If anyone knows of a clean solution to this, please let the author know.)

           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.  A subclass may override this, however.  For instance, Array and String objects always
           have a 'length' property which cannot be deleted.

       $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

       JE::Types