.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "JE::Object 3pm"
.TH JE::Object 3pm "2023-08-25" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
JE::Object \- Base class for all JavaScript objects
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use JE;
\&  use JE::Object;
\&
\&  $j = new JE;
\&
\&  $obj = new JE::Object $j;
\&
\&  $obj\->prop(\*(Aqproperty1\*(Aq, $new_value);  # sets the property
\&  $obj\->prop(\*(Aqproperty1\*(Aq);              # 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(\*(Aqproperty_name\*(Aq);
\&  delete $obj\->{property_name};
\&
\&  $obj\->method(\*(Aqmethod_name\*(Aq, \*(Aqarg1\*(Aq, \*(Aqarg2\*(Aq);
\&    # 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.
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements JavaScript objects for \s-1JE.\s0  It serves as a base
class
for all other JavaScript objects.
.PP
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
\&\f(CW\*(C`Function\*(C'\fR class (\f(CW\*(C`JE::Object::Function\*(C'\fR).
.PP
JE::Object objects can be used in Perl as a number, string or boolean.  The 
result will be the same as in JavaScript.  The \f(CW\*(C`%{}\*(C'\fR (hashref) operator is 
also overloaded and returns a hash that can be used to modify the object.
See \*(L"\s-1USING AN OBJECT AS A HASH\*(R"\s0.
.PP
See also JE::Types for descriptions of most of the methods.  Only what
is specific to JE::Object is explained here.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$obj = JE::Object\->new( $global_obj )" 4
.el .IP "\f(CW$obj\fR = JE::Object\->new( \f(CW$global_obj\fR )" 4
.IX Item "$obj = JE::Object->new( $global_obj )"
.PD 0
.ie n .IP "$obj = JE::Object\->new( $global_obj, $value )" 4
.el .IP "\f(CW$obj\fR = JE::Object\->new( \f(CW$global_obj\fR, \f(CW$value\fR )" 4
.IX Item "$obj = JE::Object->new( $global_obj, $value )"
.ie n .IP "$obj = JE::Object\->new( $global_obj, \e%options )" 4
.el .IP "\f(CW$obj\fR = JE::Object\->new( \f(CW$global_obj\fR, \e%options )" 4
.IX Item "$obj = JE::Object->new( $global_obj, %options )"
.PD
This class method constructs and returns a new JavaScript object, unless 
\&\f(CW$value\fR is
already a \s-1JS\s0 object, in which case it just returns it.  The behaviour is
the
same as the \f(CW\*(C`Object\*(C'\fR constructor in JavaScript.
.Sp
The \f(CW%options\fR are as follows:
.Sp
.Vb 3
\&  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
.Ve
.Sp
\&\f(CW\*(C`prototype\*(C'\fR only applies when \f(CW\*(C`value\*(C'\fR is omitted, undef, undefined
or null.
.Sp
To convert a hash into an object, you can use the hash ref syntax like
this:
.Sp
.Vb 1
\&  new JE::Object $j, { value => \e%hash }
.Ve
.Sp
Though it may be easier to write:
.Sp
.Vb 1
\&  $j\->upgrade(\e%hash)
.Ve
.Sp
The former is what \f(CW\*(C`upgrade\*(C'\fR itself uses.
.ie n .IP "$obj\->new_function($name, sub { ... })" 4
.el .IP "\f(CW$obj\fR\->new_function($name, sub { ... })" 4
.IX Item "$obj->new_function($name, sub { ... })"
.PD 0
.ie n .IP "$obj\->new_function(sub { ... })" 4
.el .IP "\f(CW$obj\fR\->new_function(sub { ... })" 4
.IX Item "$obj->new_function(sub { ... })"
.PD
This creates and returns a new function object.  If \f(CW$name\fR is given,
it will become a property of the object.  The function is enumerable, like
\&\f(CW\*(C`alert\*(C'\fR \fIet al.\fR in web browsers.
.Sp
For more ways to create functions, see JE::Object::Function.
.ie n .IP "$obj\->new_method($name, sub { ... })" 4
.el .IP "\f(CW$obj\fR\->new_method($name, sub { ... })" 4
.IX Item "$obj->new_method($name, sub { ... })"
.PD 0
.ie n .IP "$obj\->new_method(sub { ... })" 4
.el .IP "\f(CW$obj\fR\->new_method(sub { ... })" 4
.IX Item "$obj->new_method(sub { ... })"
.PD
This is the same as \f(CW\*(C`new_function\*(C'\fR, 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
\&\f(CW\*(C`Object.prototype\*(C'\fR, for instance, without making every for-in loop list
that method.
.Sp
For more ways to create functions, see JE::Object::Function.
.ie n .IP "$obj\->prop( $name )" 4
.el .IP "\f(CW$obj\fR\->prop( \f(CW$name\fR )" 4
.IX Item "$obj->prop( $name )"
.PD 0
.ie n .IP "$obj\->prop( $name => $value )" 4
.el .IP "\f(CW$obj\fR\->prop( \f(CW$name\fR => \f(CW$value\fR )" 4
.IX Item "$obj->prop( $name => $value )"
.ie n .IP "$obj\->prop({ ... })" 4
.el .IP "\f(CW$obj\fR\->prop({ ... })" 4
.IX Item "$obj->prop({ ... })"
.PD
See \f(CW\*(C`JE::Types\*(C'\fR for the first two uses.
.Sp
When the \f(CW\*(C`prop\*(C'\fR method is called with a hash ref as its argument, the 
prototype chain is \fInot\fR searched.
The elements of the hash are as follows:
.Sp
.Vb 8
\&  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
.Ve
.Sp
If \f(CW\*(C`dontenum\*(C'\fR, \f(CW\*(C`dontdel\*(C'\fR or \f(CW\*(C`readonly\*(C'\fR is given, the attribute in 
question will be set.
If \f(CW\*(C`value\*(C'\fR is given, the value of the property will be set, regardless of
the attributes.
.Sp
\&\f(CW\*(C`fetch\*(C'\fR and \f(CW\*(C`store\*(C'\fR, if specified, must be subroutines for
fetching/setting the value of the property.  The 'fetch' subroutine will be
called with ($object, \f(CW$storage_space\fR) as the arguments, where
\&\f(CW$storage_space\fR 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, \f(CW$new_value\fR, \f(CW$storage_space\fR) as
the arguments.  Values assigned to the storage space from within these 
routines are \fInot\fR
upgraded, neither is the return value of \f(CW\*(C`fetch\*(C'\fR. \f(CW\*(C`fetch\*(C'\fR and \f(CW\*(C`store\*(C'\fR do 
not necessarily have to go
together.  If you only specify \f(CW\*(C`fetch\*(C'\fR, then the value will be set as
usual, but \f(CW\*(C`fetch\*(C'\fR will be able to mangle the value when it is retrieved.
Likewise, if you only specify \f(CW\*(C`store\*(C'\fR, the value will be retrieved the
usual way, so you can use this for validating or normalising the assigned
value, for
instance.  \fBNote:\fR Currently, a simple scalar or unblessed coderef in the
storage space will cause autoloading, but that is subject to change.
.Sp
\&\f(CW\*(C`autoload\*(C'\fR 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
\&\f(CW$global\fR 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.  \f(CW\*(C`autoload\*(C'\fR will be
ignored completely if \f(CW\*(C`value\*(C'\fR or \f(CW\*(C`fetch\*(C'\fR is also given.  \fBWarning:\fR The
\&'calling package' may not be what you think it is if a subclass overrides
\&\f(CW\*(C`prop\*(C'\fR.  It may be the subclass in such cases.  To be on the safe side,
always begin the string of code with an explicit \f(CW\*(C`package\*(C'\fR statement.  (If
anyone knows of a clean solution to this, please let the author know.)
.Sp
This hash ref calling convention does not work on Array
objects when the property name is \f(CW\*(C`length\*(C'\fR or an array index (a 
non-negative integer 
below
4294967295).  It does not work on String objects if the
property name is \f(CW\*(C`length\*(C'\fR.
.ie n .IP "$obj\->delete($property_name, $even_if_it's_undeletable)" 4
.el .IP "\f(CW$obj\fR\->delete($property_name, \f(CW$even_if_it\fR's_undeletable)" 4
.IX Item "$obj->delete($property_name, $even_if_it's_undeletable)"
Deletes the property named \f(CW$name\fR, 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.
.Sp
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.
.ie n .IP "$obj\->typeof" 4
.el .IP "\f(CW$obj\fR\->typeof" 4
.IX Item "$obj->typeof"
This returns the string 'object'.
.ie n .IP "$obj\->class" 4
.el .IP "\f(CW$obj\fR\->class" 4
.IX Item "$obj->class"
Returns the string 'Object'.
.ie n .IP "$obj\->value" 4
.el .IP "\f(CW$obj\fR\->value" 4
.IX Item "$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.
.SH "USING AN OBJECT AS A HASH"
.IX Header "USING AN OBJECT AS A HASH"
Note first of all that \f(CW\*(C`\e%$obj\*(C'\fR is \fInot\fR the same as \f(CW\*(C`$obj\->value\*(C'\fR.
The \f(CW\*(C`value\*(C'\fR 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.  \f(CW%$obj\fR, on the other hand, is another creature...
.PP
\&\f(CW%$obj\fR returns a magic hash which only lists enumerable properties
when you write \f(CW\*(C`keys %$obj\*(C'\fR, but still provides access to the rest.
.PP
Using \f(CW\*(C`exists\*(C'\fR on this hash will check to see whether it is the object's
\&\fIown\fR property, and not a prototype's.
.PP
Assignment to the hash itself currently
throws an error:
.PP
.Vb 1
\&  %$obj = (); # no good!
.Ve
.PP
This is simply because I have not yet figured out what it should do.  If
anyone has any ideas, please let me know.
.PP
Autovivification works, so you can write
.PP
.Vb 1
\&  $obj\->{a}{b} = 3;
.Ve
.PP
and the 'a' element will be created if did not already exist.  Note that,
if the property \f(CW\*(C`did\*(C'\fR exist but was undefined (from \s-1JS\s0's point of view),
this throws an error.
.SH "INNARDS"
.IX Header "INNARDS"
Each \f(CW\*(C`JE::Object\*(C'\fR instance is a blessed reference to a hash ref.  The 
contents of the hash
are as follows:
.PP
.Vb 12
\&  $$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\*(Aqs prototype
.Ve
.PP
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 \s-1JE\s0 distribution.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1JE\s0
.PP
JE::Types