view release on metacpan or  search on metacpan

lib/JE/Types.pod  view on Meta::CPAN

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

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

B<To do:> Convert Regexp objects to
JE::Object::RegExp objects.

=head1 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. 
  
=head1 PUBLIC API

=head2 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'

=head2 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';

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

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

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

=head2 Calling Methods

To call a method on an object or primitive data type, use the C<method>
method:

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

=head2 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 C<call_with>
method:

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

=head2 Just Getting a Simple Perl Scalar

To convert one of the fancy objects returned by JE into a simple Perl
value, use the C<value> method.

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