NAME
JE::Types - JavaScript types and objects
This is just documentation, not a module.
DESCRIPTION
The various JavaScript types and objects are represented by classes in JE. Each class provides the methods listed below. In some cases, a class may throw an exception when the method is called. Note: This is going to change. I am going to remove redundant methods, and make JE::Code check for the existence of the method before calling it or throwing an exception.
If you are creating your own object classes in Perl for JavaScript to use, you can subclass JE::Object, but you don't have to. Just make sure that you provide all the methods listed below.
UPGRADING VALUES
When a value is passed to the prop
and method
methods of objects, and various other functions, it will be "upgraded" to a Perl object representing a JavaScript value. This is done by the upgrade
method of the global object.
If the value to be upgraded is a blessed reference, it is left alone (we assume you know what you are doing). Otherwise the conversion is as follows:
From To
-------------------------
undef undefined
array ref Array
hash ref Object
code ref Function
'0' number
other scalar string
WHICH CLASSES ARE WHICH
Each built-in JavaScript class or primitive type is a Perl class underneath. Here is the (not yet) complete list of object classes:
JavaScript Perl
----------------
Object JE::Object
Function JE::Object::Function
Array JE::Object::Array
String JE::Object::String
Boolean JE::Object::Boolean
Number JE::Object::Number
Date JE::Object::Date
RegExp JE::Object::RegExp
Error JE::Object::Error
SyntaxError JE::Object::Error::SyntaxError
And here are the primitive types:
string JE::String
number JE::Number
boolean JE::Boolean
null JE::Null
undefined JE::Undefined
METHODS
Each class provides the following methods. In some cases the method may simply die (as is the case, for instance, with the call
and apply
methods of non-function objects).
If you define your own classes, you must implement all the methods here, except for new
, which is optional.
- prop($name)
- prop($name, $new_value)
-
Gets or sets a property. Setting a property returns the new value. The new value will be converted to a JS value automatically if it is not one already. (See "UPGRADING VALUES".) See also the
prop({ ... })
usage below. - props
-
Returns a list of the names of enumerable properties. This is a list of Perl strings, not JE::Strings.
- delete($name)
-
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.
The return value is a Perl scalar, not a JE::Boolean.
- method($name, $arg1, $arg2, ...)
-
Invokes the specified method through the object. The arguments are automatically upgraded.
- value
-
This returns a value that is supposed to be useful in Perl.
JE::Object::Array->value
, for instance, produces an array ref. - call(@args)
-
Runs the code associated with the object if it is a function. The arguments are automatically upgraded.
- apply($obj, @args)
-
Runs the code associated with the object if it is a function.
$obj
will be passed to the function as its invocant (its 'this' value). The arguments are automatically upgraded. - construct(@args)
-
This only applies to function objects. This is just like calling a function in JS with the
new
keyword. It calls the constructor, if this function has one (functions written in JS don't have this). Otherwise, an empty object will be created and passed to the function as its invocant. The return value of the function will be discarded, and the object (possibly modified) will be returned instead.
The rest of these are mostly for internal use:
- Class->new($global_obj, @args)
-
The
@args
are in the same order that they are passed to the constructor function in JavaScript. For primitive classes, there should be only two arguments, the global object and the value.Some object classes also provide a hash ref syntax. See each object class's respective man page.
User-defined classes do not need to accept arguments in the same order as those that come with JE. They can do whatever they like.
- prop({ ... })
-
The
prop
method can be called with a hash ref as its argument. In this case, the prototype chain is not searched, and values are not upgraded. 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
If any of the last three 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.This is not supported by Arguments objects. It does not work on Array objects when the property name is an array index (an non-negative integer below 4,294,967,295).
- is_readonly($property_name)
-
Object method.
This returns a boolean indicating whether a given property is readonly. If it doesn't exist, then the
is_readonly
method of the object's prototype is called with the same arguments. If there is no prototype, false is returned. This is used internally byprop
. - typeof
-
Returns a Perl string containing the type of the object. Used by the JS
typeof
operator. - class
-
This applies to object classes only. It returns a Perl string containing the type of object. This is only used by the defoult JavaScript
toString
method. If you create your own object class without subclassing JE::Object, you should still provide theclass
method, so that this JS code will still work:YourClass.prototype.toString = Object.prototype.toString; (new YourClass).toString();
- id
-
This returns a unique id for the object or primitive, used by the JavaScript
===
operator. This id is unique as a string, not as a number.The JE primitive classes provide a unique string beginning with the data type. The JE::Object and its subclasses return the memory address of the object itself. If you subclass JE::Object, you should not have to implement this method, unless you have multiple objects that you would like JS to consider the same object.
Note that the id 'num:nan' is treated specially. It is never considered equal to itself.
- primitive
-
Returns true or false.
- prototype
- prototype ( $obj )
-
This applies to objects only, not to primitives. This method returns the prototype of the object. If
$obj
is specified, the prototype is set to that object first. Theprop
method uses this method. You should not normally need to call it yourself, unless you are subclassing JE::Object. - to_primitive($preferred_type)
- to_boolean
- to_string
- to_number
- to_object
-
These each perform the appropriate type conversion. $preferred_type, which is optional, must be either 'string' or 'number'.
Calling
to_string
orto_number
on a object is not exactly the same as callingto_primitive('string')
orto_primitive('number')
, because the argument toto_primitive
is merely a suggestion.The last four methods in this list should not be overridden by subclasses.
- global
-
Returns a reference to the global object.
OVERLOADED OPERATORS
All primitive classes overload the "" (stringification) operator. See each class's respective man page (both primitives and objects) for more info on overloaded ops.
SEE ALSO
JE and all the modules listed above.