From b190367681fe8b6abf4806906fabed7f0e7f18ce Mon Sep 17 00:00:00 2001
From: TopchetoEU <36534413+TopchetoEU@users.noreply.github.com>
Date: Sun, 26 Jan 2025 18:07:13 +0200
Subject: [PATCH] add thesis text
---
doc/text/.gitignore | 9 +
doc/text/README.md | 1 +
doc/text/build | 45 +
doc/text/document.md | 1252 ++++++++++++++++++++++++++++
doc/text/img/debugging-example.png | Bin 0 -> 98441 bytes
doc/text/img/dependencies.svg | 4 +
doc/text/img/stack-arr.png | Bin 0 -> 37167 bytes
doc/text/requirements.md | 14 +
doc/text/src/build.lua | 728 ++++++++++++++++
doc/text/src/json.lua | 244 ++++++
doc/text/src/perf.lua | 30 +
doc/text/src/utils.lua | 429 ++++++++++
doc/text/template.html | 555 ++++++++++++
13 files changed, 3311 insertions(+)
create mode 100644 doc/text/.gitignore
create mode 100644 doc/text/README.md
create mode 100755 doc/text/build
create mode 100644 doc/text/document.md
create mode 100644 doc/text/img/debugging-example.png
create mode 100644 doc/text/img/dependencies.svg
create mode 100644 doc/text/img/stack-arr.png
create mode 100644 doc/text/requirements.md
create mode 100644 doc/text/src/build.lua
create mode 100644 doc/text/src/json.lua
create mode 100644 doc/text/src/perf.lua
create mode 100644 doc/text/src/utils.lua
create mode 100644 doc/text/template.html
diff --git a/doc/text/.gitignore b/doc/text/.gitignore
new file mode 100644
index 0000000..fb06c69
--- /dev/null
+++ b/doc/text/.gitignore
@@ -0,0 +1,9 @@
+/*
+!/img
+!/src
+!/.gitignore
+!/build
+!/document.md
+!/README.md
+!/requirements.md
+!/template.html
diff --git a/doc/text/README.md b/doc/text/README.md
new file mode 100644
index 0000000..34175cf
--- /dev/null
+++ b/doc/text/README.md
@@ -0,0 +1 @@
+This is the main body of my thesis. **BE WARNED!** It is quite lengthy and written in Bulgarian.
diff --git a/doc/text/build b/doc/text/build
new file mode 100755
index 0000000..4b607c7
--- /dev/null
+++ b/doc/text/build
@@ -0,0 +1,45 @@
+#!/bin/luajit -lsrc.build
+
+local config = require "config";
+
+function profession(val)
+ if val == "sys" then
+ return {
+ profession = "481020 „Системен програмист“",
+ specialty = "4810201 „Системно програмиране“",
+ };
+ elseif val == "net" then
+ return combine {
+ profession = "523050 „Техник на компютърни системи“",
+ specialty = "5230502 „Компютърни мрежи“",
+ };
+ end
+end
+
+emit {
+ target = "res.html",
+ template {
+ template = "template.html",
+
+ build {
+ "requirements.md",
+ content = "requirements",
+ },
+ build {
+ "document.md",
+ content = "content",
+ toc = "toc",
+ ctx = {
+ chapter_format = "Глава %s
",
+ chapter_format_plain = "Глава %s: ",
+ },
+ },
+
+ profession(config.profession),
+
+ year = os.date "%Y",
+ prev_year = os.date "%Y" - 1,
+
+ config,
+ },
+}
diff --git a/doc/text/document.md b/doc/text/document.md
new file mode 100644
index 0000000..d2afe65
--- /dev/null
+++ b/doc/text/document.md
@@ -0,0 +1,1252 @@
+---
+title: Дипломна работа
+---
+# Увод {.nonum}
+
+Един от най-важните принципи на програмирането е този на разширимостта. Този принцип повелява, че софтуерът трябва да изграждан по начин, по който може неговата функционалност да бъде разширена без вече написаният софтуер да бъде променян. Това е добре известен проблем в сферата на софтуерното инженерство, като едно от най-ефективните решения е интегрирането на втори помощен език, чрез който потребителя да може да разширява функционалността на оригиналният продукт.
+
+Но защо разширимостта е толкова важна? Това се дължи на факта, че често потребителите на софтуерните продукти искат да разширят функционалността на продукта. Традиционно, разширяването може да стане само като потребителя се свърже с разработчика на продукта и да помоли за добавянето на функционалността. Това обаче е не само непрактично, но и води до прекомерно нарастване на софтуера, което го прави сложен за поддръжка и използване.
+
+Въвеждането на скриптови езици като помощни механизми за разширяване на функционалността предлага значително по-ефективно решение. Езиците като Python, Lua и JavaScript могат да бъдат използвани за добавяне на нова функционалност, без да се променя основният код на приложението, като по този начин се осигурява гъвкавост на софтуерния продукт. JavaScript, в частност, е един от най-широко използваните езици в съвременната разработка, поради своята популярност, която се дължи на употребата на езика в уеб технологиите.
+
+Целта на тази дипломна работа е да създаде лесно вградим, малък на размер интерпретатор на „EcmaScript 5.1“ езика (по-добре познат като JavaScript, както ще се и нарича оттук нататък) за продукти, написани на езикът „Java“.
+
+# Проучвателна част
+
+## Съществуващи JavaScript интерпретатори
+
+### V8
+
+V8 [@refs-v8] е интерпретатора за JavaScript на Google, написан на C++. Той е най-широко разпространената среда за изпълнение на JavaScript код. Създаден е, за да служи на Chromium браузърът (на който е базиран Google Chrome, който има близо 70% пазарен дял [@refs-market-share]). Освен това V8 се използва и от много среди за разработка на сървърен код, най-популярните от които са „NodeJS“ [@refs-nodejs] и „Deno“ [@refs-deno]. Поради своята популярност, имплементацията на JavaScript от V8 е „де факто“ стандарта за езика, заради което по времето на разработката на този проекто, NodeJS, базиран на V8, беше използван за сферяване на резултатите от този проект. Архитектурно, V8 използва „JIT“ (Just-in-Time) технологията за компилиране, която обаче не е засегната тук.
+
+- **Предимства**
+ - Бързодействие
+ - Добра поддръжка от Google
+ - Популярен, следователно добра поддръжка от обществото
+- **Недостатъци:**
+ - Голям размер на крайният изпълним код
+ - Сложно вграждане в проекти, които не са написани на C++
+
+### JavaScriptCore
+
+JavaScriptCore [@refs-jsc] е интерпретатора за JavaScript на Apple, написан на C++. Не е толкова разпространен, колкото V8, но въпреки това намира употреба в браузъра на Apple „Safari“, както и алтернативната на NodeJS среда за изпълнение „Bun“. Въпреки че не е толкова разпространен, JavaScriptCore е компетентен интерпретатор, като по много параметри се доближава и даже превъзхожда V8. Интерпретатора, подобно на V8, използва „Just-in-Time“ технологията за компилиране.
+
+- **Предимства:**
+ - Бързодействие
+ - Добра поддръжка от Apple
+- **Недостатъци:**
+ - Голям размер на крайният изпълним код
+ - Сложно вграждане в проекти, които не са написани на C++
+
+----
+
+### Nashorn
+
+Rhino [@refs-rhino], създаден през 1997 г. от Netscape като част от тогавашните им усилията да пренапишат „Navigator“ на Java, е един от първите интерпретатори за JavaScript, написани на Java [@refs-rhino-history]. Първоначално интерпретатора е компилирал JavaScript кода към Java байт-код, но поради редица проблеми е въведен нов режим на интерпретирано изпълнение. След като усилията на Netscape да пренапишат браузъра си на Java приключват, Rhino остава като JavaScript интерпретатор, който се използва от много проекти. За голям период от време, Rhino остава де факто стандартния JavaScript интерпретатор за Java.
+
+- **Предимства**
+ - Малък размер
+ - Лесно вградим в проекти
+- **Недостатъци:**
+ - Не се поддържа толкова активно
+ - Лоша производителност
+ - Непълно покритие на EcmaScript 5.1
+
+----
+
+### Rhino
+
+Nashorn [@refs-nashorn] е първият официален JavaScript интерпретатор на Oracle, вграден във виртуалната машина на Java от версия 8. Той е по-бърз от неговият предходник Rhino, понеже Nashorn отново компилира JavaScript кода към Java байт-код. От 15та версия на Java виртуалната версия включително, Oracle премахва Nashorn от виртуалната машина, като проекта бива прехвърлен на Mozilla.
+
+- **Предимства**
+ - Малък размер
+ - Лесно вградим в проекти
+ - Пълно покритие на EcmaScript 5.1
+ - Задоволително бързодействие
+- **Недостатъци:**
+ - Не се поддържа толкова активно
+
+### GraalJS
+
+GraalJS [@refs-graaljs] е най-новият JavaScript интерпретатор на Oracle, написан на Java. Той е базиран на Truffle [@refs-truffle], среда за „полиглотно“ изпълнение на код - прави възможно изпълнението на няколко езика в една среда едновременно. Освен че GraalJS използва средата Truffle, която компилира кода до ефективен Java байт-код, ако се използва алтернативната виртуална машина на Oracle GraalVM, може да бъде постигната производителност, съпоставима с V8. Въпреки че производителността, която GraalJS демонстрира е впечатляваща, проекта е с изключително голям размер, което означава, че ако даден проект има GraalJS като зависимост, размерите на изпълнимите файлове на проекта ще се умножат неколкократно.
+
+- **Предимства**
+ - Бързодействие
+ - Добра поддръжка от Oracle
+- **Недостатъци:**
+ - Голям размер на крайният изпълним код
+ - Сложен и негъвкав публичен интерфейс
+
+### QuickJS
+
+QuickJS [@refs-quickjs] е интерпретатор на JavaScript. Той споделя основната философията на този проект - да може да се вгражда лесно в други проекти, както и да бъде малък на размер. По производителност интерпретатора е около 2 - 3 пъти по-бавен от V8 в режим без компилация [@refs-quickjs-benchmark]. Проекта се разработва и поддържа от един човек - Фабрис Белърд, който освен този проект, поддържа и други проекти като FFMpeg, QEMU и TCC.
+
+- **Предимства**
+ - Малък размер
+ - Задоволително бързодействие
+ - Лесно вграждане в проекти
+- **Недостатъци:**
+ - Сложно вграждане в проекти, които не са написани на C/C++
+
+----
+
+## Стандарти и документация за JavaScript
+
+### Стандарт ECMA 262 (версия 5.1)
+
+Това е стандартът [@refs-ecma-262], който документира езикът JavaScript. Въпреки че има по-нови версии на този стандарт, този проект имплементира само тази версия на стандарта (по-нататък ще бъде уточнено защо). Стандарта се съблюдава и развива от TC39 комитета на ECMA [@refs-tc39]. Стандартът съдържа информация за всички свойства на JavaScript:
+
+- Синтаксис
+- Семантики
+- Стандартни библиотеки
+- DOM библиотеки
+- Допълнения, които уточняват поддръжката на по-старите версии на стандарта
+
+Този стандарт е основата, върху която този проект е създаден, понеже е източника на истина, който всеки интерпретатор трябва да спазва.
+
+### MDN Уеб документация
+
+MDN Уеб документацията [@refs-mdn] е документация, създадена от общността, с подобна на Уикипедия философия - всеки може да прави приноси към документацията. Тази документация е един от най-ценните и широко използвани източници на информация както за JavaScript, така и за всичко останало, свързано с уеб технологиите. Въпреки че тази документация не е създадена от ECMA, тя напълно задоволително обобщава ECMA 262 стандарта, заради което този ресурс беше използван често като заместител на ECMA 262 стандарта.
+
+## Методи за изпълнение на код
+
+За да се изпълни код е нужно той първо да бъде разчетен и превърнат във форма, четима за интерпретатора. В тази дипломна работа обаче не е засегнато разчитането на код (може да видите повече за приложения примерен компилатор в [@допълнение]).
+
+### Директно разчитане на код
+
+При този метод на изпълнение на код интерпретатора директно разчита и изпълнява описаните от кода действия. Това е най-неефективният метод за изпълнение на код, понеже всеки път когато дадена операция се изпълнява се налага тя да бъде разчетена наново, което може да бъде скъпа операция. Този метод се използва рядко в практиката, най-вече за „Shell“ езици и някой по-стари интерпретирани езици като „Basic“.
+
+### Компилиране до изпълним файл
+
+При този метод се създава програма, наречена „компилатор“ [@refs-compilers], която разчита кода и го превежда към изпълним за средата файл. Едва тогава изпълнимият файл може да бъде изпълнен, като той ще извърши същите действия и алгоритми, които са описани във входния код. Този метод традиционно се ползва за системни езици, но има проекти, които прилагат този метод и за традиционно скриптови езици.
+
+### Хибриден - компилиране до междинен език
+
+При тази архитектура се създава междинен език [@refs-il], който е по-лесен за разчитане. Не е задължително този език да има текстово представяне и най-често е асемблероподобен. След това се създават два основни компонента - компилатора, който превръща кода към този междинен език и интерпретатора, който разчита и изпълнява междинния език. Повечето модерни интерпретатори използват тази архитектура, като някой езици отделят компилатора като отделна програма, която разработчика трябва да изпълни, за да създаде изпълним код за „виртуалната машина“ на междинният език. На този принцип работят езиците „Java“ (компилиран до Java байт-код) и „C#“ (компилиран до CIL).
+
+:::{.figure}
+
+```cs
+.assembly Hello {}
+.assembly extern mscorlib {}
+.method static void Main()
+{
+ .entrypoint
+ .maxstack 1
+ ldstr "Hello, world!"
+ call void [mscorlib]System.Console::WriteLine(string)
+ ret
+}
+```
+
+Примерен CIL код, компилиран от C#
+:::
+
+### Компилация в реално време - JiT
+
+Компилацията в реално време [@refs-jit] е разширение на хибридните интерпретатори, при които междинният език, когато интерпретатора прецени, се превежда към изпълним за процесора код. При компилацията на междинния език могат да бъдат използвани редица методи за оптимизация, като:
+
+- Оптимизиране на дадени пътища на изпълнение за сметка на други
+- Правене на предположения за стойностите, с които кода ще работи
+- Статистически анализ на пътищата на изпълнение и стойностите, с които кода работи
+- Размотаване на циклите (loop unrolling)
+- Вграждане на функция (function inlining)
+
+Някои по-модерни интерпретатори (като V8 и OpenJDK) използват компилация в реално време, обаче този проект ще използва само хибридния модел за интерпретиране.
+
+# Архитектура и избор на развойна среда
+
+## Концепция на интерпретатора на JavaScript
+
+Основната концепция на този проект е да направи възможно изпълнението на JavaScript код под Java, като особена важност се придава на възможността за лесно вграждане на интерпретатора в съществуващ проект. За целта, следните основни изисквания трябва да бъдат покрити от интерпретатора, подредени по важност от най-важни до по-маловажни:
+
+- Пълно покритие на семантиките на Ecma 262 5.1 стандарта
+- Удобен API за употреба от програмисти
+- Да няма зависимости от други библиотеки (за по-лесно вграждане и по-малък размер на компилираната библиотеката)
+- Възможност за лесно вграждане в съществуващ Java проект
+- Възможност за лесна съвместна работа на Java и JavaScript
+- Достатъчно добра производителност (не е фокус на проекта, но все пак е добра идея проектът да има добра производителност)
+- Добра изолация на JavaScript кода от Java кода (за сигурност)
+- Поддръжка на по-старите версии на Java (за да може да бъде използван проекта навсякъде)
+
+## Избор на инструменти за разработка на проекта
+
+### Език за разработка - Java
+
+Java [@refs-java] е обектно-ориентиран език от високо ниво с автоматично управление на паметта (чрез т. нар. „Garbage Collector“). Езикът се компилира към байт-код и има типова проверка по време на компилацията. Компилираният байт-код не е изпълним от процесор, а се изпълнява чрез виртуалната машина на Java (JVM), което позволява на всеки софтуер, написан на Java да може да бъде изпълнен на всяка машина, за която съществува Java виртуална машина. Силната типизация на Java пък прави някои типове грешки по-сложни.
+
+Езикът има обширна стандартна библиотека и богат набор от разработени от обществото библиотеки. За този проект обаче няма да бъдат използвани тези библиотеки
+
+::: {.figure}
+
+```java
+public class Program {
+ public static boolean isSorted(int[] arr) {
+ if (arr.length < 2) return true;
+
+ int last = arr[0];
+
+ for (int i = 1; i < arr.length; i++) {
+ int curr = arr[i];
+
+ if (last > curr) return false;
+ last = curr;
+ }
+
+ return true;
+ }
+ public static void main(String[] args) {
+ int[] a = new int[] { 1, 2, 3, 4 };
+ int[] b = new int[] { 1, 5, 3, 4 };
+ System.out.println(isSorted(a)); // true
+ System.out.println(isSorted(b)); // false
+ }
+}
+```
+
+Примерен код на Java
+:::
+
+### Система за компилация - Gradle
+
+За Java съществуват две системи за компилация на проекти - Maven и Gradle. Поради лични предпочитания и възможността на Gradle да компилира и други езици (нужна за [@допълнение]), Gradle беше избран. Gradle [@refs-gradle] е една от най-използваните системи за компилация в екосистемата на Java. Основната концепция на Gradle е, че конфигурацията на проектите става чрез код, а по-конкретно - Kotlin DSL и Groovy DSL. Groovy обаче е остаряла технология [@refs-groovy-old] и няма проверки на типовете по време на компилацията, заради което разработчиците на Gradle и обществото от Java разработчици препоръчват употребата на Kotlin DSL. Заради това този проект ще бъде използван Kotlin DSL.
+
+::: {.figure}
+
+```c++
+plugins {
+ kotlin("jvm") version "1.9.0";
+ application;
+}
+
+group = "com.example";
+version = "1.0-SNAPSHOT";
+
+repositories {
+ mavenCentral();
+}
+
+dependencies {
+ implementation(kotlin("stdlib"));
+ testImplementation(kotlin("test"));
+ testImplementation("junit:junit:4.13.2");
+}
+
+application {
+ mainClass.set("com.example.MainKt");
+}
+
+tasks {
+ test {
+ useJUnit();
+ }
+}
+```
+
+Примерна конфигурация на Gradle проект чрез Kotlin DSL
+:::
+
+----
+
+## Избор на метод за интерпретиране
+
+От разгледаните в [@методи-за-изпълнение-на-код] типове интерпретатори в този проект ще бъде имплементиран хибриден интерпретатор. Като обобщение, хибридният интерпретатор не изпълнява директно програмния език, а компилира езика към междинен език, който след това бива изпълнен. Тази архитектура беше избрана, защото:
+
+- Изпълнението на кода е по-бързо, на цената на нуждата от компилация на кода преди изпълнението му
+- Възможността на замяна на компилатора с по-ефективен без промяна на изпълнителя на код
+
+За да бъде използвана тази архитектура обаче трябва да бъде създаден междинен език. За този проект беше създаден асемблероподобен език (описан по-подробно в [@междинен-език-и-неговото-изпълнение]), който да бъде интерпретиран. Решението да е асемблероподобен език е мотивирано от факта, че алгоритъма за изпълнение на поредица от инструкции е прост и ефективен - цикъл с таблица от повиквания за всяка инструкция, както и от факта, че компилацията към асемблероподобен език е сравнително лесно.
+
+# Реализация на интерпретатора
+
+Архитектурата на интерпретатора се състои от няколко основни компонента:
+
+- Управление на средата на изпълнение - т. нар. „Environment“
+- Имплементация на операциите с JavaScript стойностите
+- Междинният език и неговият изпълнител
+- Събитиен цикъл (event loop)
+- Система за съхраняване и предоставяне на данни за отстраняване на грешки
+
+## Компоненти на проекта
+
+Проекта се дели на няколко основни части:
+
+- common - Общи класове
+- runtime - Интерпретатор
+- compilation - Компилатор (описан в [@допълнение])
+- libs - Стандартни библиотеки (описан в [@допълнение])
+- repl - Команден ред (описан в [@допълнение])
+
+Предимството на тази архитектура е, че интерпретатора и компилатора са отделни - интерпретатора не знае какъв език интерпретира, докато компилатора работи независимо от интерпретатора. От това следва, че компилатора може да бъде заменен с по-добър такъв, или компилатор на различен език, но интерпретатора ще продължава да работи.
+
+Стандартната библиотека и командния ред са за удобството на потребителите и програмистите, които ще използват проекта.
+
+
+
+## Средата на изпълнение
+
+Това е най-простият, но и най-важният механизъм на интерпретатора. Той позволява персонализацията на средата на изпълнение на JavaScript кода, както и изолацията на две JavaScript среди на изпълнение. Средата на изпълнение на практика е регистър от добре познати флагови Java обекти, срещу които могат да стоят произволни стойности. Не се използват низове като идентификаторите на тези стойности, понеже може да има конфликти с ключовете - една библиотека може да използва ключа „test“ за референция към тестовите инструменти, докато потребителя може да използва същия ключ за експериментални цели.
+
+Средата за изпълнение може да бъде и наследявана от друга, като новата среда на изпълнение може да скрива ключове на родителя си, да променя стойностите срещу ключове на родителя си без да променя самите стойности в родителя си и да добавя собствени независими ключове. Тази система за наследяване е вдъхновена от системата за прототипи на JavaScript ([@обекти]).
+
+Тази структура от данни се използва в интерпретатора за съхранение и взимане на следните данни:
+
+- Стека на извикванията (`Frame.KEY`)
+- Максимална дълбочина на стека на извикванията (`Frame.MAX_STACK_COUNT`)
+- Флаг, скриващ стека на извикванията на дадена среда от общия стек на извиквания в диагностичните съобщения (`Frame.HIDE_STACK`)
+- Прототипите на елементарните стойности (`Value.BOOL_PROTO`, `Value.NUMBER_PROTO`, ...)
+- Прототипите на обектите, масивите и грешките (`Value.OBJECT_PROTO`, `Value.ARRAY_PROTO`, ...)
+- Глобалния обект (`Value.GLOBAL`)
+- Таблицата на присъщите стойности (`Value.INTRINSICS`)
+- Данните за диагностика (`DebugHandler.KEY`)
+- Флаг, скриващ кода в тази среда от отстранителя на грешки (`DebugHandler.IGNORE`)
+- Референция към събитийния цикъл, отговорен за тази среда на изпълнение (`EventLoop.KEY`)
+- Референция към настоящия компилатор (`Compiler.KEY`)
+
+----
+
+### Интерфейс за диагностика
+
+За разработката на едно приложение е изключително важно интерпретатора да има възможността да предоставя данни и интерфейс за диагностика. В нормалното действие на интерпретатора, в средата за изпълнение не присъства подобна система, но разработчика може да реши, в замяна на производителност, да въведе система за диагностика.
+
+В този интерпретатор `DebugHandler` е интерфейса, който се използва като интерфейс за диагностика. Той съдържа методи, който се повикват при дадени събития (фиг. [@debug-event-methods]), както и метода `getMap`, чрез който всички останали потребители на дадената среда могат да вземат „картата“ на дадена функция (т.е., хранилище на съответстващите местоположения на кода на всяка инструкция).
+
+Този интерфейс позволява имплементацията на традиционен дебъгер, който може да бъде използван в традиционни среди за разработка (коментира се примерна имплементация в [@допълнение]). Имплементациите на `DebugHandler` могат да бъде свързана с дадена среда за изпълнение чрез ключа `DebugHandler.KEY`.
+
+:::{.figure id=debug-event-methods}
+Име на метода | Описание
+-----------------|---
+`onSourceLoad` | Извиква се от компилатора след компилацията с оригиналния код, които е бил компилиран
+`onFunctionLoad` | Извиква се при компилирането на дадена функция с тялото на функцията и картата на тялото
+`onInstruction` | Извиква се от интерпретатора веднага след изпълнението на дадена функция
+`onFramePush` | Извиква се от интерпретатора, когато даден кадър се добавя към стека на извикванията
+`onFramePop` | Извиква се от интерпретатора, когато даден кадър се премахва от стека на извикванията
+
+Методи, съответстващи на събития в интерпретатора
+:::
+
+----
+
+## Имплементация на JavaScript стойностите
+
+За JavaScript интерпретатора е нужно да бъде създадена система за управление на JavaScript стойности. Тази система ще бъде използвана както от JavaScript кода, така и от потребителски код, за да се създават и управляват JavaScript стойности според Ecma стандарта.
+
+### Структура на Java класовете
+
+{}
+
+В този проект всички JavaScript стойности имплементират един основен интерфейс - „Value“. Този интерфейс съдържа методи, които съответстват на всяка операция, която може да бъде извършена с JavaScript стойност ([@value-methods-table]). Двата подтипа на „Value“ са интерфейса „PrimitiveValue“ и класа „ObjectValue“. „PrimitiveValue“ е интерфейса, който всички типове за елементарни стойности наслеждават. „ObjectValue“ пък е основният клас за всички типове за стойности-обекти. „ObjectValue“ има два основни подкласа - „ArrayLikeValue“, основен клас на всички класове за обектите, които се държат като масиви и „FunctionValue“, основният клас на всички класове за JavaScript функциите.
+
+### Празни стойности
+
+Празните стойности са `null` и `undefined`. Тези стойности, както и в други езици, се използват за отбелязването на липса на стойност. JavaScript предоставя две празни стойности, защото `undefined`, преди въвеждането на `in` оператора, е бил единственият начин да се разбере дали член на даден обект съществува или не. Тези стойности имат следните общи свойства:
+
+- Когато се направи опит да се достъпи техен член се хвърля грешка
+- Не са истинни (превръщат се към булевата стойност `false`)
+- Превръщат се към специалната числова стойност `NaN`
+- Нямат прототип и при опит той да бъде взет или зададен се хвърля грешка
+
+За стойността `undefined` е специално заделен типовия низ (низа, върнат при операцията `typeof` върху стойността) „undefined“ докато `null` споделя „object“ с останалите обекти.
+
+В кода и двете стойности са имплементирани с класа `VoidValue`, който може да бъде използван за да бъдат създадени и други празни стойности.
+
+----
+
+### Елементарни стойности
+
+В JavaScript елементарните стойности са всички стойности, които не са обекти. Такива стойности не могат да съдържат референция към друга JavaScript стойност. Такива стойности биват:
+
+- Празни стойности (null и undefined)
+- Булеви стойности (true и false)
+- Числови стойности (по стандарт 64-битови числа с плаваща запетая)
+- Низове (по стандарт съставени от 16-битови символи)
+- Символи (маркерни стойности, обяснени по-надолу)
+
+Всички елементарни стойности (освен празните стойности) имат константен прототип в зависимост от типа си, но нямат собствени членове (изключение прави низа, който симулира структурата на константен масив от символи).
+
+### Символи
+
+Символите са особен тим от елементарни стойности в JavaScript, въведен в по-късните разработки на Ecma. Понеже обаче символите се използват от голяма част от модерният JavaScript код, беше взето решение те да бъдат имплементирани в интерпретатора въпреки това.
+
+Символите са флагови стойности, които потребителя може да създаде сам. Отличаващото ги свойство е, че при всяко създаване на символ се създава уникален символ, т.е. не може по-късно да бъде създаден нов такъв символ. Другото свойство на низовете е, че могат да бъдат ключове на членове на обекти.
+
+На практика низовете се използват за добавянето на нови полета в обекти, без те да пречат на стар код, който не знае за съществуването на (тези) символи.
+
+В интерпретатора символите са имплементирани в класа `SymbolValue`, който имплементира интерфейса `PrimiteValue`.
+
+### Числени и целочислени стойности
+
+Числата в този интерпретатор са представени чрез основния интерфейс `NumberValue`. Това включва числата с плаваща запетая, както и целите числа. Въпреки че стандарта не уточнява тип за цели числа, този интерпретатор има прозрачна имплементация на целите числа (т.е., кода не може и не трябва да може да различи целите числа от числата с плаваща запетая).
+
+В кода, целите числа са имплементирани в класа `IntValue`, а числата с плаваща запетая - класа `DoubleValue`. Тези класове обаче не могат да бъдат инстанцирани ръчно - трябва да бъде използван метода `NumberValue.of`, който създава една от двете инстанции, в зависимост от това дали подаденото число може да бъде представено с 32-битово число.
+
+### Обекти
+
+Обектите са основополагаща концепция в JavaScript. В основата на обектите стои списък от уникални низове (т. нар. ключове) и съответстващият им член [@членове] (съществува и паралелен списък със списък от ключове-символи към членове). Обектите се използват най-вече за съхранение на няколко подстойности под формата на структурирани данни (подобно на класовете на Java), но могат да бъдат използвани и като хеш-таблици.
+
+Обектите по подразбиране са отключени за всякакъв вид промяна, но потребителя може да зададе различен режим на обекта, който ограничава дадени типове промени на обекта. Тези режими са следните:
+
+- Нормален - всякакъв тип промяна е позволен
+- Режим без разширения - прототипа на обекта не може да бъде променян и нови полета не могат да му бъдат добавяне
+- Режим без пренастройвани (запечатване) - освен ограниченията от предишният режим, полетата не могат да бъдат трити и пренастройвани
+- Режим на заключване (замразяване) - обекта става на практика константа, нито едно негово свойство не може да бъде променено
+
+JavaScript кода може да променя режима от по-свободен към по-ограничаващ, но не и обратно. Това разрешава на разработчицитие да осигурят дадено ниво на константност на данните на обектите си.
+
+Накрая, обектите имат прототипи. Прототипа може да е `null` или обект. При търсенето на член, може обект да няма дадения ключ. Тогава търсенето продължава в прототипа на обекта. Понеже обаче прототипа е обект на практика съществува свързан списък от обекти, или т. нар. прототипна верига. Прототипите са в основата на обектно-ориентираното програмиране в JavaScript, понеже може чрез прототипите да бъде дефиниран един основен обект, който да съдържа всички функции за даден „тип“ обекти, а всички обекти от този „тип“ просто имат този основен обект като прототип. Освен това обаче прототипите могат да бъдат използвани и за осъществяване на наследство на обекти - обекта „AnimalPrototype“, който съдържа члена „speak“ може да бъде прототип на обекта „DogPrototype“, който съдържа члена „bark“. При тази конфигурация, „DogPrototype“ де факто има и двете полета - „speak“ и „bark“.
+
+В кода обектите са имплементирани чрез класа „ObjectValue“. Този клас съдържа четири хеш-таблици, които съдържат съответно низовите полета, низовите свойства, символните полета и символните свойства, като тези таблици общо съхраняват всички членове на обекта. Освен това обекта съдържа и наредени хеш-таблици от низовите и символните ключове, като на всеки ключ е съпоставена булева стойност - дали ключа е свойство. Хеш-таблиците от ключовете са наредени, понеже стандарта изисква обектите да съхраняват ключовете в реда, в който са били вмъкнати в обекта.
+
+Прототипа не се съхранява директно като референция към обект, а като функционален интерфейс, който може да върне различен обект за различна среда. Това позволява обекти да бъдат използвани от няколко среди без конфликти.
+
+Накрая, обекта съхранява и режима на ограничение в едно поле от тип `State`, което е енумерация. Въпреки, че е възможно да бъде само булева стойност, която определя дали може обекта да се разшири, замразяването и запечатването на обект може да стане само с обхождане на всички полета, което е по-бавно за по-големите обекти.
+
+### Функции
+
+В JavaScript функциите не са нищо повече от обекти, които могат да бъдат извикани. Функциите могат да бъдат извикани по два начина (или по-точно, поддържат две допълнителни операции, които никой друг тип стойности не поддържа):
+
+- Чрез прилагане („applying“) - това е нормалният начин за извикване на функция. „this“ аргумента е `undefined`, освен когато функцията не бъде извикана рефлективно или синтактично като член на даден обект (тоест чрез синтаксиса `obj.key(a, b, c)`)
+- Чрез конструиране („constructing“) - при този режим на извикване функцията се изпълнява като конструктор на обект - „this“ аргумента на функцията става обект, а върнатата стойност на функцията е именно същия обект
+
+Функциите в този интерпретатор се делят на два подтипа - JavaScript функции и Java функции. JavaScript функциите (имплементирани в класа `CodeFunction`) се състоят от JavaScript код, който се изпълнява при всяко извикване на функцията, докато Java функциите (имплементирани в класа `NativeFunction`) са функции, които съдържат функционален интерфейс като поле, което бива извикано при всяко извикване на функцията. Употребата на JS функциите е очевидна, а Java функциите се използват, за да предоставят достъп до функционалност на JavaScript функциите, до който иначе те не биха имали достъп - такива функции могат да бъдат съпоставени със системните извиквания на C.
+
+### Масиви и масивоподобни обекти
+
+Масивите в JavaScript не са нищо повече от обект, който има целочислени ключове, представени чрез низове, както и специалният член „length“, който съдържа броя на елементите на масива. Понеже обаче съхранението на данните на масива заедно с останалите членове е крайно неефективно, този интерпретатор има специален подобект за масивоподобните обекти - `ArrayLikeObject`. Такива обекти фалшифицират виртуални полета с целочислени ключове, съответстващи на представлявания масив, както и полето „length“, което отразява дължината на представлявания масив.
+
+Класа `ArrayLikeObject` обаче не конкретизира по какъв начин се съхраняват данните. Това се дължи на факта, че може да има много масивоподобни данни - буфени, аргументите на функцията, нормален буферен списък от данни както и много други. В конкретния (и най-честия) случай на масивоподобните данни - прост списък от JavaScript функции, има създаден клас `ArrayObject`, който е имплементиран чрез масив, брояч на дължината и логика за динамичното уголемяване на масива. За да бъдат съхранени дупките (фиг. [@example-array-holes]) в масива се използва Java флаговата стойност „null“.
+
+:::{.figure id=example-array-holes}
+```js
+var arr = [];
+arr[0] = 5;
+arr[1] = 6;
+arr[4] = 8;
+arr[12] = 3;
+console.log(arr); // [5, 6, , 8, 3]
+```
+Пример за масив с дупки
+:::
+
+Освен за по-ефективното съхраняване на данните на масива, има нужда за подобна оптимизациа защото се елиминира нуждата от превръщане на низове към цели числа и обратно при търсенето на елементи от масива (в случаите, в които при търсенето на член от масива се подава числова стойност).
+
+### Членове
+
+Във всеки обект фигурират членове. Това са контейнерите, които съхраняват JavaScript стойностите в обектите. Членовете биват два вида: полета и свойства. Полетата са по-простият тип членове - съдържат само JS стойност, докато свойствата са членове, чиято стойност се задава и взима чрез две функции - „get“ за взимане на стойността и „set“ за съхранението на стойността.
+
+Освен това, членовете имат следните настройки:
+
+- Обходимост (enumerable) - при обхождане на ключовете на обекта, ключа на този член ще бъде обходен само ако тази настройка е `true`
+- Настройваемост (configurable) - разрешава промените на настройките на члена само ако тази настройка е `true`
+- Презаписваемост (writable) - присъства само при полетата, разрешава презаписването на стойност само ако тази настройка е `true`
+
+За настройка се приемат следните действия:
+
+- Промяната на една от тези настройки, освен ако презаписваемо, но ненастройваемо поле се направи непрезаписваемо
+- Изтриване на полето от обекта
+
+Членовете са дефинирани чрез интерфейса „Member“, полетата чрез класа „FieldMember“, а свойствата чрез „PropertyMember“. Понеже полетата могат да бъдат виртуални и контролирани от Java код, е осигурена базова имплементация за съвсем прости полета, които са само контейнер за JavaScript стойност, в класа „SimpleFieldMember“, докато по-сложна логика може да създаде собствена имплементация на „FieldMember“ класа (на този механизъм са базирани масивите).
+
+----
+
+:::{.figure id=value-methods-table}
+
+Име на операцията | Аргументи | Описание
+--------------------|---------------|-----------
+Взимане на тип | val | Връща низ, представляващ типа на аргумента. Тази операция може да върне следните типове: „undefined“, „boolean“, „string“, „number“, „object“, „function“ или „symbol“
+Прилагане | func, self, ...args | Ако `func` е функция я прилага със „this“ аргумента равен на `self` и останалите аргументи `args`. Стойността, която тази операция връща е върнатата стойност от функцията
+Конструиране | func, target, ...args | Ако `func` е функция я конструира с оригиналния конструктор [@refs-new-target] равен на `target` и останалите аргументи `args`. Стойността, която тази операция връща е върнатата стойност от функцията
+Превръщане в елементарна стойност | val | Ако стойността не е елементарна, в зависимост от наличните полета, превръща стойността в низ или число ([@refs-type-coercion])
+Превръщане в низ | val | Превръща стойността в елементарна, а след това елементарната превръща в низ
+Превръщане в число | val | Превръща стойността в елементарна, а след това елементарната превръща в число
+Превръщане в булева стойност | val | Всички стойности се превръщат в `true`, с изключение на следните: 0, NaN, false, празен низ, undefined, null
+Проверка на инстанция | obj, func | Проверява дали `func.prototype` е част от веригата от прототипи на `obj`
+Взимане на член | obj, key | Намира члена на обект, като включва и членовете на прототипа, както и неговия прототип и така нататък
+Проверка на ключ | obj, key | Като взимането на член, но вместо да върне стойността на члена, връща дали член с такъв ключ съществува в обекта
+Съхраняване на член | obj, key, val | Ако `obj` (или някой негов прототип) има свойство с ключ `key`, задава стойността на свойството. Иначе създава ново поле с ключ `key` и стойност `val` със всички настройки включени
+Взимане на собствен член | obj, key | Като взимането на член, но игнорира веригата от прототипе
+Взимане на собствен ключ | obj, key | Като взимането на собствен член, но вместо да върне стойността на члена, връща дали член с такъв ключ съществува в обекта
+Взимане на низови ключове | obj | Взима списък от всички низови ключове на стойността, като в зависимост от аргументите ще бъдат върнати само обходимите или всички членове, само собствените членове или включва и всички от прототипната верига
+Взимане на символни ключове | obj | Взима списък от всички ключове на стойността. Има подобни опции на предишната операция
+Дефиниране на собствено низово поле | obj, key, value, writable, configurable, enumerable | Дефинира даденото поле с дадените настройки
+Дефиниране на собствено низово свойство | obj, key, get, set, configurable, enumerable | Дефинира даденото поле с дадените настройки
+Дефиниране на собствено символно поле | obj, key, value, writable, configurable, enumerable | Дефинира даденото поле с дадените настройки
+Дефиниране на собствено символно свойство | obj, key, get, set, configurable, enumerable | Дефинира даденото поле с дадените настройки
+Изтриване на собствен член | obj, key | Изтрива дадения член от таблицата на обекта
+Задаване на прототип | obj, proto | Задава нов прототип `proto` на `obj`. Трябва `proto` да е `null`, `undefined` или обект
+Визмане на прототип | obj | Връща прототипа на дадения `obj`
+Визмане на обектно състояние | obj | За елементарните стойности връща състояние „замръзнал“. За обектите връща състоянието на ограничение
+Забраняване на разширения | obj | Ако това няма да фигурира в нивото на ограничение, поставя стойността в режим на „забранени разширения“
+Запечатване | obj | Ако това няма да фигурира в нивото на ограничение, поставя стойността в режим на „запечатване“
+Замръзване | obj | Ако това няма да фигурира в нивото на ограничение, поставя стойността в режим на „замръзване“
+Сбор | a, b | Превръща `a` и `b` в елементарни стойности. Ако и двете елементарни стойности са числа връща сбора им, иначе превръща двете стойности в низове и ги свързва в един
+Разлика | a, b | Превръща двете стойности в числа и извършва аритметичното изваждане на `b` от `a`
+Делимо | a, b | Превръща двете стойности в числа и извършва аритметичното деление на `b` с `a`
+Произведени | a, b | Превръща двете стойности в числа и извършва аритметичното умножение на `b` и `a`
+Деление с остатък | a, b | Превръща двете стойности в числа и извършва аритметичното деление с остатък на `b` с `a`
+Побитово и | a, b | Превръща двете стойности в цели числа със знак и извършва побитовата „и“ операция
+Побитово или | a, b | Превръща двете стойности в цели числа със знак и извършва побитовата „или“ операция
+Побитово изкл. или | a, b | Превръща двете стойности в цели числа със знак и извършва побитовата „изключително или“ операция
+Стриктно равенство | a, b | Извършва алгоритъма за стриктно сравнение на две стойности, описан в [@refs-strict-equals]
+Стриктно неравенство | a, b | Връща обратната стойност на стриктното равенство
+„Хлабаво“ равенство | a, b | Извършва алгоритъма за „хлабаво“ сравнение на две стойности, описан в [@refs-loose-equals]
+„Хлабаво“ неравенство | a, b | Връща обратната стойност на хлабавото равенство
+По-голямо | a, b | Превръща двете стойности в елементарни. Ако и двете елементарни стойности са низове ги сравнява символ по символ, иначе стойностите се превръщат в числа и тогава се сравняват. Върнатата стойност е `true` ако `a` e по-голяма от `b`
+По-голямо или равно | a, b | Използва се алгоритъма за сравнение, описан по-горе. Върнатата стойност е `true` ако стойността на `a` e по-голяма или равна на тази на `b`
+По-малко | a, b | Използва се алгоритъма за сравнение, описан по-горе. Върнатата стойност е `true` ако стойността на `a` e по-малка от тази на `b`
+По-малко или равно | a, b | Използва се алгоритъма за сравнение, описан по-горе. Върнатата стойност е `true` ако стойността на `a` e по-малка или равна от тази на `b`
+Побитово обръщане | val | Превръща `val` в 32-битово число със знак и връща същото число с обърнати битове
+Булево обръщане | val | Превръща `val` в булева стойност и връща противоположната булева стойност на превърнатата
+Знаково обръщане | val | Превръща `val` в число и връща противоположната (-val) стойност
+Побитово ляво изместване на битовете | a, b | Превръща стойностите в 32-битови числа със знак и извършва битово преместване наляво на `a` с `b` бита
+Побитово дясно изместване на битовете | a, b | Превръща стойностите в 32-битови числа със знак и извършва битово преместване надясно на `a` с `b` бита
+Побитово ляво изместване на битовете (със знака) | a, b | Превръща стойностите в 32-битови числа без знак и извършва битово преместване надясно на `a` с `b` бита
+
+Списък от всички операции, които могат да бъдат извършвани със JavaScript стойностите
+:::
+
+----
+
+## Междинен език и неговото изпълнение
+
+За да се реализира избраната хибридна архитектура на интерпретатора беше нужно да се създаде междинен език. Езикът, който беше създаден е асемблероподобен език, базиран на операции върху стека. Всяка JavaScript функция има свой списък от инструкции, наречен „тяло“ на функцията, което се изпълнява всеки път, когато функцията бъде извикана.
+
+При изпълнението на тялото на една функция се създава т. нар. „кадър“, който е структурата от данни, отговорна за съхранението на състоянието на изпълнението на функцията. Параметрите, които се записват в един кадър са показани на фигура [@frame-storage]:
+
+:::{.figure id=frame-storage}
+
+Име | Начална стойност | Описание
+----------------- | ---------------- | ---------------------
+Стек | Празен масив | Структура, описана в [@стек]
+Указател на стека | 0 | Съхранява колко елемента от стека се използват
+Указател на кода | 0 | Съхранява инструкцията, до която е достигнало изпълнението на кода
+Променливи | | Структура, описана в [@локални-променливи]
+Аргументи | | Подадените при извикването на функцията аргументи
+Функция | | Функцията, чието тяло изпълнява този кадър
+
+Информацията, съхранявана в един кадър
+:::
+
+----
+
+### Стек
+
+Стекът е структура, която може да бъде сравнена с метафорична „купчина“ от елементи. Елементи могат да бъдат добавяни върху стека и да бъдат отнемани от върха на стека. Тази структура от данни се нарича „последните вътре са първите вън“ (на англ. LIFO, фиг. [@stack-lifo]).
+
+Имплементацията на тази структура от данни е лесно осъществима с масив и указател към първия свободен елемент от стека. При добавяне на елемент в масива се слага елемента на мястото, към което сочи указателя, след което указателя се увеличава с едно. За да се премахне елемент е нужно само да се намали указателя. Този метод беше използван и за имплементацията на стековете за кадрите.
+
+{id=stack-lifo}
+
+
+
+:::{.figure}
+```java
+class ArrayStack {
+ int stack[] = new int[16];
+ int ptr = 0;
+
+ void push(int val) {
+ if (this.ptr >= this.stack.length) {
+ int newStack = new int[this.stack.length * 2];
+ System.arraycopy(this.stack, 0, newStack, 0, this.stack.length);
+ this.stack = newStack;
+ }
+
+ this.stack[this.ptr] = val;
+ this.ptr++;
+ }
+ int pop() {
+ this.ptr--;
+ return this.stach[this.ptr];
+ }
+}
+```
+Примерна имплементация на добавяне и премахване на елемент от стек, базиран на масив
+:::
+
+### Локални променливи
+
+Освен стека, кода има достъп и до променливи. Променливите, за разлика от стека, са контейнери за стойности, които поддържат случаен достъп (всяка променлива може да бъде достъпена по всяко време). Всяка програма трябва да дефинира броя променливи, от които се нуждае, като при всяко създаване на кадър ще бъдат създавани съответния брой променливи.
+
+Понеже функциите могат да бъдат „вграждани“ една в друга, съществува механизъм, чрез който функция, вградена в друга, може да използва променливите на родителя си. Това се постига чрез въвеждането на 3 вида променливи:
+
+- локални - използваеми само за текущата функция
+- уловими - използваеми както за текущата функция, така и за вградените в текущата функция функции
+- уловени - референции към даден набор от уловимите и уловените променливи на родителя на текущата функция
+
+Променливите могат да бъдат и индексирани, като отрицателните индекси съответстват на уловените променливи (като -1 е първата уловена, -2 е втората и т.н.), а положителните индекси индексират първо локалните, а след това уловимите променливи, все едно са един масив (ако има 3 локални и 5 уловими променливи, 0 е първата локална, 3 е първата уловима, а 8 е първият индекс, който е извън границите)
+
+В програмен код, променливите са дефинирани като три масива в класа `Frame`. Локалните променливи са масив от класа `Value` (`Value[]`), докато уловените и уловимите променливи са масиви от масиви с една стойност от типа `Value` (`Value[][1]`). Използва се такава структура за уловимите и уловените променливи, за да бъде възможно споделянето на една променлива от няколко подфункции.
+
+При създаването на вградена функция, която улавя променливи, се подава масив от уловими и уловени променливи, които функцията е декларирала, че уловява. Този масив ще съответства директно на масива `captures`, използван в кода.
+
+:::{.figure}
+```java
+class Frame {
+ // ...
+ public final Value[][] captures;
+ public final Value[] locals;
+ public final Value[][] capturables;
+
+ // Взима стойността на променлива
+ public Value getVar(int i) {
+ if (i < 0) return this.captures[-i - 1][0];
+ else if (i < locals.length) return this.locals[i];
+ else return this.capturables[i - this.locals.length][0];
+ }
+ // Задава нова стойност на дадената променлива
+ public Value setVar(int i, Value val) {
+ if (i < 0) return this.captures[-i - 1][0] = val;
+ else if (i < this.locals.length) return this.locals[i] = val;
+ else return this.capturables[i - this.locals.length][0] = val;
+ }
+ // Улавя дадената променлива
+ public Value[] captureVar(int i) {
+ if (i < 0) return this.captures[~i];
+ if (i >= this.locals.length) {
+ return this.capturables[i - this.locals.length];
+ }
+ else throw new RuntimeException("Illegal capture");
+ }
+
+ // ...
+}
+
+```
+
+Опростена версия на кода за управление на променливите
+:::
+
+### Инструкциите и тяхното изпълнение
+
+Инструкцията е основната единица, която съставя тялото на една функция. Всяка инструкцията се състои от тип и даден брой операнди в съответствие на типа на инструкцията. Зад всяка инструкция стои дадена логика, която се изпълнява, когато интерпретатора „изпълни“ интрукцията. Примери за инструкции могат да бъдат „Събери стойностите на операнд 1 и операнд 2 и изпечатай стойността“ или „Задай нова стойност програмния брояч равна на операнд 1“. Във таблица [@instruction-set-table] са описани всички инструкции.
+
+За да се изпълнят инструкциите обаче е нужен програмен брояч. Програмният брояч съхранява индекса на инструкцията, до която е стигнал интерпретатора. Броячът се използва, за да е възможно прекъсването на изпълнението на тялото, както и скоковете в тялото от други инструкции.
+
+Накрая, самото изпълнение на една инструкция се свежда до цикъл, в който се прави избор на метода, който изпълнява логиката на инструкцията според нейния тип. Примерен код, който прави това е показан на фигура [@example-instr-exec], а примерен код, който използва примерният интерпретатор е показан на фигура [@example-instr-usage]
+
+:::{.figure id=example-instr-exec}
+```java
+public class Frame {
+ private Value executeLoadNumber(Instruction instruction) {
+ double value = instruction.getOperand(0);
+ this.stackPush(NumberValue.of(instruction.value));
+ this.codePtr++;
+ return null;
+ }
+ private Value executeDuplicate(Instruction instruction) {
+ Value val = this.stackPeek();
+ this.stackPush(val);
+ this.codePtr++;
+ return null;
+ }
+ private Value executeAdd(Instruction instruction) {
+ Value a = this.stackPop();
+ Value b = this.stackPop();
+
+ this.stackPush(NumberValue.of(a.toNumber() + b.toNumber()));
+ this.codePtr++;
+
+ return null;
+ }
+ private Value executeJmp(Instruction instruction) {
+ this.codePtr += instruction.getOperand(0);
+ return null;
+ }
+ private Value executeRet(Instruction instruction) {
+ if (this.stackPtr == 0) return Value.UNDDEFINED;
+ else return this.stackPop();
+ }
+ private Value executePrint(Instruction instruction) {
+ System.out.println(this.stackPop());
+ this.stackPtr++;
+ return null;
+ }
+
+ public Value executeNext() {
+ switch (this.body[this.codePtr].type) {
+ case LOAD_NUMBER: return executeLoadNumber(instruction);
+ case ADD: return executeAdd(instruction);
+ case JMP: return executeJmp(instruction);
+ case RET: return executeRet(instruction);
+ case DUP: return executeDuplicate(instruction);
+ case PRINT: return executePrint(instruction);
+ }
+ }
+ public Value executeUntilReturn() {
+ while (true) {
+ Value res = executeNext();
+ if (res != null) return res;
+ }
+ }
+}
+```
+Опростена версия на интерпретатора
+:::
+
+:::{.figure id=example-instr-usage}
+```txt
+; Добавя 10 към стека
+LOAD_NUMBER 10
+; Добадя 1 към стека
+LOAD_NUMBER 1
+; Добавя първият елемент на
+; стека с новодобавената единица
+ADD
+; Клонира резултата, за
+; да не бъде загубен
+DUP
+; Печата клонираният резултат
+PRINT
+; Връща се към LOAD_NUMBER 1
+JMP -4
+; Преди скока на стека вече е останал
+; един елемент, с едно по-голям от предишният
+```
+```java
+int temp = 10;
+while (true) {
+ temp = temp + 1;
+ System.out.println(temp);
+}
+```
+---
+Примерен код, използващ примерния интерпретатор по-горе, и негов еквивалент, написан на Java
+:::
+
+### Възможност за прекъсване на изпълнението на кадър
+
+Кадрите в този интерпретатор дават възможността инструкциите им да бъдат изпълнявани по една наведнъж. Това позволява на потребител на интерпретатора да прекъснат изпълнението на даден кадър, като по-късно изпълнението на същия кадър може да бъде възобновено по всяко време, като кадъра запазва състоянието си, все едно кода никога не е спирал.
+
+В основата на този механизъм стои идеята, че кадъра изпълнява инструкциите си една наведнъж (тоест метода `next` изпълнява само една инструкция). Това до известна степен усложнява имплементацията, но позволява тази гъвкавост.
+
+Освен самата възможност за прекъсване на изпълнението на кадър, това позволява и вмъкването на върната стойност от предишна инструкция, индуцирането на върната стойност от кадъра ,както и индуцирането на изключение, хвърлена от кадъра. Това позволява имплементирането на JavaScript генератори без допълнителна компилационна стъпка.
+
+:::{.figure}
+```java
+Frame frame = ...;
+int i = 0;
+
+while (true) {
+ var res = frame.next();
+
+ if (res != null) {
+ System.out.println("Returned value: " + res.toReadable(env));
+ break;
+ }
+
+ if (i++ % 10 == 0) {
+ System.out.println(i + " instructions executed, sleeping 2 seconds...");
+ Thread.sleep(2000);
+ }
+}
+```
+
+Пример за прекъсване на кадър, по средата на неговото изпълнение
+:::
+
+### Набор от инструкции
+
+За този интерпретатор беше създаден набор от инструкции, чрез които код, написан чрез тях да може да обработва стека, да управлява изпълнението на кода и да борави с JavaScript стойности.
+
+:::{.figure id=instruction-set-table}
+Име | Операнди | Аргументи от стека | Описание
+-------------|---------------|--------------------|----
+RETURN | | value | Приключва изпълнението на функцията с върната стойност `value`
+NOP | | | Не прави нищо
+THROW | | error | Създава изключение [@система-за-изключения] от `error`
+THROW_SYNTAX | msg | | Създава изключение за синтактична грешка с даденото съобщение `msg`
+DELETE | | key, object | Изпълнява логиката за премахване на члена `key` от `object`. Връща булева стойност на стека, в зависимост от резултата от операцията
+TRY_START | catchStart, finallyStart, end | | Създава нова зона за изпълнение на защитен код ([@защитено-изпълнение-на-кода]) и започва тестовия регион от следващата функция
+TRY_END | | | Извършва изход от текущия регион на защитения режим по нормален начин
+CALL | argN, hasSelf | args, function, this | Прилага `function` с `this` и аргументи `args`. Аргументите на извикването се взимат от стека в обратен ред (първите вътре са първите излезли), за да се запази ред на изпълнение
+CALL_NEW | argN | args, function | Конструира `function` с оригинален конструктор същата функция и аргументи `args`. Аргументите се взимат от стека както CALL ги взима
+JMP_IF | offset | value | Ако `value` е истинна стойност, `offset` се прибавя към `codePtr`
+JMP_IFN | offset | value | Ако `value` е лъжовна стойност, `offset` се прибавя към `codePtr`
+JMP | offset | | Добавя `offset` към `codePtr`
+PUSH_UNDEFINED | | | Добавя `undefined` към стека
+PUSH_NULL | | | Добавя `null` към стека
+PUSH_BOOL | value | | Добавя булевият операнд `value` към стека
+PUSH_NUMBER | value | | Добавя 64-битовото IEEE 754 числото с плаваща запетая `value` към стека
+PUSH_STRING | value | | Добавя низа от символи `value` към стека
+DUP | count, offset | | Добавя елемента `offset` на брой елементи преди последния елемент на стека `count` на брой пъти върху стека
+DISCARD | | | Премахва последната стойност от стека без да прави нищо с нея
+LOAD_FUNC | id, name, captures... | | Създава функция с даденото ID, име и уловени променливи и я добавя към стека. За повече информация, вижте [@функции]
+LOAD_ARR | count | | Създава масив с `count` на брой празни елемента и го добавя към стека
+LOAD_OBJ | | | Създава празен обект и го добавя към стека
+LOAD_GLOB | | | Добавя глобалният обект към стека
+LOAD_INSTINSIC | name | | Добавя вътрешната стойност с даденото име `name` към стека
+LOAD_ARG | i | | Добавя стойността на `i`-тия аргумент от текущото извикване към стека
+LOAD_ARGS_N | | | Добавя броят на аргументите на текущото извикване към стека
+LOAD_CALLED | | | Добавя стойността на изпълняванта функция към стека
+LOAD_THIS | | | Добавя „this“ аргумента към стека
+LOAD_ERROR | | | Когато изпълнението на програмата е в регион на защитено изпълнение в състояние на хванато изключение, тази инструкция добавя хванатото изключение към стека
+LOAD_VAR | i | | Зарежда променливата с индекс `i` и добавя стойността ѝ към стека
+LOAD_MEMBER | | key, object | Взима члена `key` на `object` и го добавя към стека
+LOAD_MEMBER_STR | key | object | Еквивалент на LOAD_MEMBER, но с константен низов ключ `key`
+LOAD_MEMBER_INT | key | object | Еквивалент на LOAD_MEMBER, но с константен числов ключ `key`
+STORE_VAR | i, keep | value | Съхранява `value` в променливата с индекс `i`. Ако `keep` е `true`, добавя `value` към стека
+STORE_VAR | i, keep | value | Съхранява `value` в променливата с индекс `i`. Ако `keep` е `true`, добавя `value` към стека
+STORE_MEMBER | keep | value, key, object | Задава нова стойност `value` на члена `key` на `object`. Ако `keep` е `true`, добавя `value` към стека
+STORE_MEMBER_STR | key, keep | value, object | Еквивалент на STORE_MEMBER, но с константен низов ключ `key`
+STORE_MEMBER_INT | key, keep | value, object | Еквивалент на STORE_MEMBER, но с константен числов ключ `key`
+GLOB_GET | name, force | | Зарежда променливата `name` от глобалния обект. Ако `force` е `true` не се хвърля грешка ако променливата не съществува. Стойността на променливата се добавя към стека
+GLOB_SET | name, keep, force | value | Съхранява променливата `name` в глобалния обект. Ако `force` е `true` не се хвърля грешка ако променливата не съществува. Стойността на променливата се добавя към стека, ако `keep` е `true`
+GLOB_DEF | name | value | Създава променливата `name` със стойност `undefined` в глобавният обект, ако не съществува
+OPERATION | type | values... | Изпълнява дадената операция (фиг. [@operations-table]) с даденият брой операнда, които операцията изисква. Добавя стойността при изчислението на операцията към стека
+
+Набор от инструкции на междинния език (бележка: в колоната с аргументи от стека са показани аргументите в реда, в който се взимат от стека, освен ако друг ред не е уточнен)
+:::
+
+:::{.figure id=operations-table}
+
+Име | Операнди | Еквивалентна операция
+-----------------------|------------|--------------
+ADD | a, b | Сбор
+SUBTRACT | a, b | Разлика
+DIVIDE | a, b | Деление
+MULTIPLY | a, b | Произведение
+MODULO | a, b | Остатък от деление
+AND | a, b | Побитово и
+OR | a, b | Побитово или
+XOR | a, b | Побитово изключително или
+EQUALS | a, b | Стриктно равенство
+NOT_EQUALS | a, b | Стриктно неравенство
+LOOSE_EQUALS | a, b | Хлабаво равенство
+LOOSE_NOT_EQUALS | a, b | Хлабаво неравенство
+GREATER | a, b | По-голямо
+GREATER_EQUALS | a, b | По-голямо или равно
+LESS | a, b | По-малко
+LESS_EQUALS | a, b | По-малко или равно
+INVERSE | val | Побитово обръщане
+NOT | val | Булево обръщане
+POS | val | Превръщане в число
+NEG | val | Знаково обръщане
+SHIFT_LEFT | a, b | Побитово ляво изместване на битовете
+SHIFT_RIGHT | a, b | Побитово дясно изместване на битовете
+USHIFT_RIGHT | a, b | Побитово дясно изместване на битовете (със знака)
+TYPEOF | val | Взимане на типа
+IN | key, obj | Проверка на ключ
+INSTANCEOF | obj, class | Проверка на инстанция
+
+Набор от операциите, които OPERATION инструкцията може да изпълнява (бележка: операндите се взимат от стека в обратен ред - първо се взимат последните, всяка операция добавя стойност на стека или хвърля грешка. За подробно описание на операциите вижте фиг. [@value-methods-table])
+
+:::
+
+## Система за изключения
+
+Изключенията са основна част от JavaScript. Те се използват за сигнализирането на неочаквано състояние или събитие от кода. Ecma стандарта уточнява два механизъма, чрез които JavaScript кода може да борави с изключения: хвърляне на изключения и изпълняване на код в защитен режим за улавянето на изключение.
+
+### Създаване на изключения
+
+Създаването (или „хвърлянето“) на изключение спира изпълнението на текущата функция и продължава изпълнението на програмата в първия обработвач на изключения, или ако няма такива, изпълнението на програмата се прекратява.
+
+Понеже семантиките за хвърляне на грешка на JavaScript и Java са подобни, беше създадено Java изключение, наречено `EngineException`. То съдържа както стойността, която е хвърлена, така и диагностични данни за стека на повикванията по времето на хвърлянето на грешката. Когато JavaScript кода иска да хвърли грешка, интерпретатора създава служебна Java грешка от типа `EngineException`, която обвива хвърлената грешка. След това създадената грешка просто се хвърля. От друга страна, всеки кадър улавя `EngineException` грешките и добавя текущата точна от изпълнението на кода в събрания от изключението стек от повиквания, като след това отново изхвърля грешката.
+
+:::{.figure}
+```java
+class InstructionRunner {
+ ...
+ private static Value execThrow(
+ Environment env, Instruction instr, Frame frame
+ ) {
+ throw new EngineException(frame.pop());
+ }
+ ...
+ public static Value exec(
+ Environment env, Instruction instr, Frame frame
+ ) {
+ switch (instr.type) {
+ ...
+ case THROW: return execThrow(env, instr, frame);
+ ...
+ }
+ }
+}
+class Frame {
+ ...
+ public final Value next(...) {
+ try {
+ ...
+ return InstructionRunner.exec(env, instruction, this);
+ }
+ catch (EngineException e) {
+ throw e.add(env, function.name, getExecutionLocation());
+ }
+ }
+ ...
+}
+
+```
+Код за изхвърляне и „обогатяване“ на JavaScript изключенията
+:::
+
+### Защитено изпълнение на кода
+
+Другата част от системата за изключения е режима на защитено изпълнение на код. Той позволява улавянето на хвърлени от дадено парче код, както и обработката на дадената грешка. Режима за защитено изпълнение има три часа - тестова част, част за улавяне на грешката и част за финализиране на режима на защитено изпълнение.
+
+Първо, тестовата част (`try`) се изпълнява. Ако тя бъде изпълнена успешно, програмата продължава в нормалния си ход. Ако обаче тестовата част хвърли грешка, кода продължава в частта за улавяне на грешката (`catch`) се изпълнява. В рамките на тази част кода може да вземе стойността на уловената грешка и да прецени какво да бъде направено според нейната стойност.
+
+Частта за финализиране на защитеното изпълнение се изпълнява след като кода в предишните две части приключи своята работа. Ако предишните части върнат стойност, хвърлят грешка или направят скоко извън защитената зона, частта за финализиране се изпълнява преди изхода от режима да бъде направен. Ако частта за финализиране излезе необичайно (т.е., не завърши изпълнението си в края на частта на финализиране), изхода от частта на финализиране се използва.
+
+Няколко защитени зони могат да бъдат вградени една в друга. Тогава, ако вътрешната зона излезе по някакъв начин, външната зона обработва този изход като гореописаният начин.
+
+В кода, тази логика е описана чрез стек от класа `TryCtx`, който описва състоянието на дадена защитена зона. След изпълнението на дадена инструкция,
+
+За имплементацията на `try-catch` обаче е нужен по-сложен механизъм, за да бъде запазена възможността за изпълнението на JavaScript инструкциите една по една. В основата на механизма стои
+
+# Ръководство на потребителя
+
+Въпреки че не са част от тази дипломна работа, допълнително бяха разработени три библиотеки, които ще бъдат използвани в част от примерите:
+
+- Компилатор на JavaScript към междинния език, описан в [@междинен-език-и-неговото-изпълнение]
+- Имплементация на част от стандартната библиотека за JavaScript, на JavaScript
+- Интеграция на Babel за поддръжката на по-нов синтаксис
+- Примерна имплементация на команден ред за интерпретатора
+
+## Компилиране на проекта
+
+Можете да изтеглите кода на проекта, като и всичко нужно за компилирането му от приложената флашка (в директорията „j2s“) или от Git репозиторията . За компилацията на кода е нужен следния софтуер:
+
+- OpenJDK 17 SDK
+- Gradle 8.10
+
+След като софтуера е инсталиран е достатъчно командата „gradle build“ да бъде изпълнена в главната директория на проекта. След като командата приключи своето изпълнение, проектът ще се е компилирал. В директорията „build/libs“ ще намерите всички изходни файлове. Тези, които са по-важните са:
+
+- j2s-common-0.10.9-beta.jar - Общите за интерпретатора и компилатора компоненти
+- j2s-runtime-0.10.9-beta.jar - Интерпретатора
+- j2s-compilation-0.10.9-beta.jar - Компилатора на JavaScript, виж [@допълнение]
+- j2s-lib-0.10.9-beta.jar - Стандартните библиотеки и интеграцията на Babel, виж [@допълнение]
+- j2s-repl-0.10.9-beta.jar - Простият команден ред за интерпретатора, виж [@допълнение]
+- j2s-repl-0.10.9-beta-all.jar - Комбиниран „Fat Jar“ на всички гореизброени библиотеки
+
+Ако не искате да компилирате проекта или нямате възможност да изтеглите нужните инструменти, на приложената флашка, в директорията executables“, има всички гореизброени файлове, както и Java 17 среда за изпълнение, за да можете да изпълните проекта. Изпълнимите файлове са налични също и на уеб страницата .
+
+## Използване на проекта като зависимост в друг проект
+
+За проекта е налично и Maven хранилище, достъпно чрез URL адреса [https://git.topcheto.eu/api/packages/topchetoeu/maven], в което присъстват всички компонети на проекта.
+
+----
+
+### Maven
+
+Първо е нужно да бъде конфигурирано хранилището. За целта, добавете следните редове в „pom.xml“ файлът Ви:
+
+```xml
+
+
+ topchetoeu
+ https://git.topcheto.eu/api/packages/topchetoeu/maven
+
+
+```
+
+След това, в `` вмъкнете следния код:
+
+```xml
+
+ me.topchetoeu.j2s
+ [нужната библиотека]
+ 0.10
+
+```
+
+Като на мястото на „[нужната библиотека]“ въведете името на нужната Ви библиотека.
+
+### Gradle
+
+Първо е нужно да бъде конфигурирано хранилището. За целта, добавете следните редове в „build.gradle(.kts)“ файлът Ви:
+
+```kotlin
+repositories {
+ mavenCentral();
+ maven {
+ url = uri("https://git.topcheto.eu/api/packages/topchetoeu/maven");
+ }
+}
+```
+
+След това, в `dependencies` блока вмъкнете следния код:
+
+```kotlin
+dependencies {
+ ...
+ implementation("me.topchetoeu.j2s:[нужната библиотека]:0.10");
+}
+```
+
+Като на мястото на „[нужната библиотека]“ въведете името на нужната Ви библиотека.
+
+## Изпълнение на командния ред
+
+Изпълнението на командния ред става чрез изпълнението на „jar“ файла „j2s-repl-0.10.9-beta-all.jar“. Това може да стане чрез следната команда:
+
+```sh
+java -jar build/libs/j2s-repl-0.10.9-beta-all.jar
+```
+
+При изпълнението на файла ще се отпечата следното съобщение:
+
+```
+Loaded babel!
+Running j2s v0.10.9-beta by TopchetoEU
+```
+
+В този момент командния ред очаква да бъде написан JavaScript код. За жалост още не се поддържат команди на повече от един ред, но може да използвате командата `dofile("име на файла")`, за да изпълните даден файл.
+
+Освен добре известните стандартни библиотеки са налични и следните допълнителни глобални функции:
+
+- print - по-кратък еквивалент на `console.log`
+- exit - прекратява командния ред
+- measure - приема функция като аргумент и печата на стандартния изход колко милисекунди е отнело изпълнението на функцията
+
+Понеже командния ред е с вграден Babel транспилатор може да се ползват по-нови конструкции, както е показано на фиг. [@babel-usage]
+
+:::{.figure id=babel-usage}
+```txt
+Loaded babel!
+Running j2s v0.10.9-beta by TopchetoEU
+
+$ class A { a = 10; b = 5; printme() { print(`{ a = ${this.a}, b = ${this.b} }`);} }
+undefined
+$ A
+function A(...)
+$ const test = new A();
+undefined
+$ test
+{ a: 10i, b: 5i }
+$ test.printme()
+{ a = 10, b = 5 }
+undefined
+$ function* myGen(b, e, s = 1) { for (let i = b; i < e; i += 10) yield i; }
+undefined
+$ for (const el of myGen(0, 30, 10)) print(el);
+0i
+10i
+20i
+undefined
+```
+Употреба на по-нов синтаксиси, с помощта на Babel
+:::
+
+----
+
+## Внедряване на интерпретатора в проект
+
+Основната цел на този проект е да служи като внедрим интерпретатор на JavaScript в други проекти. За да бъде внедрен в проекта Ви е нужно да добавите зависимости към `compiler`, `runtime`, `common` и `libs` (за инструкции използвайте ръководството по-горе).
+
+### Създаване на среда за изпълнение
+
+За да бъде изпълняван какъвто и да е JavaScript код е нужно да създадете средата за изпълнение. За да създадете средата, изпълнете следния код:
+
+```java
+// Събитийният цикъл, който ще използва средата
+var engine = new Engine();
+// Средата, която ще се използва от интерпретатора
+var env = new Environment();
+// Пуска събитийния цикъл в отделна нишка
+var thread = engine.start();
+
+// Регистрира събитийния цикъл
+env.add(EventLoop.KEY, engine);
+// Добавя стандартната библиотека в средата
+StdLib.addGlobals(env);
+// Регистрира нормалния JS компилатор
+env.add(Compiler.KEY, Compilers.jsCompiler());
+```
+
+Ако искате да регистрирате транспилатори, може да използвате следния код (имайте в предвид, че тези функции създават нова среда и нова стандартна библиотека за всеки транспилатор, за да бъдат изолирани от останалия код.):
+
+```java
+env.add(Compiler.KEY, Compilers.typescriptCompiler(Compilers.jsCompiler(), env));
+// или
+env.add(Compiler.KEY, Compilers.babelCompiler(Compilers.jsCompiler(), env));
+// а може и да бъдат комбинирани
+env.add(Compiler.KEY, Compilers.chainTranspilers(
+ Compilers.jsCompiler(), env,
+ Compilers::babelCompiler,
+ Compilers::coffeescriptCompiler
+));
+```
+
+Накрая, за да се изпълни код, той трябва да бъде само добавен към събитийния цикъл:
+
+```java
+engine.pushMsg(false, env, new Filename("test", "test"), "console.log(10 + 5, \"this is from the JS Code\", Math.pow(10, 5))");
+// 15 this is from the JS Code 10000i
+```
+
+### Работа с JavaScript обекти
+
+Работата с JavaScript обекти е лесна, трябва да бъдат използвани само описаните в [@имплементация-на-javascript-стойностите] методи:
+
+```java
+ArrayValue doInterestingStuff(Environment env, Value input) {
+ var obj = new ObjectValue();
+ obj.defineOwnField(env, "test", NumberValue.of(10));
+ obj.defineOwnField(env, "a", StringValue.of("fsadf"));
+ obj.setPrototype(env, (ObjectValue)input.getMember(env, "prototype"));
+
+ var arr = new ArrayValue();
+ arr.set(env, 0, obj);
+ arr.set(env, 1, new SymbolValue("mySymbol"));
+
+ return arr;
+}
+```
+
+Често ще Ви се налага да създавате и Java функцкии (трябва да правите такива функции с повишено внимание, понеже те имат неограничен достъп до Java средата на изпълнение, което може да означава че зле написана Java функция може да компрометира сигурността). Следния код е пример как се създава Java функция:
+
+```java
+var func = new NativeFunction("myFunc", args -> {
+ var a = args.get(0);
+ var b = args.get(1);
+
+ return new ArrayValue(a, b);
+});
+```
+
+# Заключение {.nonum}
+
+В настоящата дипломна работа е демонстриран интерпретатора на JavaScript, написан на Java. За да бъде създаден, беше направено проучване на съществуващите технологии, както и методите на интерпретиране. Беше отделено и голямо внимание на добрата и проста архитектура на проекта. Архитектурата се развиваше заедно с кода, докато достигне до днешната си форма, като не стана заплетена и ненужно сложна. Интерпретатора беше тестван най-вече ръчно чрез сравнение с държанието на V8 при същия код, както и чрез трите транспилатора „Babel“, „TypeScript“ и „CoffeeScript“.
+
+В крайната си форма, проекта може да изпълни всеки JavaScript 5.1 код правилно и със задоволителна производителност (зарежда Babel и CoffeeScript за около 5 секунди, като повечето от това време се отделя за компилиране на кода) и е относително лесен за внедряване във вече съществуващ проект.
+
+Въз основа на всичко, казано дотук, считам, че целите на дипломната работа са изпълнени, а с описаното в [@допълнение] - преизпълнени.
+
+В бъдеще може да се създадат няколко класически оптимизации, като например:
+
+- Кеширане на достъпа на полета и използване на „фигури“
+- Динамично оптимизиране на междинният код
+- Цялостни оптимизации на алгоритмите
+
+# Допълнение
+
+В тази глава са описани другите два основни проекта, които вървят „ръка с ръка“ с интерпретатора, а това са именно:
+
+- „compiling“ - компилатор на JavaScript към междинния език
+- „lib“ - стандартната библиотека на JavaScript, както и няколко популярни транспилатора
+
+Описанията няма да бъдат толкова подробни и изчерпателни, предвид опасенията ми да не надхвърля разумните граници за обема на дипломната работа.
+
+## Компилатора
+
+Няма да се отдели особено голямо време на компилатора, понеже е изключително прост, не особено ефективен и генерира неефективен код. На кратко, компилатора се състои от две основни части: четеца на кода към синтактично дърво и компилатора на това дърво към междинния език.
+
+### Четец
+
+За прочитането на кода се използва рекурсивно четене, където се дефинират отделни методи, които четат различни конструкции. Например за `throw` конструкцията би се дефинирал следния четец:
+
+```java
+// Пропускат се празните места преди символите, които ни интересуват
+var n = Parsing.skipEmpty(src, i);
+var loc = src.loc(i + n);
+
+// Ако не се намери "throw", четеца сигнализира, че не е разпознал конструкцията
+if (!Parsing.isIdentifier(src, i + n, "throw")) return ParseRes.failed();
+n += 5;
+
+// Рекурсивно се обръщаме към четеца на израз
+var val = JavaScript.parseExpression(src, i + n, 0);
+// Ако не е разчетен израза, се хвърля грешка, понеже сме сигурни, че след throw следва стойност
+if (val.isFailed()) return ParseRes.error(src.loc(i + n), "Expected a throw value");
+n += val.n;
+
+// Шаблонен код за разчитане на края на израза
+var end = JavaScript.parseStatementEnd(src, i + n);
+if (end.isSuccess()) {
+ n += end.n;
+ return ParseRes.res(new ThrowNode(loc, val.result), n);
+}
+else return end.chainError(src.loc(i + n), "Expected end of statement");
+```
+
+От своя страна пък `parseExpression`, въпреки че е по-сложен четец, евентуално може да разчете функция, която в тялото си отново да съдържа `throw` инструкция.
+
+Един от недостатъците на имплементацията на четеца е, че не се използва токенизиране, което го прави значително по-бавен. Така беше направен четеца, за да бъде написан по-бързо.
+
+### Преводач на дървото
+
+Преводача на дървото не е нищо друго освен по-сложно двойно обхождане на дървото, което се получава след прочита. На първото обхождане се инициализират функционалните области на променливи, като се започва от най-плитките функции и се приключва в най-дълбоките функции. Следващото обхождане компилира самият код. При него, компилацията започва от най-дълбоките функции към най-плитките. Това се прави, за да бъдат правилно уловени и разграничени локалните от уловимите променливи.
+
+Всеки клас за елемент от синтактичното дърво съответно има следните три основни функции:
+
+- `compile` - Добавя съответставщите на елемента инструкции в подадения `CompileResult`
+- `compileFunctions` - Използва се като служебна функция, която да позволява компилирането първо на по-дълбоките функции
+- `resolve` - Дефинира в подадения `CompileResult` променливите, които елемента декларира
+
+Целият компилатор се базира на основната функция `JavaScript.compile`, която взима входния код и връща инстанция от класа „CompileResult“, която съдържа служебните данни по време на компилацията, картите с местоположения за всяка функция, както и самите компилирани функции.
+
+### Четец на JSON
+
+Понеже за имплементацията на JavaScript стандартните библиотеки е нужен и JSON четец, основната логика за четене беше отделена в класа `Parsing`. За JSON четенето беше създаден отделния клас „JSON“, който е отговорен за разчитането на JSON текст, както и превръщането на JSON обект в текст.
+
+----
+
+## Стандартна библиотека и транспилатори
+
+Компонента „lib“ се състои от целия код, нужен за създаването на съвместима със уеб стандартите среда за изпълнение на код. Тя включва стандартни библиотеки, транспилаторите „Babel“, „CoffeeScript“ и TypeScript“, както и дефиниции за буферни масиви (`UInt8Array`, `Int32Array` и т.н.).
+
+Създадените стандартни библиотеки покриват базовите глобални обекти [@refs-mdn-globals]. Имплементацията не е пълна, но покрива нужните функции за изпълнението на включените транспилатори. Библиотеките са написани на TypeScript, но се компилират до съвместим с интерпретатора JavaScript чрез „Rollup“, като стандартната библиотека, заедно с потребителския код, се изпълнява чрез интерпретатора.
+
+Включените транспилатори „Babel“, „CoffeeScript“ и TypeScript“ отново се пакетират чрез „Rollup“, като само е създаден код, който да свързва транспилаторите с интерпретатора, както и код, който да разчита картите (Source Maps) на кода. Интерпретаторите могат да бъдат използвани чрез предоставените методи в `Compilers`.
+
+Създадената система за добавяне на интерпретатори от своя страна е създадена такава, че може няколко интерпретатора да бъдат „наредени“ един след друг. Това позволява изключителна гъвкавост, както и допълнителна изолация на средата - може код, който използва компилатор да дефинира собствен компилатор без да знае за компилатора, на който е базиран.
+
+Освен кода, за изпълнението на TypeScript кода са включени и типизации на стандартните билиотеки, описващи специфичната стандартна библиотека, дефинирана тук.
+
+За да има достъп кода на стандартната библиотека до някои вътрешни функции на интерпретатора, беше създаден и класа „Primordials“, който създава набор от функции, които могат да бъдат използвани за ***незащитен*** достъп до иначе недостъпните чрез синтаксис функционалности.
+
+----
+
+## Дебъгер
+
+Това е втората част от „lib“ компонента. Той използва `DebugHandler` механизма, за да прихване различните събития на изпълнението на кода. Специалното на дебъгера е, че имплементира V8 протокола за дебъгване [@refs-v8-debug-protocol], което означава, че дебъгването на програма, изпълнявана в този интерпретатор, е възможно в инструментите за разработчици на Chrome, както и във Visual Studio Code.
+
+
+
+# Използвани термини и чуждици {.nonum}
+
+1. Дебъгер - инструмент, чрез който може да бъде спряно изпълнението на кода и да бъде изследвано състоянието на програмата
+2. Компилатор - програма, която превръща програмен код в изпълним файл
+3. Интерпретатор - програма, която разчита програмен код и извършва действията, описани в него
+4. Среда на изпълнение - съвкупността от конфигурации и системи, от които изпълнявания код може да се възползва
+5. Изключение - специален механизъм за сигнализиране на грешка по време на изпълнението на програмата, който присъства в повечето модерни езици
+6. Инструкция - единица от данни, която дадена програма може да разпознае и изпълни по даден дефиниран начин
+7. Междинен език - език, който не се използва за писането на програми, а към него се компилира език от по-високо ниво, като междинния език вече директно се изпълнява
+8. TypeScript - транспилиран към JavaScript език, разработен от Microsoft, който „надгражда“ синтаксиса на JavaScript, като добавя силно типизиране и няколко нови конструкции
+9. CoffeeScript - транспилиран към JavaScript език, който дефинира по-различен и компактен синтаксис от JavaScript
+10. JavaScript - по-популярното име на езикът, дефиниран от Ecma 262 стандарта
+
+# Използвана литература {.nonum}
+
+1. V8 Виртуална машина за изпълнение на JavaScript код - {id=refs-v8}
+2. Пазарен дял на различните браузъри - {id=refs-market-share}
+3. NodeJS - {id=refs-nodejs}
+4. Deno - {id=refs-deno}
+5. JavaScriptCore - {id=refs-jsc}
+6. QuickJS - {id=refs-quickjs}
+7. Производителност на QuickJS, сравнена с други интерпретатори - {id=refs-quickjs-benchmark}
+8. Rhino - {id=refs-rhino}
+9. Кратка история на Rhino - {id=refs-rhino-history}
+10. Nashorn - {id=refs-nashorn}
+11. GraalJs - {id=refs-graaljs}
+12. Truffle - {id=refs-truffle}
+13. TC39 комитет - {id=refs-tc39}
+14. MDN Уеб документация - {id=refs-mdn}
+14. Еcma 262 - {id=refs-ecma-262}
+15. Компилатори - {id=refs-compilers}
+16. Междинни езици/формати - {id=refs-il}
+17. Компилация в реално време - {id=refs-jit}
+18. Gradle - {id=refs-gradle}
+19. Статия на Gradle за миграция към Kotlin DSL - {id=refs-groovy-old}
+20. Играта „Minecraft“ - {id=refs-minecraft}
+21. Програмният език „Java“ - {id=refs-java}
+22. Алгоритъм за стриктно сравнение на JavaScript стойности - {id=refs-strict-equals}
+23. Алгоритъм за „хлабаво“ сравнение на JavaScript стойности - {id=refs-loose-equals}
+24. `new.target`, т.е., оригиналният конструктор в JavaScript - {id=refs-new-target}
+25. Типово преобразувание - {id=refs-type-coercion}
+26. V8 дебъг протокола - {id=refs-v8-debug-protocol}
+27. Глобални променливи в JavaScript - {id=refs-mdn-globals}
+
+# Съдържание {.nonum}
diff --git a/doc/text/img/debugging-example.png b/doc/text/img/debugging-example.png
new file mode 100644
index 0000000000000000000000000000000000000000..0811052d4c69d1ab92e06a243cee892a338a151b
GIT binary patch
literal 98441
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%0DlySyxD~Z?xq25`S)Nx_<2b;8_FD
z8t{bkEq8*4763P`U?Yv^gYObP^NTZcFNtF3grp3NuEYCCl4;odoRhzHyx*!dTq#9Rb^A=Fn3x=UVZnDuon+@dkd2_9oiMcE3Cwg(f+y-g|&pPH~NV
zOkz(YZS~%q>r(^X;vBKbfoSwWIrziJ$;>R@;!GYc#J<{R;aM(>R23fks8
zv$xXH;Iuq#l?D3uc#=eA9HEAi%PR(mjAR@OX&bG338!XRasVn6QQn1aMTJra0>RnW
zB*h1!-W-eY2QF5aosE&d0>lhf?jSu@4A8f@5PEI(TjY33y`@^V+V)k8m&F_>L#^|~
zpKV$hQt|Cw6+(ze!tHy7j!dR}%j0_Pgdh6xzSTqWle<4&jEA6-b6xl$68!Cbf$k7=
zdguJ#Pgp}zVI)vau;Q8m!}Wgw;JD@3csf*~v7{7_=EF|_aS?+lneI)Wq71U6n7C0^
zo%f}LezBvAHP#EEz!gD$p31)x6MRMc(_nc91jnjDy7k~D$=(wD#ZS`TUYf>#E5PojiN#8P34ia0Z@kV|3m@+)(rX
zAaC`)!ixZsT3hV!39D>4++;?6WGBJjT@}h3xdi|(es*~?JI>f16YQ_n?2(+`Pq6Te
z?U{<|Hl2@#ZnU37d#p*h?u7(fI0J;3hgzy4FfxzEknztBG_!=w4q@g)rFig?!O
zTRt*8)M>^r{!4h~x
zqdh^FUWG@*2aq@h{o^T#y--&q(L}dk^yqs>%i;hi^X6;va!K%NgvH4q&C8pfqnd7$
z&ai;Xg}0teUydinr}`bg_EA@xiio4eH|+cHj5<|EP(on6&KW!_=*V((%shh_?0e+h
z-Hx-qN5$H&E@NZ{S&>tpa4HE)s=}q@Zrmu02P!0X3nmvbr1SEF=D3&_xpCUzY
zWZ~uH9PaNN#tQPA(Mk0VUR0r_dg-PmhNvbcm2`vIgvFq!dvzEV}0@Yr>mE|N1Xct1gX4elZYOv++W|*xu@5qlKFE2Z$$v{dlc4p
zS7xh2|5-)+iER(z!w-G_X$WBe6J36XwIF0#!hPHKYSG9a_1DDi&7
ziK=d4=;>f8lg8tfvEuxE
zCDfJoD)W}{v66ED9{0iiBleborJ+f&npq3A0sgaJ={GVyG1~
z7NmRjVk<$R!y%Tc&-lk-iGPivBv4zdUshj$NYWq4CLJ3qOR@N9qn(>d<#0mRK8}Nn
z9RqcBVSVtNaB?>~NlE>bw}R{~B}(J^5wmGJ%VaArO2giVBpP5_C6E))*br`(0}2I?IzZ4L_KI>)XN}c>KiFCeA4R)}+UtkGywVp$y6`r{uH3+k)RR&@
zybt{;zDS|E$(%we=PkD1=filK@JAGfnxUZB4ykTub?ua55}Bz-Fn9wNV7bVHA{fl|
zUo{J;Sy=PwMZ5E{dTQ{L1@EvG6iq+Th#q2V;?Yi>iGzSp+2Cw&I9pF1`kRC+yn(!K
z*DOI;N%R%Ow@~GL#raoAc@2$_
z&Q6~o(tmYT4)&@!J|4eT`L)JczEfXw6Kp*g-zGh-!$q?H;b?Adovyc3bL3ioMxrRa
zva|2ecJ^i0>jqcc*`cJS%Vr`D^;(U}I$=Z>N{=EzLPC0bdy_B0c`hpvH(VWrZ~oAu
zroemV$n?C!V~3izb?)|tW2m|>%CAr&CggPocn)#s?p*vU`
z&dOg{y}yrAm&*G@QXD-2l5PgBe9Y#3OTaHAGzFqw4X5%OT1`m1yklLYFhmg9%n#?(
z+aYb9X-f&p5EAH^+UYG}xtoENeK=wEiQc|&UvGb*S+jiGE90`
z5}&iN=GG6cGlvb2a(tlxFosYx=FvROr#~P!n;IAc*}?go9Z+sln<;`YHnUN&2~Pr{
zvr7ENn$m^I(N!LES*F-MzxTE-hLgt?UJqWF#aJ+jS|5E``xz`6bVq
z*a5)geAuDQ%boTOll0;AGUpOIYX?hf;f%EQWbNMnH&WOB93moS!!Y$U52@I4CfW*{=Hy!#D@TQ3Y_%_M9?I>Yt?bNH~3r+h-@*;F*99>3mL!T^5~0yLzX
zo12<6NGm3##f*hOfdA@D?~)iyKp&V>oo>77k}ezHJ0+MsByc7ozT?H)cpK)#Zc$Z_^g#Mmkw@7XUkv
z7o%~|b62%`&4V*syBb^k9&I=tyf<8abwR?a=lQ`Il)@au|C7L08s9(r!d~n9=37-9
ze#96(IH|y{t%(sk=9&(x`oOr!L-6d`J84Q?fl=N?b~t_+2{7nVq693TDDLX3uPbiY
zP%*@2v=a7id{1Sm!EhthHNF!wyDWhyFh%{Qv`bq#e3&^d1acneQ@FlHlwRPMK5yH9JZgk{c5OXMaq^)t6v>A&u`r
z{RpC$EbpIT$-}Ou6~JI|ohZ#jZ~UB_8KYt)>a^>CF>bwuLrMxVI?)`6+Cu->9Xwhk
z-0e>FkbhcjZL6(s(~Tv&S6YP%4fNza|5IsorMv65SWOYUc`kVNj{Y4%|X^ck7GM`>Z~;G)LutctMokT`5i9Gl~QW
zg_T-Q;EhW?l-)((r-w-@requoLqunsPwsrZ8=^DMPvMEh>p`(B#>{;eMwdGNd)$Qk
zGD$LDuyQdrBg4DDf7`6Ou6}1nRCT7lbSX2>NVX`M?&!q!H3wVb()$lk)CtAC+Y(L3
zwO)78x7PJ-dKKGZbubiD*Tl*5ourQPJ#9BqF6xK4o`kN@hie?0=tHgHT5*0J>7s(_
z_G!+R_$>wzD9APJq$`<2HQaJ@JB&Dc%*TidT&BrE@Jx|UPKBB3?CVC`t_+aZ7+T1p
z!0D)tiy={7+mfWVsRplpVYjXRHWV(#zV3s2y{%mV{Xk)D?WXqTQx4mQK=C5-cayaV
z9f0jmgCdvl#4Nfdvvc*adK&^NnIwf=PHz52I1VLoZ~shX%)+_jDGeFrIy`AbmUMAya|1}IFp<(ytE~jC&eWby;+LB)yn})WwPwsv+!Y9vK6kQ0
zv~S?|29PJAAPz*F7F%T%v(<$s>!fScmIr305;*h3Njh*DN=72@)GTbf+^YU4S75i!
zc6v28*yST#IIEfNSznKl
zcmP3h{V<~tlew7_kxea2j_kz+E^qJ|N2sq)0%20K7q|mQMHS!FT(ouO>Q{?Mt6DSp
zYE;tWtWoA^+Ukl*6kw=i#_;LE^e8y{Zovqpmgx7Gb7mer9j#82{eb0L{poV+?~JyO
zE-Q-FiP2Gh@{TY3lVdRJ8ZTlPa(q7xdOMx+=Dnu~#v>aOc5Xiss_fQ1lud+dFKb1F
z$G!ZBP}do4%+1QGJNA+;T@R6nr^z*wel1kxivn66QP(;xzD=NuhHvtY$Z6qFsLiNr
zfPDM6^g6*-M(_(^)9z~1{W)3c1-+mmusRG`j)nWi69-Zh!%e>yE{D@J5)xs7E^8Fn
z?x1I^evgH0zqPGOs1%nPR9tdUx?18XTM&>+s=OQmAfs!^p3G3})TI5h71#L6=-_v=
zo!PrPBKs8@tH*Z6m
z?Ujl^EYyao8+EdR(H$wK=>`Xl#s|IyoidI1=npR!J?hH*pZl#F2%0gIF9_E;vI*Q0}^4t5m{FabJaiQDT?}`2o*1K#i~(gK+D1
zowal&@KSn-By}k$w)Bt%J#SL%(Ny7vgZfw;
z`dAy|>XcRUXwcAdSdnb@-SuHV2
z)haK}7(kqQlKOjmA%c%CM&oWsS#bmPYwS1%83QwewaQ6tFz@VS&3PM6SQ@2MPu&&stm<-feq
z!_Ap-Ijjfqo5Q+WVZvu7QxX#kYWwbOf_!Dc583cPhn_+Lpq7_j-;waBDsGzqV8mo{
zMrJOMl7O$pK@HXCKiSHcZ{&j?Hr(C=g1(etG^c^DC1b&)@9K;qPHGZmRE1N@h-MUx^&HBeWEaMNJ=%<<
zeA%(hR5V~Up$zHMEK{OlAC!xXf7HE!dOV~yLdk6Jnq-L;MzgRW-bp&<{p-DQZMuX`
z`8OR_o5RW;S-I6KJk90?G(IdytNiaMINaLaWWgPubqNDwACrk=rOpsBA86<#ac!^Q
zHp!_^FIn}aSJ+E1>mjbv_=I)H<$DuXq_0VQl3MS()$DE`nS}Dnts!Iqz*|ga;}LPs
zJNaZw65~@vHm_#i@7z=8`oIP&a3BsXl`)5p7CRC{Y>gw;=;A&bFWNYQNx6HJzzZNq
zF(H!7L5BI|NPOf1!P^1El+U;P9{keE6V{GX+EU0$M1BNu`e=_p$fQ&rE{h%CA
z{O^$sc@D({wB;1k-6o7m2~`Q3s9c;yVOI>UAj)3Epz@PxzCwkod4-xOeBCRnL9`daDLvCd=08YVUmR6kEc
z|D(H@c8l{yIJe#2df_?KrNw?R$N!f*HAXOCA?)q%>oER3(FD*)El!sU$M$vkIZn1U
zfFT1DuiB`b+-VXkz2S~~g*eWuIx`m+7f?Eab8EZocesQ$tD4lAATcLGw$?8vhuMd<
zxWl|(dfz-xd6iwwa8pwVT9A9XIX%DQ?9Ij!t;6UysD9A5v)bdTzBZHYh~DG*b_Nlu
zwni`kuv;S-!S3$i^?&^EDJj`PFa@C=yh+9w%_(OOqrfLB#5w*0=Y
zK&Vy~y_;iJJDJxv)GsvN&#yFUmM@ghE~##oC|`>de^!G5Htro-dDq7%uTFK+MO9i~{f`7;L@6~T-fbz`D&H4rGY=xJ0+4l@!s}Vg
z$fH?-Xsdiy)Q2cv@xkwditu}$vtx*B~?acV_e8y@s^?5u2TGfPXers>dZ?XLPlfN>dd?YUaYu;pA{#l=iqPwGwNM%HFXKH@#d;v?d;gPY?AOO21*A@aELr~#RtyU88
zf|4xw@j3HflkhTODW*zTpDf?xDd+HLxC4e)9`q;V&Ij{A54TSNJJ+s7HYM9;`;2P@
z^r{~mgvMxUG|iD+sABrcJTF~8A#{w-*4zA1$A8iJ+tNhjKCR1ftUw_D7#JTFXKEW1
z6KkOhCkwd39s%$>d(@iKeCsqosa5%s6i)?VNXBTH7OJF&=GJadF?)O$B0Q+J1GX8`
ze`?QyYu+ICmEW35;9m5tH>=@JP)t)K=IOmKS-vqcjo#VNp+DAjJpSn1IO&8N#Dd93
z%_7@ku9XxS;(vKde=hKXF*{eA@?WfV%@zW@=1iy$sMJ2x9#%y}H}a0`O?ft04PUN_
zC-yu|b2+YDO9#jNT_u=Ak?-yapmgns!uRUt`ecdgScbWDl17?JrJMvj*55;0pBo51
zAQD&mpA>eJ*xadB;awoAT3zXvDQh{_)#t6vDm05tR2?wf_Jb&Gi%5R#POeo0%o4+J#pY4?95HeEkAnT>yNhS#fgF9=GNr+9aCz6&`}dxt>!@gD8)Kuhr#+n=sljZb
zQfF2aV~As6c)#Ae@~j`E>i$2xy=72dUC=EE!4lkp6N0}y`02sC?
zr0(^^>!tN4?0q#aL62kYzM3?IyXUP59qd4KqYDO*4x{bIRI~m#WaIrFkz;nEb(Jsl
zRItZ_Ou!D2#)!TFTE;>NtZkE8rw8GQ?VK*NBU>HbI=u2o`$`AnI2mut^$-&u7Lc@>
z>(bw&ri4AbJHNK-TTT>Nlo>dgc_q=L4ysMmfgnajG*Z1|qUr{Jnn
z+BAE1^t6?lV|oQRZ+*Dx9+`H?2s97DP`0ujFQi-!t=)*amRv~Fdok4;oFfBOm$QuT
zLbmg3GuhVHSFP4@xghcC(zh?R1J2eyRBws$OboIYO1*YY-4!+0Hy)!e_%yw%>tbUG>OQ5o(fW1`N-(=iZ*wq6lx
zMHU`j*e}z4Pn(V$-u@I2l+oL=yk7&K@P;tjhG?cZ1kYPavn2}*x+lNvme8xo)cpBG
zCM~a|TbNgP?OG*K+WNP{{qf6nzdK
z8%r6=WSHEd>fk}uWc;kkhFyzjq81_;SlxwKAqF3QNwPXQ<<=B%}w06I;7IozIcDhl2kK}Tc1yY
z;3C=AFg=Vl3P=I^%Fl&E%~Iel_=4#u7<+c0};$jv(=AK
zpy|s1VT~{p=KP1^mttxDjgS`;GfO>pf5#+d;^z_>sCA(^!&+zo
z&Yr4(ktSr97e~4kI+XM`i}gf}L=oVVd6`DE1bLyheBahT-C!=xfyvzfKO6emXnjbp
z2Gd-hJ%O1hh|Lk}5BiGGAFwh~9^=!@
zp$g-V7S=#C2+JU3W|mrbZnPGML7&=)WZPCj$l-aTNOiaOZ62v@MhHA04wJRI4eLxT
z#TFA}CqYNk&eaKba?Oo?yn^t_us9wWX-nRy=GJ;LXt*naRajnbvW{ziA}k`}HiWIy
zS+8j?)qLTPVOT>qupa0|<2_lC*0PmL#G)`|CcmpRf3(a7h7p|OBnCSQH+|TI|LO)(
zk7{9_1>>r0XTb19H_x=5`CcvkK%S0+%l9Vv5-=!PW!?)I=R%>vSk#zc`N`{hM8G;ru?6#1fE?@06Kb>5JOx5XnXEPYF+3kSy9f;CHt=64~(qfb$J_H|lb-nMm$c;El4yHda(jHnSNXl+L7dzjLjJ!19
zU^F_Ym)`8-XnrSqdbTF~+1lPhXGmn(H~QP&^;VXw93>Vyv^$H)~F&i4S#A$WNuzJt_`Mv^fi;sK3?Xe*LLo_0?w@Wbj_LzZ2
zq1SjJZEJX)K8h3t{kluwmuVwJ9FWLBf^aCEt&6}2)zu$80wa&T-To!7vgF40xAylS
zEN1iCqi5XAt1^q&qsRrkuh5sE`IdnB+R1WWTPE;#%H8V`8|SwO&v2v
z&zQjx3WxvB$$>7cSzrCzO#-hI+N-j4poS9IL8J@vsdBl;F|N7cBJ1|kG^6>z^Yz#G
z+4|g&w#Y_Q?-k>qlDYN~bY6GN(GzB>#;4EA-tRL_byXek{ZJ?FCt!D=WTXt6`^R4Z
z?w=N{Gj70g{U^T{U&cp1ucr)%@B_fF>$*g+-Yy5bgW(z=Ke~HQ@XR{xwzwp<*&1)s
zTZ9RxP8pw6sF$V|>G{pbk1gDJFlj>8H}8cK(5U#&u5#lF2=P~5RnXtviW1)~gSYM+
zu`E2#oy6peXNqREN?CkY*EoKEiK^_`l&B_4pvVf=|4v@_2C|@mWy@~S2#Y6cabYFN
zp+%-%&MURYp($RMTfLaLu9iAXUx>>r&w*lNfr{Aa*gZ;LZawTS@R
zIo!022H{^}J!dkvRlsXEwP4a_v3-!IYR&-2gG2D(bzNgb>#!)vW`c+w}1^40g(iXSsi3cxj<#sGiuAaS{ENPq7B^e
zc?*0uZ<+CwRps%v2e;X8J3v+fc$^oAXK3*5P4
zDKju`eWtrg#p!&UAllw7rxp)_$gYi&Rk7WD&SI)RwyWJ?AtCNxrpeD?eHxhVt16Hu
zmQ;l(eZ0Y(PHJbea&v$v6is5hAH$?Av;P7?x!nN>R^40HHg+%{X03h`RUT;C=4wMi
zidGZgLk9k**6}4}p=aosim5zIuUFXdeLu*F3}@;%O{#y3pe+g#S6;fXoAd)O0P`S4
ztL&fD`#p;(^{{aGz&e}#1@!t51~(T|XotFku;3C*+|F6gkrvNroi1d5_+RI@;Y<-CV^lekeqwfiT83Lo#FXo1L
zvdGPQrBew)b{d7=5`NH~6%t5_wVbrI><#@DD?jOh-y7vju&hGYZAoIiYIcVK`YWZ`fSr+G
zyk7L@B+xabE?H*nDP2JutAMP>l^tkC(rwi?an)uWQTk7
za3xmVa@AqqxM#Zh8$u%`R4)$fa;evoI*V6-R3XVtY7lHt7Zsv7?=C!$1t-aNiEViebriFb>ByEf9-x5x2)c2zw^voo!k`e
zq1}C4rzN->X-Eht^&YXF)A?m@})?vc+j7%h~t}NaB4%*uDeWlz3Bv
z{TCfw*U{N;_$A;p2HSt8zp+s5@bD?u;hE^JCkWM%%)R$bWhr|c|3mw}2*V}=*LN%N
zXyMrb#@!vY!G4c4EZxp=7Ln88c=CQMvv3~3=xupMFr++QXyMpTs&cJ{P^mBXr5Iep
zsftFWeH495PZN?m7v4_gJy6F=RR2=ujKtgrtt_l<*O;rC3(kFzg~w$YUkn+~(P1qzB8=~QX9u=PQw>7eFpFT|Pz{`D~cQDCbRO7}%KJf;wjaeH3Z
zq-?bO_em+z$}=f$ua=4pI{!m5IThwLUgAb}?wQxy%!F=m6^ZXgt$9e6E31C2W&F#v
zZOQX=8V6CWfpF#C*v9uCVS%`7@I?q5!lXnK(a#M18f~~?h)MNcq`AI1_-t5dV~j+6
z0w!ckEO&Xwa+qRs&S$%0i>88Rr;0eMeaoe5Ij3QyxTXy&qui|0B+8Y&+DZd^-t9f^
zLEn$hvTXMg!~`MDZDz0s)EYt)(%@7}U{%c=l5uWY?V1^4ggV|JBnTv2pAYvJ6lYaD
z4yjt{;UWmL8gx{93*3C9j9HG{BD(4CthBxCc3YY$OIZ_pua>@CuIK-LKVbH<
zO@R05S$^;7uxg0DF2uXs(x$$~^UiRef^mKBB3+EXLwS4KrZRhbWs9nqv_CK9HO^e)
zdplBLkM)9LH5SxceSt-20~_{oVzpP$pESo!rnq{%Ij{V4_OJ-9B4BX$%H=(enyZ;_
z@wyz=THO&78Y?V0$W7Xn`p~p;?bkaZ9S$x50ma%eSb}g>osEAP=&p7dL51AS#3uQ5
z$NLhVa(%R|s7Dj<*43F>-yC2o-8td$1>f1`tB-cj#wz|C*<_qmO(MMh>agu)Ltz$C
z{&T%Lo7{S_dKXah&y8JQYclCRxisSPthRYrU(e5O5)a&kwv7Rt|3fiYmGyh@C@Ku8
z`}_jXPhx5>_L+_DBss5aZYR|D*PU>t3kYSpvr8Vem@uw8?T><=o|^8juXh&(=T5iU
zSm&#nI)Aw4LsZGS*|6eOYWId!wh2g^6D$rVF=#l0lFkStp`(P7P$e#0z?f9Z5Gf;I
zz@a(~*FHrOvWUq{_QByWi7-6Q?T$n_$li1@zTB+`fGApcg{;3kVXmE-zf^H%F;`mV
z{w>FUt$%Ln>WB{|fr4Y+-Jr9vxi^|?eM7EnZGutQF-TmcPa1%4Ii3|}DId-ePU?Hv
zWsP%bUx$>!8vfRl2dgT$dY$66BFxmW`BmWL7d6>X2iaZ-fo{JY#{}p
z>+#{=`}O}?v`u|td>_duU|pp1WXh7s(irNBXwUSow{0BLl4#3Y+ec}gd!le78=&-m
zNPSu)R3G%#_5^#)yTATidDSl??c_2!5&h>uS6OmEe>aTt;YndzAccz}a68PSz6sdBhKpyytFZdIvXWQq7y{fBf
z(#4WWl8zm7s1@or?QOR1_=b>smVE}-5jca<2x4-+?!Z?_=+Y%LW2cz}c~uAeni`zs
z@Pc}G>$Tn?pj>e~l)ym*n=eV&tS@1Ojyz-lL~2hn^kP4i=pvyJ*z7-X#O~Ba~CMY0?Pw|AdS;
zW$*TaX;GJF*VZ=fg$9ZOL#%j4Lh9crvvg!GLB_)xz?QV#PMP8otM$atQeUmFrg<%i
z4@D|3ZRX~=o&v@~7%+=We$@^LPTe?^aJg^Vn*7LzOkc
zT5$!~Gv~m5STSFH6QD!i(T_V$R7}$kq1CayfaTS~P{`fjoE)*?)8Kte231otn3^ed
z$9hiu94hE_JRn6RpbX;}_bNHZacGxu9x9n-W!R@kvc?
zgDp`)w-lnCq9-;+`VRMgs;VInX;2PhO{aIvr?X!7@0;6{5slFr8!nj$;@4tdH>gG_
zCRN`HL8JBB=!GLqmXmTe6ah3!uXmI`ei0T=r%|qi9Z|`vj}}W7KkqCLR~}2V5bIWb
z2wB2Tig2{oJTlqFCWwt0y{)hm7#w~M<{wDXmgVJ?FUalG22eR9Pt2U_t!ks7wSdKQ
zdylSY+yF`8;ywfOs~M>=(!Uj-r%cX@zy$F8R_+ST-0%_Bbq$DB$*p4#K(2~x7_
zkgA0eJJgQ7@tRU^T2BmNE>DHN>ewHU;rc+}0t3P-Q_Z>ime7@Lk7e+T0$zDrAEw--
zy)rUo-0JN_?^K3PATe-yA!x
zQFDR<_S$OUBbyVQ{vaLVYL_Mcvk(g6{V+JTisW#TgOd=7g?c9x6%XfcixNq(nFvkn
zUlkic-Qji<&~ReDD$Z!BE(9WE?yAjaP_;QRTqhanvSJRbDhgUkTbnWjFxV^)+V9s)Vy9jD+qmJRM*|#^=BMj6Mu0LHBI-4uU=o{5v3w;)&GGSxAmrog+
z!W*^Lup;&(f4_$Dbf-0V>tj9!D>#Yv<7va_n)@{n
zA_K?|B5HB5DUVi~g(|xOvr5e=yH_K_{PH9~bU6G?rb~8Hukf%fzI^Ie@761kV!1L3I(m@$>FT+eCo%kbun?blSkO%h_3t1za&TZu!2V-K
zXrnvcT1<_wpPZOKmVp*1m$tlunOIsH?hM2TB)U9`