pas2js modules: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		# Module import
2	2
3	3		pas2js can convert the \$linklib directive to a JS import statement:
4	4
5	5		The following:
6	6
7		-	~~`{$linklib ./modules/canvas.js canvas}`~~
	7	+	```text
	8	+	{$linklib ./modules/canvas.js canvas}
	9	+	```
8	10
9	11		is converted to
10	12
11		-	~~`import * as canvas from "./modules/canvas.js";`~~
	13	+	```text
	14	+	import * as canvas from "./modules/canvas.js";
	15	+	```
12	16
13	17		If the alias is omitted, one is constructed for you:
14	18
15		-	~~`{$linklib ./modules/some-api.js}`~~
	19	+	```text
	20	+	{$linklib ./modules/some-api.js}
	21	+	```
16	22
17		-	~~is converted to `import * as some_api from "./modules/some-api.js";`~~
	23	+	is converted to
18	24
	25	+	```text
	26	+	import * as some_api from "./modules/some-api.js";
	27	+	```
	28	+
19	29		The import statements are always inserted in the main program. This is because modules are like windows libraries: self-contained programs, which only import and export well-defined symbols.
20	30
21	31		For this reason, a new target "operating system" has been invented: the module. This means that you must compile with target module:
22	32
23		-	~~`pas2js -Tmodule -Jirtl.js main.pp`~~
	33	+	```text
	34	+	pas2js -Tmodule -Jirtl.js main.pp
	35	+	```
24	36
25	37		The nodejs target will also work, but in the future the 2 targets may diverge.
26	38
27	39		# Demos
28	40
29	41		The pas2js demos/modules directory contains a series of subdirectories. Each subdirectory has 1 demo. Compile with the command-line as above:
30	42
31		-	~~`pas2js -Tmodule -Jirtl.js main.pp`~~
	43	+	```text
	44	+	pas2js -Tmodule -Jirtl.js main.pp
	45	+	```
32	46
33	47		## Basic
34	48
35	49		This shows a simple program, no units, that uses the linklib directive to import a javascript module. It uses an external class definition to access the exported symbols from the modules.
36	50
37	51		## Basic-Units
38	52
39	53		This is the same as the Basic example, but the import definitions are split out in units.
40	54
41	55		## Flat
42	56
43	57		This shows a simple program, no units, that uses the linklib directive to import a javascript module. It uses only external 'name' definitions to access the exported symbols from the modules; no external class is used.
44	58
45	59		## Flat-Units
46	60
47	61		This is the same as the flat example, but the import definitions are split out in units.
48	62
49	63		# Module export
50	64
51	65		Module export is implemented using the existing pascal Library concept.
52	66
53	67		A pas2js library is transpiled into a Javascript module with its own rtl.js and rtl.run. It can export global functions, static methods, and global variables.
54	68
55	69		For example a library exporting a function twice, as name Swim and as Move:
56	70
57	71		``` pascal
58	72		library Fish;
59	73		procedure Swim(w: word);
60	74		begin
61	75		writeln('Swimming ',w,' meters');
62	76		end;
63	77		exports
64	78		Swim;
65	79		Swim name 'Move';
66	80		begin
67	81		end.
68	82		```
69	83
70	84		Compiled with "pas2js -Tmodule -Jirtl.js -Jc fish.pas" generates the following fish.js:
71	85
72	86		``` javascript
73	87		...rtl.js and system unit...
74	88		rtl.module("library", [], function () {
75	89		var $mod = this;
76	90		this.Swim = function (w) {
77	91		pas.System.Writeln("Swimming ",w," meters");
78	92		};
79	93		$mod.$main = function () {
80	94		};
81	95		});
82	96		rtl.run("library");
83	97		export const Swim = pas.library.Swim;
84	98		export const Move = pas.library.Swim;
85	99		```
86	100
87	101		# Using a Pascal Library
88	102
89	103		Javascript modules can be used using the Javascript [import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) statement.
90	104
91	105		Consider the following HTML:
92	106
93	107		``` html
94	108		<!DOCTYPE html>
95	109		<html lang="en-US">
96	110		<head>
97	111		<meta charset="utf-8">
98	112		<title>Basic Pas2JS library example</title>
99	113		<script type="module" src="fish.js"></script>
100	114		</head>
101	115		<body>
102	116
103	117		</body>
104	118		</html>
105	119		```
106	120
107	121		Note that the script has type module, and that no script tag with the rtl.run(); statement is present in the HTML body. It is not possible to use or import a module from a regular script tag.
108	122
109	123		## Using Pascal Library from JavaScript
110	124
111	125		The imports from a pascal library are no different from a regular Javascript import.
112	126
113	127		Taking the above HTML as the example, if the file swim.js contains the following javascript:
114	128
115	129		``` javascript
116	130		import Swim from "fish.js";
117	131
118	132		Swim(10);
119	133		```
120	134
121	135		Then the browser console will show the output of the program:
122	136
123		-	~~` Swimming 10 meters`~~
	137	+	```text
	138	+	Swimming 10 meters
	139	+	```
124	140
125	141		## Using Pascal Library from Pascal
126	142
127	143		As mentioned above, using a Pascal produced library from pascal is done no different from using a Javascript module, and is no different from using a library in a native program. Our 'fish' library can be used using the following program:
128	144
129	145		``` pascal
130	146		// Import the functions in an object called aqua
131	147		{$linklib ./fish.js aqua}
132	148
133	149		// We use the aqua object name in the external:
134	150		procedure Swim(aMeters: word); external name 'aqua.Swim';
135	151		procedure SwimHarder(aMeters: word); external name 'aqua.Move';
136	152
137	153		begin
138	154		Swim(3);
139	155		SwimHarder(10);
140	156		end.
141	157		```
142	158
143	159		compile using the module target:
144	160
145		-	~~` ``pas2js -Tmodule -Jc -Jirtl.js swim.lpr`~~
	161	+	```text
	162	+	pas2js -Tmodule -Jc -Jirtl.js swim.lpr
	163	+	```
146	164
147	165		Again, the output will be shown on the console.
148	166
149	167		You can find another example in the pas2js [Pas2JS demos](https://gitlab.com/freepascal.org/fpc/pas2js/-/tree/main/demo/library)
150	168
151	169		# Navigation
152	170
153	171		- Back to [[pas2js]]
154	172		- Back to [[lazarus pas2js integration]]
155	173
156	174		Note that we made a pascal program for the swim.js, but we could just as well have made a library.
157	175
158	176		---
159	177		From the Free Pascal wiki, page "pas2js modules", as it stood on 2022-02-22 after a change by Michael, 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).
160	178		Category: Pas2js

Back to history