Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
JE::Object(3)	      User Contributed Perl Documentation	 JE::Object(3)

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

perl v5.32.0			  2014-10-20			 JE::Object(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | USING AN OBJECT AS A HASH | INNARDS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=JE::Object&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help