NAME

PerlArray - Encapsulate a Perl ARRAY in JavaScript space

Any ARRAY reference that you pass from perl to javascript will be automatically wrapped as an instance of PerlArray.

JAVASCRIPT INTERFACE

Any perl ARRAY is exposed in javascript space as an instance of PerlArray. Them behave like native javascript Arrays and implements all methods documented for native ones.

When perl ARRAY enters javascript space for the first time a PerlArray wrapper will be created, multiple visits of the same ARRAY will use the same wrapper, i.e the same instance of a PerlArray.

The wrapper holds a reference to the ARRAY, this means that if you modify it, the changes are visible from perl side (if you hold a reference there). If the array has perl magic, for example if its tied, any access from javascript to the array will invoke the associated magic in perl.

For example you can expose the program arguments to javascript:

$ctx->bind_value(Argv => \@ARGV); 

PerlArray instances inherit from PerlArray.prototype. As with all javascript objects you can change its constructor prototype object to make changes to all PerlArray instances.

As every object in javascript, PerlArray instances inherits, via its prototype chain, all the methods and properties from Object. You can even set non-numeric properties in them, but those changes will not be normally visible from perl space.

Constructor

var array = new PerlArray(...);

You can create new perl ARRAYs from javascript.

The arguments are use to initialize the array.

var parray = new PerlArray(3, 4, 'foo', someval);

When those objects land in perl space they will be normal perl ARRAYs, i.e. with out any "magic".

Properties

Instances of PerlArray can be accessed as a normal arrays using integer indexes. If a negative index is used it is relative to the tail.

length

parray.length;        // Get the length of parray
parray.length = fill; // Change the length of parray

length is the actual number of items in the array.

You can set this property to modify the length of the array, similar to Perl's $#array = $fill. Remember: length is the number of elements while $#array is the index to the last one.

When the array is extended the new elements will be undefined (undef in Perl). When the array is truncated, the excess elements are freed.

Setting parray.length = 0; effectively clears the array.

Methods

All the methods documented for instances of Array are implemented for instances of PerlArray, please check your javascript documentation.

The more common are:

push(arg1, ...)

Pushes the arguments onto the array.

unshift(arg1, ...)

Unshifts (i.e. inserts at the beginning) the arguments into the array.

pop( )

Returns the top element.

shift( )

Returns the bottom element.

join( )

join(joinexp)

Returns a string with all the array elements, converted to strings if necessary, concatenated with joinexp, by default ',' if none provided.

slice( )

slice(begin)

slice(begin, end)

Returns a new one level deep copy of the array, from begin to end. If begin isn't provided defaults to 0, if end isn't provided defaults to the index of the last element.

Note that the array isn't changed in any way. A new Array is created and returned.

reverse( )

Reverse the array in place. The reversed array is returned

sort( )

sort( sorter )

This will sort the array in place. In the first form, without an argument, the sort will be in lexicographical order.

In the second form, sorter is a function used to perform the comparations of the array elements. If supplied, the array elements are sorted according to the return value of the compare function. If a and b are two elements being compared, then:

• If sorter(a, b) is less than 0, sort a to a lower index than b.

• If sorter(a, b) returns 0, leave a and b unchanged with respect to each other, but sorted with respect to all different elements.

• If sorter(a, b) is greater than 0, sort b to a lower index than a.

• sorter(a, b) must always returns the same value when given a specific pair of elements a and b as its two arguments. If inconsistent results are returned then the sort order is undefined.

The sorted array is returned.

toString( )

Joins the array and returns one string containing each array element separated by commas.

Javascript calls the toString method automatically when a PerlArray is to be represented as a text value or when a PerlArray is referred to in a string concatenation.

indexOf(searchElement)

indexOf(searchElement, fromIndex)

Returns the first index at which a given searchElement element can be found in the array, or -1 if it is not present. The search starts at fromIndex, if provided or from the beginning if not.

lastIndexOf(searchElement)

lastIndexOf(searchElement, fromIndex)

Returns the last index at which a given element can be found in the array, or -1 if it is not present. The array is searched backwards, starting at fromIndex if provided or from the end if not.

toSource ( )

Returns a string that when evaluated recreated the PerlArray.

// Asumes 'parray' as defined above
say(parray.toSource()); // "new PerlArray(3,4,'foo',someval)"

PERL INTERFACE

PACKAGE VARIABLES

$construct_blessed

When you set the variable $JSPL::PerlArray::construct_blessed to a TRUE value, you are turning on the Claes's JavaScript compatibility mode. This affects the behavior of the javascript PerlHash constructor.

This feature can be removed at any time. I strongly recommend against using it. Read "Migrating from JavaScript.txt" for the details.