Overview

About pas2js

• file cache - loading, caching files, converting to UTF-8
• file resolver - handling search paths, finding used units and include files
• scanner - reading tokens, handling compiler directives like $IfDef and $Include
• parser - reading the tokens, checking syntax, creating Pascal nodes
• resolver - resolving references, type checking and checking duplicate identifiers
• use analyzer - finding unused identifiers, emit hints and warning
• converter - translating Pascal nodes into JavaScript nodes
• compiler - handling config files, parameters, compiling recursively all used units, writes js
• command line interface - a small wrapper to embed the compiler into a console program
• library and interface - a small wrapper to embed the compiler into a library

Command line parameters

Usage: pas2js <your.pas>
Options:
Put + after a boolean switch option to enable it, - to disable it
  @<x>    : Read compiler options from file <x> in addition to the default pas2js.cfg
  -B      : Rebuild all
  -d<x>   : Defines the symbol <x>. Optional: -d<x>:=<value>
  -i<x>   : Write information and halt. <x> is a combination of the following:
    -iD   : Write compiler date
    -iSO  : Write compiler OS
    -iSP  : Write compiler host processor
    -iTO  : Write target platform
    -iTP  : Write target processor
    -iV   : Write short compiler version
    -iW   : Write full compiler version
    -ic   : Write list of supported JS processors usable by -P<x>
    -io   : Write list of supported optimizations usable by -Oo<x>
    -it   : Write list of supported targets usable by -T<x>
    -iJ   : Write list of supported JavaScript identifiers -JoRTL-<x>
  -C<x>   : Code generation options. <x> is a combination of the following letters:
    o     : Overflow checking
    r     : Range checking
    R     : Object checks. Verify method calls and object type casts.
  -F...   Set file names and paths:
   -Fe<x> : Redirect output to file <x>. UTF-8 encoded.
   -FE<x> : Set main output path to <x>
   -Fi<x> : Add <x> to include paths
   -FN<x> : add <x> to namespaces. Namespaces with trailing - are removed.
                  Delphi calls this flag "unit scope names".
   -Fu<x> : Add <x> to unit paths
   -FU<x> : Set unit output path to <x>
  -I<x>   : Add <x> to include paths, same as -Fi
  -J...  Extra options of pas2js
   -Jc    : Write all JavaScript concatenated into the output file
   -Je<x> : Encode messages as <x>.
     -Jeconsole : Console codepage. Default.
     -Jesystem  : System codepage. On non Windows console and system are the same.
     -Jeutf-8   : Unicode UTF-8. Default when using -Fe.
     -JeJSON    : Output compiler messages as JSON. Logo etc are outputted as-is.
   -Ji<x> : Insert JS file <x> into main JS file. E.g. -Jirtl.js. Can be given multiple times.
   -Jl    : lower case identifiers
   -Jm    : generate source maps
     -Jmsourceroot=<x> : use x as "sourceRoot", prefix URL for source file names.
     -Jmbasedir=<x> : write source file names relative to directory x, default is map file folder.
     -Jminclude : include Pascal sources in source map.
     -Jmabsolute: store absolute filenames, not relative.
     -Jmxssiheader : start source map with XSSI protection )]}.
     -Jm- : disable generating source maps
   -Jo<x> : Enable or disable extra option. The x is case insensitive:
     -JoSearchLikeFPC : search source files like FPC, default: search case insensitive.
     -JoUseStrict : add "use strict" to modules, default.
     -JoCheckVersion-: do not add rtl version check, default. (since 1.1)
     -JoCheckVersion=main: insert rtl version check into main. (since 1.1)
     -JoCheckVersion=system: insert rtl version check into system unit init. (since 1.1)
     -JoCheckVersion=unit: insert rtl version check into every unit init. (since 1.1)
     -JoRTL-<x>=<y>: set RTL identifier x to value y. See -iJ. (since 1.1)
   -Jpcmd<command> : Run postprocessor. For each generated js execute
                  command passing the js as stdin and read the new js from stdout.
                  This option can be added multiple times to call several
                  postprocessors in succession.
   -Ju<x> : Add <x> to foreign unit paths. Foreign units are not compiled.
  -l      : Write logo
  -MDelphi: Delphi 7 compatibility mode
  -MObjFPC: FPC's Object Pascal compatibility mode (default)
  -NS<x>  : obsolete: add <x> to namespaces. Same as -FN<x>
  -n      : Do not read the default config files
  -o<x>   : Change main JavaScript file to <x>, "." means stdout
  -O<x>   : Optimizations:
    -O-   : Disable optimizations
    -O1   : Level 1 optimizations (quick and debugger friendly)
    -Oo<x> : Enable or disable optimization. The x is case insensitive:
      -OoEnumNumbers[-] : write enum values as number instead of name. Default in -O1.
      -OoRemoveNotUsedPrivates[-] : Default is enabled
      -OoRemoveNotUsedDeclarations[-] : Default enabled for programs with -Jc
      -OoRemoveNotUsedPublished[-] : Default is disabled
  -P<x>   : Set target processor. Case insensitive:
    -Pecmascript5  : default
    -Pecmascript6
  -S<x>   : Syntax options. <x> is a combination of the following letters:
    a     : Turn on assertions
    c     : Support operators like C (*=,+=,/= and -=)
    d     : Same as -Mdelphi
    m     : Enables macro replacements
    2     : Same as -Mobjfpc (default)
  -SI<x>   : Set interface style to <x>
    -SIcom   : COM, reference counted interface (default)
    -SIcorba : CORBA interface
  -T<x>   : Set target platform, case insensitive.
    -Tbrowser : default
    -Tnodejs  : add pas.run(), includes -Jc
  -u<x>   : Undefines the symbol <x>
  -v<x>   : Be verbose. <x> is a combination of the following letters:
    e     : Show errors (default)
    w     : Show warnings
    n     : Show notes
    h     : Show hints
    i     : Show info
    l     : Show line numbers, needs -vi
    a     : Show everything
    0     : Show nothing (except errors)
    b     : Show file names with full path
    c     : Show conditionals
    t     : Show tried/used files
    d     : Show debug notes and info, enables -vni
    q     : Show message numbers
    x     : Show used tools
    v     : Write pas2jsdebug.log with lots of debugging info
    z     : Write messages to stderr, -o. still uses stdout.
  -vm<x>,<y>: Do not show messages numbered <x> and <y>.
  -?      : Show this help
  -h      : Show this help

Environment variable PAS2JS_OPTS is parsed after default config
and before command line parameters.

Delphi and ObjFPC mode

Delphi mode

• Defines macro DELPHI
• Assigning a function to a function type variable does not require the @ operator. For example, you can write either OnGetThing:=GetValue; or OnGetThing:=@GetValue;.
• A function type variable reference without brackets is treated as a call. For example: If OnGetThing is a variable of type function: integer you can write: If OnGetThing=3 then ;.
• You must use the @@ operator to get the procedure address (i.e. JS reference) of a procedure type variable. For example instead of If OnClick=nil then ; you must use if @@OnClick=nil then ;.
• Every procedure/method overload needs the 'overload' modifier.

ObjFPC mode

• Defines macro OBJFPC
• Assigning a function to a function type variable requires the @ operator. For example: OnGetThing:=@GetValue;.
• A function type variable always needs brackets to be called. For example: If OnGetThing is a variable of type function: integer then this is allowed: If OnGetThing()=3 then ;. While this gives an error: If OnGetThing=3 then ;.
• You can compare a procedure type with nil. For example If OnClick=nil then ;.
• You can compare a procedure type with a procedure address (i.e. JS reference). For example If OnClick=@OnFormClick then ;.
• The procedure modifier 'overload' can be omitted when all overloads are in one scope, e.g. a unit or a class. And if one procedure has such modifier all procedures with same name and in same scope are overloads as well.

