README-perlito5-js

* Perlito5 compiler globals

- context: system-wide; shared by all modules

    $Perlito5::CORE_PROTO = { 'CORE::join' => '$@' }
    - hashref with subroutine-full-name to prototype mappings in the CORE package only

    $Perlito5::PROTO = { 'main::mysub' => undef }
    - hashref with subroutine-full-name to prototype mappings

- context: module-wide

    $Perlito5::PKG_NAME = "main"
    - the current package name (unescaped string)

- context: subroutine-wide

    $Perlito5::THROW = 1
    - boolean value; tracks if the current subroutine needs to catch a javascript "throw" as a return-value

- context: lexical block

    $Perlito5::VAR = [ { '$_'    => { decl => 'our', namespace => 'main' } ]
    - arrayref-of-hashes with variable-short-names to (declaration type, namespace) mappings



* Perlito5 Javascript Data model Overview


method call
- lookup the method in the _class_ attribute; follow the class hierarchy through @ISA until the UNIVERSAL base class.
- do a native call on the method.
- the argument list is the named array "List__" (that is, "@_").
- additional arguments can be used to pass out-of-band data, such as: caller(), wantarray()
- the invocant is the first argument. "this" is not used.

subroutine call 
- lookup the subroutine in the current namespace; follow the hierarchy until the CORE base class.
- do a native method call.
- the argument list is the named array "List__" (that is, "@_").
- additional arguments can be used to pass out-of-band data, such as: caller(), wantarray()
- "this" is not used.

Hash
- native {}

Array
- native []

Scalar
- native value

HashRef
- native {} wrapped in a "HashRef" object

ArrayRef
- native [] wrapped in a "ArrayRef" object

ScalarRef
- native value wrapped in a "ScalarRef" object

CodeRef
- native value

Object
- one of the reference types, with a _class_ attribute

Class
- classes are stored in the CLASS global hash
- the _class_ attribute points to the class itself
- classes inherit from UNIVERSAL

Namespace
- namespaces are stored in the p5pkg global hash
- current namespace object is in the PKG variable
- Namespace inherits from from CORE::GLOBAL, which inherits from CORE
- Namespace is a copy of the Class, but with a different inheritance
- Namespace and Class are updated in parallel, both when a sub is declared or when using typeglob assignment

Calling context ("wantarray", caller)
- TODO

- these are the possible compile-time contexts:
    'scalar'
    'list'
    'void'
    'runtime' (unknown)

    'str'
    'bool'
    'num'

- at run-time the contexts are in wantarray ("p5want" variable):
    1
    0
    undef

Alias
- TODO
- using String/Boolean/Number (boxed types) as SCALARs doesn't seem to work

List (eg. subroutine return value)
- native []

eval string
- the compiler gets the current namespace as an argument
- javascript eval() happens at the current runtime lexical context

eval block
- ...

do block
- ...

AUTOLOAD
- TODO

my
- ...

local
- ...

our
- ...



* Javascript resources


https://github.com/eriwen/javascript-stacktrace
- how to get a stacktrace in browsers

https://github.com/audreyt/pugs/tree/master/perl5/PIL2JS
- Pugs Perl6 in javascript


* Regex

- modifiers: g i m

- slashes must be escaped

- From http://www.regular-expressions.info/javascript.html

    No \A or \Z anchors to match the start or end of the string. Use a caret or dollar instead.
    Lookbehind is not supported at all. Lookahead is fully supported.
    No atomic grouping or possessive quantifiers
    No Unicode support, except for matching single characters with
    No named capturing groups. Use numbered capturing groups instead.
    No mode modifiers to set matching options within the regular expression.
    No conditionals.
    No regular expression comments. 


* Cell-based aliasing (TODO)


- slow
- allows aliasing (rw parameters to functions)
- allows "tie", because collection access is done through methods
- simplifies autovivification
- allows lvalue subroutines, such as chop(), chomp(), keys(), pos(), substr(), undef()
- allows "our"

- examples:

v = new Cell();
v.set(5);
f(v);   // f gets a copy of the cell; v.set() inside f() modifies the original variable.
1 + v;  // calls v.valueOf()
x = v;  // alias (copies the cell); v.set() modifies x.valueOf()
x.set( v.valueOf() );  // copies the value (doesn't alias)

h.lookup("x");  // looks up h["x"] for a cell; autovivifies if needed
v.lookup("x");  // error if the cell in v contains something else than undef or an arrayref

- see mp6_Scalar class in src6/lib/Perlito/Python/Runtime.py