NAME

JSPL::Stash - Perl namespaces reflector for JavaScript.

DESCRIPTION

Every perl namespace when exposed to JavaScript either automatically or by the methods of the JSPL::Controller perl class is represented by an instance of a Stash.

In perl a particular namespace can be used for different things. From simply to collect a bunch of variables and subroutines, to implement a complete class, or can act as a class "broker" when its static methods are constructors for other classes. The ways in which you can use Stash instances in javascript are different too.

In fact a perl namespace can be exposed to javascript without binding the associated Stash instance into any property in your global object, making it invisible and its use transparent. That whats happens when a perl object enters javascript land and you call its instance methods.

Javascript interface

TBD

Perl interface

The value returned by "add" in JSPL::Controller and Stash instances entering perl land are wrapped as JSPL::Stash objects.

    my $ctl = $ctx->get_controller;
    my $stash = $ctl->add('DBI'); # Expose to js the package 'DBI'.

Instance methods

allow_from_js ( [ BOOLEAN ] )

    my $old = $stash->allow_from_js($bool);

Call this with a TRUE value to allow javascript code to make changes to the associated perl namespace. All namespaces are, by default, not modifiable from javascript. Returns the previous state of the flag.

For example:

    # Expose the namespace 'ForJSUse'
    my $stash = $ctl->add('ForJSuse');
    # Make 'ForJSUse' modifiable by js code
    $stash->allow_from_js(1);

class_bind ( BIND_POINT )

    $stash->class_bind($prop_name);

Make the package visible in javascript as a class under the given property BIND_POINT.

For example:

    require 'DBI';
    $ctl->add('DBI')->class_bind('DBI');

Exposes the perl package 'DBI' and binds it to the property of the same name as a class, allowing to call its methods as static ones.

package_bind ( BIND_POINT )

    $stash->package_bind($prop_name);

Make the package visible in javascript as a simple collection of values (normally soubroutines) under the property BIND_POINT.

For example:

    require 'POSIX';
    $ctl->add('POSIX')->package_bind('POSIX');

So you can call any subroutine in package 'POSIX' from javascript:

    // In javascript land
    var fd = POSIX.open('foo', POSIX.O_RDONLY());
    // Yes, fd is a real file descriptor
    POSIX.lseek(fd, 0, POSIX.SEEK_SET())
    ...
    POSIX.close(fd);

set_constructor ( )

set_constructor ( CODE )

set_constructor ( SUB_NAME )

TBD

add_properties

TBD