Provided by: libje-perl_0.060-1_all bug

NAME

       JE::Types - JavaScript types and objects

       This is just documentation, not a module.

DESCRIPTION

       The various JavaScript types and objects are represented by Perl classes in JE (which are
       listed below).  This document describes the basic interface implemented by these classes.
       Information specific to each class can be found on its own manual page.

UPGRADING VALUES

       When a value is passed from Perl to JavaScript, 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, and the class into which it is blessed
       has been bound using JE's "bind_class" method, it is wrapped up in a proxy object that
       provides the methods JS needs.  A blessed reference whose class has not been bound will be
       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

       WARNING: The 'upgrading' of simple scalars (strings/numbers) and regexps is still subject
       to change.

       To do: Make &JE::upgrade detect whether a simple scalar is a string or number.

       To do: Convert Regexp objects to JE::Object::RegExp objects.

WHICH CLASSES ARE WHICH

       Each built-in JavaScript class or primitive type is a Perl class underneath. Here is the
       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
         RangeError      JE::Object::Error::RangeError
         ReferenceError  JE::Object::Error::ReferenceError
         SyntaxError     JE::Object::Error::SyntaxError
         TypeError       JE::Object::Error::TypeError
         URIError        JE::Object::Error::URIError

       And here are the primitive types:

         string          JE::String
         number          JE::Number
         boolean         JE::Boolean
         null            JE::Null
         undefined       JE::Undefined

       And I might also mention a few special cases:

         Global              JE
         Math                JE::Object::Math
         Arguments           JE::Object::Function::Arguments
         Function scope      JE::Object::Function::Call
         RegExp constructor  JE::Object::Function::RegExpConstructor

       The last three are for internal use.

PUBLIC API

   Using JS Values as Scalars
       Every JS data type can be used as a string, boolean or number.  It works exactly as it
       does in JavaScript.  For example:

         $num = $je->eval('42');
         $num2 = $je->eval('NaN');
         print $num2; # prints NaN
         print 0+$num2; # prints nan or NaN, depending or your system
                        # (or something really weird on Windows).

         $zero_str = $je->eval("'0'");
         print "true" if $zero_str; # prints 'true'
         print "false" unless 0+$zero_str; # prints 'false'

         $false = $je->eval('false');
         print $false; # prints 'false'
         print "false" unless $false; # also prints 'false'

   Property Access
       To access the property of a JS object, or of the JS environment itself (i.e., a global
       variable), just use it as a hash ref:

         $je->{String};    # gives you the String constructor function
         $je->{undefined}; # the undefined value
         my $obj = $je->eval('var obj = new Object; return obj');
         $obj->{foo} = 'bar';

       "keys" will return a list of the object's enumerable properties, including those inherited
       from its prototype.  The following example prints 'baz foo ':

         $obj = $je->eval('Object.prototype.foo="bar"; ({baz:43}) ');
         print "$_ " for keys %$obj;

       "exists" and "delete" act upon properties of the object itself, ignoring those of its
       prototype, so "exists $obj->{foo}" will return false.

   Calling Methods
       To call a method on an object or primitive data type, use the "method" method:

         my $number = $je->eval('42');
         $number->method('toString', 16); # returns the number in hexadecimal

   Calling Functions
       Just use a function as though it were a coderef:

         $je->{Array}->();

       If you need to specify the invocant ('this' value), use the "call_with" method:

         $je->{Number}{prototype}{toString}->call_with($je->eval('42'), 16);

   Just Getting a Simple Perl Scalar
       To convert one of the fancy objects returned by JE into a simple Perl value, use the
       "value" method.

         $number->value; # simple Perl scalar
         $str->value;    # likewise
         $obj->value;    # hash ref
         $array->value;  # array ref

       Currently the "value" method of objects and arrays is not recursive, but I plan to make it
       so later on.  The only way to get consistent behaviour between this and future versions is
       to pass "recursive => 0" as arguments.

DATA TYPE API (in more detail)

       If you are going to write your own custom data types, proxy objects, or subclasses of JE's
       classes, you'll need to read this.  If not, you shouldn't need to, but you might like to
       anyway. :-)

       Be warned that some of the methods described here can be hard to use, and can easily
       result in code that's hard to debug, if misused.  This applies to those that expect their
       arguments already to be objects compatible with the JE::Types interface.  If you are not
       sure that a value you have is such, run it through the global object's "upgrade" method
       (or just use the "PUBLIC API", above).

       These are the methods that the JavaScript engine itself uses (as opposed to those provided
       for convenient access from the Perl side).  Each class provides whichever of the following
       methods are applicable.  If an object does not support a particular method, a TypeError
       will be thrown when JavaScript code (indirectly) tries to call that method.  (For
       instance, "'some_string'()" will attempt to call the "call" method of JE::String, thus
       resulting in a TypeError).

       prop($name)
       prop($name, $new_value)
           Gets or sets a property.  Setting a property returns the new value.  The return value
           will be a Perl undef if the property does not exist.  See also JE::Object, for the
           "prop({ ... })" usage.

           The new value is expected already to be an object compatible with the JE::Types
           interface.

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

           JE::Object will also take a second argument, that allows one to indicate whether an
           undeletable property should be deleted.  This is required by custom classes if the
           object in question is the global object.

           The return value is a Perl scalar, not a JE::Boolean.

       value
           This returns a value that is supposed to be useful in Perl.  The "value" method of a
           JE::Object::Array, for instance, produces an array ref.

       call(@args)
           Runs the code associated with the object if it is a function.  The arguments are
           passed as-is, and are not 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 passed, as-is, and
           are not upgraded.

       construct(@args)
           This is just like calling a function in JS with the "new" keyword (which itself calls
           this method).  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 returned if it is
           an object.  Otherwise it will be discarded, and the object originally passed to the
           function will be returned instead (possibly modified).

       exists($property_name)
           Returns a boolean indicating whether the property exists and is not inherited from a
           prototype.  Used by "Object.prototype.hasOwnProperty".  (The "in" operator checks to
           see whether the return value of "prop" is defined.)

           To do: Implement this method in subclasses of JE::Object.

       is_readonly($property_name)
           Not supported by the primitive JE classes.  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 by JE::Object's "prop" method.

       is_enum($property_name)
           Not supported (yet) by the primitive JE classes.  This returns a boolean indicating
           whether a given property is enumerable.  This is used by
           "Object.prototype.propertyIsEnumerable".

       typeof
           Returns a Perl string containing the type of the object.  Used by the JS "typeof"
           operator.

       class
           This applies to object classes only (though it is going to change, so that primitives
           can pretend to be objects).  It returns a Perl string containing the type of object.
           This is only used by the default JavaScript "toString" method.  If you create your own
           object class without subclassing JE::Object, you should still provide the "class"
           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, or undef if there is no prototype.  If $obj is specified, the prototype is
           set to that object first.  The "prop" method uses this method, as does
           "JE::Object->new".

       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" or "to_number" on a object is not exactly the same as calling
           "to_primitive('string')" or "to_primitive('number')", because the argument to
           "to_primitive" is merely a suggestion.

           The last four methods in this list should not be overridden by subclasses of
           JE::Object.

       global
           Returns a reference to the global object.

       taint($taint_brush)
           This will only be called if it is implemented.  Of JE's types, only primitive strings
           and numbers implement this.

           $taint_brush will always be a tainted empty string.  If the object's internal value is
           not tainted, this method should return a tainted clone of the object.  Otherwise, it
           should return the object itself.

SEE ALSO

       JE and all the modules listed above under "WHICH CLASSES ARE WHICH".