[[ecmascript]]
ECMAScript support?!
~~~~~~~~~~~~~~~~~~~~

Yes, there is some ECMAScript support in ELinks. There isn't anything we could
call complete, but some bits could help with the most common ECMAScript usage
cases - help you (and then us ;) get into your banking account, pass through
those ignorant page redirects done by JavaScript code snippets and so.

ELinks does not have own ECMAScript parser and compiler; instead it reuses
other people's work (this may eventually change, see the bottom of this file).
First we aimed at the NJS engine, which is easy to install, small and compact;
has nice naming scheme, horrible calling conventions and very lacking
documentation; is not actively developed; and generally looks broken and
extremely clumsy to work with. So we instead went the way of the SpiderMonkey
(SM) engine (property of Mozilla), which is hard to install, bigger (mind you,
it comes from Mozilla ;), has ugly naming scheme but nice calling conventions,
acceptable documentation, is actively developed and ought to work.


Ok, so how to get the ECMAScript support working?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

On Debian testing or unstable (SID), run the following:

	$ apt-get install libmozjs-128-dev

On Arch Linux, run the following:

	$ pacman -S js128

SpiderMonkey is disabled by default, enable it like this:

	$ meson build -Dspidermonkey=true

Check for the following line in the features summary:

	Run-time dependency mozjs-128 found: YES 128.5.0

Then run:

	$ cd build/
	$ ninja
	$ sudo ninja install

Enjoy.


The ECMAScript support is buggy! Shall I blame Mozilla people?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Likely not. The ECMAScript engine provides only the language compiler and some
basic built-in objects, and it's more than likely that the problem is on our
side in the implementation of some of the HTML/DOM objects (perhaps we just
haven't bothered to implement it at all yet). So better tell us first, and if
we think it's not our fault we will tell you to go complain to Mozilla (better
yet if it does not work in the Mozilla browsers neither ;-).


Now, I would still like NJS or a new JS engine from scratch...
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

\...and you don't fear some coding? That's fine then! ELinks is in no way tied
to SpiderMonkey, in fact the ECMAScript support was carefully implemented so
that there are no SpiderMonkey references outside of
`src/ecmascript/spidermonkey.*`. If you want to implement an alternative
ECMAScript backend, go ahead - you will just need to write an autoconf
detection for it and tie it to `src/ecmascript/ecmascript.c`, which should be
easy. We await your patches eagerly.


As of 2024
^^^^^^^^^^

There are 3 javascript engines you could choose from:

- Spidermonkey (mozjs128). Passed tests, but segfaults occur, especially
on shutdown.
- QuickJS. Tests also passed. For machines with limited resources,
for example DOS machines. Not all memory is released on shutdown.
Needs more work.
- MuJS. For fans of MuJS. Not all tests passed. I don't know
how to implement missing bits.

By, tests I mean:

	meson ... -Dtest=true ...
	ninja test

There as some assertions in these tests. Small subset of DOM HTML is "covered".
If you have some knowledge of these engines, you can help.
On some sites ELinks might crash, or slowdown. There is a workaround for this.
Files allow.txt and disallow.txt.
In the file ~/.config/elinks/allow.txt one can enter prefixes of urls
which are allowed. These are urls for text/html pages.

For example:

	file://
	https://www.example.com/news.php

All scripts in local pages are allowed, scripts at https://www.example.com/news.php
are also allowed, but other not. If allow.txt is not empty, urls which prefixes
do not occur in this file are forbidden.
In the file ~/.config/elinks/disallow.txt you can also put prefixes, but this time
disallowed. If allow.txt is empty or nonexistent, all scripts allowed, besides
pages which prefixes occuring in disallow.txt.

Sample content of disallow.txt:

	http://
	https://www.example.org/

All scripts on pages with protocol http are forbidden. The scripts on pages starting
with https://www.example.com/ are also disallowed. When both files exist, you must
check it out yourself.