Translating modules

Program <unitname>;
Implementation
  [implementation section]
Begin
  [main code]
End.

pas.<program>={
  [implementation section],
  $main: function() {
    [main code]
  }
};

Unit MyModule;
Interface
Uses Sysutils;
var
  dIntf: double;
  sIntf: string = 'abc';
procedure MyIntfProc;
Implementation
Uses Classes;
Var dImpl:double;
Procedure MyIntfProc;
Begin
  dImpl:=dIntf;
End;
Procedure MyImplProc;
Begin
  dImpl:=dIntf;
End;
Initialization
End.

rtl.module("MyModule",
["System","SysUtils"],
function(){
  var $mod = this;
  var $impl = $mod.$impl;
  this.dIntf = 0.0;
  this.sIntf = "abc";
  this.MyIntfProc = function(){
    $impl.dImpl = $mod.dIntf;
  };
  this.$init = function() {
  };
},
["Classes"],
function(){
  var $mod = this;
  var $impl = $mod.$impl;
  $impl.dImpl = 0.0;
  $impl.MyImplProc = function() {
    $impl.dImpl = $mod.dIntf;
  };
});

• Unit System is always loaded implicitely.
• References to other units are translated to full path. For example TObject is translated to pas.system.TObject
• References to dotted unitnames, aka units with namespaces are translated to pas["namespace.unitname"].

Translating variables

Unit MyModule;
Interface
Uses Classes,Forms;
const
  c1:integer=3;
  c2 = 'abc';
  c3 = 234;
  c4 = 12.45;
  c5 = nil;
var
  v1:string;
  v2,v3:double;
  v4:byte=0;
  v5:TForm;
  v6:TIdentMapEntry;
  v7:string='abcäöü';
  v8:char='c';
  v9:array of byte;
Implementation
End.

rtl.module("MyModule",
["System","Classes","Forms"],
function(){
  this.c1 = 3;
  this.c2 = "abc";
  this.c3 = 234;
  this.c4 = 12.45;
  this.c5 = null;
  this.v1 = "";
  this.v2 = 0.0;
  this.v3 = 0.0;
  this.v4 = 0;
  this.v5 = null;
  this.v6 = new pas.Classes.TIdentMapEntry();
  this.v7 = "abcäöü";
  this.v8 = "c";
  this.v9 = [];
},
[]);

• Type casting a boolean to integer, gives 0 for false and 1 for true.
• Type casting an integer to boolean, gives false for 0 and true otherwise.
• A char is translated to a JS string, because JS lacks a native char type.
• A char is a single JS char code. An UTF-16 codepoint can contain one or two char.
• Integers overflows at runtime differ from Delphi/FPC, due to the double format. For example adding var i: byte = 200; ... i:=i+100; will result in i=300 instead of i=44 as in Delphi/FPC. When range checking {$R+} is enabled i=300 will raise an ERangeError.
• type cast integer to integer, e.g. byte(aLongInt)
  • with range checking enabled: error if outside range
  • without range checking: emulates the FPC/Delphi behaviour: e.g. byte(value) translates to value & 0xff, shortint(value) translates to value & 0xff <<24 >> 24.
• The mod-operator works 32-bit signed in JS.

Translating string

Translating resourcestrings

Unit MyModule;
Interface
resourcestring
  rsCompiler = 'pas2js';
var
  s:string;
Implementation
initialization
  s:=rsCompiler;
End.

rtl.module("test1",["System"],function () {
  var $mod = this;
  this.s = "";
  $mod.$resourcestrings = {rsCompiler: {org: "pas2js"}};
  $mod.$init = function () {
    $mod.s = rtl.getResStr(pas.test1,"rsCompiler");
  };
});

Translating currency

• CurA := 1.12345 -> CurA = 11234
• CurA + CurB -> CurA + CurB
• CurA * CurB -> CurA * CurB/10000
• CurA / CurB -> Math.floor(CurA/CurB * 10000)
• CurA ^^ CurB -> Math.floor(Math.pow(CurA/10000,CurB/10000) * 10000)
• Currency + Double -> Currency + (Double*10000)
• Double := Currency -> Double = Currency/10000
• Currency := Double -> Currency = Math.floor(Double*10000)
• JSValue := Currency -> JSValue = Currency/10000
• Keep in mind that a double has only 52 bits for the number, so calculating values greater than 450,359,962,737 might give a different result than in Delphi/FPC. See SysUtils.MinCurrency/MaxCurrency

Translating Types

Translating pointer

Translating record type

Unit MyModule;
Interface
Type
  TMyRecord = Record
    i: integer;
    s: string;
    d: TDateTime;
  End;
Var
  r, s: TMyRecord;
Implementation
Initialization
  r.i := 123;
  r:=s;
  if r=s then ;
End.

rtl.module("MyModule",
["System"],
function(){
  var $mod = this;
  this.TMyRecord = function(s) {
    if (s){
      this.i = s.i;
      this.s = s.s;
      this.d = s.d;
    } else {
      this.i = 0;
      this.s = "";
      this.d = 0.0;
    };
    this.$equal = function (b) {
      return (this.i == b.i) &&
        (this.s == b.i) && (this.d == b.d);
    };
  };
  this.r = new this.TMyRecord();
  $mod.$init = function() {
    $mod.r.i=123;
    $mod.r = new $mod.TMyRecord($mod.s);
    if ($mod.r.$equal($mod.s)) ;
  },
},
[]);

