JE::Object(3pm)

✨ JE::Object ✨ — the manual page, bestie edition 💅

okay so this is JE::Object from the Perl user-contributed docs, and it's literally the base class for all JavaScript objects. sit with me, we're gonna get through this together 🫶

---

🌸 NAME 🌸

JE::Object — the base class for all JavaScript objects. it's giving founding mother, it's giving matriarch of the whole object hierarchy 💖

---

🎀 SYNOPSIS 🎀

here's the vibe in code form, no cap:

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.

(yes bestie, that 0+$obj" with the stray quote is in the original, we do not edit the sacred texts 🙈)

---

🦋 DESCRIPTION 🦋

so this module implements JavaScript objects for JE, and it's the base class for every other JavaScript object out there. main character energy, honestly.

a JavaScript object is an associative array, and its elements? those are its properties. and a method? a method is just a property that happens to be an instance of the Function class (JE::Object::Function). that's it. that's the whole thing. iykyk.

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

also go read JE::Types for descriptions of most of the methods, because this page only explains what's specific to JE::Object. the rest is somebody else's section, we stay in our lane 💅

---

⭐ 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 brand new JavaScript object. unless $value is already a JS object, in which case it just returns it — like, no dupe, we're not copying, we're just handing it back. 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. periodt.

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)

and fun fact: the former is literally what "upgrade" itself uses. the way that it's self-referential 😭

🧚 $obj->new_function($name, sub { ... })

🧚 $obj->new_function(sub { ... })

this creates and returns a new function object. if $name is given, it becomes a property of the object. and the function is enumerable, just like "alert" et al. in web browsers. iconic behaviour, honestly.

for more ways to create functions, see JE::Object::Function. ✨

🌈 $obj->new_method($name, sub { ... })

🌈 $obj->new_method(sub { ... })

same as "new_function", except:

1. the subroutine's first argument will be the object with which the function is called, and
2. the property created will not be enumerable.

this lets you add methods to "Object.prototype", for instance, without making every for-in loop list that method. we love a low-profile queen 🙈

for more ways to create functions, see JE::Object::Function. ✨

💜 $obj->prop( $name )

💜 $obj->prop( $name => $value )

💜 $obj->prop({ ... })

for the first two uses, go see "JE::Types".

but when "prop" 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. (yes, value wins, don't fight it)

"fetch" and "store", if specified, must be subroutines for fetching/setting the value of the property.

• the 'fetch' subroutine gets 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, no pressure).
• the 'store' subroutine gets called with ($object, $new_value, $storage_space) as the arguments.

values assigned to the storage space from within these routines are not upgraded, and 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. slay 💅

Note: currently, a simple scalar or unblessed coderef in the storage space will cause autoloading, but that is subject to change. (so don't build your whole personality on it bestie)

"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 the warning below), in a scope that has a variable named $global that refers to the global object. the result becomes 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 — the author is literally asking, bestie, they're one of us 🫶)

also, heads up: 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). and it does not work on String objects if the property name is "length". them's the rules 🫠

💀 $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. (yes, that grammar is in the original, we keep the sacred typos 🙈) a subclass may override this, however — for instance, Array and String objects always have a 'length' property which cannot be deleted. no negotiating with those.

💅 $obj->typeof

returns the string 'object'. that's it. that's the method. tiny but mighty ✨

👑 $obj->class

returns the string 'Object'. capital O, bestie, respect it.

🦋 $obj->value

returns a hash ref of the object's enumerable properties. and it's a copy of the object's properties — modifying it does not modify the object itself. no feedback loops here, we're safe 💖

---

🌈 USING AN OBJECT AS A HASH 🌈

okay first of all, and i need you to hear me on this: "\%$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, no drama.
• %$obj, on the other hand, is another creature entirely...

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

using "exists" on this hash checks 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!

and this is simply because the author has not yet figured out what it should do. if anyone has any ideas, please let them know 🙏 (we love an honest king)

autovivification works, so you can write

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

and the 'a' element will be created if it did not already exist. but note: if the property did exist but was undefined (from JS's point of view), this throws an error. so like, check first, bestie 😭

---

🧚 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. that's your safe space, protect it 🫶

---

🌸 SEE ALSO 🌸

• JE
• JE::Types

---

and that's the whole page, bestie!! 💖 it's perl v5.36.0, dated 2023-08-25, and it's the JE::Object(3pm) page from the Perl user-contributed docs. go forth and object-orient, you absolute icon 👑✨🦋