Pas2js Transpiler: what changed
Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | 1 | ## About pas2js | |
| 2 | 2 | ||
| 3 | 3 | pas2js is a compiler/transpiler to translate programs written in Pascal (subset of Delphi/ObjFPC syntax) to JavaScript.\ | |
| 4 | 4 | The goal is to use strong typing, while still be able to use low level whenever you choose.\ | |
| 5 | 5 | The compiled Pascal functions can be used in DOM events or called by JavaScript.\ | |
| 6 | 6 | pas2js is written completely in FPC, runs on many platforms like Windows, Mac and Linux and more. It is built modular consisting of the following parts: | |
| 7 | 7 | ||
| 8 | 8 | - file cache - loading, caching files, converting to UTF-8 | |
| 9 | 9 | - file resolver - handling search paths, finding used units and include files | |
| 10 | 10 | - scanner - reading tokens, handling compiler directives like \$IfDef and \$Include | |
| 11 | 11 | - parser - reading the tokens, checking syntax, creating Pascal nodes | |
| 12 | 12 | - resolver - resolving references, type checking and checking duplicate identifiers | |
| 13 | 13 | - use analyzer - finding unused identifiers, emit hints and warning | |
| 14 | 14 | - converter - translating Pascal nodes into JavaScript nodes | |
| 15 | 15 | - compiler - handling config files, parameters, compiling recursively all used units, writes js | |
| 16 | 16 | - command line interface - a small wrapper to embed the compiler into a console program | |
| 17 | 17 | - library and interface - a small wrapper to embed the compiler into a library | |
| 18 | 18 | ||
| 19 | 19 | Each part is tested separately and is used by other FPC tools as well. For example the scanner and parser are used by fpdoc too. Thus they are tested and extended by other programmers, reducing greatly the work for developing pas2js. Consistency is kept by several test suites, containing thousands of tests. | |
| 20 | 20 | ||
| 21 | 21 | Note: The modular structure allows to compile any parts or the whole compiler into an IDE addon (not yet started). | |
| 22 | 22 | ||
| 23 | 23 | ## Command line parameters | |
| 24 | 24 | ||
| 25 | 25 | Most parameters work the same as their FPC equivalent. pas2js has some options of its own (see -J options). | |
| 26 | 26 | ||
| 27 | 27 | ||
| 28 | 28 | Options: | |
| 29 | 29 | Put + after a boolean switch option to enable it, - to disable it | |
| 30 | 30 | @<x> : Read compiler options from file <x> in addition to the default | |
| 31 | 31 | pas2js.cfg | |
| 32 | 32 | -B : Rebuild all | |
| 33 | 33 | -d<x> : Defines the symbol <x>. Optional: -d<x>:=<value> | |
| 34 | 34 | -i<x> : Write information and halt. <x> is a combination of the following: | |
| 35 | 35 | -iD : Write compiler date | |
| 36 | 36 | -iSO : Write compiler OS | |
| 37 | 37 | -iSP : Write compiler host processor | |
| 38 | 38 | -iTO : Write target platform | |
| 39 | 39 | -iTP : Write target processor | |
| 40 | 40 | -iV : Write short compiler version | |
| 41 | 41 | -iW : Write full compiler version | |
| 42 | 42 | -ic : Write list of supported JS processors usable by -P<x> | |
| 43 | 43 | -im : Write list of supported modeswitches usable by -M<x> | |
| 44 | 44 | -io : Write list of supported optimizations usable by -Oo<x> | |
| 45 | 45 | -it : Write list of supported targets usable by -T<x> | |
| 46 | 46 | -iJ : Write list of supported JavaScript identifiers -JoRTL-<x> | |
| 47 | 47 | -C<x> : Code generation options. <x> is a combination of the following | |
| 48 | 48 | letters: | |
| 49 | 49 | o : Overflow checking of integer operations | |
| 50 | 50 | r : Range checking | |
| 51 | 51 | R : Object checks. Verify method calls and object type casts. | |
| 52 | 52 | -F... Set file names and paths: | |
| 53 | 53 | -Fe<x>: Redirect output to file <x>. UTF-8 encoded. | |
| 54 | 54 | -FE<x>: Set main output path to <x> | |
| 55 | 55 | -Fi<x>: Add <x> to include paths | |
| 56 | 56 | -FN<x>: add <x> to namespaces. Namespaces with trailing - are removed. | |
| 57 | 57 | Delphi calls this flag "unit scope names". | |
| 58 | 58 | -Fu<x>: Add <x> to unit paths | |
| 59 | 59 | -FU<x>: Set unit output path to <x> | |
| 60 | 60 | -I<x> : Add <x> to include paths, same as -Fi | |
| 61 | 61 | -J... Extra options of pas2js | |
| 62 | 62 | -Ja<x>: Append JS file <x> to main JS file. E.g. -Jamap.js. Can be given | |
| 63 | 63 | multiple times. To remove a file name append a minus, e.g. | |
| 64 | 64 | -Jamap.js-. | |
| 65 | 65 | -Jc : Write all JavaScript concatenated into the output file | |
| 66 | 66 | -Je<x>: Encode messages as <x>. | |
| 67 | 67 | -Jeconsole: Console codepage. This is the default. | |
| 68 | 68 | -Jesystem : System codepage. On non Windows console and system are the | |
| 69 | 69 | same. | |
| 70 | 70 | -Jeutf-8 : Unicode UTF-8. Default when using -Fe. | |
| 71 | 71 | -JeJSON : Output compiler messages as JSON. Logo etc are outputted | |
| 72 | 72 | as-is. | |
| 73 | 73 | -Ji<x>: Insert JS file <x> into main JS file. E.g. -Jirtl.js. Can be given | |
| 74 | 74 | multiple times. To remove a file name append a minus, e.g. | |
| 75 | 75 | -Jirtl.js-. | |
| 76 | 76 | -Jl : lower case identifiers | |
| 77 | 77 | -Jm : generate source maps | |
| 78 | 78 | -Jmsourceroot=<x>: use x as "sourceRoot", prefix URL for source file | |
| 79 | 79 | names. | |
| 80 | 80 | -Jmbasedir=<x>: write source file names relative to directory x, default | |
| 81 | 81 | is map file folder. | |
| 82 | 82 | -Jminclude: include Pascal sources in source map. | |
| 83 | 83 | -Jmabsolute: store absolute filenames, not relative. | |
| 84 | 84 | -Jmxssiheader: start source map with XSSI protection )]}', default. | |
| 85 | 85 | -Jm-: disable generating source maps | |
| 86 | 86 | -Jo<x>: Enable or disable extra option. The x is case insensitive: | |
| 87 | 87 | -JoSearchLikeFPC: search source files like FPC, default: search case | |
| 88 | 88 | insensitive. | |
| 89 | 89 | -JoUseStrict: add "use strict" to modules, default. | |
| 90 | 90 | -JoCheckVersion-: do not add rtl version check, default. | |
| 91 | 91 | -JoCheckVersion=main: insert rtl version check into main. | |
| 92 | 92 | -JoCheckVersion=system: insert rtl version check into system unit init. | |
| 93 | 93 | -JoCheckVersion=unit: insert rtl version check into every unit init. | |
| 94 | 94 | -JoRTL-<y>=<z>: set RTL identifier y to value z. See -iJ. | |
| 95 | 95 | -Jr<x> Control writing of resource string file | |
| 96 | 96 | -Jrnone: Do not write resource string file | |
| 97 | 97 | -Jrunit: Write resource string file per unit with all resource strings | |
| 98 | 98 | -Jrprogram: Write resource string file per program with all used | |
| 99 | 99 | resource strings in program | |
| 100 | 100 | -JR<x> Control writing of linked resources | |
| 101 | 101 | -JRnone: Skip resource directives | |
| 102 | 102 | -JRjs: Write resources in Javascript structure | |
| 103 | 103 | -JRhtml[=filename] : Write resources as preload links in HTML file | |
| 104 | 104 | (default is projectfile-res.html) | |
| 105 | 105 | -Jpcmd<command>: Run postprocessor. For each generated js execute command | |
| 106 | 106 | passing the js as stdin and read the new js from stdout. This | |
| 107 | 107 | option can be added multiple times to call several postprocessors | |
| 108 | 108 | in succession. | |
| 109 | 109 | -Ju<x>: Add <x> to foreign unit paths. Foreign units are not compiled. | |
| 110 | 110 | -JU: This pas2js does not support PCU files | |
| 111 | 111 | -l : Write logo | |
| 112 | 112 | -M<x> : Set language mode or enable/disable a modeswitch | |
| 113 | 113 | -MDelphi: Delphi 7 compatibility mode | |
| 114 | 114 | -MObjFPC: FPC's Object Pascal compatibility mode (default) | |
| 115 | 115 | -M<x> : enable or disable modeswitch, see option -im | |
| 116 | 116 | Each mode (as listed above) enables its default set of modeswitches. | |
| 117 | 117 | Other modeswitches are disabled and need to be enabled one by another. | |
| 118 | 118 | -NS<x> : obsolete: add <x> to namespaces. Same as -FN<x> | |
| 119 | 119 | -n : Do not read the default config files | |
| 120 | 120 | -o<x> : Change main JavaScript file to <x>, "." means stdout | |
| 121 | 121 | -O<x> : Optimizations: | |
| 122 | 122 | -O- : Disable optimizations | |
| 123 | 123 | -O1 : Level 1 optimizations (quick and debugger friendly) | |
| 124 | 124 | -O2 : Level 2 optimizations (Level 1 + not debugger friendly) | |
| 125 | 125 | -Oo<x>: Enable or disable optimization. The x is case insensitive: | |
| 126 | 126 | -OoEnumNumbers[-]: write enum value as number instead of name. Default | |
| 127 | 127 | in -O1. | |
| 128 | 128 | -OoRemoveNotUsedPrivates[-]: Default is enabled | |
| 129 | 129 | -OoRemoveNotUsedDeclarations[-]: Default enabled for programs with -Jc | |
| 130 | 130 | -OoRemoveNotUsedPublished[-] : Default is disabled | |
| 131 | 131 | -OoShortRefGlobals[-]: Insert JS local var for types, modules and | |
| 132 | 132 | static functions. Default enabled in -O2 | |
| 133 | 133 | -P<x> : Set target processor. Case insensitive: | |
| 134 | 134 | -Pecmascript5: default | |
| 135 | 135 | -Pecmascript6 | |
| 136 | 136 | -S<x> : Syntax options. <x> is a combination of the following letters: | |
| 137 | 137 | 2 : Same as -Mobjfpc (default) | |
| 138 | 138 | a : Turn on assertions | |
| 139 | 139 | c : Support operators like C (*=,+=,/= and -=) | |
| 140 | 140 | d : Same as -Mdelphi | |
| 141 | 141 | j : Allows typed constants to be writeable (default) | |
| 142 | 142 | m : Enables macro replacements | |
| 143 | 143 | -SI<x> : Set interface style to <x> | |
| 144 | 144 | -SIcom : COM, reference counted interface (default) | |
| 145 | 145 | -SIcorba: CORBA interface | |
| 146 | 146 | -T<x> : Set target platform | |
| 147 | 147 | -Tbrowser: default | |
| 148 | 148 | -Tnodejs : add pas.run(), includes -Jc | |
| 149 | 149 | -Telectron: experimental | |
| 150 | 150 | -Tmodule : add pas.run(), includes -Jc | |
| 151 | 151 | -u<x> : Undefines the symbol <x> | |
| 152 | 152 | -v<x> : Be verbose. <x> is a combination of the following letters: | |
| 153 | 153 | e : Show errors (default) | |
| 154 | 154 | w : Show warnings | |
| 155 | 155 | n : Show notes | |
| 156 | 156 | h : Show hints | |
| 157 | 157 | i : Show info | |
| 158 | 158 | l : Show line numbers, needs -vi | |
| 159 | 159 | a : Show everything | |
| 160 | 160 | 0 : Show nothing (except errors) | |
| 161 | 161 | b : Show file names with full path | |
| 162 | 162 | c : Show conditionals | |
| 163 | 163 | t : Show tried/used files | |
| 164 | 164 | d : Show debug notes and info, enables -vni | |
| 165 | 165 | q : Show message numbers | |
| 166 | 166 | x : Show used tools | |
| 167 | 167 | v : Write pas2jsdebug.log with lots of debugging info | |
| 168 | 168 | z : Write messages to stderr, -o. still uses stdout. | |
| 169 | 169 | -vm<x>,<y>: Do not show messages numbered <x> and <y>. | |
| 170 | 170 | -? : Show this help | |
| 171 | 171 | -h : Show this help | |
| 172 | 172 | ||
| 173 | 173 | Environment variable PAS2JS_OPTS is parsed after default config and before | |
| 174 | 174 | command line parameters. | |
| 175 | 175 | ||
| 176 | 176 | ## Delphi and ObjFPC mode | |
| 177 | 177 | ||
| 178 | 178 | ### Delphi mode | |
| 179 | 179 | ||
| 180 | 180 | - Defines macro *DELPHI* | |
| 181 | 181 | - Assigning a function to a function type variable does not require the @ operator. For example, you can write either *OnGetThing:=GetValue;* or *OnGetThing:=@GetValue;*. | |
| 182 | 182 | - 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 ;*. | |
| 183 | 183 | - 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 ;*. | |
| 184 | 184 | - Every procedure/method overload needs the 'overload' modifier. | |
| 185 | 185 | ||
| 186 | 186 | ### ObjFPC mode | |
| 187 | 187 | ||
| 188 | 188 | This the default mode of pas2js and is generally more strict than the Delphi mode, and allows some more operations. | |
| 189 | 189 | ||
| 190 | 190 | - Defines macro *OBJFPC* | |
| 191 | 191 | - Assigning a function to a function type variable requires the @ operator. For example: *OnGetThing:=@GetValue;*. | |
| 192 | 192 | - 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 ;*. | |
| 193 | 193 | - You can compare a procedure type with *nil*. For example *If OnClick=nil then ;*. | |
| 194 | 194 | - You can compare a procedure type with a procedure address (i.e. JS reference). For example *If OnClick=@OnFormClick then ;*. | |
| 195 | 195 | - 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. | |
| 196 | 196 | ||
| 197 | 197 | ## Translating modules | |
| 198 | 198 | ||
| 199 | 199 | A Pascal Program is translated into the following JavaScript structure: | |
| 200 | 200 | ||
| 201 | 201 | **Pascal** | |
| 202 | 202 | ||
| 203 | 203 | **JavaScript Structure, not code!** | |
| 204 | 204 | ||
| 205 | 205 | Program <unitname>; | |
| 206 | 206 | Implementation | |
| 207 | 207 | [implementation section] | |
| 208 | 208 | Begin | |
| 209 | 209 | [main code] | |
| 210 | 210 | End. | |
| 211 | 211 | ||
| 212 | 212 | pas.<program>={ | |
| 213 | 213 | [implementation section], | |
| 214 | 214 | $main: function() { | |
| 215 | 215 | [main code] | |
| 216 | 216 | } | |
| 217 | 217 | }; | |
| 218 | 218 | ||
| 219 | 219 | ||
| 220 | 220 | A Pascal Unit is translated into the following JavaScript structure: | |
| 221 | 221 | ||
| 222 | - | ||
| 223 | - | ||
| 224 | - | ||
| 225 | - | ||
| 226 | - | ||
| 227 | - | ||
| 228 | - | ||
| 229 | - | ||
| 230 | - | ||
| 231 | - | ||
| 232 | - | ||
| 233 | - | ||
| 234 | - | ||
| 235 | - | ||
| 236 | - | ||
| 237 | - | ||
| 238 | - | ||
| 239 | - | ||
| 240 | - | ||
| 241 | - | ||
| 242 | - | ||
| 243 | - | ||
| 244 | - | ||
| 222 | + | | Pascal | JavaScript Structure, not code! | | |
| 223 | + | |---|---| | |
| 224 | + | | `Unit <unitname>;` · `Interface` · ` [interface section]` · `Implementation` · ` [implementation section]` · `Initialization` · ` [initialization section]` · `End.` | `pas.<unitname>={` · ` [interface section],` · ` $impl: {` · ` [implementation section],` · ` },` · ` $init: function() {` · ` [initialization section]` · ` }` · `};` | | |
| 245 | 225 | ||
| 246 | 226 | Note: The **finalization** section is not supported by pas2js.\ | |
| 247 | 227 | ||
| 248 | 228 | To create and initialize the units in topological order the compiler translates an Unit to the following JavaScript code: | |
| 249 | 229 | ||
| 250 | - | ||
| 251 | - | ||
| 252 | - | ||
| 253 | - | ||
| 254 | - | ||
| 255 | - | ||
| 256 | - | ||
| 257 | - | ||
| 258 | - | ||
| 259 | - | ||
| 260 | - | ||
| 261 | - | ||
| 262 | - | ||
| 263 | - | ||
| 264 | - | ||
| 265 | - | ||
| 266 | - | ||
| 267 | - | ||
| 268 | - | ||
| 269 | - | ||
| 270 | - | ||
| 271 | - | ||
| 272 | - | ||
| 273 | - | ||
| 274 | - | ||
| 275 | - | ||
| 276 | - | ||
| 277 | - | ||
| 278 | - | ||
| 230 | + | | Pascal | JavaScript | | |
| 231 | + | |---|---| | |
| 232 | + | | `Unit <unitname>;` · `Interface` · ` [interface section]` · `Implementation` · ` [implementation section]` · `Initialization` · ` [initialization section]` · `End.` | `rtl.module('<unitname>',` · ` ['system',...other used units of the interface section...],` · ` function(){` · ` var $mod = this;` · ` var $impl = $mod.$impl;` · ` [interface section]` · ` $mod.$implcode = function(){` · ` [implementation section]` · ` }` · ` $mod.$init = function(){` · ` [initialization section]` · ` };` · ` },` · ` [...used units of the implementation section]` · ` };` | | |
| 279 | 233 | ||
| 280 | 234 | Here is a more detailed example to make it more clear: | |
| 281 | 235 | ||
| 282 | - | ||
| 283 | - | ||
| 284 | - | ||
| 285 | - | ||
| 286 | - | ||
| 287 | - | ||
| 288 | - | ||
| 289 | - | ||
| 290 | - | ||
| 291 | - | ||
| 292 | - | ||
| 293 | - | ||
| 294 | - | ||
| 295 | - | ||
| 296 | - | ||
| 297 | - | ||
| 298 | - | ||
| 299 | - | ||
| 300 | - | ||
| 301 | - | ||
| 302 | - | ||
| 303 | - | ||
| 304 | - | ||
| 305 | - | ||
| 306 | - | ||
| 307 | - | ||
| 308 | - | ||
| 309 | - | ||
| 310 | - | ||
| 311 | - | ||
| 312 | - | ||
| 313 | - | ||
| 314 | - | ||
| 315 | - | ||
| 316 | - | ||
| 317 | - | ||
| 318 | - | ||
| 319 | - | ||
| 320 | - | ||
| 321 | - | ||
| 322 | - | ||
| 323 | - | ||
| 324 | - | ||
| 325 | - | ||
| 326 | - | ||
| 327 | - | ||
| 236 | + | | Pascal | JavaScript | | |
| 237 | + | |---|---| | |
| 238 | + | | `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;` · ` };` · ` $mod.$implcode = function(){` · ` $impl.dImpl = 0.0;` · ` $impl.MyImplProc = function() {` · ` $impl.dImpl = $mod.dIntf;` · ` };` · ` }` · ` $mod.$init = function() {` · ` };` · `},` · `["Classes"]);` | | |
| 328 | 239 | ||
| 329 | 240 | Notes: | |
| 330 | 241 | ||
| 331 | 242 | - Unit *System* is always loaded implicitely. | |
| 332 | 243 | - References to other units are translated to full path. For example *TObject* is translated to *pas.system.TObject* | |
| 333 | 244 | - References to dotted unitnames, aka units with namespaces are translated to *pas\["namespace.unitname"\]*. | |
| 334 | 245 | ||
| 335 | 246 | ## Translating variables | |
| 336 | 247 | ||
| 337 | 248 | Variables are converted without type, because JavaScript lacks a clear type. They are however always initialized, which helps JavaScript engines to optimize. | |
| 338 | 249 | ||
| 339 | - | ||
| 340 | - | ||
| 341 | - | ||
| 342 | - | ||
| 343 | - | ||
| 344 | - | ||
| 345 | - | ||
| 346 | - | ||
| 347 | - | ||
| 348 | - | ||
| 349 | - | ||
| 350 | - | ||
| 351 | - | ||
| 352 | - | ||
| 353 | - | ||
| 354 | - | ||
| 355 | - | ||
| 356 | - | ||
| 357 | - | ||
| 358 | - | ||
| 359 | - | ||
| 360 | - | ||
| 361 | - | ||
| 362 | - | ||
| 363 | - | ||
| 364 | - | ||
| 365 | - | ||
| 366 | - | ||
| 367 | - | ||
| 368 | - | ||
| 369 | - | ||
| 370 | - | ||
| 371 | - | ||
| 372 | - | ||
| 373 | - | ||
| 374 | - | ||
| 375 | - | ||
| 376 | - | ||
| 377 | - | ||
| 378 | - | ||
| 379 | - | ||
| 380 | - | ||
| 381 | - | ||
| 382 | - | ||
| 383 | - | ||
| 250 | + | | Pascal | JavaScript | | |
| 251 | + | |---|---| | |
| 252 | + | | `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 = [];` · `},` · `[]);` | | |
| 384 | 253 | ||
| 385 | 254 | Notes: | |
| 386 | 255 | ||
| 387 | 256 | - Type casting a *boolean* to *integer*, gives *0* for *false* and *1* for *true*. | |
| 388 | 257 | - Type casting an *integer* to *boolean*, gives *false* for *0* and *true* otherwise. | |
| 389 | 258 | - A **char** is translated to a JS string, because JS lacks a native char type. | |
| 390 | 259 | - A **char** is a single JS char code. An UTF-16 codepoint can contain one or two **char**. | |
| 391 | 260 | - **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. | |
| 392 | 261 | - **type cast integer to integer**, e.g. *byte(aLongInt)* | |
| 393 | 262 | - with range checking enabled: error if outside range | |
| 394 | 263 | - without range checking: emulates the FPC/Delphi behaviour: e.g. *byte(value)* translates to *value & 0xff*, *shortint(value)* translates to *value & 0xff \<\<24 \>\> 24.* | |
| 395 | 264 | - The **mod-operator** works 32-bit signed in JS. | |
| 396 | 265 | ||
| 397 | 266 | ## Translating string | |
| 398 | 267 | ||
| 399 | 268 | Strings are translated to JavaScript strings. They are initialized with "" and are never **null**.\ | |
| 400 | 269 | There are no *ShortString, AnsiString or RawByteString*. *Unicodestring* and *Widestring* are alias of *String*.\ | |
| 401 | 270 | JavaScript strings are immutable, which means that changing a single character in a string, creates a new string. So a *s\[2\]:='c';* is a slow operation in pas2js compared to Delphi/FPC.\ | |
| 402 | 271 | Although pas2js creates .js files encoded as UTF-8 with BOM, JavaScript strings are UTF-16 at runtime. Keep in mind that one UTF-16 codepoint can need two *char*, and a visible glyph can need several codepoints. Same as in Delphi. | |
| 403 | 272 | ||
| 404 | 273 | ## Translating resourcestrings | |
| 405 | 274 | ||
| 406 | 275 | Resourcestrings are translated to JS objects with original (org) and current value. | |
| 407 | 276 | ||
| 408 | - | ||
| 409 | - | ||
| 410 | - | ||
| 411 | - | ||
| 412 | - | ||
| 413 | - | ||
| 414 | - | ||
| 415 | - | ||
| 416 | - | ||
| 417 | - | ||
| 418 | - | ||
| 419 | - | ||
| 420 | - | ||
| 421 | - | ||
| 422 | - | ||
| 423 | - | ||
| 424 | - | ||
| 425 | - | ||
| 426 | - | ||
| 427 | - | ||
| 428 | - | ||
| 429 | - | ||
| 430 | - | ||
| 431 | - | ||
| 277 | + | | Pascal | JavaScript | | |
| 278 | + | |---|---| | |
| 279 | + | | `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");` · ` };` · `});` | | |
| 432 | 280 | ||
| 433 | 281 | ## Translating currency | |
| 434 | 282 | ||
| 435 | 283 | *Currency* in Delphi/FPC is an int64 with a factor of 10000. This is translated to a double with factor 10000 and truncated. | |
| 436 | 284 | ||
| 437 | 285 | - *CurA := 1.12345* -\> *CurA = 11234* | |
| 438 | 286 | - *CurA + CurB* -\> *CurA + CurB* | |
| 439 | 287 | - *CurA * CurB* -\> *CurA * CurB/10000* | |
| 440 | 288 | - *CurA / CurB* -\> *Math.floor(CurA/CurB * 10000)* | |
| 441 | 289 | - *CurA ^^ CurB* -\> *Math.floor(Math.pow(CurA/10000,CurB/10000) * 10000)* | |
| 442 | 290 | - *Currency + Double* -\> *Currency + (Double*10000)* | |
| 443 | 291 | - *Double := Currency* -\> *Double = Currency/10000* | |
| 444 | 292 | - *Currency := Double* -\> *Currency = Math.floor(Double*10000)* | |
| 445 | 293 | - *JSValue := Currency* -\> *JSValue = Currency/10000* | |
| 446 | 294 | - Keep in mind that a double has only 54 bits for the number, so calculating values greater than 900,719,925,474 might give a different result than in Delphi/FPC. See SysUtils.MinCurrency/MaxCurrency | |
| 447 | 295 | ||
| 448 | 296 | ## Translating Types | |
| 449 | 297 | ||
| 450 | 298 | JavaScript type design has no declarative form, except for object types (so-called prototypes). That's why all the derivatives from simple Pascal types can not be translated. The compiler ensures type safety at compile time though, which is a big plus for using Pascal.\ | |
| 451 | 299 | Complex Pascal types (classes, records, or arrays) are translated into JavaScript objects or arrays respectively.\ | |
| 452 | 300 | ||
| 453 | 301 | ## Translating pointer | |
| 454 | 302 | ||
| 455 | 303 | A *pointer* is translated to a JS reference. It can be assigned a class, a class instance, a class-of, an array, a procedure var, a method var, a @proc address, a @method address, or a pointer of record. There is no pointer arithmetic, i.e. no p+1, and no typed pointers, except for pointer of record. You can find out its type using the functions *isArray*, *isClass*, *isClassRef*, *isCallback*, etc of unit *JS*. | |
| 456 | 304 | ||
| 457 | 305 | ## Translating record type | |
| 458 | 306 | ||
| 459 | 307 | A record is translated to a JavaScript object. | |
| 460 | 308 | ||
| 461 | - | ||
| 462 | - | ||
| 463 | - | ||
| 464 | - | ||
| 465 | - | ||
| 466 | - | ||
| 467 | - | ||
| 468 | - | ||
| 469 | - | ||
| 470 | - | ||
| 471 | - | ||
| 472 | - | ||
| 473 | - | ||
| 474 | - | ||
| 475 | - | ||
| 476 | - | ||
| 477 | - | ||
| 478 | - | ||
| 479 | - | ||
| 480 | - | ||
| 481 | - | ||
| 482 | - | ||
| 483 | - | ||
| 484 | - | ||
| 485 | - | ||
| 486 | - | ||
| 487 | - | ||
| 488 | - | ||
| 489 | - | ||
| 490 | - | ||
| 491 | - | ||
| 492 | - | ||
| 493 | - | ||
| 494 | - | ||
| 495 | - | ||
| 496 | - | ||
| 497 | - | ||
| 498 | - | ||
| 499 | - | ||
| 500 | - | ||
| 501 | - | ||
| 502 | - | ||
| 503 | - | ||
| 504 | - | ||
| 505 | - | ||
| 506 | - | ||
| 507 | - | ||
| 508 | - | ||
| 509 | - | ||
| 510 | - | ||
| 511 | - | ||
| 512 | - | ||
| 513 | - | ||
| 514 | - | ||
| 515 | - | ||
| 516 | - | ||
| 517 | - | ||
| 518 | - | ||
| 519 | - | ||
| 520 | - | ||
| 521 | - | ||
| 522 | - | ||
| 523 | - | ||
| 524 | - | ||
| 525 | - | ||
| 526 | - | ||
| 527 | - | ||
| 528 | - | ||
| 529 | - | ||
| 530 | - | ||
| 531 | - | ||
| 532 | - | ||
| 533 | - | ||
| 534 | - | ||
| 535 | - | ||
| 536 | - | ||
| 309 | + | | Pascal | JS Pas2js 1.3 | JS Pas2js 1.2 | | |
| 310 | + | |---|---|---| | |
| 311 | + | | `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;` · ` 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)) ;` · ` },` · `},` · `[]);` | `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)) ;` · ` },` · `},` · `[]);` | | |
| 537 | 312 | ||
| 538 | 313 | - The record variable creates a JavaScript object. | |
| 539 | 314 | - Variant records are not supported. | |
| 540 | 315 | - Supported: Assign, pass as argument, equal, not equal, array of record, pointer of record, const, default(), RTTI. | |
| 541 | 316 | - Advanced record (since pas2js 1.3): | |
| 542 | 317 | - visibility private, strict private, public, default is public | |
| 543 | 318 | - methods, class methods (must be static like in Delphi/FPC) | |
| 544 | 319 | - class vars | |
| 545 | 320 | - const fields | |
| 546 | 321 | - property, class property, array property, default array property | |
| 547 | 322 | - sub types | |
| 548 | 323 | - constructor | |
| 549 | 324 | - class constructor | |
| 550 | 325 | - Not yet implemented: | |
| 551 | 326 | - operator overloading | |
| 552 | 327 | - reference counted interfaces as fields | |
| 553 | 328 | - Interfaces as nested types | |
| 554 | 329 | - default non array property | |
| 555 | 330 | - 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. | |
| 556 | 331 | - Since record types are JS objects it is possible to typecast a record type to the JS Object, e.g. *TJSObject(TPoint)*. Note that you cannot typecast directly to a *TJSObject* descendant. You can use *TJSWindow(TJSObject(aRecord))*. | |
| 557 | 332 | - A pointer of record is simply a reference. | |
| 558 | 333 | - *p:=@r* translates to *p=r* | |
| 559 | 334 | - *p^.x* becomes *p.x*. | |
| 560 | 335 | - *New(PointerOfRecord)* creates a new record | |
| 561 | 336 | - *Dispose(PointerOfRecord)* Sets the variable to null if possible. | |
| 562 | 337 | - Passing a record to an untyped arguments (e.g. ''TObject.Dispatch(var Msg)'') passes the record JS object directly, not creating a temporary reference object. | |
| 563 | 338 | - Typecasting RecordType(UntypedArgument) returns the argument, i.e. no conversion. | |
| 564 | 339 | ||
| 565 | 340 | ## Translating generics | |
| 566 | 341 | ||
| 567 | 342 | Generics are not translated, their specializations are. | |
| 568 | 343 | ||
| 569 | 344 | - Specializations are created with a \$ number postfix, for example **TList\$G3**. | |
| 570 | 345 | - Their RTTI name has the full name, for example **TList\<project1.TBird\>** | |
| 571 | 346 | - Multiple specializations of *TList\<word\>* creates only one specialization. That is true for the whole program. | |
| 572 | 347 | - Specializations are created in the unit, where the generic is defined, not where they are specialized. | |
| 573 | 348 | - Important: This means that a new specialization of *TList* require a recompile of the js of unit *generics.collections*. | |
| 574 | 349 | ||
| 575 | 350 | ## Translating functions | |
| 576 | 351 | ||
| 577 | - | ||
| 578 | - | ||
| 579 | - | ||
| 580 | - | ||
| 581 | - | ||
| 582 | - | ||
| 583 | - | ||
| 584 | - | ||
| 585 | - | ||
| 586 | - | ||
| 587 | - | ||
| 588 | - | ||
| 589 | - | ||
| 590 | - | ||
| 591 | - | ||
| 592 | - | ||
| 593 | - | ||
| 594 | - | ||
| 595 | - | ||
| 596 | - | ||
| 597 | - | ||
| 598 | - | ||
| 599 | - | ||
| 600 | - | ||
| 601 | - | ||
| 352 | + | | Pascal | JavaScript | | |
| 353 | + | |---|---| | |
| 354 | + | | `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;` · ` };` · `},` · `[]);` | | |
| 602 | 355 | ||
| 603 | 356 | Notes: | |
| 604 | 357 | ||
| 605 | 358 | - Local variables become local JavaScript variables: *var l = 0;*. | |
| 606 | 359 | - Local constants become JavaScript variables in the unit/program implementation section. | |
| 607 | 360 | - Local types are elevated to module. | |
| 608 | 361 | - Overloaded functions are given an unique name by appending \$1, \$2, ... | |
| 609 | 362 | - Supported: default values, const/var/out/default, FuncName:= | |
| 610 | 363 | ||
| 611 | 364 | ## Translating passing a parameter by reference | |
| 612 | 365 | ||
| 613 | 366 | JavaScript lacks passing by reference. Instead a temporary object is created with a *get* and *set* function. That means changes within the procedure are immediately visible outside, compatible with Pascal. | |
| 614 | 367 | ||
| 615 | - | ||
| 616 | - | ||
| 617 | - | ||
| 618 | - | ||
| 619 | - | ||
| 620 | - | ||
| 621 | - | ||
| 622 | - | ||
| 623 | - | ||
| 624 | - | ||
| 625 | - | ||
| 626 | - | ||
| 627 | - | ||
| 628 | - | ||
| 629 | - | ||
| 630 | - | ||
| 631 | - | ||
| 632 | - | ||
| 633 | - | ||
| 634 | - | ||
| 635 | - | ||
| 636 | - | ||
| 637 | - | ||
| 638 | - | ||
| 639 | - | ||
| 640 | - | ||
| 641 | - | ||
| 642 | - | ||
| 643 | - | ||
| 644 | - | ||
| 645 | - | ||
| 646 | - | ||
| 647 | - | ||
| 648 | - | ||
| 649 | - | ||
| 650 | - | ||
| 651 | - | ||
| 652 | - | ||
| 653 | - | ||
| 654 | - | ||
| 655 | - | ||
| 656 | - | ||
| 657 | - | ||
| 658 | - | ||
| 659 | - | ||
| 660 | - | ||
| 661 | - | ||
| 368 | + | | Pascal | JavaScript | | |
| 369 | + | |---|---| | |
| 370 | + | | `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);` · ` }` · `},` · `[]);` | | |
| 662 | 371 | ||
| 663 | 372 | When the passed value is from another context, the context is passed too: | |
| 664 | 373 | ||
| 665 | - | ||
| 666 | - | ||
| 667 | - | ||
| 668 | - | ||
| 669 | - | ||
| 670 | - | ||
| 671 | - | ||
| 672 | - | ||
| 673 | - | ||
| 674 | - | ||
| 675 | - | ||
| 676 | - | ||
| 677 | - | ||
| 678 | - | ||
| 679 | - | ||
| 680 | - | ||
| 681 | - | ||
| 682 | - | ||
| 683 | - | ||
| 684 | - | ||
| 685 | - | ||
| 686 | - | ||
| 687 | - | ||
| 688 | - | ||
| 689 | - | ||
| 690 | - | ||
| 691 | - | ||
| 692 | - | ||
| 693 | - | ||
| 694 | - | ||
| 695 | - | ||
| 696 | - | ||
| 697 | - | ||
| 698 | - | ||
| 699 | - | ||
| 700 | - | ||
| 701 | - | ||
| 374 | + | | Pascal | JavaScript | | |
| 375 | + | |---|---| | |
| 376 | + | | `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;` · ` }` · ` });` · ` }` · `},` · `[]);` | | |
| 702 | 377 | ||
| 703 | 378 | Notes: | |
| 704 | 379 | ||
| 705 | 380 | - Contrary to Delphi/FPC it is allowed to pass a property to a var/out parameter. | |
| 706 | 381 | ||
| 707 | 382 | ## Translating nested functions | |
| 708 | 383 | ||
| 709 | 384 | A nested function is translated to a local variable. | |
| 710 | 385 | ||
| 711 | - | ||
| 712 | - | ||
| 713 | - | ||
| 714 | - | ||
| 715 | - | ||
| 716 | - | ||
| 717 | - | ||
| 718 | - | ||
| 719 | - | ||
| 720 | - | ||
| 721 | - | ||
| 722 | - | ||
| 723 | - | ||
| 724 | - | ||
| 725 | - | ||
| 726 | - | ||
| 727 | - | ||
| 728 | - | ||
| 729 | - | ||
| 730 | - | ||
| 731 | - | ||
| 732 | - | ||
| 733 | - | ||
| 734 | - | ||
| 735 | - | ||
| 736 | - | ||
| 737 | - | ||
| 738 | - | ||
| 739 | - | ||
| 740 | - | ||
| 741 | - | ||
| 742 | - | ||
| 743 | - | ||
| 744 | - | ||
| 745 | - | ||
| 746 | - | ||
| 747 | - | ||
| 748 | - | ||
| 749 | - | ||
| 750 | - | ||
| 751 | - | ||
| 752 | - | ||
| 753 | - | ||
| 386 | + | | Pascal | JavaScript | | |
| 387 | + | |---|---| | |
| 388 | + | | `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;` · ` };` · `},` · `[]);` | | |
| 754 | 389 | ||
| 755 | 390 | Note: You can assign a nested procedure to a procedure variable. A nested procedure of a method can be assigned to a method variable.\ | |
| 756 | 391 | JavaScript preserves the current local scope, including references to the local variables of parent functions. Local types and constants belong to the unit scope (singleton).\ | |
| 757 | 392 | When a method has nested functions, the compiler adds a local var *Self*. | |
| 758 | 393 | ||
| 759 | 394 | ## Translating for-loops | |
| 760 | 395 | ||
| 761 | 396 | The JavaScript for-loop executes the end expression every iteration, while Pascal only executes it once. Therefore a local variable is introduced. If the loop is not entered at all, the variable is not touched. If the loop was entered the variable contanis the last value. | |
| 762 | 397 | ||
| 763 | - | ||
| 764 | - | ||
| 765 | - | ||
| 766 | - | ||
| 767 | - | ||
| 768 | - | ||
| 769 | - | ||
| 770 | - | ||
| 771 | - | ||
| 772 | - | ||
| 773 | - | ||
| 774 | - | ||
| 775 | - | ||
| 776 | - | ||
| 777 | - | ||
| 778 | - | ||
| 779 | - | ||
| 780 | - | ||
| 781 | - | ||
| 782 | - | ||
| 783 | - | ||
| 784 | - | ||
| 785 | - | ||
| 786 | - | ||
| 787 | - | ||
| 788 | - | ||
| 789 | - | ||
| 790 | - | ||
| 791 | - | ||
| 792 | - | ||
| 793 | - | ||
| 794 | - | ||
| 795 | - | ||
| 796 | - | ||
| 797 | - | ||
| 798 | - | ||
| 799 | - | ||
| 800 | - | ||
| 801 | - | ||
| 398 | + | | Pascal | JavaScript | | |
| 399 | + | |---|---| | |
| 400 | + | | `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;` · ` };` · `},` · `[]);` | | |
| 802 | 401 | ||
| 803 | 402 | Note: The after-loop decrement is only added if *i* is read after the loop.\ | |
| 804 | 403 | ||
| 805 | 404 | ## Translating repeat..until | |
| 806 | 405 | ||
| 807 | 406 | The *repeat..until* is translated to a *do{}while()*. | |
| 808 | 407 | ||
| 809 | - | ||
| 810 | - | ||
| 811 | - | ||
| 812 | - | ||
| 813 | - | ||
| 814 | - | ||
| 815 | - | ||
| 816 | - | ||
| 817 | - | ||
| 818 | - | ||
| 819 | - | ||
| 820 | - | ||
| 821 | - | ||
| 822 | - | ||
| 823 | - | ||
| 824 | - | ||
| 825 | - | ||
| 826 | - | ||
| 827 | - | ||
| 828 | - | ||
| 829 | - | ||
| 830 | - | ||
| 831 | - | ||
| 832 | - | ||
| 833 | - | ||
| 834 | - | ||
| 835 | - | ||
| 836 | - | ||
| 837 | - | ||
| 838 | - | ||
| 839 | - | ||
| 840 | - | ||
| 841 | - | ||
| 842 | - | ||
| 843 | - | ||
| 844 | - | ||
| 845 | - | ||
| 846 | - | ||
| 847 | - | ||
| 408 | + | | Pascal | JavaScript | | |
| 409 | + | |---|---| | |
| 410 | + | | `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;` · ` };` · `},` · `[]);` | | |
| 848 | 411 | ||
| 849 | 412 | ## Translating while..do | |
| 850 | 413 | ||
| 851 | - | ||
| 852 | - | ||
| 853 | - | ||
| 854 | - | ||
| 855 | - | ||
| 856 | - | ||
| 857 | - | ||
| 858 | - | ||
| 859 | - | ||
| 860 | - | ||
| 861 | - | ||
| 862 | - | ||
| 863 | - | ||
| 864 | - | ||
| 865 | - | ||
| 866 | - | ||
| 867 | - | ||
| 868 | - | ||
| 869 | - | ||
| 870 | - | ||
| 871 | - | ||
| 872 | - | ||
| 873 | - | ||
| 874 | - | ||
| 875 | - | ||
| 876 | - | ||
| 877 | - | ||
| 878 | - | ||
| 879 | - | ||
| 880 | - | ||
| 881 | - | ||
| 882 | - | ||
| 883 | - | ||
| 884 | - | ||
| 885 | - | ||
| 886 | - | ||
| 887 | - | ||
| 888 | - | ||
| 889 | - | ||
| 414 | + | | Pascal | JavaScript | | |
| 415 | + | |---|---| | |
| 416 | + | | `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;` · ` };` · `},` · `[]);` | | |
| 890 | 417 | ||
| 891 | 418 | ## Translating case..do | |
| 892 | 419 | ||
| 893 | 420 | Although JavaScript has something similar in form of the "switch" statement, it lacks ranges and is on current JS engines often slower than "if-else". Therefore a case..of is translated to if..else. | |
| 894 | 421 | ||
| 895 | - | ||
| 896 | - | ||
| 897 | - | ||
| 898 | - | ||
| 899 | - | ||
| 900 | - | ||
| 901 | - | ||
| 902 | - | ||
| 903 | - | ||
| 904 | - | ||
| 905 | - | ||
| 906 | - | ||
| 907 | - | ||
| 908 | - | ||
| 909 | - | ||
| 910 | - | ||
| 911 | - | ||
| 912 | - | ||
| 913 | - | ||
| 914 | - | ||
| 915 | - | ||
| 916 | - | ||
| 917 | - | ||
| 918 | - | ||
| 919 | - | ||
| 920 | - | ||
| 921 | - | ||
| 922 | - | ||
| 923 | - | ||
| 924 | - | ||
| 925 | - | ||
| 926 | - | ||
| 927 | - | ||
| 422 | + | | Pascal | JavaScript | | |
| 423 | + | |---|---| | |
| 424 | + | | `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;` · ` }` · ` };` · `},` · `[]);` | | |
| 928 | 425 | ||
| 929 | 426 | ## Translating with..do | |
| 930 | 427 | ||
| 931 | 428 | JavaScript has a **with**, but it is slow and deprecated. Instead a temporary variable is used: | |
| 932 | 429 | ||
| 933 | - | ||
| 934 | - | ||
| 935 | - | ||
| 936 | - | ||
| 937 | - | ||
| 938 | - | ||
| 939 | - | ||
| 940 | - | ||
| 941 | - | ||
| 942 | - | ||
| 943 | - | ||
| 944 | - | ||
| 945 | - | ||
| 946 | - | ||
| 947 | - | ||
| 948 | - | ||
| 949 | - | ||
| 950 | - | ||
| 951 | - | ||
| 952 | - | ||
| 953 | - | ||
| 954 | - | ||
| 955 | - | ||
| 956 | - | ||
| 957 | - | ||
| 958 | - | ||
| 959 | - | ||
| 960 | - | ||
| 961 | - | ||
| 962 | - | ||
| 963 | - | ||
| 964 | - | ||
| 965 | - | ||
| 966 | - | ||
| 967 | - | ||
| 968 | - | ||
| 969 | - | ||
| 970 | - | ||
| 971 | - | ||
| 430 | + | | Pascal | JavaScript | | |
| 431 | + | |---|---| | |
| 432 | + | | `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;` · ` };` · `},` · `[]);` | | |
| 972 | 433 | ||
| 973 | 434 | Note: If the with-expression is already a local variable no new variable is created. This is Delphi/FPC compatible. | |
| 974 | 435 | ||
| 975 | 436 | ## Translating enums | |
| 976 | 437 | ||
| 977 | 438 | Enum values are translated to numbers. The enum type is translated to an object containing a mapping from name to number and number to name. | |
| 978 | 439 | ||
| 979 | - | ||
| 980 | - | ||
| 981 | - | ||
| 982 | - | ||
| 983 | - | ||
| 984 | - | ||
| 985 | - | ||
| 986 | - | ||
| 987 | - | ||
| 988 | - | ||
| 989 | - | ||
| 990 | - | ||
| 991 | - | ||
| 992 | - | ||
| 993 | - | ||
| 994 | - | ||
| 995 | - | ||
| 996 | - | ||
| 997 | - | ||
| 998 | - | ||
| 999 | - | ||
| 1000 | - | ||
| 1001 | - | ||
| 1002 | - | ||
| 1003 | - | ||
| 1004 | - | ||
| 1005 | - | ||
| 1006 | - | ||
| 1007 | - | ||
| 1008 | - | ||
| 1009 | - | ||
| 1010 | - | ||
| 1011 | - | ||
| 1012 | - | ||
| 1013 | - | ||
| 1014 | - | ||
| 1015 | - | ||
| 1016 | - | ||
| 1017 | - | ||
| 1018 | - | ||
| 1019 | - | ||
| 1020 | - | ||
| 1021 | - | ||
| 1022 | - | ||
| 440 | + | | Pascal | JavaScript | | |
| 441 | + | |---|---| | |
| 442 | + | | `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;` · ` };` · `},` · `[]);` | | |
| 1023 | 443 | ||
| 1024 | 444 | - Supported: ord(), low(), high(), pred(), succ(), type cast number to enum. | |
| 1025 | 445 | - With optimization level -O1 the compiler uses numbers instead of names. | |
| 1026 | 446 | - Not yet implemented: custom values for enum values. | |
| 1027 | 447 | ||
| 1028 | 448 | ## Translating sets | |
| 1029 | 449 | ||
| 1030 | 450 | A set s is translated to a JavaScript object, where for each included enum holds *s.enumvalue==true*. This allows arbitrary large sets and the *in* operator is fast. | |
| 1031 | 451 | ||
| 1032 | - | ||
| 1033 | - | ||
| 1034 | - | ||
| 1035 | - | ||
| 1036 | - | ||
| 1037 | - | ||
| 1038 | - | ||
| 1039 | - | ||
| 1040 | - | ||
| 1041 | - | ||
| 1042 | - | ||
| 1043 | - | ||
| 1044 | - | ||
| 1045 | - | ||
| 1046 | - | ||
| 1047 | - | ||
| 1048 | - | ||
| 1049 | - | ||
| 1050 | - | ||
| 1051 | - | ||
| 1052 | - | ||
| 1053 | - | ||
| 1054 | - | ||
| 1055 | - | ||
| 1056 | - | ||
| 1057 | - | ||
| 1058 | - | ||
| 1059 | - | ||
| 1060 | - | ||
| 1061 | - | ||
| 1062 | - | ||
| 1063 | - | ||
| 1064 | - | ||
| 1065 | - | ||
| 1066 | - | ||
| 1067 | - | ||
| 1068 | - | ||
| 1069 | - | ||
| 1070 | - | ||
| 1071 | - | ||
| 1072 | - | ||
| 1073 | - | ||
| 1074 | - | ||
| 1075 | - | ||
| 1076 | - | ||
| 1077 | - | ||
| 1078 | - | ||
| 1079 | - | ||
| 1080 | - | ||
| 1081 | - | ||
| 1082 | - | ||
| 1083 | - | ||
| 1084 | - | ||
| 1085 | - | ||
| 1086 | - | ||
| 1087 | - | ||
| 1088 | - | ||
| 1089 | - | ||
| 1090 | - | ||
| 452 | + | | Pascal | JavaScript | | |
| 453 | + | |---|---| | |
| 454 | + | | `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);` · ` };` · `},` · `[]);` | | |
| 1091 | 455 | ||
| 1092 | 456 | - Supported: | |
| 1093 | 457 | - Include | |
| 1094 | 458 | - Exclude | |
| 1095 | 459 | - literal | |
| 1096 | 460 | - literal range, e.g. *\[EnumA..EnumB\], \['a'..'z'\]* | |
| 1097 | 461 | - union + | |
| 1098 | 462 | - difference - | |
| 1099 | 463 | - intersect * | |
| 1100 | 464 | - symmetrical difference \>\< | |
| 1101 | 465 | - equal = | |
| 1102 | 466 | - unequal \<\> | |
| 1103 | 467 | - subset \<= | |
| 1104 | 468 | - superset \>= | |
| 1105 | 469 | - set of anonymous enum type: *set of (enum1,enum2,...)* | |
| 1106 | 470 | - Not supported: set of char, set of boolean | |
| 1107 | 471 | - There is no optimization yet for small sets like in Delphi/FPC. | |
| 1108 | 472 | - 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). | |
| 1109 | 473 | - Passing a set as an argument might clone the set. Use the *const* modifier for parameters whenever possible. | |
| 1110 | 474 | - 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. | |
| 1111 | 475 | ||
| 1112 | 476 | ## Translating array type | |
| 1113 | 477 | ||
| 1114 | 478 | All arrays are translated into JavaScript arrays.\ | |
| 1115 | 479 | Contrary to Delphi/FPC dynamic arrays are not reference counted and do not copy on write. That means if you pass an array to a procedure and change an element, the original array is changed. | |
| 1116 | 480 | ||
| 1117 | - | ||
| 1118 | - | ||
| 1119 | - | ||
| 1120 | - | ||
| 1121 | - | ||
| 1122 | - | ||
| 1123 | - | ||
| 1124 | - | ||
| 1125 | - | ||
| 1126 | - | ||
| 1127 | - | ||
| 1128 | - | ||
| 1129 | - | ||
| 1130 | - | ||
| 1131 | - | ||
| 1132 | - | ||
| 1133 | - | ||
| 1134 | - | ||
| 1135 | - | ||
| 1136 | - | ||
| 1137 | - | ||
| 1138 | - | ||
| 1139 | - | ||
| 1140 | - | ||
| 1141 | - | ||
| 1142 | - | ||
| 1143 | - | ||
| 1144 | - | ||
| 1145 | - | ||
| 1146 | - | ||
| 1147 | - | ||
| 1148 | - | ||
| 1149 | - | ||
| 1150 | - | ||
| 1151 | - | ||
| 1152 | - | ||
| 1153 | - | ||
| 1154 | - | ||
| 1155 | - | ||
| 1156 | - | ||
| 1157 | - | ||
| 1158 | - | ||
| 1159 | - | ||
| 1160 | - | ||
| 1161 | - | ||
| 1162 | - | ||
| 1163 | - | ||
| 1164 | - | ||
| 1165 | - | ||
| 1166 | - | ||
| 1167 | - | ||
| 1168 | - | ||
| 1169 | - | ||
| 1170 | - | ||
| 1171 | - | ||
| 1172 | - | ||
| 1173 | - | ||
| 1174 | - | ||
| 481 | + | | Pascal | JavaScript | | |
| 482 | + | |---|---| | |
| 483 | + | | `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);` · ` }` · ` };` · `},` · `[]);` | | |
| 1175 | 484 | ||
| 1176 | 485 | Notes: | |
| 1177 | 486 | ||
| 1178 | 487 | - Supported features of dynamic arrays: SetLength(), Length(), equal/notequal nil, low(), high(), assigned(), concat(), copy(), insert(), delete(), multi dimensional, array of record | |
| 1179 | 488 | - 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\]* | |
| 1180 | 489 | - Supported features of static arrays: length(), low(), high(), assigned(), concat(), copy(), const, const records | |
| 1181 | 490 | - Open arrays are implemented as dynamic arrays. | |
| 1182 | 491 | - 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. | |
| 1183 | 492 | - 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*. | |
| 1184 | 493 | - *function Assigned(array): boolean* results true iff *length(array)\>0*. | |
| 1185 | 494 | - array of const: | |
| 1186 | 495 | - Works the same: vtInteger, vtBoolean, vtPointer, vtObject, vtClass, vtWideChar, vtInterface, vtUnicodeString | |
| 1187 | 496 | - ''longword'' is converted to ''vtNativeInt''. Delphi/FPC converts to ''vtInteger'', changing big numbers to negative numbers. | |
| 1188 | 497 | - vtExtended is double, Delphi/FPC: PExtended | |
| 1189 | 498 | - vtCurrency is currency, Delphi/FPC: PCurrency | |
| 1190 | 499 | - Not supported: vtChar, vtString, vtPChar, vtPWideChar, vtAnsiString, vtVariant, vtWideString, vtInt64, vtQWord | |
| 1191 | 500 | - only in pas2js: vtNativeInt, vtJSValue | |
| 1192 | 501 | - Assignation using constant array, e.g. *a:=\[1,1,2\];* | |
| 1193 | 502 | - String like operation: + operator concatenates arrays. e.g. *a:=\[1\]+\[2\];*. This is controlled by modeswitch arrayoperators, which is enabled in mode delphi. | |
| 1194 | 503 | - *function copy(array,start=0,count=max): array* | |
| 1195 | 504 | - *procedure insert(item,var array,const position)* | |
| 1196 | 505 | - *procedure delete(var array,const start,count)* | |
| 1197 | 506 | ||
| 1198 | 507 | ## Translating class type | |
| 1199 | 508 | ||
| 1200 | 509 | Classes are implemented using *Object.create* and some rtl magic. | |
| 1201 | 510 | ||
| 1202 | - | ||
| 1203 | - | ||
| 1204 | - | ||
| 1205 | - | ||
| 1206 | - | ||
| 1207 | - | ||
| 1208 | - | ||
| 1209 | - | ||
| 1210 | - | ||
| 1211 | - | ||
| 1212 | - | ||
| 1213 | - | ||
| 1214 | - | ||
| 1215 | - | ||
| 1216 | - | ||
| 1217 | - | ||
| 1218 | - | ||
| 1219 | - | ||
| 1220 | - | ||
| 1221 | - | ||
| 1222 | - | ||
| 1223 | - | ||
| 1224 | - | ||
| 1225 | - | ||
| 1226 | - | ||
| 1227 | - | ||
| 1228 | - | ||
| 1229 | - | ||
| 1230 | - | ||
| 1231 | - | ||
| 1232 | - | ||
| 1233 | - | ||
| 1234 | - | ||
| 1235 | - | ||
| 1236 | - | ||
| 1237 | - | ||
| 1238 | - | ||
| 1239 | - | ||
| 1240 | - | ||
| 1241 | - | ||
| 1242 | - | ||
| 1243 | - | ||
| 511 | + | | Pascal | JavaScript | | |
| 512 | + | |---|---| | |
| 513 | + | | `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");` · ` };` · `},` · `[]);` | | |
| 1244 | 514 | ||
| 1245 | 515 | Notes: | |
| 1246 | 516 | ||
| 1247 | 517 | - Each class and each instance is an JS object. | |
| 1248 | 518 | - Each class has a globally unique JS object, created by rtl.createClass. | |
| 1249 | 519 | - *Self* is never *nil*. | |
| 1250 | 520 | - The method *TObject.Free* is using compiler magic. See \[#tobjectfree Translating TObject.Free\]. | |
| 1251 | 521 | - *Class.\$class* is a reference to the class itself. | |
| 1252 | 522 | - *Class.\$ancestor* is a reference to the ancestor class. | |
| 1253 | 523 | - A class has *c.\$ancestor == Object.getPrototypeOf(c)*. | |
| 1254 | 524 | - A class instance has *o.\$class == Object.getPrototypeOf(o)*. | |
| 1255 | 525 | - *Class.\$classname* is the short name. E.g. *TClassA.\$classname == 'TClassA*'. | |
| 1256 | 526 | - *Class.\$name* is the long name. E.g. *TClassA.\$name == 'MyModule.TClassA*'. | |
| 1257 | 527 | - *Class.\$unitname* is the unit name. E.g. *TClassA.\$unitname == 'MyModule*'. | |
| 1258 | 528 | - The "*is*"-operator is implemented using "*isPrototypeOf*". Note that "*instanceof*" cannot be used, because classes are JS objects. | |
| 1259 | 529 | - The "*as*" operator is implemented as *rtl.as(Object,Class)*. | |
| 1260 | 530 | - Supported: | |
| 1261 | 531 | - constructor, destructor | |
| 1262 | 532 | - private, protected, public, strict private, strict protected | |
| 1263 | 533 | - class vars, const, nested types | |
| 1264 | 534 | - methods, class methods, class constructor, external methods | |
| 1265 | 535 | - method modifiers overload, reintroduce, virtual, override, abstract, static, external name, message integer, message string | |
| 1266 | 536 | - call inherited | |
| 1267 | 537 | - assigned() | |
| 1268 | 538 | - type cast | |
| 1269 | 539 | - class sealed, class abstract | |
| 1270 | 540 | - Not supported: class destructor | |
| 1271 | 541 | - Property: | |
| 1272 | 542 | - References are replaced by getter/setter. | |
| 1273 | 543 | - Supported: argument lists, default property, class property, stored modifier, index modifier. | |
| 1274 | 544 | - Not supported: getter/setter to an array element, e.g. *property A: char read FArray\[0\];* | |
| 1275 | 545 | - Class property getter/setter can be static or non static. Delphi: must be static. | |
| 1276 | 546 | - 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. | |
| 1277 | 547 | ||
| 1278 | 548 | ## Translating class-of type | |
| 1279 | 549 | ||
| 1280 | 550 | A class-of is a reference to a class. See above about translating class. | |
| 1281 | 551 | ||
| 1282 | - | ||
| 1283 | - | ||
| 1284 | - | ||
| 1285 | - | ||
| 1286 | - | ||
| 1287 | - | ||
| 1288 | - | ||
| 1289 | - | ||
| 1290 | - | ||
| 1291 | - | ||
| 1292 | - | ||
| 1293 | - | ||
| 1294 | - | ||
| 1295 | - | ||
| 1296 | - | ||
| 1297 | - | ||
| 1298 | - | ||
| 1299 | - | ||
| 1300 | - | ||
| 1301 | - | ||
| 1302 | - | ||
| 1303 | - | ||
| 1304 | - | ||
| 1305 | - | ||
| 1306 | - | ||
| 1307 | - | ||
| 1308 | - | ||
| 1309 | - | ||
| 1310 | - | ||
| 1311 | - | ||
| 1312 | - | ||
| 1313 | - | ||
| 1314 | - | ||
| 1315 | - | ||
| 1316 | - | ||
| 1317 | - | ||
| 1318 | - | ||
| 1319 | - | ||
| 1320 | - | ||
| 1321 | - | ||
| 1322 | - | ||
| 1323 | - | ||
| 1324 | - | ||
| 1325 | - | ||
| 1326 | - | ||
| 1327 | - | ||
| 1328 | - | ||
| 1329 | - | ||
| 1330 | - | ||
| 1331 | - | ||
| 1332 | - | ||
| 1333 | - | ||
| 1334 | - | ||
| 1335 | - | ||
| 1336 | - | ||
| 1337 | - | ||
| 1338 | - | ||
| 552 | + | | Pascal | JavaScript | | |
| 553 | + | |---|---| | |
| 554 | + | | `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);` · ` };` · `},` · `[]);` | | |
| 1339 | 555 | ||
| 1340 | 556 | Note that *this* in a class method is the class itself.\ | |
| 1341 | 557 | ||
| 1342 | 558 | Notes:\ | |
| 1343 | 559 | ||
| 1344 | 560 | - Contrary to Delphi/FPC the "is" operator works with class-of. | |
| 1345 | 561 | ||
| 1346 | 562 | ## Translating TObject.Free | |
| 1347 | 563 | ||
| 1348 | 564 | In Delphi/FPC AnObject.Free checks if Self is nil, then calls the destructor and frees the memory, without changing the reference. In JavaScript however calling a method with AnObject=nil causes a crash. And memory cannot be freed explicitely. Memory is only freed if all references are gone (e.g. set to *null*).\ | |
| 1349 | 565 | Therefore pas2js adds code to call the destructor and sets the variable to *nil*:\ | |
| 1350 | 566 | ||
| 1351 | 567 | - *Obj.Free* on a local variable or argument is translated to *Obj = rtl.freeLoc(Obj);*. | |
| 1352 | 568 | - *Obj.Free* on a non local variable is translated to *rtl.free(this,"Obj");*. | |
| 1353 | 569 | - Not supported: Freeing a property or function result.\ | |
| 1354 | 570 | For example *List\[i\].Free* gives a compiler error. The property setter might create side effects, which would be incompatible to Delphi/FPC. | |
| 1355 | 571 | ||
| 1356 | 572 | Notes: | |
| 1357 | 573 | ||
| 1358 | 574 | - 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. | |
| 1359 | 575 | - Alternatively you can use *FreeAndNil*, which first changes the variable to *nil* and then calls the destructor. | |
| 1360 | 576 | ||
| 1361 | 577 | ## Translating class interfaces | |
| 1362 | 578 | ||
| 1363 | 579 | JavaScript has nothing like it, so they are emulated.\ | |
| 1364 | 580 | An interfacetype is a JS-object with some hidden properties, containing the GUID (\$guid) and an array with the method names (\$names). Here is how IUnknown looks like in JS:\ | |
| 1365 | 581 | ||
| 1366 | 582 | `{`\ | |
| 1367 | 583 | ` $module: [object Object],`\ | |
| 1368 | 584 | ` $name: "IUnknown",`\ | |
| 1369 | 585 | ` $fullname: "System.IUnknown",`\ | |
| 1370 | 586 | ` $guid: "{00000000-0000-0000-C000-000000000046}",`\ | |
| 1371 | 587 | ` $names: ["QueryInterface","_AddRef","_Release"],`\ | |
| 1372 | 588 | ` $rtti: [object Object],`\ | |
| 1373 | 589 | ` $kind: "com",`\ | |
| 1374 | 590 | `}` | |
| 1375 | 591 | ||
| 1376 | 592 | A class implementing interfaces has a variable *\$intfmaps*, which has for each implemented GUID a map or delegator function. A map is a JS instance of the interfacetype plus a for each method name a function to call the class method. Here is an example map of *IUnknown* of *TInterfacedObject*:\ | |
| 1377 | 593 | ||
| 1378 | 594 | `{`\ | |
| 1379 | 595 | ` QueryInterface: function (){ return fn.apply(this.$o,arguments); },`\ | |
| 1380 | 596 | ` _AddRef: function (){ return fn.apply(this.$o,arguments); },`\ | |
| 1381 | 597 | ` _Release: function (){ return fn.apply(this.$o,arguments); },`\ | |
| 1382 | 598 | ` ...`\ | |
| 1383 | 599 | `}` | |
| 1384 | 600 | ||
| 1385 | 601 | When an interface is created for an object (here: a Pascal class instance), for example by using the *as*-operator "*ObjVar as IUnknown*", a JS object is created, which is an instance of the map object with its *\$o* set to the *ObjVar*.\ | |
| 1386 | 602 | ||
| 1387 | 603 | Supported: | |
| 1388 | 604 | ||
| 1389 | 605 | - methods, properties, default property | |
| 1390 | 606 | - *{\$interfaces com\|corba\|default}*\ | |
| 1391 | 607 | * 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 | |
| 1392 | 608 | - CORBA: lightweight, no automatic reference counting, no default ancestor, fast support checks. | |
| 1393 | 609 | - inheriting | |
| 1394 | 610 | - An interface without a GUID gets one autogenerated from its name and method names. | |
| 1395 | 611 | - Contrary to Delphi/FPC you can assign an interface type or var to the type TGuidString. | |
| 1396 | 612 | - a class implementing an interface must not be external | |
| 1397 | 613 | - 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. | |
| 1398 | 614 | - method resolution, procedure IUnknown._AddRef = IncRef; | |
| 1399 | 615 | - delegation: property Name: interface\|class read Field\|Getter implements AnInterface; | |
| 1400 | 616 | - is-operator: | |
| 1401 | 617 | - IntfVar is IntfType - types must be releated | |
| 1402 | 618 | - IntfVar is ClassType - types can be unrelated, class must not be external | |
| 1403 | 619 | - ObjVar is IntfType - can be unrelated | |
| 1404 | 620 | - as-operator | |
| 1405 | 621 | - IntfVar as IntfType - types must be releated | |
| 1406 | 622 | - IntfVar as ClassType - types can be unrelated, nil returns nil, invalid raises EInvalidCast | |
| 1407 | 623 | - ObjVar as IntfType - can be unrelated, nil if not found, COM: uses _AddRef | |
| 1408 | 624 | - typecast: | |
| 1409 | 625 | - IntfType(IntfVar) - must be related | |
| 1410 | 626 | - ClassType(IntfVar) - can be unrelated, nil if invalid | |
| 1411 | 627 | - IntfType(ObjVar) - nil if not found, COM: if ObjVar has delegate uses _AddRef | |
| 1412 | 628 | - TJSObject(IntfTypeOrVar). Note that you cannot typecast directly to a *TJSObject* descendant. You can use *TJSWindow(TJSObject(IntfType))*. | |
| 1413 | 629 | - jsvalue(intfvar) | |
| 1414 | 630 | - Assign operator: | |
| 1415 | 631 | - IntfVar:=nil; | |
| 1416 | 632 | - IntfVar:=IntfVar2; - IntfVar2 must be same type or a descendant | |
| 1417 | 633 | - IntfVar:=ObjVar; - nil if unsupported | |
| 1418 | 634 | - jsvalue:=IntfVar; | |
| 1419 | 635 | - TGUIDVar:=IntfType; | |
| 1420 | 636 | - TGUIDVar:=IntfVar; | |
| 1421 | 637 | - TGUIDVar:=stringconstant; | |
| 1422 | 638 | - TGUIDStringVar:=IntfVar; | |
| 1423 | 639 | - StringVar:=GuidVar; | |
| 1424 | 640 | - Equal/Inequal operator: | |
| 1425 | 641 | - IntfVar=nil; | |
| 1426 | 642 | - IntfVar=IntfVar2; - must be related | |
| 1427 | 643 | - jsvalue=IntfVar; | |
| 1428 | 644 | - TGUIDVar=IntfType; | |
| 1429 | 645 | - TGUIDVar=IntfVar; | |
| 1430 | 646 | - TGUIDVar=string; | |
| 1431 | 647 | - TGUIDStringVar=IntfVar; | |
| 1432 | 648 | - Passing an COMIntfVar to an untyped parameter or *JSValue* does not trigger *_AddRef, _Release*. | |
| 1433 | 649 | - Assigned(IntfVar) | |
| 1434 | 650 | - RTTI, typeinfo(IntfType), typeinfo(IntfVar) | |
| 1435 | 651 | ||
| 1436 | 652 | Not yet supported: array of intferfacetype, interface as record member. | |
| 1437 | 653 | ||
| 1438 | 654 | ## Translating helpers | |
| 1439 | 655 | ||
| 1440 | 656 | Pas2js supports class helpers, record helpers and type helpers since 1.3. The extend is only virtual, the helped type is kept untouched.\ | |
| 1441 | 657 | ||
| 1442 | 658 | - A **class helper** can "extend" Pascal classes and external JS classes. | |
| 1443 | 659 | - A **record helper** can "extend" a record type. In \$mode delphi a record helper can extend other types as well, see *type helper* | |
| 1444 | 660 | - 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.\ | |
| 1445 | 661 | Type helpers are enabled by default in *\$mode delphi* and disabled in *\$mode objfpc*. You can enable them with **{\$modeswitch typehelpers}**. | |
| 1446 | 662 | - 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.\ | |
| 1447 | 663 | A class with ancestors can have one active helper per ancestor type, so multiple helpers can be active, same as FPC/Delphi.\ | |
| 1448 | 664 | Using **{\$modeswitch multihelpers}** you can activate all helpers within scope. | |
| 1449 | 665 | - Nested helpers (e.g. *TDemo.TSub.THelper*) are elevated. Visibility is ignored. Same as FPC/Delphi. | |
| 1450 | 666 | - Helpers cannot be forward defined (e.g. no *THelper = helper;*). | |
| 1451 | 667 | - Helpers must not have fields. | |
| 1452 | 668 | - **Class Var, Const, Type** | |
| 1453 | 669 | - **Visibility** : *strict private .. published* | |
| 1454 | 670 | - **Function, procedure**: In class and record helpers *Self* is the class/record instance. For other types Self is a reference to the passed value. | |
| 1455 | 671 | - **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. | |
| 1456 | 672 | - **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. | |
| 1457 | 673 | - no destructor | |
| 1458 | 674 | - **Property** : getters/setters can refer to members of the helper, its ancestors and the helped class/record. | |
| 1459 | 675 | - **Class property** : getter can be static or non static. Delphi/FPC only allows static. | |
| 1460 | 676 | - **Ancestors** : Helpers can have an ancestor helper, but they do not have a shared root class, especially not *TObject*. | |
| 1461 | 677 | - **no virtual, abstract, override**. Delphi allows them, but 10.3 crashes when calling. | |
| 1462 | 678 | - **inherited** : *inherited* inside a method of a class/record calls helper of ancestor.\ | |
| 1463 | 679 | *inherited* inside a helper depends on the \$mode: | |
| 1464 | 680 | - *\$mode objfpc* : *inherited;* and *inherited Name(args);* work the same and searches first in HelperForType, then in ancestor(s). | |
| 1465 | 681 | - *\$mode delphi: inherited;* : skip ancestors and HelperForType, searches first in helper(s) of ancestor of HelperForType. | |
| 1466 | 682 | - *\$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. | |
| 1467 | 683 | - **RTTI**: *typeinfo(somehelper)* returns a pointer to *TTypeInfoHelper* with *Kind tkHelper*. | |
| 1468 | 684 | - There are some special cases when using a **type helper** function/procedure on a value: | |
| 1469 | 685 | - *function result* : using a temporary variable | |
| 1470 | 686 | - *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. | |
| 1471 | 687 | - *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. | |
| 1472 | 688 | - *with value do ;* : uses a temporary variable. Delphi/FPC do not support it. | |
| 1473 | 689 | - A method with *external name* modifier is treated as an external method of the helped type. | |
| 1474 | 690 | ||
| 1475 | 691 | ## Translating attributes | |
| 1476 | 692 | ||
| 1477 | 693 | Attributes are stored in the TTypeInfo objects as streams stored in an array. See the function *GetRTTIAttributes* in unit *TypInfo* for details. | |
| 1478 | 694 | ||
| 1479 | 695 | ## Translating try..finally | |
| 1480 | 696 | ||
| 1481 | 697 | JavaScript has the same, so it translates straight forward. | |
| 1482 | 698 | ||
| 1483 | 699 | ## Translating try..except | |
| 1484 | 700 | ||
| 1485 | - | ||
| 1486 | - | ||
| 1487 | - | ||
| 1488 | - | ||
| 1489 | - | ||
| 1490 | - | ||
| 1491 | - | ||
| 1492 | - | ||
| 1493 | - | ||
| 1494 | - | ||
| 1495 | - | ||
| 1496 | - | ||
| 1497 | - | ||
| 1498 | - | ||
| 1499 | - | ||
| 1500 | - | ||
| 1501 | - | ||
| 1502 | - | ||
| 1503 | - | ||
| 1504 | - | ||
| 1505 | - | ||
| 1506 | - | ||
| 1507 | - | ||
| 1508 | - | ||
| 1509 | - | ||
| 1510 | - | ||
| 1511 | - | ||
| 1512 | - | ||
| 1513 | - | ||
| 1514 | - | ||
| 1515 | - | ||
| 1516 | - | ||
| 1517 | - | ||
| 1518 | - | ||
| 1519 | - | ||
| 1520 | - | ||
| 1521 | - | ||
| 1522 | - | ||
| 1523 | - | ||
| 1524 | - | ||
| 1525 | - | ||
| 1526 | - | ||
| 1527 | - | ||
| 1528 | - | ||
| 1529 | - | ||
| 1530 | - | ||
| 1531 | - | ||
| 1532 | - | ||
| 1533 | - | ||
| 1534 | - | ||
| 1535 | - | ||
| 1536 | - | ||
| 1537 | - | ||
| 1538 | - | ||
| 1539 | - | ||
| 1540 | - | ||
| 1541 | - | ||
| 1542 | - | ||
| 701 | + | | Pascal | JavaScript | | |
| 702 | + | |---|---| | |
| 703 | + | | `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;` · ` };` · `},` · `[]);` | | |
| 1543 | 704 | ||
| 1544 | 705 | Notes: | |
| 1545 | 706 | ||
| 1546 | 707 | - Division by zero does not raise an exception in JavaScript. Instead it results in Infinity, except for 0/0 which results in NaN. | |
| 1547 | 708 | - There is no ExceptObject in SysUtils. | |
| 1548 | 709 | - When calling external functions keep in mind that JS allows to throw (raise) any value, often a string.\ | |
| 1549 | 710 | You can access the current except value via JSExceptValue in unit JS.\ | |
| 1550 | 711 | Note that this is only valid inside the catch-block. The compiler will not warn, if you use it outside. | |
| 1551 | 712 | ||
| 1552 | 713 | ## Translating enumerators | |
| 1553 | 714 | ||
| 1554 | 715 | The for..in..do supports enumerating: | |
| 1555 | 716 | ||
| 1556 | 717 | - ordinal types like char, boolean, byte, ..., longword, enums, custom ranges are translated to a for loop. | |
| 1557 | 718 | - set types are translated to a for loop, while const sets and set variables are enumerated via a for(...in...) loop. | |
| 1558 | 719 | - string and array variables are enumerated via for loops. | |
| 1559 | 720 | - for aString in ArrayOfString do ... | |
| 1560 | 721 | - *for key in jsvalue do* translates to *for (key in jsvalue){}* | |
| 1561 | 722 | - *for key in ExternalClass do*\ | |
| 1562 | 723 | * 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. | |
| 1563 | 724 | - Otherwise it translates to *for (key in externalclass){}*, which enumerates the keys (property names) of the JS object. | |
| 1564 | 725 | ||
| 1565 | 726 | The class GetEnumerator function is translated like this: | |
| 1566 | 727 | ||
| 1567 | - | ||
| 1568 | - | ||
| 1569 | - | ||
| 1570 | - | ||
| 1571 | - | ||
| 1572 | - | ||
| 1573 | - | ||
| 1574 | - | ||
| 1575 | - | ||
| 1576 | - | ||
| 1577 | - | ||
| 1578 | - | ||
| 1579 | - | ||
| 1580 | - | ||
| 1581 | - | ||
| 1582 | - | ||
| 1583 | - | ||
| 1584 | - | ||
| 1585 | - | ||
| 1586 | - | ||
| 1587 | - | ||
| 1588 | - | ||
| 1589 | - | ||
| 1590 | - | ||
| 1591 | - | ||
| 1592 | - | ||
| 1593 | - | ||
| 1594 | - | ||
| 1595 | - | ||
| 1596 | - | ||
| 1597 | - | ||
| 1598 | - | ||
| 1599 | - | ||
| 1600 | - | ||
| 1601 | - | ||
| 1602 | - | ||
| 1603 | - | ||
| 1604 | - | ||
| 1605 | - | ||
| 1606 | - | ||
| 1607 | - | ||
| 728 | + | | Pascal | JavaScript | | |
| 729 | + | |---|---| | |
| 730 | + | | `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)` · ` };` · ` };` · `},` · `[]);` | | |
| 1608 | 731 | ||
| 1609 | 732 | Notes: | |
| 1610 | 733 | ||
| 1611 | 734 | - Not supported: operator Enumerator, member modifier enumerator (i.e. custom Current and MoveNext) | |
| 1612 | 735 | ||
| 1613 | 736 | ## Translating function types | |
| 1614 | 737 | ||
| 1615 | 738 | JavaScript functions work like Delphi's "reference to function", which means like closures, capturing outer variables. Assigning a normal function or nested function to a procedural variable is translated to a simple assignment. A Pascal method needs **this** to be the class or class instance.\ | |
| 1616 | 739 | Note that *bind* cannot be used, because it does not support the *equal* operator. Instead a wrapper is created: | |
| 1617 | 740 | ||
| 1618 | - | ||
| 1619 | - | ||
| 1620 | - | ||
| 1621 | - | ||
| 1622 | - | ||
| 1623 | - | ||
| 1624 | - | ||
| 1625 | - | ||
| 1626 | - | ||
| 1627 | - | ||
| 1628 | - | ||
| 1629 | - | ||
| 1630 | - | ||
| 1631 | - | ||
| 1632 | - | ||
| 1633 | - | ||
| 1634 | - | ||
| 1635 | - | ||
| 1636 | - | ||
| 1637 | - | ||
| 1638 | - | ||
| 1639 | - | ||
| 1640 | - | ||
| 1641 | - | ||
| 1642 | - | ||
| 1643 | - | ||
| 1644 | - | ||
| 1645 | - | ||
| 1646 | - | ||
| 1647 | - | ||
| 1648 | - | ||
| 1649 | - | ||
| 1650 | - | ||
| 1651 | - | ||
| 1652 | - | ||
| 1653 | - | ||
| 1654 | - | ||
| 1655 | - | ||
| 1656 | - | ||
| 1657 | - | ||
| 1658 | - | ||
| 1659 | - | ||
| 1660 | - | ||
| 1661 | - | ||
| 1662 | - | ||
| 1663 | - | ||
| 1664 | - | ||
| 1665 | - | ||
| 1666 | - | ||
| 1667 | - | ||
| 1668 | - | ||
| 1669 | - | ||
| 1670 | - | ||
| 1671 | - | ||
| 1672 | - | ||
| 1673 | - | ||
| 1674 | - | ||
| 1675 | - | ||
| 1676 | - | ||
| 1677 | - | ||
| 1678 | - | ||
| 1679 | - | ||
| 1680 | - | ||
| 1681 | - | ||
| 1682 | - | ||
| 1683 | - | ||
| 741 | + | | Pascal | JavaScript | | |
| 742 | + | |---|---| | |
| 743 | + | | `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;` · ` if (typeof(fn)==='string'){` · ` cb = function(){` · ` return scope[fn].apply(scope,arguments);` · ` };` · ` } else {` · ` cb = function(){` · ` return fn.apply(scope,arguments);` · ` };` · ` };` · ` cb.scope = scope;` · ` cb.fn = fn;` · ` return cb;` · ` },` · ` ...` | | |
| 1684 | 744 | ||
| 1685 | 745 | Notes: | |
| 1686 | 746 | ||
| 1687 | 747 | - You can assign a nested procedure to procedure variable. You don't need and you must not add the FPC "*is nested*" modifier. | |
| 1688 | 748 | - In pas2js a procedural typed declared as **reference to** accepts procedures, local procedures and methods. Delphi only supports capturing procedures and methods. FPC 3.0.4 does not support reference-to. | |
| 1689 | 749 | - In pas2js the calling convention *safecall* has a special meaning:\ | |
| 1690 | 750 | Assigning a procedure/method, uses *rtl.createSafeCallback* instead of *createCallback*, enclosing a call in a *try..catch* block. When an exception is thrown by JS, it is caught and delegated to *rtl.handleUncaughtException(err)*.\ | |
| 1691 | 751 | For example:\ | |
| 1692 | 752 | *aButtonElement.OnClick:=@DoClick;* uses *rtl.createSafeCallback*\ | |
| 1693 | 753 | *aButtonElement.OnClick:=SomeElement.OnClick;* does not.\ | |
| 1694 | 754 | ||
| 1695 | 755 | ## Translating anonymous functions | |
| 1696 | 756 | ||
| 1697 | 757 | Anonymous functions are supported since pas2js 1.1.\ | |
| 1698 | 758 | Note that in pas2js local procedures are closures as well. See below.\ | |
| 1699 | 759 | For pas2js 1.0 the next best thing are local procedures. For example: | |
| 1700 | 760 | ||
| 1701 | - | ||
| 1702 | - | ||
| 1703 | - | ||
| 1704 | - | ||
| 1705 | - | ||
| 1706 | - | ||
| 1707 | - | ||
| 1708 | - | ||
| 1709 | - | ||
| 1710 | - | ||
| 1711 | - | ||
| 1712 | - | ||
| 1713 | - | ||
| 1714 | - | ||
| 1715 | - | ||
| 1716 | - | ||
| 1717 | - | ||
| 1718 | - | ||
| 1719 | - | ||
| 1720 | - | ||
| 1721 | - | ||
| 1722 | - | ||
| 1723 | - | ||
| 1724 | - | ||
| 1725 | - | ||
| 1726 | - | ||
| 1727 | - | ||
| 1728 | - | ||
| 1729 | - | ||
| 1730 | - | ||
| 1731 | - | ||
| 1732 | - | ||
| 1733 | - | ||
| 1734 | - | ||
| 1735 | - | ||
| 1736 | - | ||
| 1737 | - | ||
| 1738 | - | ||
| 1739 | - | ||
| 1740 | - | ||
| 1741 | - | ||
| 1742 | - | ||
| 1743 | - | ||
| 761 | + | | Delphi | Pas2js | | |
| 762 | + | |---|---| | |
| 763 | + | | `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.` | | |
| 1744 | 764 | ||
| 1745 | 765 | ## Translating var modifier absolute | |
| 1746 | 766 | ||
| 1747 | 767 | The absolute modifier works as an alias. That means it works FPC/Delphi compatible for related types like Pointer and TObject, and works incompatible for unrelated types like longword and record (e.g. *var r: TPoint absolute MyLongInt*).\ | |
| 1748 | 768 | The modifier is currently only supported for local variables. | |
| 1749 | 769 | ||
| 1750 | 770 | ## Translating assert() | |
| 1751 | 771 | ||
| 1752 | 772 | The Assert(boolean\[,string\]) function is translated to *if(bool) throw x*. If unit sysutils is used, it creates an EAssertFailed exception.\ | |
| 1753 | 773 | Otherwise it throws a string.\ | |
| 1754 | 774 | ||
| 1755 | 775 | - Command line enable with -Sa, disable with -Sa- | |
| 1756 | 776 | - In code enable with *{\$C+}* or *{\$Assertions on}*, disable with *{\$C-}* or *{\$Assertions off}* | |
| 1757 | 777 | ||
| 1758 | 778 | ## Dispatch messages | |
| 1759 | 779 | ||
| 1760 | 780 | The procedure modifier **message** and the **Dispatch** method works similar to FPC/Delphi, as it expects a record of a specific format and ***TObject.Dispatch*** calls the corresponding method with that message number or string.\ | |
| 1761 | 781 | The procedure modifier *message \<integer\>* adds an entry to hidden *YourClass.\$msgint* object, while the modifier *message \<string\>* adds an entry to the hidden *YourClass.\$msgstr* object.\ | |
| 1762 | 782 | Two new directives ***{\$DispatchField fieldname}**'' and***{\$DispatchStrField fieldname}**'' were added. Insert these directives in front of your class declaration to let the compiler check all methods with message modifiers of this class and its descendants whether they pass a record with the required field. For example: | |
| 1763 | 783 | ||
| 1764 | 784 | ` {$DispatchField Msg} // enable checking message methods for record field name "Msg"`\ | |
| 1765 | 785 | ` {$DispatchStrField MsgStr}`\ | |
| 1766 | 786 | ` TObject = class`\ | |
| 1767 | 787 | ` procedure Dispatch(var aMessage); virtual;`\ | |
| 1768 | 788 | ` procedure DispatchStr(var aMessage); virtual;`\ | |
| 1769 | 789 | ` end;`\ | |
| 1770 | 790 | ` TMouseDownMsg = record`\ | |
| 1771 | 791 | ` Id: integer; // Id instead of Msg, works in FPC, but not in pas2js`\ | |
| 1772 | 792 | ` x,y: integer;`\ | |
| 1773 | 793 | ` end;`\ | |
| 1774 | 794 | ` TMouseUpMsg = record`\ | |
| 1775 | 795 | ` MsgStr: string;`\ | |
| 1776 | 796 | ` X,Y: integer;`\ | |
| 1777 | 797 | ` end;`\ | |
| 1778 | 798 | ` TWinControl = class`\ | |
| 1779 | 799 | ` procedure MouseDownMsg(var Msg: TMouseDownMsg); message 3; // warning: Dispatch requires record field Msg`\ | |
| 1780 | 800 | ` procedure MouseUpMsg(var Msg: TMouseUpMsg); message 'up'; // ok, record with string field name MsgStr`\ | |
| 1781 | 801 | ` end;` | |
| 1782 | 802 | ||
| 1783 | 803 | Note that descendant classes can override the *\$DispatchField* or disable the check using *{\$DispatchField -}*. | |
| 1784 | 804 | ||
| 1785 | 805 | ## Calling JavaScript from Pascal | |
| 1786 | 806 | ||
| 1787 | 807 | Pas2js allows to write low level functions and/or access a JavaScript library with the following possibilities: | |
| 1788 | 808 | ||
| 1789 | 809 | ## The asm block | |
| 1790 | 810 | ||
| 1791 | 811 | The asm block is pure JavaScript, that is copied directly into the generated .js file. | |
| 1792 | 812 | ||
| 1793 | - | ||
| 1794 | - | ||
| 1795 | - | ||
| 1796 | - | ||
| 1797 | - | ||
| 1798 | - | ||
| 1799 | - | ||
| 1800 | - | ||
| 1801 | - | ||
| 1802 | - | ||
| 1803 | - | ||
| 1804 | - | ||
| 1805 | - | ||
| 1806 | - | ||
| 1807 | - | ||
| 1808 | - | ||
| 1809 | - | ||
| 1810 | - | ||
| 1811 | - | ||
| 1812 | - | ||
| 1813 | - | ||
| 1814 | - | ||
| 1815 | - | ||
| 1816 | - | ||
| 1817 | - | ||
| 1818 | - | ||
| 1819 | - | ||
| 813 | + | | Pascal | JavaScript | | |
| 814 | + | |---|---| | |
| 815 | + | | `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);` · ` };` · ` },` · ` []);` · ` ` | | |
| 1820 | 816 | ||
| 1821 | 817 | Notes: | |
| 1822 | 818 | ||
| 1823 | 819 | - 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. | |
| 1824 | 820 | - The compiler does neither parse, nor check the syntax of the JS. | |
| 1825 | 821 | - 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;* | |
| 1826 | 822 | - Accessing an interface, program or library identifier:\ | |
| 1827 | 823 | * From inside the module you can use *\$mod.Identifier*. | |
| 1828 | 824 | - Otherwise use the fully qualified path *pas.Unitname.Identifier*. | |
| 1829 | 825 | - Accessing an implementation identifier:\ | |
| 1830 | 826 | * From inside the unit you can use *\$impl.Identifier*. | |
| 1831 | 827 | - Otherwise use the path *pas.Unitname.\$impl.Identifier*. | |
| 1832 | 828 | - 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*. | |
| 1833 | 829 | - 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*. | |
| 1834 | 830 | - Accessing a class member (class var, class procedure, class function) from a class method of the class: use *this.Identifier*. | |
| 1835 | 831 | - Access to Properties must use the getter/setter. | |
| 1836 | 832 | - When calling a Pascal method, make sure the **this** is correct: | |
| 1837 | 833 | - A class method (e.g. *class function*, *class procedure*) needs the class as *this*.\ | |
| 1838 | 834 | **Wrong**: *aCar.DoIt(params,...)*\ | |
| 1839 | 835 | **Correct**: *aCar.\$class.DoIt(params,...)*\ | |
| 1840 | 836 | - 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.\ | |
| 1841 | 837 | Pascal methods needs a wrapper to set *this* to the instance. Examples: | |
| 1842 | 838 | - An unit function: *DOMElement.onclick = \$mod.DoIt;* | |
| 1843 | 839 | - An implementation function: *DOMElement.onclick = \$impl.DoIt;*. | |
| 1844 | 840 | - A method: *DOMElement.onclick = this.DoIt.bind(this);* | |
| 1845 | 841 | - A class function/procedure: *DOMElement.onclick = this.DoIt.bind(this.\$class);* | |
| 1846 | 842 | - A nested function: *DOMElement.onclick = DoIt;*. | |
| 1847 | 843 | ||
| 1848 | 844 | ## The procedure modifier assembler | |
| 1849 | 845 | ||
| 1850 | 846 | You can write pure JavaScript functions like this: | |
| 1851 | 847 | ||
| 1852 | - | ||
| 1853 | - | ||
| 1854 | - | ||
| 1855 | - | ||
| 1856 | - | ||
| 1857 | - | ||
| 1858 | - | ||
| 1859 | - | ||
| 1860 | - | ||
| 1861 | - | ||
| 1862 | - | ||
| 1863 | - | ||
| 1864 | - | ||
| 1865 | - | ||
| 1866 | - | ||
| 1867 | - | ||
| 1868 | - | ||
| 1869 | - | ||
| 1870 | - | ||
| 1871 | - | ||
| 1872 | - | ||
| 1873 | - | ||
| 1874 | - | ||
| 1875 | - | ||
| 1876 | - | ||
| 1877 | - | ||
| 1878 | - | ||
| 848 | + | | Pascal | JavaScript | | |
| 849 | + | |---|---| | |
| 850 | + | | `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!");` · ` };` · `},` · `[]);` | | |
| 1879 | 851 | ||
| 1880 | 852 | See also \[#asm asm\]. | |
| 1881 | 853 | ||
| 1882 | 854 | ## The procedure modifier external | |
| 1883 | 855 | ||
| 1884 | 856 | The procedure modifier *external* requires a string constant and tells the compiler to replace a reference with this string value. The value is not checked for JS syntax. | |
| 1885 | 857 | ||
| 1886 | - | ||
| 1887 | - | ||
| 1888 | - | ||
| 1889 | - | ||
| 1890 | - | ||
| 1891 | - | ||
| 1892 | - | ||
| 1893 | - | ||
| 1894 | - | ||
| 1895 | - | ||
| 1896 | - | ||
| 1897 | - | ||
| 1898 | - | ||
| 1899 | - | ||
| 1900 | - | ||
| 1901 | - | ||
| 1902 | - | ||
| 1903 | - | ||
| 1904 | - | ||
| 1905 | - | ||
| 1906 | - | ||
| 858 | + | | Pascal | JavaScript | | |
| 859 | + | |---|---| | |
| 860 | + | | `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!");` · ` };` · `},` · `[]);` | | |
| 1907 | 861 | ||
| 1908 | 862 | ## The procedure modifier varargs | |
| 1909 | 863 | ||
| 1910 | 864 | Appending the **varargs** modifier to a procedure allows to pass arbitrary more parameters to a function. By default these parameters are untyped, i.e. any type fits. Alternatively you can use **varargs of aType** to allow only specific types.\ | |
| 1911 | 865 | To access these arguments use either *JSArguments* from unit JS or an *asm..end* block. | |
| 1912 | 866 | ||
| 1913 | - | ||
| 1914 | - | ||
| 1915 | - | ||
| 1916 | - | ||
| 1917 | - | ||
| 1918 | - | ||
| 1919 | - | ||
| 1920 | - | ||
| 1921 | - | ||
| 1922 | - | ||
| 1923 | - | ||
| 1924 | - | ||
| 1925 | - | ||
| 1926 | - | ||
| 1927 | - | ||
| 1928 | - | ||
| 1929 | - | ||
| 1930 | - | ||
| 1931 | - | ||
| 1932 | - | ||
| 1933 | - | ||
| 1934 | - | ||
| 1935 | - | ||
| 1936 | - | ||
| 1937 | - | ||
| 1938 | - | ||
| 1939 | - | ||
| 1940 | - | ||
| 1941 | - | ||
| 1942 | - | ||
| 1943 | - | ||
| 1944 | - | ||
| 1945 | - | ||
| 1946 | - | ||
| 1947 | - | ||
| 1948 | - | ||
| 1949 | - | ||
| 1950 | - | ||
| 1951 | - | ||
| 1952 | - | ||
| 1953 | - | ||
| 1954 | - | ||
| 1955 | - | ||
| 1956 | - | ||
| 1957 | - | ||
| 1958 | - | ||
| 1959 | - | ||
| 1960 | - | ||
| 1961 | - | ||
| 867 | + | | Pascal | JavaScript | | |
| 868 | + | |---|---| | |
| 869 | + | | `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);` · ` };` · `},` · `[]);` | | |
| 1962 | 870 | ||
| 1963 | 871 | The above example defines a function *Sum*, that requires the first parameter to be a boolean and then an arbitrary number of parameters. The compiler does not type check the other parameters, so you can pass anything readable. | |
| 1964 | 872 | ||
| 1965 | 873 | ## The var modifier external | |
| 1966 | 874 | ||
| 1967 | 875 | The var modifier *external* allows to use a JavaScript variable or constant. | |
| 1968 | 876 | ||
| 1969 | - | ||
| 1970 | - | ||
| 1971 | - | ||
| 1972 | - | ||
| 1973 | - | ||
| 1974 | - | ||
| 1975 | - | ||
| 1976 | - | ||
| 1977 | - | ||
| 1978 | - | ||
| 1979 | - | ||
| 1980 | - | ||
| 1981 | - | ||
| 1982 | - | ||
| 1983 | - | ||
| 1984 | - | ||
| 1985 | - | ||
| 1986 | - | ||
| 1987 | - | ||
| 1988 | - | ||
| 1989 | - | ||
| 1990 | - | ||
| 1991 | - | ||
| 877 | + | | Pascal | JavaScript | | |
| 878 | + | |---|---| | |
| 879 | + | | `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;` · ` };` · `},` · `[]);` | | |
| 1992 | 880 | ||
| 1993 | 881 | ## The external modifier of class members | |
| 1994 | 882 | ||
| 1995 | 883 | The method modifier *external* works as the procedure modifier, except it uses the scope of the class or instance.\ | |
| 1996 | 884 | The field modifier *external* works as the var modifier, except it uses the scope of the class or instance.\ | |
| 1997 | 885 | Requires the modeswitch **externalclass**. | |
| 1998 | 886 | ||
| 1999 | - | ||
| 2000 | - | ||
| 2001 | - | ||
| 2002 | - | ||
| 2003 | - | ||
| 2004 | - | ||
| 2005 | - | ||
| 2006 | - | ||
| 2007 | - | ||
| 2008 | - | ||
| 2009 | - | ||
| 2010 | - | ||
| 2011 | - | ||
| 2012 | - | ||
| 2013 | - | ||
| 2014 | - | ||
| 2015 | - | ||
| 2016 | - | ||
| 2017 | - | ||
| 2018 | - | ||
| 2019 | - | ||
| 2020 | - | ||
| 2021 | - | ||
| 2022 | - | ||
| 2023 | - | ||
| 2024 | - | ||
| 2025 | - | ||
| 2026 | - | ||
| 2027 | - | ||
| 2028 | - | ||
| 2029 | - | ||
| 2030 | - | ||
| 2031 | - | ||
| 2032 | - | ||
| 2033 | - | ||
| 2034 | - | ||
| 2035 | - | ||
| 2036 | - | ||
| 2037 | - | ||
| 2038 | - | ||
| 2039 | - | ||
| 2040 | - | ||
| 2041 | - | ||
| 2042 | - | ||
| 2043 | - | ||
| 2044 | - | ||
| 2045 | - | ||
| 2046 | - | ||
| 2047 | - | ||
| 887 | + | | Pascal | JavaScript | | |
| 888 | + | |---|---| | |
| 889 | + | | `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);` · ` };` · `},` · `[]);` | | |
| 2048 | 890 | ||
| 2049 | 891 | - Non identifiers like "0" or "A B" must be enclosed in brackets. | |
| 2050 | 892 | ||
| 2051 | 893 | ## External classes | |
| 2052 | 894 | ||
| 2053 | 895 | pas2js introduces a new class modifier "*external name*", which makes the whole class external. External classes allow to easily declare Pascal wrappers for JavaScript objects and function objects.\ | |
| 2054 | 896 | They need the modeswitch **externalclass** in front of the class.\ | |
| 2055 | 897 | An external class is not a TObject and has none of its methods.\ | |
| 2056 | 898 | All members are external. If you omit the *external* modifier the external name is the member name. Keep in mind that JS is case sensitive.\ | |
| 2057 | 899 | Properties work the same as with Pascal classes, i.e. are replaced by Getter/Setter.\ | |
| 2058 | 900 | Destructors are not allowed.\ | |
| 2059 | 901 | Constructors are supported in four ways: | |
| 2060 | 902 | ||
| 2061 | 903 | - *constructor New* is translated to *new ExtClass(params)*, and for nested external class: *new ExtParentClass.ExtClass(Params)* | |
| 2062 | 904 | - *constructor New; external name ''GlobalFunc''* is translated to *new GlobalFunc(params)*. | |
| 2063 | 905 | - *constructor SomeName; external name*'{}' is translated to *{}*. | |
| 2064 | 906 | - Otherwise it is translated to *new ExtClass.FuncName(params)*, and for nested external class: *new ExtParentClass.ExtClass.FuncName(params)*. | |
| 2065 | 907 | ||
| 2066 | - | ||
| 2067 | - | ||
| 2068 | - | ||
| 2069 | - | ||
| 2070 | - | ||
| 2071 | - | ||
| 2072 | - | ||
| 2073 | - | ||
| 2074 | - | ||
| 2075 | - | ||
| 2076 | - | ||
| 2077 | - | ||
| 2078 | - | ||
| 2079 | - | ||
| 2080 | - | ||
| 2081 | - | ||
| 2082 | - | ||
| 2083 | - | ||
| 2084 | - | ||
| 2085 | - | ||
| 2086 | - | ||
| 2087 | - | ||
| 2088 | - | ||
| 2089 | - | ||
| 2090 | - | ||
| 2091 | - | ||
| 2092 | - | ||
| 2093 | - | ||
| 2094 | - | ||
| 2095 | - | ||
| 2096 | - | ||
| 2097 | - | ||
| 2098 | - | ||
| 908 | + | | Pascal | JavaScript | | |
| 909 | + | |---|---| | |
| 910 | + | | `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);` · ` };` · `});` | | |
| 2099 | 911 | ||
| 2100 | 912 | Notes: | |
| 2101 | 913 | ||
| 2102 | 914 | - An external class can descend from another external class. | |
| 2103 | 915 | - Any class instance can be type casted to any root class. | |
| 2104 | 916 | - A Pascal class can descend from an external class. | |
| 2105 | 917 | - You can define a class-of external class and the **is** and **as** operators work similar. | |
| 2106 | 918 | - 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*. | |
| 2107 | 919 | - Const with an expression are replaced by the expression. | |
| 2108 | 920 | - Const without an expression are treated as a readonly variable. | |
| 2109 | 921 | - Class functions and class procedures are allowed, but can only be called via the class, not via an instance.\ | |
| 2110 | 922 | For example you can call the class function *TJSString.fromCharCode()*, but you cannot call *aJSString.fromCharCode()*. | |
| 2111 | 923 | - 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))*. | |
| 2112 | 924 | - 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, except when typecasting to *TJSFunction* (pas2js 1.5+). | |
| 2113 | 925 | ||
| 2114 | 926 | ## External class as ancestor | |
| 2115 | 927 | ||
| 2116 | 928 | A Pascal class can descend from an external class - a JS object or function.\ | |
| 2117 | 929 | The methods *AfterConstruction* and *BeforeDestruction* are called if they exist.\ | |
| 2118 | 930 | New instances of a JS Object descendant are created by default with *Object.create(ancestorclass)*.\ | |
| 2119 | 931 | New instances of a JS Function descendant are created by default with *new DescendantFunc()*.\ | |
| 2120 | 932 | You can override this, by providing a non private\ | |
| 2121 | 933 | **class function NewInstance(fnname: string; const paramsarray): TPasClass; virtual;**. This method is called to create a new instance and before calling the constructor. The name is arbitrary, but the function must be the **first non private**, non external, virtual class function with the class as result type.\ | |
| 2122 | 934 | ||
| 2123 | - | ||
| 2124 | - | ||
| 2125 | - | ||
| 2126 | - | ||
| 2127 | - | ||
| 2128 | - | ||
| 2129 | - | ||
| 2130 | - | ||
| 2131 | - | ||
| 2132 | - | ||
| 2133 | - | ||
| 2134 | - | ||
| 2135 | - | ||
| 2136 | - | ||
| 2137 | - | ||
| 2138 | - | ||
| 2139 | - | ||
| 2140 | - | ||
| 2141 | - | ||
| 2142 | - | ||
| 2143 | - | ||
| 2144 | - | ||
| 2145 | - | ||
| 2146 | - | ||
| 2147 | - | ||
| 2148 | - | ||
| 2149 | - | ||
| 2150 | - | ||
| 2151 | - | ||
| 2152 | - | ||
| 2153 | - | ||
| 2154 | - | ||
| 2155 | - | ||
| 2156 | - | ||
| 2157 | - | ||
| 2158 | - | ||
| 2159 | - | ||
| 2160 | - | ||
| 2161 | - | ||
| 2162 | - | ||
| 2163 | - | ||
| 2164 | - | ||
| 2165 | - | ||
| 2166 | - | ||
| 2167 | - | ||
| 2168 | - | ||
| 2169 | - | ||
| 2170 | - | ||
| 2171 | - | ||
| 2172 | - | ||
| 2173 | - | ||
| 2174 | - | ||
| 2175 | - | ||
| 2176 | - | ||
| 2177 | - | ||
| 2178 | - | ||
| 2179 | - | ||
| 2180 | - | ||
| 2181 | - | ||
| 2182 | - | ||
| 2183 | - | ||
| 2184 | - | ||
| 2185 | - | ||
| 2186 | - | ||
| 2187 | - | ||
| 2188 | - | ||
| 2189 | - | ||
| 2190 | - | ||
| 2191 | - | ||
| 2192 | - | ||
| 2193 | - | ||
| 2194 | - | ||
| 2195 | - | ||
| 2196 | - | ||
| 2197 | - | ||
| 2198 | - | ||
| 2199 | - | ||
| 2200 | - | ||
| 2201 | - | ||
| 2202 | - | ||
| 2203 | - | ||
| 2204 | - | ||
| 2205 | - | ||
| 2206 | - | ||
| 2207 | - | ||
| 2208 | - | ||
| 935 | + | | Pascal | JavaScript | | |
| 936 | + | |---|---| | |
| 937 | + | | `// Example for descending a Pascal class from a JS Object` · `Program MyModule;` · `{$modeswitch externalclass}` · `type` · ` TExtA = class external name 'ExtA'` · ` end;` · ` TMyB = class(TExtA)` · ` protected` · ` // optional: override default allocation` · ` 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); // that is what the rtl does` · ` 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 () {` · ` };` · `});` | | |
| 2209 | 938 | ||
| 2210 | - | ||
| 939 | + | | Pascal | JavaScript | | |
| 940 | + | |---|---| | |
| 941 | + | | `// Example for descending a Pascal class from a JS Function` · `Program MyModule;` · `{$modeswitch externalclass}` · `uses JS;` · `type` · ` TExternalFunc = class external name 'ExternalFunc'(TJSFunction)` · ` constructor New(a: word);` · ` end;` · ` TMyFunc = class(TExternalFunc)` · ` constructor Create(b: word);` · ` end;` · `constructor TMyFunc.Create(b: word);` · `Begin` · ` inherited New(b+1); // optional: call inherited constructor function` · `End;` · · `var` · ` f: TMyFunc;` · `Begin` · ` f:=TMyFunc.Create(3);` · ` writeln(jsInstanceOf(f,TExternalFunc)); // writes true, instanceof operator works as expected` · `End.` | `rtl.module("program",["System","js"],function () {` · ` var $mod = this;` · ` rtl.createClassExt($mod, "TMyFunc", ExternalFunc, "", function () {` · ` this.$init = function () {` · ` };` · ` this.$final = function () {` · ` };` · ` this.Create$2 = function (b) {` · ` this.$ancestorfunc(b+1);` · ` };` · ` });` · ` this.f = null;` · ` $mod.$main = function () {` · ` f = $mod.TMyFunc.$create("Create$2",[3]);` · ` pas.System.Writeln(pas.JS.jsInstanceOf(f,ExternalFunc));` · ` };` · `});` | | |
| 2211 | 942 | ||
| 2212 | 943 | ## The JSValue type | |
| 2213 | 944 | ||
| 2214 | 945 | Pas2js introduces a new type **JSValue**, which works similar to a JS variable. You can assign almost any value to it and it can be type casted to many types. JSValue is useful for JS wrappers, when a variable can have multiple types. And it can be used for containers storing arbitrary data, e.g. a list of JSValue.\ | |
| 2215 | 946 | Key features:\ | |
| 2216 | 947 | ||
| 2217 | 948 | - A JSValue variable initial value is undefined. | |
| 2218 | 949 | - Operators: =, \<\> | |
| 2219 | 950 | - type casting a *JSValue* to ... | |
| 2220 | 951 | - *Integer: Math.floor(aJSValue)* Note: may return *NaN* | |
| 2221 | 952 | - *Boolean: !(aJSValue == false)* Note: works for numbers too, *0==false* | |
| 2222 | 953 | - *Double: rtl.getNumber(aJSValue)* Note: *typeof(n)=="number"?n:NaN;* | |
| 2223 | 954 | - *String: ""+aJSValue* | |
| 2224 | 955 | - *Char: rtl.getChar(aJSValue)* Note: *((typeof(c)!="string") && (c.length==1)) ? c : ""* | |
| 2225 | 956 | - class instance or class-of: *rtl.getObject()* Note: checks for type *"object"* | |
| 2226 | 957 | - enum type | |
| 2227 | 958 | - pointer | |
| 2228 | 959 | - 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. | |
| 2229 | 960 | - *function Assigned(V: jsvalue): boolean* returns true if\ | |
| 2230 | 961 | *(V!=undefined) && (V!=null) && (!rtl.isArray(V) \|\| (V.length \> 0))* | |
| 2231 | 962 | - *function StrictEqual(const A: jsvalue; const B): boolean* | |
| 2232 | 963 | - *function StrictInequal(const A: jsvalue; const B): boolean* | |
| 2233 | 964 | - Any array can be assigned to an *array of jsvalue*. | |
| 2234 | 965 | - is-operator: *jsvalue is class-type*, *jsvalue is class-of-type*\ | |
| 2235 | 966 | - The unit JS provides many utility functions for JSValue, like *hasString, hasValue, isBoolean, isNumber, isInteger, isObject, isClass, isClassInstance, etc..* | |
| 2236 | 967 | ||
| 2237 | 968 | ## Accessing JS object properties with the bracket accessor | |
| 2238 | 969 | ||
| 2239 | 970 | Pas2js allows to define index properties that map directly to the JS object properties. For example the default property of TJSObject allows to get and set the properties of an object. For example *TJSObject(AnObject)\['Name'\]:=Value;*\ | |
| 2240 | 971 | Another example is the default property of TJSArray, that allows access via integers *aTJSArray\[3\]:=Value;*\ | |
| 2241 | 972 | To define your own bracket accessor define a normal index property and define the getter/setter as *external name '\[\]*'.\ | |
| 2242 | 973 | Here is an example for a read only accessor: | |
| 2243 | 974 | ||
| 2244 | - | ||
| 2245 | - | ||
| 2246 | - | ||
| 2247 | - | ||
| 2248 | - | ||
| 2249 | - | ||
| 2250 | - | ||
| 2251 | - | ||
| 2252 | - | ||
| 2253 | - | ||
| 2254 | - | ||
| 2255 | - | ||
| 2256 | - | ||
| 2257 | - | ||
| 2258 | - | ||
| 2259 | - | ||
| 2260 | - | ||
| 2261 | - | ||
| 2262 | - | ||
| 2263 | - | ||
| 2264 | - | ||
| 2265 | - | ||
| 2266 | - | ||
| 2267 | - | ||
| 2268 | - | ||
| 2269 | - | ||
| 2270 | - | ||
| 2271 | - | ||
| 2272 | - | ||
| 2273 | - | ||
| 975 | + | | Pascal | JavaScript | | |
| 976 | + | |---|---| | |
| 977 | + | | `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];` · ` };` · `});` | | |
| 2274 | 978 | ||
| 2275 | 979 | Notes: | |
| 2276 | 980 | ||
| 2277 | 981 | - 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. | |
| 2278 | 982 | ||
| 2279 | 983 | ## RTTI - Run Time Type Information | |
| 2280 | 984 | ||
| 2281 | 985 | The RTTI provides access to the type data of all published properties, fields and methods. The type data provides similar information as Delphi/FPC, but the internals are very different. Delphi/FPC uses pointers, variant records and fake static arrays, which have no equivalent in JS. Instead pas2js uses external classes. For example: | |
| 2282 | 986 | ||
| 2283 | 987 | ` TTypeInfo = class external name 'rtl.tTypeInfo'`\ | |
| 2284 | 988 | ` public`\ | |
| 2285 | 989 | ` Name: String external name 'name';`\ | |
| 2286 | 990 | ` Kind: TTypeKind external name 'kind';`\ | |
| 2287 | 991 | ` end;`\ | |
| 2288 | 992 | ` TTypeInfoClass = class of TTypeInfo;`\ | |
| 2289 | 993 | ||
| 2290 | 994 | ` TTypeInfoInteger = class external name 'rtl.tTypeInfoInteger'(TTypeInfo)`\ | |
| 2291 | 995 | ` public`\ | |
| 2292 | 996 | ` MinValue: NativeInt external name 'minvalue';`\ | |
| 2293 | 997 | ` MaxValue: NativeInt external name 'maxvalue';`\ | |
| 2294 | 998 | ` OrdType : TOrdType external name 'ordtype';`\ | |
| 2295 | 999 | ` end;`\ | |
| 2296 | 1000 | ||
| 2297 | 1001 | The **typeinfo** function works on type, var, const and property identifiers. By default it returns a *pointer*. If the typinfo unit is used it returns the appropiate *TTypeInfo*. For instance *typeinfo(integer)* returns a *TTypeInfoInteger*.\ | |
| 2298 | 1002 | *Typeinfo* of a *var* or *const* returns the typeinfo of its type, not of its current runtime value. The exception is a class and class-of instance variable (e.g. *var o: TObject; ... typeinfo(o)*), which returns the typeinfo of the current runtime value. If *o* is *nil* it will give a JS error.\ | |
| 2299 | 1003 | Local types (i.e. inside a procedure) do not have typeinfo.\ | |
| 2300 | 1004 | Open array parameters are not yet supported.\ | |
| 2301 | 1005 | Note that FPC *typeinfo(aClassVar)* returns the compiletime type, so it works on *nil*.\ | |
| 2302 | 1006 | ||
| 2303 | 1007 | ## Async/AWait | |
| 2304 | 1008 | ||
| 2305 | 1009 | Pas2js supports the JS operators async and await to simplify the use of Promise. The await operator corresponds to three intrinsic Pas2js functions: | |
| 2306 | 1010 | ||
| 2307 | 1011 | - *function await(AsyncFunctionWithResultT()): T;* // implicit promise, the inner () can be omitted | |
| 2308 | 1012 | - *function await(aType; p: TJSPromise): aType;* // explicit promise requires the resolved type | |
| 2309 | 1013 | - *function await(aType; j: jsvalue): aType;* // explicit promise requires the resolved type | |
| 2310 | 1014 | ||
| 2311 | 1015 | The await function can only be used inside a procedure with the async modifier.\ | |
| 2312 | 1016 | Example for the explicit promise: | |
| 2313 | 1017 | ||
| 2314 | - | ||
| 2315 | - | ||
| 2316 | - | ||
| 2317 | - | ||
| 2318 | - | ||
| 2319 | - | ||
| 2320 | - | ||
| 2321 | - | ||
| 2322 | - | ||
| 2323 | - | ||
| 2324 | - | ||
| 2325 | - | ||
| 2326 | - | ||
| 2327 | - | ||
| 2328 | - | ||
| 2329 | - | ||
| 2330 | - | ||
| 2331 | - | ||
| 2332 | - | ||
| 2333 | - | ||
| 2334 | - | ||
| 2335 | - | ||
| 2336 | - | ||
| 2337 | - | ||
| 2338 | - | ||
| 2339 | - | ||
| 2340 | - | ||
| 2341 | - | ||
| 2342 | - | ||
| 2343 | - | ||
| 2344 | - | ||
| 2345 | - | ||
| 2346 | - | ||
| 2347 | - | ||
| 2348 | - | ||
| 2349 | - | ||
| 2350 | - | ||
| 2351 | - | ||
| 2352 | - | ||
| 2353 | - | ||
| 2354 | - | ||
| 2355 | - | ||
| 2356 | - | ||
| 2357 | - | ||
| 2358 | - | ||
| 2359 | - | ||
| 2360 | - | ||
| 2361 | - | ||
| 2362 | - | ||
| 2363 | - | ||
| 2364 | - | ||
| 2365 | - | ||
| 2366 | - | ||
| 2367 | - | ||
| 1018 | + | | Pascal | JavaScript | | |
| 1019 | + | |---|---| | |
| 1020 | + | | `Program MyModule;` · · `uses JS, Web;` · · `function ResolveAfter2Seconds: TJSPromise;` · `begin` · ` Result:=TJSPromise.new(procedure(resolve, reject : TJSPromiseResolver)` · ` begin` · ` window.setTimeout(procedure` · ` begin` · ` resolve('resolved');` · ` end,` · ` 2000); // wait 2 seconds` · ` end);` · `end;` · · `procedure AsyncCall; async;` · `var s: string;` · `begin` · ` writeln('calling');` · ` s := await(string,resolveAfter2Seconds()); // does not check if result is really a string` · ` writeln(s); // expected output: 'resolved'` · `end;` · · `begin` · ` AsyncCall;` · `end.` | `rtl.module("program",["System","JS","Web"],function () {` · ` "use strict";` · ` var $mod = this;` · ` this.ResolveAfter2Seconds = function () {` · ` var Result = null;` · ` Result = new Promise(function (resolve, reject) {` · ` window.setTimeout(function () {` · ` resolve("resolved");` · ` },2000);` · ` });` · ` return Result;` · ` };` · ` this.AsyncCall = async function () {` · ` var s = "";` · ` pas.System.Writeln("calling");` · ` s = await $mod.ResolveAfter2Seconds();` · ` pas.System.Writeln(s);` · ` };` · ` $mod.$main = function () {` · ` $mod.AsyncCall();` · ` };` · `});` | | |
| 2368 | 1021 | ||
| 2369 | 1022 | Notes: | |
| 2370 | 1023 | ||
| 2371 | 1024 | - The await function does only compile time checks, no runtime checks. | |
| 2372 | 1025 | - Inside an async function/procedure you can pass a *TJSPromise* to the *exit()* function. For example:\ | |
| 2373 | 1026 | *exit(aPromise);*\ | |
| 2374 | 1027 | *exit(inherited);* | |
| 2375 | 1028 | ||
| 2376 | 1029 | ## Compiler directives | |
| 2377 | 1030 | ||
| 2378 | 1031 | In config files: | |
| 2379 | 1032 | ||
| 2380 | 1033 | - \#IFDEF macroname | |
| 2381 | 1034 | - \#IFNDEF macroname | |
| 2382 | 1035 | - \#IF expression - same as \$if, except only defines | |
| 2383 | 1036 | - \#ELSEIF | |
| 2384 | 1037 | - \#ELSE | |
| 2385 | 1038 | - \#ENDIF | |
| 2386 | 1039 | - \#ERROR text | |
| 2387 | 1040 | ||
| 2388 | 1041 | In source files: | |
| 2389 | 1042 | ||
| 2390 | 1043 | - {\$Define *MacroName*}: defines macro *MacroName* with value '1'. | |
| 2391 | 1044 | - {\$Define *MacroName:=value*}: defines macro *MacroName* with custom value. | |
| 2392 | 1045 | - {\$Undef *MacroName*}: undefines macro *MacroName*. | |
| 2393 | 1046 | - {\$IfDef *MacroName*}: if *MacroName* is not defined, skip to next \$Else or \$EndIf. Can be nested. | |
| 2394 | 1047 | - {\$IfNDef *MacroName*}: as \$IfDef, except negated. | |
| 2395 | 1048 | - {\$If *boolean expression*}: if *expression* evaluates to true (not '0'), skip to next \$Else or \$EndIf. Can be nested.\ | |
| 2396 | 1049 | Supported functions and operators:\ | |
| 2397 | 1050 | * macro - replaced by its value, a simple define has value '1' | |
| 2398 | 1051 | - defined(macro) - '1' if defined, '0' otherwise | |
| 2399 | 1052 | - undefined(macro) - as *not defined(macro)* | |
| 2400 | 1053 | - option(letter) - same as *{\$IFOpt letter+}* | |
| 2401 | 1054 | - not - first level of precedence | |
| 2402 | 1055 | - *, /, div, mod, and, shl, shr - second level of precedence | |
| 2403 | 1056 | - +, -, or, xor - third level of precedence | |
| 2404 | 1057 | - =, \<\>, \<, \>, \<=, \>= - fourth level of precedence | |
| 2405 | 1058 | - If the operands can be converted to numbers they are combined as numbers, otherwise as strings. Not supported functions and operators:\ | |
| 2406 | 1059 | - defined(Pascal identifier), undefined(Pascal identifier) | |
| 2407 | 1060 | - declared(Pascal identifier) | |
| 2408 | 1061 | - in operator | |
| 2409 | 1062 | - {\$IfOpt *Letter+,-*}: if *expression* evaluates to true (not '0'), skip to next \$Else or \$EndIf. Can be nested. | |
| 2410 | 1063 | - {\$Else}: If previous \$IfDef, \$If or \$IfOpt was skipped, execute next block, otherwise skip. | |
| 2411 | 1064 | - {\$ElseIf *boolean expression*} : As \$Else, except with an extra expression like \$if to test. There can be multiple \$elseif. | |
| 2412 | 1065 | - {\$EndIf} : ends an \$IfDef block | |
| 2413 | 1066 | - {\$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. | |
| 2414 | 1067 | - {\$modeswitch externalclass} : allow declaring external classes | |
| 2415 | 1068 | - {\$modeswitch arrayoperators} : allow + operator to concatenate arrays, default in mode delphi | |
| 2416 | 1069 | - {\$modeswitch OmitRTTI} : treat published sections as public | |
| 2417 | 1070 | - {\$macro on\|off} enables macro replacements. Only macros with a value are replaced. Macros are never replaced inside directives. | |
| 2418 | 1071 | - {\$I filename} or {\$include filename} - insert include file | |
| 2419 | 1072 | - {\$I %param%} : | |
| 2420 | 1073 | - %date%: current date as string literal, '\[yyyy/mm/dd\]' | |
| 2421 | 1074 | - %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. | |
| 2422 | 1075 | - %file%: current source filename as string literal, e.g. **unit1.pas** | |
| 2423 | 1076 | - %line%: current source line number as string literal, e.g. **123** | |
| 2424 | 1077 | - %linenum%: current source line number as integer, e.g. *123* | |
| 2425 | 1078 | - %currentroutine%: name of current routine as string literal | |
| 2426 | 1079 | - %pas2jstarget%, %pas2jstargetos%, %fpctarget%, %fpctargetos%: target os as string literal, e.g. 'Browser' | |
| 2427 | 1080 | - %pas2jstargetcpu%, %fpctargetcpu%: target cpu as string literal, e.g. 'ECMAScript5' | |
| 2428 | 1081 | - %pas2jsversion%, %fpcversion%: compiler version as strnig literal, e.g. '1.0.2' | |
| 2429 | 1082 | - 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. | |
| 2430 | 1083 | - {\$Warnings on\|off} | |
| 2431 | 1084 | - {\$Notes on\|off} | |
| 2432 | 1085 | - {\$Hints on\|off} | |
| 2433 | 1086 | - {\$Error text} : emit an error | |
| 2434 | 1087 | - {\$Warning text} : emit a warning | |
| 2435 | 1088 | - {\$Note text} : emit a note | |
| 2436 | 1089 | - {\$Hint text} : emit a hint | |
| 2437 | 1090 | - {\$Message hint-text} : emit a hint | |
| 2438 | 1091 | - {\$Message hint\|note\|warn\|error\|fatal text} : emit a message | |
| 2439 | 1092 | - {\$Warn identifier on\|off\|default\|error} : enable or disable a specific hint.\ | |
| 2440 | 1093 | 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.\ | |
| 2441 | 1094 | Identifier can be a message number as written by -vq or one of the following case insensitive:\ | |
| 2442 | 1095 | * CONSTRUCTING_ABSTRACT : Constructing an instance of a class with abstract methods. | |
| 2443 | 1096 | - IMPLICIT_VARIANTS : Implicit use of the variants unit. | |
| 2444 | 1097 | - NO_RETVAL : Function result is not set | |
| 2445 | 1098 | - SYMBOL_DEPRECATED : Deprecated symbol. | |
| 2446 | 1099 | - SYMBOL_EXPERIMENTAL : Experimental symbol | |
| 2447 | 1100 | - SYMBOL_LIBRARY | |
| 2448 | 1101 | - SYMBOL_PLATFORM : Platform-dependent symbol. | |
| 2449 | 1102 | - SYMBOL_UNIMPLEMENTED : Unimplemented symbol. | |
| 2450 | 1103 | - HIDDEN_VIRTUAL : method hides virtual method of ancestor | |
| 2451 | 1104 | - GARBAGE : text after final end. | |
| 2452 | 1105 | - BOUNDS_ERROR : range check errors | |
| 2453 | 1106 | - MESSAGE_DIRECTIVE : user defined \$message | |
| 2454 | 1107 | - {\$M+}, {\$TypeInfo on} : switches default visibility for class members from public to published | |
| 2455 | 1108 | - {\$ScopedEnums on\|off} disabled(default): propagate enums to global scope, enable: needs fqn e.g. TEnumType.EnumValue. | |
| 2456 | 1109 | - {\$C+} generate code for assertions | |
| 2457 | 1110 | - {\$H+} , but not {\$H-} | |
| 2458 | 1111 | - {\$J-}, {\$WriteableConst off} : Typed const become readonly. For example *const i:byte=3; ... i:=4* creates a compile time error. | |
| 2459 | 1112 | - {\$M+} : allow published members | |
| 2460 | 1113 | - {\$Q+} : not yet supported, ignored | |
| 2461 | 1114 | - {\$R+}, {\$RangeChecks on} : compile time range check hints become errors and add runtime range checks for assignments. | |
| 2462 | 1115 | - {\$ObjectChecks on\|off} : | |
| 2463 | 1116 | - Verify method calls, i.e. check at runtime in every method if *Self* is a descendant class. | |
| 2464 | 1117 | - Check type casts, e.g. *TBird(AnObject)* becomes *AnObject as TBird* | |
| 2465 | 1118 | - {\$DispatchField Msg} : enable checking *message number* methods for record field name "Msg" | |
| 2466 | 1119 | - {\$DispatchStrField MsgStr} : enable checking *message string* methods for record field name "Msg" | |
| 2467 | 1120 | - {\$Optimization Name} : same as command line option -OoName | |
| 2468 | 1121 | - {\$linklib filename \[alias\]}: | |
| 2469 | 1122 | - filename filename to import. | |
| 2470 | 1123 | - alias alias for this import. Must be a pascal identifier. If no alias is specified, the last part of the filename is used, all non-alphanumeric characters are converted to underscores. | |
| 2471 | 1124 | ||
| 2472 | 1125 | Defines: | |
| 2473 | 1126 | ||
| 2474 | 1127 | - PAS2JS | |
| 2475 | 1128 | - PAS2JS_FULLVERSION - major*1000+minor*100+release, e.g. 1.2.3 = 10203 | |
| 2476 | 1129 | - Target platform: Browser, NodeJS, Pas2JSTargetOS=\<value\> | |
| 2477 | 1130 | - Target processor: ECMAScript5, ECMAScript6, ECMAScript=5, Pas2JSTargetCPU=\<value\> | |
| 2478 | 1131 | - Mode: DELPHI, OBJFPC | |
| 2479 | 1132 | ||
| 2480 | 1133 | ## Numbers | |
| 2481 | 1134 | ||
| 2482 | 1135 | `JavaScript only supports double. All Pascal number types and enum values are mapped to this. A double supports integers from`\ | |
| 2483 | 1136 | ` MinInteger = -$10000000000000;`\ | |
| 2484 | 1137 | ` MaxInteger = $fffffffffffff;`\ | |
| 2485 | 1138 | ` MinDouble = 5.0e-324;`\ | |
| 2486 | 1139 | ` MaxDouble = 1.7e+308;`\ | |
| 2487 | 1140 | ||
| 2488 | 1141 | ` Intrinsic integer types:` | |
| 2489 | 1142 | ||
| 2490 | 1143 | - Byte - unsigned 8-bit | |
| 2491 | 1144 | - ShortInt - signed 8-bit | |
| 2492 | 1145 | - Word - unsigned 16-bit | |
| 2493 | 1146 | - SmallInt - signed 16-bit | |
| 2494 | 1147 | - LongWord - unsigned 32-bit | |
| 2495 | 1148 | - LongInt - signed 32-bit | |
| 2496 | 1149 | - NativeUInt - unsigned 53-bit | |
| 2497 | 1150 | - NativeInt - signed 54-bit | |
| 2498 | 1151 | ||
| 2499 | 1152 | Notes: | |
| 2500 | 1153 | ||
| 2501 | 1154 | - Division by zero does not raise an exception. 0/0 results in NaN, positive/0 is Infinity, negative/0 is -Infinity. | |
| 2502 | 1155 | - NaN\<\>NaN | |
| 2503 | 1156 | - 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. | |
| 2504 | 1157 | - Math.isNan(double) tests for NaN. Otherwise false. isNan(Infinity)=false. | |
| 2505 | 1158 | - Math.isFinite(double) tests if not NaN, positive or negative infinity. | |
| 2506 | 1159 | - Math.isInfinite(double) tests if positive or negative infinity. | |
| 2507 | 1160 | - For more functions see unit Math. | |
| 2508 | 1161 | - 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. | |
| 2509 | 1162 | ||
| 2510 | 1163 | ## Other supported Pascal elements | |
| 2511 | 1164 | ||
| 2512 | 1165 | - **break**, **continue**, **exit**, **exit()** | |
| 2513 | 1166 | - **chr**, **ord** | |
| 2514 | 1167 | - alias type and type alias type | |
| 2515 | 1168 | - *inc()* and *dec()* to += -= | |
| 2516 | 1169 | - Converts "a div b" to "Math.floor(a / b)" | |
| 2517 | 1170 | - and, or, xor, not: logical and bitwise | |
| 2518 | 1171 | - Name conflicts with JS identifiers are automatically fixed by changing case. For example a Pascal function "*apply"* is renamed to "*Apply*". | |
| 2519 | 1172 | - 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*.\ | |
| 2520 | 1173 | In *\$mode objfpc* units can use in-filenames too and alias are allowed, e.g. *uses foo in 'bar.pas*'. | |
| 2521 | 1174 | - The intrinsic procedure **str** works with boolean, integer, float and enumvalue.\ | |
| 2522 | 1175 | 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).\ | |
| 2523 | 1176 | 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. | |
| 2524 | 1177 | - Intrinsic procedure WriteStr(out s: string; params...) | |
| 2525 | 1178 | - *Debugger;* converts to *debugger;*. If a debugger is running it will break on this line just like a break point. | |
| 2526 | 1179 | - *function concat(string1,string2,...): string* since 1.3 | |
| 2527 | 1180 | - *\$mode delphi: function lo\|hi(integer): byte* since 1.3 | |
| 2528 | 1181 | - *\$mode objfpc: function lo\|hi(integer): byte\|word\|longword* since 1.3 | |
| 2529 | 1182 | - *function GetTypeKind(Type or Var): TTypeKind;* since 1.5 | |
| 2530 | 1183 | ||
| 2531 | 1184 | ## Not supported elements | |
| 2532 | 1185 | ||
| 2533 | 1186 | - Class destructor | |
| 2534 | 1187 | - Enums with custom values | |
| 2535 | 1188 | - Global properties | |
| 2536 | 1189 | - Futures | |
| 2537 | 1190 | - Inline | |
| 2538 | 1191 | - Objects | |
| 2539 | 1192 | - Operator overloading | |
| 2540 | 1193 | - Pointer arithmetic | |
| 2541 | 1194 | - Package | |
| 2542 | 1195 | - Resources | |
| 2543 | 1196 | - RTTI extended, \$RTTI | |
| 2544 | 1197 | - Variant records | |
| 2545 | 1198 | - Variants | |
| 2546 | 1199 | ||
| 2547 | 1200 | ## JavaScript Version | |
| 2548 | 1201 | ||
| 2549 | 1202 | Code generation depending on -P option: | |
| 2550 | 1203 | ||
| 2551 | 1204 | - ECMAScript5 | |
| 2552 | 1205 | - ECMAScript6: using 0b for binary literals, and 0o for octal literals | |
| 2553 | 1206 | ||
| 2554 | 1207 | ## Creating source maps | |
| 2555 | 1208 | ||
| 2556 | 1209 | Source maps are files telling the browser what JavaScript comes from which original source (e.g. Pascal file), similar to debug information in FPC/Delphi.\ | |
| 2557 | 1210 | In 2017 FireFox and Chrome supports source maps.\ | |
| 2558 | 1211 | You can enable generating source map files by using the *-Jm* option.\ | |
| 2559 | 1212 | The compiler generates one module.js.map file for every generated module.js file. The last line of the .js file contains the line\ | |
| 2560 | 1213 | *//# sourceMappingURL=module.js.map*\ | |
| 2561 | 1214 | telling the browser where to find the source map.\ | |
| 2562 | 1215 | The source map contains references to the Pascal files and included .js files (e.g. -Jirtl.js) relative to the location of the source map. Note that if the Pascal file lies in a parent directory, the relativ path contains '../'. You can change the base directory of the relative paths by using the option *-Jmbasedir=\<x\>*. For example *-JmC:\www\pas* creates paths relative to C:\www\pas.\ | |
| 2563 | 1216 | You can set the base URL, where the browser finds the Pascal sources, by passing the *-Jmsourceroot=\<x\>* option. For example *-Jmsourceroot=<http://www.yoursite.com/pas/>*. The browser prepends this to the source map filenames when downloading the original source files (e.g. the .pas files).\ | |
| 2564 | 1217 | You can include the whole Pascal sources in the source map using the option *-Jminclude*.\ | |
| 2565 | 1218 | ||
| 2566 | 1219 | To show the generated mapping for each line you can use the tool fpc/packages/fcl-js/examples/srcmapdump.\ | |
| 2567 | 1220 | ||
| 2568 | 1221 | - Option -JmXSSIHeader: According to the specifications sourcemap should start with the XSSI (cross site script inclusion) protection header *)\]}*'. If your browser does not support that, disable it with *-JmXSSIHeader-*. See here the specs: <https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit#heading=h.h7yy76c5il9v> | |
| 2569 | 1222 | ||
| 2570 | 1223 | ## See Also | |
| 2571 | 1224 | ||
| 2572 | 1225 | - [[pas2js]] | |
| 2573 | 1226 | ||
| 2574 | 1227 | --- | |
| 2575 | 1228 | *From the Free Pascal wiki, page "Pas2js Transpiler", as it stood on 2023-05-08 after a change by Maxerist, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* | |
| 2576 | 1229 | Category: Pas2js |