rtl.module("MyModule",
["System"],
function(){
  var $mod = this;
  rtl.recNewT($mod, "TMyRecord", function() {
    this.i = 0;
    this.s = "";
    this.d = 0.0;
    this.$eq = function (b) {
      return (this.i == b.i) &&
         (this.s == b.i) && (this.d == b.d);
    };
    this.$assign = function (s) {
      this.i = s.i;
      this.s = s.s;
      this.d = s.d;
      return this;
    };
  };
  this.r = this.TMyRecord.$new();
  $mod.$init = function() {
    $mod.r.i=123;
    $mod.r.$assign($mod.s);
    if ($mod.r.$eq($mod.s)) ;
  },
},
[]);

• The record variable creates a JavaScript object.
• Variant records are not supported.
• Supported: Assign, pass as argument, equal, not equal, array of record, pointer of record, const, default(), RTTI.
• Advanced record (since pas2js 1.3):
  • visibility private, strict private, public, default is public
  • methods, class methods (must be static like in Delphi/FPC)
  • class vars
  • const fields
  • property, class property, array property, default array property
  • sub types
  • constructor
• Not yet implemented:
  • operator overloading
  • class constructor
  • reference counted interfaces as fields
  • Interfaces as nested types
  • default non array property
• Until Pas2js 1.2 when assigning a record it is cloned, creating a new JS object. Since Pas2js 1.3 only values are copied, keeping the object, so pointer of record is compatible.
• Since record types are JS objects it is possible to typecast a record type to the JS Object, e.g. TJSObject(TPoint)
• A pointer of record is simply a reference.
  • p:=@r translates to p=r
  • p^.x becomes p.x.
  • New(PointerOfRecord) creates a new record
  • Dispose(PointerOfRecord) Sets the variable to null if possible.

Translating functions

Unit MyModule;
Interface
Function DoubleIt(n: integer): integer;
Implementation
Function DoubleIt(n: integer): integer;
Begin
  Result:=2*n;
End;
End.

rtl.module("MyModule",
["System"],
function(){
  this.DoubleIt = function(n){
    Result = 0;
    Result = 2*n;
    return Result;
  };
},
[]);

• Local variables become local JavaScript variables: var l = 0;.
• Local constants become JavaScript variables in the unit/program implementation section.
• Overloaded functions are given an unique name by appending $1, $2, ...
  Overloading is always on. You don't need to add the overload modifier.
• Supported: default values, local types, FuncName:=

Translating passing a parameter by reference

Program MyModule;
Procedure DoubleIt(var n: integer);
Begin
  n:=2*n;
End;
Function Doubling(n: integer): integer;
Begin
  DoubleIt(n);
  Result:=n;
End;
Var
  i: integer = 7;
Begin
  Doubling(i);
End.

rtl.module("program",
["System"],
function(){
  var $mod = this;
  this.i = 7;
  this.DoubleIt = function(n){
    n.set(2*n.get());
  };
  this.Doubling = function(n){
    var Result = 0;
    DoubleIt({
      get:function(){
        return n
      },
      set:function(v){
        n=v;
      }
    });
    Result = n;
    return n;
  };
  $mod.$main = function(){
    Doubling($mod.i);
  }
},
[]);

Program MyModule;
Procedure DoubleIt(var n: integer);
Begin
  n:=2*n;
End;
Var
  i: integer = 7;
Begin
  DoubleIt(i);
End.

rtl.module("program",
["System"],
function(){
  var $mod = this;
  this.i = 7;
  this.DoubleIt = function(n){
    n.set(2*n.get());
  };
  $mod.$main = function(){
    DoubleIt({
        p:$mod,
        get:function(){
          return this.p.i
        },
        set:function(v){
          this.p.i=v;
        }
      });
  }
},
[]);

• Contrary to Delphi/FPC it is allowed to pass a property to a var/out parameter.

Translating nested functions

Unit MyModule;
Interface
Function SumNNumbers(n, Adder: integer): integer;
Implementation
Function SumNNumbers(n, Adder: integer): integer;

  Function Add(k: integer): integer;
  Begin
    if k=1 then
      Result:=1
    else
      Result:=Add(k-1)+Adder;
  End;

Begin
  Result:=Add(n);
End;
End.

rtl.module("MyModule",
["System"],
function(){
  this.DoubleIt = function(n,Adder){
    Result = 0;
    var Add = function(k) {
      Result = 0;
      if (k==1) {
        Result = 1;
      } else {
        Result = Add(k-1)+Adder;
      }
      return Result;
    };
    Result = Add(n);
    return Result;
  };
},
[]);

Translating for-loops

Unit MyModule;
Interface
Function SumNNumbers(n: integer): integer;
Implementation
Function SumNNumbers(n: integer): integer;
Var
  i, j: integer;
Begin
  j:=0;
  For i:=1 To n Do
  Begin
    j:=j+i;
  End;
  if i<1 then j:=1;
  Result:=j;
End;
End.

rtl.module("MyModule",
["System"],
function(){
  this.SumNNumbers=function(n){
    Result = 0;
    j = 0;
    for (var $l1 = 1, $le2 = n; $l1 <= $le2; $l1++) {
      i = $l1;
      j = j + i;
    };
    if (i<1) j=1;
    Result = j;
    return Result;
  };
},
[]);

Translating repeat..until

Unit MyModule;
Interface
Function SumNNumbers(n: integer): integer;
Implementation
Function SumNNumbers(n: integer): integer;
Var
  i, j: integer;
Begin
  j:=0;
  i:=0;
  Repeat
    i:=i+1;
    j:=j+i;
  Until i>=n;
  Result:=j;
End;
End.

rtl.module("MyModule",
["System"],
function(){
  this.SumNNumbers=function(n){
    Result = 0;
    j = 0;
    i = 0;
    do{
      i = (i + 1);
      j = (j + i);
    } while (!(i>=n));
    Result = j;
    return Result;
  };
},
[]);

Translating while..do

Unit MyModule;
Interface
Function SumNNumbers(n: integer): integer;
Implementation
Function SumNNumbers(n: integer): integer;
Var
  i, j: integer;
Begin
  j:=0;
  i:=0;
  While i<n Do Begin
    i:=i+1;
    j:=j+i;
  End;
  Result:=j;
End;
End.

rtl.module("MyModule",
["System"],
function(){
  this.SumNNumbers=function(n){
    var Result = 0;
    var j = 0;
    var i = 0;
    while(i<n){
      i = (i + 1);
      j = (j + i);
    };
    Result = j;
    return Result;
  };
},
[]);

Translating case..do

Program MyModule;
Var
  i: integer;
Begin
  case i of
    1: ;
    2: i:=3;
  else
    i:=4;
  end;
End.

rtl.module("program",
["System"],
function(){
  var $mod = this;
  this.i = 0;
  $mod.$main=function(n){
    $tmp1 = $mod.i;
    if ($tmp1 == 1){
    } else if ($tmp1 == 2) {
      i=3;
    } else {
      i=4;
    }
  };
},
[]);

Translating with..do

Unit MyModule;
Interface
type
  TClassA = class
    i: integer;
  end;

procedure DoIt;

Implementation

procedure DoIt;
begin
  with TClassA.Create do
    i:=3;
end;

End.

rtl.module("MyModule",
["System"],
function(){
  var $mod = this;
  rtl.createClass($mod, "TClassA", pas.System.TObject, function () {
    this.$init = function () {
      this.i = 0;
    };
  });
  this.DoIt = function(){
    var $with1 = $mod.TClassA.$create("Create");
    $with1.i = 3;
  };
},
[]);

Translating enums

Unit MyModule;
Interface
type
  TMyEnum = (
    Red,
    Green,
    Blue);
var
  e: TMyEnum = Blue;

procedure DoIt;

Implementation

procedure DoIt;
begin
  e := Green;
end;

End.

rtl.module("MyModule",
["System"],
function(){
  var $mod = this;
  this.TMyEnum = {
    "0":"Red",
    Red:0,
    "1":"Green",
    Green:1,
    "2":"Blue",
    Blue:2
    };
  this.e = $mod.TMyEnum.Blue;
  this.DoIt = function(){
    $mod.e = $mod.TMyEnum.Green;
  };
},
[]);

• Supported: ord(), low(), high(), pred(), succ(), type cast number to enum.
• With optimization level -O1 the compiler uses numbers instead of names.
• Not yet implemented: custom values for enum values.

Translating sets

Unit MyModule;
Interface
type
  TColor = (Red, Green, Blue);
  TColors = set of TColor;

procedure DoIt;

Implementation

procedure DoIt;
var
  c: TColor;
  S, T: TColors;
  b: boolean;
begin
  S:=T;
  b:=Red in S;
  Include(S,Blue);
  Exclude(S,Blue);
  S:=S+T;
  S:=S-[Red,c];
  b:=c in [Red..Blue];
end;

End.

rtl.module("MyModule",
["System"],
function(){
  var $mod = this;
  this.TColor = {
    "0":"Red",
    Red:0,
    "1":"Green",
    Green:1,
    "2":"Blue",
    Blue:2
    };
  $mod.DoIt = function(){
    var c = 0;
    var S = {};
    var T = {};
    var b = false;
    S = rtl.refSet(T);
    b = $mod.TColor.Red in S;
    S = rtl.includeSet(S,$mod.TColor.Blue);
    S = rtl.excludeSet(S,$mod.TColor.Blue);
    S = rtl.unionSet(S,T);
    S = rtl.diffSet(S,rtl.createSet($mod.TColor.Red,c));
    b = c in rtl.createSet(null,$mod.TColor.Red,$mod.TColor.Blue);
  };
},
[]);

• Supported:
  • Include
  • Exclude
  • literal
  • literal range, e.g. [EnumA..EnumB], ['a'..'z']
  • union +
  • difference -
  • intersect *
  • symmetrical difference ><
  • equal =
  • unequal <>
  • subset <=
  • superset >=
  • set of anonymous enum type: set of (enum1,enum2,...)
• Not supported: set of char, set of boolean
• There is no optimization yet for small sets like in Delphi/FPC.
• Assigning a set or passing the set as an argument only creates a reference and marks the set as shared. When a shared set is altered with Include/Exclude a new set is created (copy on write).
• Passing a set as an argument might clone the set. Use the const modifier for parameters whenever possible.
• Constant sets in expressions (e.g. if c in ['a'..'z'] then) are not yet optimized and created every time. Create a const to avoid this.

Translating array type

Unit MyModule;
Interface
Type
  TIntArr = Array of integer;
  TObjArr = Array of TObject;
  TRec = record c: char; end;
  TRecArr = Array of TRec;
Procedure Test;
Implementation
Procedure Test;
Var
  IntArr: TIntArr = (1,2,3);
  ObjArr: TObjArr;
  RecArr: TRecArr;
Begin
  IntArr:=nil;
  SetLength(IntArr,4);
  IntArr[2]:=2;
  IntArr[1]:=length(IntArr);
  SetLength(ObjArr,5);
  SetLength(RecArr,2,TRec);
End;
End.

rtl.module("MyModule",
["System"],
function(){
  var $mod = this;
  this.Test = function(){
    this.TRec = function(s){
      if (s){
        this.c = s.c;
      } else {
        this.c = "";
      };
      this.$equal = function(b){
        return (this.c == b.c);
      };
    };
    this.IntArr = [1,2,3];
    this.ObjArr = [];
    this.RecArr = [];
    this.Test = function(){
      $mod.IntArr = [];
      rtl.arraySetLength($mod.IntArr,4,0);
      $mod.IntArr[2] = 2;
      $mod.IntArr[1] = $mod.IntArr.length;
      rtl.setArrayLength($mod.ObjArr,5,null);
      rtl.setArrayLength($mod.RecArr,2,$mod.TRec);
    }
  };
},
[]);

• Supported features of dynamic arrays: SetLength(), Length(), equal/notequal nil, low(), high(), assigned(), concat(), copy(), insert(), delete(), multi dimensional, array of record
• Dynamic array constants. E.g. in mode ObjFPC const a: array of byte = (1,2). In mode Delphi you must use square brackets, ... = [1,2]
• Supported features of static arrays: length(), low(), high(), assigned(), concat(), copy(), const, const records
• Open arrays are implemented as dynamic arrays.
• Calling Concat() with only one array simply returns the array (no cloning). Calling it with multiple arrays creates a clone. This is Delphi 10.1 compatible.
• In Delphi/FPC an empty array is nil. In JS it can be null or []. For compatibility comparing an array with nil checks for length(a)>0.
• function Assigned(array): boolean results true iff length(array)>0.
• array of const:
  • Works the same: vtInteger, vtBoolean, vtPointer, vtObject, vtClass, vtWideChar, vtInterface, vtUnicodeString
  • vtExtended is double, Delphi/FPC: PExtended
  • vtCurrency is currency, Delphi/FPC: PCurrency
  • Not supported: vtChar, vtString, vtPChar, vtPWideChar, vtAnsiString, vtVariant, vtWideString, vtInt64, vtQWord
  • only in pas2js: vtNativeInt, vtJSValue
• Assignation using constant array, e.g. a:=[1,1,2];
• String like operation: + operator concatenates arrays. e.g. a:=[1]+[2];. This is controlled by modeswitch arrayoperators, which is enabled in mode delphi.
• function copy(array,start=0,count=max): array
• procedure insert(item,var array,const position)
• procedure delete(var array,const start,count)

Translating class type

Unit MyModule;
Interface
Type
  TClassA = Class(TObject)
  Public
    i: integer;
    Procedure Add(a: integer);
  End;
var
  ObjA: TClassA;
Implementation
Procedure TClassA.Add(a: integer);
Begin
  i:=i+a;
End;
Initialization
  ObjA:=TClassA.Create;
End.

rtl.module("MyModule",
["System"],
function(){
  var $mod = this;
  rtl.createClass($mod,"TClassA",pas.System.TObject,function(){
    this.$init = function () {
      this.i = 0;
    };
    this.Add = function(a){
      this.i = this.i + a;
    };
  });
  this.ObjA = null;
  $mod.$init = function(){
    $mod.ObjA = $mod.TClassA.$create("Create");
  };
},
[]);

• Each class and each instance is an JS object.
• Each class has a globally unique JS object, created by rtl.createClass.
• Self is never nil.
• The method TObject.Free is using compiler magic. See Translating TObject.Free.
• Class.$class is a reference to the class itself.
• Class.$ancestor is a reference to the ancestor class.
• A class has c.$ancestor == Object.getPrototypeOf(c).
• A class instance has o.$class == Object.getPrototypeOf(o).
• Class.$classname is the short name. E.g. TClassA.$classname == 'TClassA'.
• Class.$name is the long name. E.g. TClassA.$name == 'MyModule.TClassA'.
• Class.$unitname is the unit name. E.g. TClassA.$unitname == 'MyModule'.
• The "is"-operator is implemented using "isPrototypeOf". Note that "instanceof" cannot be used, because classes are JS objects.
• The "as" operator is implemented as rtl.as(Object,Class).
• Supported: constructor, destructor, private, protected, public, strict private, strict protected, class vars, class methods, external methods, virtual, override, abstract, call inherited, assigned(), type cast, overloads, reintroduce, sealed class, nested types.
• Not supported: class constructor/destructor
• Property:
  • References are replaced by getter/setter.
  • Supported: argument lists, default property, class property, stored modifier, index modifier.
  • Not supported: getter/setter to an array element, e.g. property A: char read FArray[0];
  • Class property getter/setter are not static as in Delphi.
  • The Index modifier supports any constant, e.g. a string, while Delphi only allows an ordinal (longint). -2147483648 is not a special number in pas2js. Overriding a property with an index property is allowed in Delphi and pas2js.

Translating class-of type

Unit MyModule;
Interface
Type
  TBird = Class(TObject)
  Public
    Class var Count: integer;
    Class Procedure Add(a: integer); virtual;
  End;
  TBirds = class of TBird;

  TPigeon = Class(TBird)
  Public
    Class Procedure Add(a: integer); override;
  End;

var
  BirdType: TBirds;
Implementation
Class Procedure TBird.Add(a: integer);
Begin
  Count:=Count+a;
End;
Class Procedure TPigeon.Add(a: integer);
Begin
  inherited Add(a+1);
End;
Initialization
  BirdType:=TPigeon;
  BirdType.Add(1);
End.

rtl.module("MyModule",
["System"],
function(){
  var $mod = this;
  rtl.createClass($mod,"TBird",pas.System.TObject,function () {
    this.Count = 0;
    this.Add = function (a) {
      this.Count = this.Count + a;
    };
  });
  rtl.createClass($mod,"TPigeon",$mod.TBird,function () {
    this.Add = function (a) {
      $mod.TBird.Add.call(this,a + 1);
    };
  });
  $mod.$init = function(){
    $mod.BirdType = $mod.TPigeon;
    $mod.BirdType.Add(1);
  };
},
[]);

• Contrary to Delphi/FPC the "is" operator works with class-of.

Translating TObject.Free

• Obj.Free on a local variable or argument is translated to Obj = rtl.freeLoc(Obj);.
• Obj.Free on a non local variable is translated to rtl.free(this,"Obj");.
• Not supported: Freeing a property or function result.
  For example List[i].Free gives a compiler error. The property setter might create side effects, which would be incompatible to Delphi/FPC.

• If the destructor raises an exception, the variable is not set to nil. This is compatible to Delphi/FPC, where the memory is not freed in this case.
• Alternatively you can use FreeAndNil, which first changes the variable to nil and then calls the destructor.

Translating class interfaces

{
  $module: [object Object],
  $name: "IUnknown",
  $fullname: "System.IUnknown",
  $guid: "{00000000-0000-0000-C000-000000000046}",
  $names: ["QueryInterface","_AddRef","_Release"],
  $rtti: [object Object],
  $kind: "com",
}

{
  QueryInterface: function (){ return fn.apply(this.$o,arguments); },
  _AddRef: function (){ return fn.apply(this.$o,arguments); },
  _Release: function (){ return fn.apply(this.$o,arguments); },
  ...
}

• methods, properties, default property
• {$interfaces com|corba|default}
  
  • COM is default, default ancestor is IUnknown (mode delphi: IInterface), managed type, i.e. automatically reference counted via _AddRef, _Release, the checks for support call QueryInterface
  • CORBA: lightweight, no automatic reference counting, no default ancestor, fast support checks.
• inheriting
• An interface without a GUID gets one autogenerated from its name and method names.
• Contrary to Delphi/FPC you can assign an interface type or var to the type TGuidString.
• a class implementing an interface must not be external
• a ClassType "supports" an interface, if it itself or one of its ancestors implements the interface. It does not automatically support an ancestor of the interface.
• method resolution, procedure IUnknown._AddRef = IncRef;
• delegation: property Name: interface|class read Field|Getter implements AnInterface;
• is-operator:
• IntfVar is IntfType - types must be releated
• IntfVar is ClassType - types can be unrelated, class must not be external
• ObjVar is IntfType - can be unrelated
• as-operator
• IntfVar as IntfType - types must be releated
• IntfVar as ClassType - types can be unrelated, nil returns nil, invalid raises EInvalidCast
• ObjVar as IntfType - can be unrelated, nil if not found, COM: uses _AddRef
• typecast:
• IntfType(IntfVar) - must be related
• ClassType(IntfVar) - can be unrelated, nil if invalid
• IntfType(ObjVar) - nil if not found, COM: if ObjVar has delegate uses _AddRef
• TJSObject(IntfTypeOrVar)
• jsvalue(intfvar)
• Assign operator:
• IntfVar:=nil;
• IntfVar:=IntfVar2; - IntfVar2 must be same type or a descendant
• IntfVar:=ObjVar; - nil if unsupported
• jsvalue:=IntfVar;
• TGUIDVar:=IntfType;
• TGUIDVar:=IntfVar;
• TGUIDVar:=stringconstant;
• TGUIDStringVar:=IntfVar;
• StringVar:=GuidVar;
• Equal/Inequal operator:
• IntfVar=nil;
• IntfVar=IntfVar2; - must be related
• jsvalue=IntfVar;
• TGUIDVar=IntfType;
• TGUIDVar=IntfVar;
• TGUIDVar=string;
• TGUIDStringVar=IntfVar;
• Passing an COMIntfVar to an untyped parameter does not trigger _AddRef, _Release.
• Assigned(IntfVar)
• RTTI, typeinfo(IntfType), typeinfo(IntfVar)

Translating helpers

• A class helper can "extend" Pascal classes and external JS classes.
• A record helper can "extend" a record type. In $mode delphi a record helper can extend other types as well, see type helper
• A type helper can extend all base types like integer, string, char, boolean, double, currency, and user types like enumeration, set, range, array, class, record and interface types. It cannot extend helpers and procedural types.
  Type helpers are enabled by default in $mode delphi and disabled in $mode objfpc. You can enable them with {$modeswitch typehelpers}.
• By default only one helper is active per type, same as in FPC/Delphi. If there are multiple helpers for the same type, the last helper in scope wins.
  A class with ancestors can have one active helper per ancestor type, so multiple helpers can be active, same as FPC/Delphi.
  Using {$modeswitch multihelpers} you can activate all helpers within scope.
• Nested helpers (e.g. TDemo.TSub.THelper) are elevated. Visibility is ignored. Same as FPC/Delphi.
• Helpers cannot be forward defined (e.g. no THelper = helper;).
• Helpers must not have fields.
• Class Var, Const, Type
• Visibility : strict private .. published
• Function, procedure: In class and record helpers Self is the class/record instance. For other types Self is a reference to the passed value.
• Class function, class procedure: Helpers for Pascal classes/records can add static and non static class functions. Helpers for external classes and other types can only add static class functions.
• Constructor. Not for external classes. Works similar to construcors, i.e. THelpedClass.Create creates a new instance, while AnObj.Create calls the constructor function as normal method. Note that Delphi does not allow calling helper construcors as normal method.
• no destructor
• Property : getters/setters can refer to members of the helper, its ancestors and the helped class/record.
• Class property : getter can be static or non static. Delphi/FPC only allows static.
• Ancestors : Helpers can have an ancestor helper, but they do not have a shared root class, especially not TObject.
• no virtual, abstract, override. Delphi allows them, but 10.3 crashes when calling.
• inherited : inherited inside a method of a class/record calls helper of ancestor.
  inherited inside a helper depends on the $mode:
  • $mode objfpc : inherited; and inherited Name(args); work the same and searches first in HelperForType, then in ancestor(s).
  • $mode delphi: inherited; : skip ancestors and HelperForType, searches first in helper(s) of ancestor of HelperForType.
  • $mode delphi: inherited name(args); : same as $mode objfpc first searches in HelperForType, then Ancestor(s)
  In any case if inherited; has no ancestor to call, it is silently ignored, while inherited Name; gives an error.
• RTTI: typeinfo(somehelper) returns a pointer to TTypeInfoHelper with Kind tkHelper.
• There are some special cases when using a type helper function/procedure on a value:
  • function result : using a temporary variable
  • const, const argument : When helper function tries to assign a value, pas2js raises a EPropReadOnly exception. FPC/Delphi use a temporary variable allowing the write.
  • property : uses only the getter, ignoring the setter. This breaks OOP, as it allows to change fields without calling the setter. This is FPC/Delphi compatible.
  • with value do ; : uses a temporary variable. Delphi/FPC do not support it.
• A method with external name modifier is treated as an external method of the helped type.

Translating attributes

Translating try..finally

Translating try..except

Unit MyModule;
Interface
Uses SysUtils, Math, JS;
Function DoIt(n: integer): double;
Implementation
Function DoIt(n: integer): double;
var E: Exception;
Begin
  try
    Result:=double(7.0)/n;
    if not IsFinite(Result) then
      if n=0 then
        raise EZeroDivide.Create
      else
        raise EOverflow.Create;
  except
    on EZeroDivide do Result:=0.0;
    on E2: EOverflow do Result:=0.0;
    else
      raise EAbort.Create('Something other: '+String(JS.JSExceptObject));
  end;
End;
End.

rtl.module("MyModule",
["System","SysUtils"],
function(){
  this.DoIt=function(n){
    Result = 0;
    var E = null;
    try{
      Result = 7.0 / n;
      if (!IsFinite(Result)){
        if (n==0){
          throw pas.SysUtils.EZeroDivide.$create("Create");
        } else {
          throw pas.SysUtils.EOverflow.$create("Create");
        };
      };
    }catch($e){
      if (pas.SysUtils.EZeroDivide.isPrototypeOf($e)){
        Result = 0.0;
      } else if (pas.SysUtils.EOverflow.isPrototypeOf($e)){
        var E2 = $e;
        Result = 0.0;
      } else {
        throw pas.SysUtils.EAbort.$create("Create",["Something other: "+(""+$e)]);
      }
    }
    return Result;
  };
},
[]);

• Division by zero does not raise an exception in JavaScript. Instead it results in Infinity, except for 0/0 which results in NaN.
• There is no ExceptObject in SysUtils.
• When calling external functions keep in mind that JS allows to throw (raise) any value, often a string.
  You can access the current except value via JSExceptValue in unit JS.
  Note that this is only valid inside the catch-block. The compiler will not warn, if you use it outside.

Translating enumerators

• ordinal types like char, boolean, byte, ..., longword, enums, custom ranges are translated to a for loop.
• set types are translated to a for loop, while const sets and set variables are enumerated via a for(...in...) loop.
• string and array variables are enumerated via for loops.
• for aString in ArrayOfString do ...
• for key in jsvalue do translates to for (key in jsvalue){}
• for key in ExternalClass do
  
  • If the externalclass has a ''length'' and a matching default property it uses the enumeration of an array. For example for value in TJSArray do enumerates the values of the array, not the index. It checks if the array is nil.
  • Otherwise it translates to for (key in externalclass){}, which enumerates the keys (property names) of the JS object.

Unit MyModule;
Interface

uses Classes;

procedure DoIt(List: TList);

Implementation

procedure DoIt(List: TList);
var
  Item: Pointer;
begin
  for Item in List do
    if Item<>nil then ;
end;

End.

rtl.module("MyModule",
["System","Classes"],
function(){
  this.DoIt=function(List){
    var Item = null;
    var $in1 = List;
    try {
      while ($in1.MoveNext()) {
        Item = $in1.GetCurrent();
        if (Item !== null) ;
      }
    } finally {
      $in1 = rtl.freeLoc($in1)
    };
  };
},
[]);

• Not supported: operator Enumerator, member modifier enumerator (i.e. custom Current and MoveNext)

Translating function types

Program MyModule;
type
  TMyMethod = procedure(n: integer) of object;
  TBird = class
    procedure DoIt(n: integer); virtual; abstract;
  end;
  TMyProc = procedure(n: integer);
procedure DoSome(n: integer);
begin
end;
var
  m: TMyMethod;
  Bird: TBird;
  p: TMyProc;
Begin
  m:=@Bird.DoIt;
  m(3);
  p:=@DoSome;
  p(4);
End.

rtl.module("program",
["System","UnitA"],
function(){
  var $mod = this;
  rtl.createClass($mod,"TBird",pas.System.TObject,function(){
    this.DoIt = function (n) {
    };
  });
  this.DoSome = function (n) {
  };
  this.m = null;
  this.Bird = null;
  this.p = null;
  $mod.$main = function() {
    $mod.m = rtl.createCallback($mod.Bird,"DoIt");
    $mod.m(3);
    $mod.p = $mod.DoSome;
    $mod.p(4);
  };
},
[]);

rtl = {
  ...
  createCallback: function(scope, fn){
    var cb = function(){
      return scope[fn].apply(scope,arguments);
    };
    cb.scope = scope;
    cb.fn = fn;
    return cb;
  },
  ...

• You can assign a nested procedure to procedure variable. You don't need and you must not add the FPC "is nested" modifier.
• A procedural typed declared as 'reference to' accepts in pas2js procedures, local procedures and methods. Delphi only supports capturing procedures and methods. FPC 3.0.4 does not support reference-to.

Translating anonymous functions

Program MyModule;
type
  TAdder = reference to function(n: integer): integer;

function CreateAdder(a: integer): TAdder;
begin
  Result:=function(b: integer)
    begin
      Result:=a+b;
    end;
end;

var
  Adder: TAdder;
Begin
  Adder:=CreateAdder(3);
  writeln(Adder(5)); // gives 8
End.

Program MyModule;
type
  TAdder = reference to function(n: integer): integer;

function CreateAdder(a: integer): TAdder;
  function Add(b: integer): integer;
  begin
    Result:=a+b;
  end;
begin
  Result:=@Add;
end;

var
  Adder: TAdder;
Begin
  Adder:=CreateAdder(3);
  writeln(Adder(5)); // gives 8
End.

Translating var modifier absolute

Translating assert()

• Command line enable with -Sa, disable with -Sa-
• In code enable with {$C+} or {$Assertions on}, disable with {$C-} or {$Assertions off}

Calling JavaScript from Pascal

The asm block

Program MyModule;
var
  s: string;
Begin
  s = 'Hello World!';
  Asm
    console.log(s);
  End;
End.

rtl.module("program",
["System"],
function(){
  var $mod = this;
  this.s = '';
  $mod.$main = function(){
    $mod.s = "Hello World!";
    console.log(s);
  };
},
[]);

• The block is indented to produce more readable JS code. All lines are indented or unindented the same amount, i.e. sub indentation is kept.
• The compiler does neither parse, nor check the syntax of the JS.
• The compiler does not know what Pascal identifiers are used by the asm-block and might remove them, if no Pascal code is using them. To make sure that an identifier is kept, add some dummy code like if MyVar=0 then;
• Accessing an interface, program or library identifier:
  
  • From inside the module you can use $mod.Identifier.
  • Otherwise use the fully qualified path pas.Unitname.Identifier.
• Accessing an implementation identifier:
  
  • From inside the unit you can use $impl.Identifier.
  • Otherwise use the path pas.Unitname.$impl.Identifier.
• Accessing a class instance member (field, procedure, function, constructor, destructor) from a method of the class: use this.Identifier. Inside a nested function of a method you use the Self.Identifier.
• Accessing a class member (class var, class procedure, class function) from a method of the class: for writing use this.$class.Identifier, for reading you can omit the $class.
• Accessing a class member (class var, class procedure, class function) from a class method of the class: use this.Identifier.
• Access to Properties must use the getter/setter.
• When calling a Pascal method, make sure the this is correct:
  • A class method (e.g. class function, class procedure) needs the class as this.
    Wrong: aCar.DoIt(params,...)
    Correct: aCar.$class.DoIt(params,...)
    
• Calling a Pascal function from a HTML/DOM-element: For example to call a function when user clicks a DOM element you can assign a function to the onclick property. This will call the function with this set to the DOM element.
  Pascal methods needs a wrapper to set this to the instance. Examples:
  • An unit function: DOMElement.onclick = $mod.DoIt;
  • An implementation function: DOMElement.onclick = $impl.DoIt;.
  • A method: DOMElement.onclick = this.DoIt.bind(this);
  • A class function/procedure: DOMElement.onclick = this.DoIt.bind(this.$class);
  • A nested function: DOMElement.onclick = DoIt;.

The procedure modifier assembler

Program MyModule;

Procedure Log(const s: string); assembler;
Asm
  console.log(s);
end;

Begin
  Log('Hello World!');
End.

rtl.module("program",
["System"],
function(){
  var $mod = this;
  this.Log = function(s){
    console.log(s);
  };
  $mod.$main = function(){
    $mod.Log("Hello World!");
  };
},
[]);

The procedure modifier external

Program MyModule;
Procedure ConsoleLog(const s: string); external name 'console.log';
// Note: an external procedure has no begin..end block
Begin
  ConsoleLog('Hello World!');
End.

rtl.module("program",
["System"],
function(){
  var $mod = this;
  $mod.$main = function(){
    console.log("Hello World!");
  };
},
[]);

The procedure modifier varargs

Program MyModule;
uses JS;
function Sum(b: boolean): longint; varargs;
var i: longint;
begin
  if b then
    asm
      for (var i=0; i<arguments.length; i++) Result+=arguments[i];
    end
  else
    for i:=0 to JSArguments.length-1 do
      Result:=Result+longint(JSArguments[i]);
end;
var
  i: integer;
Begin
  i:=Sum(true,2,4,6); // i=12
  i:=Sum(false,2,4,6); // i=12
End.

rtl.module("program",
["System","JS"],
function(){
  var $mod = this;
  this.Sum = function(b){
    var Result = 0;
    var i = 0;
    if (b){
      for (var i=0; i<arguments.length; i++) Result+=arguments[i];
    } else {
      for (var $l1 = 1, $le2 = argumens.length; $l1 <= $le2; $l1++){
        $i = $l1;
        Result = Result + arguments[i];
      }
    }
    return Result;
  };
  this.i = 0;
  $mod.$main = function(){
    $mod.i = $mod.Sum(true,2,4,6);
    $mod.i = $mod.Sum(false,2,4,6);
  };
},
[]);

The var modifier external

Program MyModule;
var
  EulersNumber: Double; external name 'Math.E';
  d: double;
Begin
  d:=EulersNumber;
End.

rtl.module("program",
["System"],
function(){
  var $mod = this;
  this.d = 0.0;
  $mod.$main = function(){
    $mod.d = Math.E;
  };
},
[]);

The external modifier of class members

Program MyModule;
{$modeswitch externalclass}
type
  TWrapper = class
  private
    // let's assume this object has the properties "$Handle", "$id", and "0"
  public
    Id: NativeInt; external name '$Id';
    x: NativeInt; external name '[0]';
    y: NativeInt; external name '["A B"]';
    function GetState(typ: longint): NativeInt; external name '$Handle.GetState';
    procedure DoIt;
  end;
procedure TWrapper.DoIt;
begin
  Id := GetState(4);
end;
var
  W: TWrapper;
Begin
  W.Id := 2;
  W.x := 3;
  W.y := 4;
  W.GetState(5);
End.

rtl.module("program",
["System"],
function(){
  var $mod = this;
  rtl.createClass($mod, "TWrapper", pas.System.TObject, function () {
    this.DoIt = function(){
      this.$Id = this.$Handle.GetState(4);
    };
  });
  this.W = null;
  $mod.$main = function(){
    $mod.W.$Id = 2;
    $mod.W[0] = 3;
    $mod.W["A B"] = 4;
    $mod.W.$Handle.GetState(5);
  };
},
[]);

• Non identifiers like "0" or "A B" must be enclosed in brackets.

External classes

Program MyModule;
{$modeswitch externalclass}
type
  TJSDate = class external name 'Date'
  private
    function getYear: NativeInt;
    procedure setYear(const AValue: NativeInt);
  public
    constructor New;
    constructor New(const MilliSecsSince1970: NativeInt);
    class function now: NativeInt;
    property Year: NativeInt read getYear write setYear;
  end;
var
  d: TJSDate;
Begin
  d:=TJSDate.New;
  d.Year:=d.Year+1;
End.

rtl.module("program",["System"],function () {
  var $mod = this;
  this.d = null;
  $mod.$main = function () {
    $mod.d = new Date();
    $mod.d.setYear($mod.d.getYear() + 1);
  };
});

• Any class instance can be type casted to any root class.
• A Pascal class can descend from an external class.
• You can define a class-of external class and the is and as operators work similar.
• Class variables work as in JavaScript. That means, each descendant and each instance can have its own value. For example TExtA.Value might be different from InstanceExtA.Value. Setting InstanceExtA.Value does not change TExtA.Value.
• Const with an expression are replaced by the expression.
• Const without an expression are treated as a readonly variable.
• Class functions and class procedures are allowed, but can only be called via the class, not via an instance.
  For example you can call the class function TJSString.fromCharCode(), but you cannot call aJSString.fromCharCode().
• An external class can descend from another external class.
• Since class types are JS objects it is possible to typecast a class type to the JS Object, e.g. TJSObject(TObject). Note that you cannot typecast directly to a TJSObject descendant in $mode objfpc. You can use TJSWindow(TJSObject(ExtClassInstance)).
• You can typecast function addresses and function references to JS function, e.g. TJSFunction(@SomeProc), TJSFunction(OnClick). Keep in mind that typecasting a method address creates a function wrapper to bind the Self argument.

External class as ancestor

Program MyModule;
{$modeswitch externalclass}
type
  TExtA = class external name 'ExtA'
  end;
  TMyB = class(TExtA)
  protected
    class function NewInstance(fnname: string; const paramarray): TMyB; virtual;
  end;
class function TMyB.NewInstance(fnname: string; const paramarray): TMyB;
Begin
  asm
  Result = Object.create(ExtA);
  end;
End;

Begin
End.

rtl.module("program",["System"],function () {
  var $mod = this;
  rtl.createClassExt($mod, "TMyB", ExtA, "NewInstance", function () {
    this.$init = function () {
    };
    this.$final = function () {
    };
    this.NewInstance = function (fnname, paramarray) {
      var Result = null;
      Result = Object.create(ExtA);
      return Result;
    };
  });
  $mod.$main = function () {
  };
});

The JSValue type

• A JSValue variable initial value is undefined.
• Operators: =, <>
• type casting a JSValue to ...
  • Integer: Math.floor(aJSValue) Note: may return NaN
  • Boolean: !(aJSValue == false) Note: works for numbers too, 0==false
  • Double: rtl.getNumber(aJSValue) Note: typeof(n)=="number"?n:NaN;
  • String: ""+aJSValue
  • Char: rtl.getChar(aJSValue) Note: ((typeof(c)!="string") && (c.length==1)) ? c : ""
  • class instance or class-of: rtl.getObject() Note: checks for type "object"
  • enum type
  • pointer
• A JSValue in a conditional expressions If aJSValue then, while aJSValue do, repeat until aJSValue has the same meaning as in JS: the condition is true, if the value is not undefined, false, null, NaN, 0, ''. Note that new Boolean(false) is not null and the condition is true.
• function Assigned(V: jsvalue): boolean returns true if
  (V!=undefined) && (V!=null) && (!rtl.isArray(V) || (V.length > 0))
• function StrictEqual(const A: jsvalue; const B): boolean
• function StrictInequal(const A: jsvalue; const B): boolean
• Any array can be assigned to an array of jsvalue.
• is-operator: jsvalue is class-type, jsvalue is class-of-type
  
• The unit JS provides many utility functions for JSValue, like hasString, hasValue, isBoolean, isNumber, isInteger, isObject, isClass, isClassInstance, etc..

Accessing JS object properties with the bracket accessor

Program MyModule;
{$modeswitch externalclass}
type
  TExtA = class external name 'ExtA'
  private
    function GetItems(Index: integer): String; external name '[]';
  public
    property Items[Index: integer]: String read GetItems; default;
  end;
var
  Obj: TExtA;
  s: String;
Begin
  ... get Obj from somewhere ...
  s:=Obj[2];
End.

rtl.module("program",["System"],function () {
  var $mod = this;
  this.Obj = undefined;
  this.s = "";
  $mod.$main = function () {
    $mod.s = Obj[2];
  };
});

• A property can have a mix of normal accessor and bracket accessor. For example a bracket accessor as getter and a normal function as setter.

RTTI - Run Time Type Information

    TTypeInfo = class external name 'rtl.tTypeInfo'
    public
      Name: String external name 'name';
      Kind: TTypeKind external name 'kind';
    end;
    TTypeInfoClass = class of TTypeInfo;

    TTypeInfoInteger = class external name 'rtl.tTypeInfoInteger'(TTypeInfo)
    public
      MinValue: NativeInt external name 'minvalue';
      MaxValue: NativeInt external name 'maxvalue';
      OrdType : TOrdType external name 'ordtype';
    end;
    

Compiler directives

• #IFDEF macroname
• #IFNDEF macroname
• #IF expression - same as $if, except only defines
• #ELSEIF
• #ELSE
• #ENDIF
• #ERROR text

• {$Define MacroName}: defines macro MacroName with value '1'.
• {$Define MacroName:=value}: defines macro MacroName with custom value.
• {$Undef MacroName}: undefines macro MacroName.
• {$IfDef MacroName}: if MacroName is not defined, skip to next $Else or $EndIf. Can be nested.
• {$IfNDef MacroName}: as $IfDef, except negated.
• {$If boolean expression}: if expression evaluates to true (not '0'), skip to next $Else or $EndIf. Can be nested.
  Supported functions and operators:
  
  • macro - replaced by its value, a simple define has value '1'
  • defined(macro) - '1' if defined, '0' otherwise
  • undefined(macro) - as not defined(macro)
  • option(letter) - same as {$IFOpt letter+}
  • not - first level of precedence
  • *, /, div, mod, and, shl, shr - second level of precedence
  • +, -, or, xor - third level of precedence
  • =, <>, <, >, <=, >= - fourth level of precedence
  • If the operands can be converted to numbers they are combined as numbers, otherwise as strings.
  Not supported functions and operators:
  
  • defined(Pascal identifier), undefined(Pascal identifier)
  • declared(Pascal identifier)
  • in operator
• {$IfOpt Letter+,-}: if expression evaluates to true (not '0'), skip to next $Else or $EndIf. Can be nested.
• {$Else}: If previous $IfDef, $If or $IfOpt was skipped, execute next block, otherwise skip.
• {$ElseIf boolean expression}: As $Else, except with an extra expression like $if to test. There can be multiple $elseif.
• {$EndIf}: ends an $IfDef block
• {$mode delphi} or {$mode objfpc}: Same as -Mdelphi or -Mobjfpc, but only for this unit. You can use units of both modes in a program. If present must be at the top of the unit, or after the module name.
• {$modeswitch externalclass}: allow declaring external classes
• {$modeswitch arrayoperators}: allow + operator to concatenate arrays, default in mode delphi
• {$macro on|off} enables macro replacements. Only macros with a value are replaced. Macros are never replaced inside directives.
• {$I filename} or {$include filename} - insert include file
• {$I %param%}:
  • %date%: current date as string literal, '[yyyy/mm/dd]'
  • %time%: current time as string literal, 'hh:mm:ss'. Note that the inclusion of %date% and %time% will not cause the compiler to recompile the unit every time it is used: the date and time will be the date and time when the unit was last compiled.
  • %file%: current source filename as string literal, e.g. 'unit1.pas'
  • %line%: current source line number as string literal, e.g. '123'
  • %linenum%: current source line number as integer, e.g. 123
  • %currentroutine%: name of current routine as string literal
  • %pas2jstarget%, %pas2jstargetos%, %fpctarget%, %fpctargetos%: target os as string literal, e.g. 'Browser'
  • %pas2jstargetcpu%, %fpctargetcpu%: target cpu as string literal, e.g. 'ECMAScript5'
  • %pas2jsversion%, %fpcversion%: compiler version as strnig literal, e.g. '1.0.2'
  • If param is none of the above it will use the environment variable. Keep in mind that depending on the platform the name may be case sensitive. If there is no such variable an empty string '' is inserted.
• {$Warnings on|off}
• {$Notes on|off}
• {$Hints on|off}
• {$Error text} : emit an error
• {$Warning text} : emit a warning
• {$Note text} : emit a note
• {$Hint text} : emit a hint
• {$Message hint-text} : emit a hint
• {$Message hint|note|warn|error|fatal text} : emit a message
• {$Warn identifier on|off|default|error} : enable or disable a specific hint.
  Note, that some hints like "Parameter %s not used" are currently using the enable state at the end of the module, not the state at the hint source position.
  Identifier can be a message number as written by -vq or one of the following case insensitive:
  
  • CONSTRUCTING_ABSTRACT: Constructing an instance of a class with abstract methods.
  • IMPLICIT_VARIANTS: Implicit use of the variants unit.
  • NO_RETVAL: Function result is not set
  • SYMBOL_DEPRECATED: Deprecated symbol.
  • SYMBOL_EXPERIMENTAL: Experimental symbol
  • SYMBOL_LIBRARY
  • SYMBOL_PLATFORM: Platform-dependent symbol.
  • SYMBOL_UNIMPLEMENTED: Unimplemented symbol.
  • HIDDEN_VIRTUAL: method hides virtual method of ancestor
  • GARBAGE: text after final end.
  • BOUNDS_ERROR: range check errors
  • MESSAGE_DIRECTIVE: user defined $message
• {$M+}, {$TypeInfo on}: switches default visibility for class members from public to published
• {$ScopedEnums on|off} disabled(default): propagate enums to global scope, enable: needs fqn e.g. TEnumType.EnumValue.
• {$C+} generate code for assertions
• {$H+}, but not {$H-}
• {$J-}, {$WriteableConst off}: Typed const become readonly. For example const i:byte=3; ... i:=4 creates a compile time error.
• {$M+} : allow published members
• {$Q+} : not yet supported, ignored
• {$R+}, {$RangeChecks on}: compile time range check hints become errors and add runtime range checks for assignments.
• {$ObjectChecks on|off}:
  • Verify method calls, i.e. check at runtime in every method if Self is a descendant class.
  • Check type casts, e.g. TBird(AnObject) becomes AnObject as TBird

• PASJS
• PAS2JS_FULLVERSION - major*1000+minor*100+release, e.g. 1.2.3 = 10203
• Target platform: Browser, NodeJS, Pas2JSTargetOS=<value>
• Target processor: ECMAScript5, ECMAScript6, ECMAScript=5, Pas2JSTargetCPU=<value>
• Mode: DELPHI, OBJFPC

Numbers

• Byte - unsigned 8-bit
• ShortInt - signed 8-bit
• Word - unsigned 16-bit
• SmallInt - signed 16-bit
• LongWord - unsigned 32-bit
• LongInt - signed 32-bit
• NativeUInt - unsigned 52-bit
• NativeInt - signed 53-bit

• Division by zero does not raise an exception. 0/0 results in NaN, positive/0 is Infinity, negative/0 is -Infinity.
• NaN<>NaN
• Overflows work differently. For example in Delphi adding 100 to a byte of 200 gives 300 and $ff = 44, while in pas2js it gives 300, which is not a byte anymore.
• Math.isNan(double) tests for NaN. Otherwise false. isNan(Infinity)=false.
• Math.isFinite(double) tests if not NaN, positive or negative infinity.
• Math.isInfinite(double) tests if positive or negative infinity.
• For more functions see unit Math.
• To make porting easier Single is defined in the system unit as alias of double, but gives a warning. Since using higher precision might give unexpected results you should check every place.

Other supported Pascal elements

• break, continue, exit, exit()
• chr, ord
• alias type and type alias type
• inc()/dec() to += -=
• Converts "a div b" to "Math.floor(a / b)"
• and, or, xor, not: logical and bitwise
• Name conflicts with JS identifiers are automatically fixed by changing case. For example a Pascal function "apply" is renamed to "Apply".
• uses unitname in 'filename'. In $mode delphi the in-filenames are only allowed in the program and the unitname must fit the filename, e.g. uses unit1 in 'sub/Unit1.pas'.
  In $mode objfpc units can use in-filenames too and alias are allowed, e.g. uses foo in 'bar.pas'.
• The intrinsic procedure str works with boolean, integer, float and enumvalue.
  Additionally there is str function, that takes an arbitrary number of arguments and returns a concatenated string. It supports string as parameter too. For example s:=str(i,' ',d:1:5).
  Width and precision is supported. str(i:10) will add spaces to the left to fill up to 10 characters. str(aDouble:1:5) returns a string in decimal format with 5 digits for the fraction.
• Intrinsic procedure WriteStr(out s: string; params...)
• Debugger; converts to debugger;. If a debugger is running it will break on this line just like a break point.
• function concat(string1,string2,...): string since 1.3
• $mode delphi: function lo|hi(integer): byte since 1.3
• $mode objfpc: function lo|hi(integer): byte|word|longword since 1.3

Not supported elements

• Attributes
• Class constructor, class destructor
• Enums with custom values
• Generics
• Global properties
• Futures
• Inline
• Library
• Objects
• Operator overloading
• Pointer arithmetic
• Package
• Resources
• RTTI extended, $RTTI
• Runtime checks: Overflow -Co, $Q
• Variant records
• Variants

JavaScript Version

• ECMAScript5
• ECMAScript6: using 0b for binary literals, and 0o for octal literals

Creating source maps