Pas2js is an open source Pascal to JavaScript transpiler. It parses Object Pascal and emits JavaScript.
The JavaScript is currently of level ECMAScript 5 and should run in any browser or in Node.js (target "nodejs").
It is available in 5 forms:
as a library
as a command-line program
as a webserver
as a node.js program
as a program running in the browser.
It transpiles from actual Pascal source, it has no intermediate .ppu files.
That means all sources must always be available.
Through external class definitions, the compiler can use JavaScript classes:
All classes available in the JavaScript runtime, and in the browser are available
through import units (comparable to the windows or unix units for the native compiler).
For Node.js, basic support for the nodejs runtime environment is available.
An import unit for jQuery is available (libjquery)
As a non commercial open source project we are always searching for helping hands. If you want to contribute see here.
This project is not related to a similar named project on github.
For the generated code to work, a small JavaScript file is needed: rtl.js. It defines an object rtl.
This object will start the Object Pascal code if you include a call to rtl.run() in the HTML page.
On the left, go to Modules tab, select pas2js-rtl then click Install module.
Pas2JS will be installed in the ccr subdirectory in the selected install path (defaults to C:\fpcupdeluxe on Windows and ~/fpcupdeluxe on UNIXes) - including pas2js binary, pas2js.cfg which may already present in your FPC installation
The sources are available on gitlab, and a read-only mirror exists on github.
The makefile expects the sources of FPC to be present under the compiler directory.
You can copy/clone the FPC sources there or set enviroment variable FPCDIR.
Note that a symlink to the FPC sources will not work.
This creates bin/$(TargetCPU)-$(TargetOS)/pas2js (Windows: pas2js.exe). For example on Linux 64bit it creates bin/x86_64-linux/pas2js, while under Windows 64bit it creates bin\x86_64-win\pas2js.exe.
And a basic config file bin/x86_64-linux/pas2js.cfg.
Make sure that you use the make.exe from fpc, not the one from Delphi by setting the
PATH: For example if you installed the 32-bit version of fpc in
C:\YourPathOfFPC\3.2.2:
If you see "Error makefile ... Command syntax error" your "set PATH" was
not correct.
When make all has succesfully finished it created with a 32-bit fpc the executable
bin/i386-win32/pas2js.exe and a basic config file
bin/i386-win32/pas2js.cfg.
The command-line arguments are kept mostly the same as the FPC command-line arguments.
Error messages are also in the same format.
The compiler needs access to all sources, and so you need to specify the path to the sources of
all used units.
As for the FPC compiler, a configuration file is supported, which has the same syntax as the FPC config file. Note that the snapshots and svn version already contains a default pas2js.cfg with unit search paths (-Fu) for the rtl and fcl. See here how for details about the pas2js.cfg.
Basically, the command is the same as any FPC command line. The only thing that is different is the target: -Tbrowser or -Tnodeejs
A significant amount of Object Pascal syntax is supported, including RTTI.
A more detailed list can be found in the Pas2js Transpiler file in the sources.
arrays static, dynamic, open, multi dimensionals, array of const
String like array operations: a:=[1,2,3]+[1,1];
class type, visibility, virtual, override, abstract, overload, properties, class properties, class var, class const, constructor, destructor, class constructor (since 1.5)
To import a javascript class, one writes a normal class definition that mimics the Javascript class.
It is possible to use properties. Many examples can be found in the JS, web, nodejs and libjquery units.
This declares the TJSFunction object : in Javascript, functions are objects.
The "external name 'Function'" means that you declare a Javascript class where the Javascript name of the class is 'Function'.
The (TJSObject) means it descends from TJSObject also an external class. There does not need to be an ancestor type.
Fields are declared just as in Pascal.
To declare read-only fields, a trick can be used: declare the field using an external name "thename" modifier, and declare a read-only property with the same name.
(see the length declaration)
Varargs can be used to indicate that a function accepts any number of arguments.
JSValue can be used to indicate an unknown type.
It is more or less equivalent to a Variant.
The pas2js transpiler can generate a JSON file (extension .jrs) with all the resource strings in your program.
This is a quite simple file. A JSON object exists for every unit, with each json property a resource string.
{
"trs2" : {
"ResUsed" : "This resourcestring is used",
"ResUnUsed" : "This resourcestring is not used",
"ImplResUsed" : "This implementation resourcestring is used"
},
"trs1" : {
"MyString" : "The very nice string we will need to translate"
}
}
This file can be translated, and the translation file can be loaded using the rstranslate unit, part of the rtl.
There are demo programs which demonstrate the use of this feature.
The generating of this file is controlled by the -Jr option. It can take 3 possible arguments:
none This is the default, no file is generated.
unit one file per compiled unit will be generated. This file will contain all resource strings of the unit.
program one file is generated for the main file. This fill will contain all used resource strings for the main file and all the units it uses.
If you compile a program, then the program option will generate a file with all the used resource strings in your program.
The above example was generated using the command:
pas2js -Jrprogram trs1.pp -B
Note that the format is different from the format used by FPC:
Identifiers in the file are case sensitive: the names must be typed as they appear in the source file.
The strings are grouped per unit, this allows to load them fasters
The hash and bytes parts are missing, they make little sense in a Javascript context.
Exceptions are translated to actual Javascript exceptions. The rtl.js has several mechanisms to deal with uncaught exceptions.
The basic mechanism is setting the showUncaughtExceptions to true before calling rtl.run() in your html file:
The generated Javascript source code is of course visible and debuggable in the browser.
Moreover, the transpiler can generate a source map, which means that you will be able to see and debug the Pascal code in the browser.
(not everything will work, but many things do. This depends on the browser too.)
A source map can be generated using the command-line parameter:
-Jm
The easiest is to include the Pascal sources in the source map:
-Jminclude
By default all source filenames are relative to .js.map. You can tell the compiler to store all file names relative to a specific local base directory:
-Jmbasedir=DirName
And you can store an URL in the map, so the browser will use URL/above-relative-file-name to get the source:
See here for tips and traps porting code from FPC and Delphi.
Delphi cannot parse some of the constructs that exist in pas2js (namely: external classes).
You can create stub declarations suitable for the Delphi parser with the stub creator.
This is mainly due to the used rtl.js. The rtl.js contains code for Pascal modules, classes, RTTI, sets, range checks, etc and is written with big WebApps in mind, not for scripts with a few lines of code.
You can use a Javascript minifier to reduce the created Javascript
You can create your own minified rtl.js by removing all functions you don't need. Eventually this will be done automatically by pas2js.
Asm blocks are useful for things you cannot do with pas2js. But there are some downsides:
pas2js does not parse the JS. Neither does it check the syntax, nor does it know what Pascal identifiers the code is referencing. That means any identifier only accessed by the asm block will be removed by the pas2js' optimizer.
Therefore always try to do it in Pascal. Remember you can typecast values to JSValue, objects to TJSObject, arrays to TJSArray, strings to TJSString, etc to use almost all JS features.
Any compiletime JS parser can only do a syntax check and parse only simple JS. But since simple JS can be better written in Pascal, it is somewhat pointless and has therefore low priority.