Skip to content

Commit

Permalink
Merge branch 'master' of https://github.com/Vereis/jrlscript
Browse files Browse the repository at this point in the history
  • Loading branch information
@osolodo
osolodo committed Mar 28, 2018
2 parents 8d547e9 + 47fc692 commit 3d3e2a9
Show file tree
Hide file tree
Showing 3 changed files with 124 additions and 10 deletions.
16 changes: 8 additions & 8 deletions doc/Technical_Report/Jarlang Technical Report.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@
\includegraphics[scale=0.6]{Kent_Comp_294_RGB} \\
School of Computing \\
University of Kent \\
United Kingdom \\ \vspace{10mm} \\ Word Count: 6,565 (via texcount)}
United Kingdom \\ \vspace{10mm} \\ Word Count: 6,335 (via texcount)}
\begin{document}

\newgeometry{hmarginratio=1:1} %% make layout symmetric
Expand Down Expand Up @@ -107,7 +107,7 @@ \section{Project Results}
\end{itemize}

\subsection{The Jarlang Runtime Environment}
The Jarlang runtime environment is implemented in many separate JavaScript modules, which are processed and bound together by our NodeJS toolchain and tools such as \textit{Gulp}. The runtime is split into three distinct segments.
The Jarlang runtime environment is implemented in many separate JavaScript modules, which are processed and bound together by our NodeJS toolchain and tools such as \textit{Gulp} \citep{gulpGitHub}. The runtime is split into three distinct segments.

\begin{itemize}
\item Erlang Datatypes - Each Erlang datatype implemented as an ES6-spec JavaScript class in its own closure to keep track of private and public methods/properties.
Expand Down Expand Up @@ -303,11 +303,11 @@ \subsubsection{Concurrent Programming} \label{sssec:num2}
As a more detailed example then, of how we are implementing concurrency as far as the Jarlang compiler \& runtime environment is concerned:

\begin{enumerate}
\item Compile normal sequential Erlang code into normal sequential JavaScript. If we reach a receieve block, split the function into three pieces such that we have a PRE-RECIEVE function, a POST-RECIEVE function and finally the receieve block itself.
\item Compile normal sequential Erlang code into normal sequential JavaScript. If we reach a receieve block, split the function into three pieces such that we have a PRE-RECEIVE function, a POST-RECEIVE function and finally the receieve block itself.
\item Assemble these function segments as inline anonymous function calls, passing variables from one segment of the function to another by use of a closure --- this allows us to bind variables from one function into another quite naturally.
\item Modify the recieve blocks such that if no messages are matched, set the process behaviour to the same recieve block allowing us to indefinitely defer processes until a message is matched.
\item Modify the receive blocks such that if no messages are matched, set the process behaviour to the same receive block allowing us to indefinitely defer processes until a message is matched.
\item When a function containing non-sequential Erlang is run, the process runs sequentially until the receive block is met (the PRE-RECEIVE block). Once the receive block is met, the process defers itself indefinitely such that the only thing it does each tick of worktime it gets given is check its message inbox.
\item When a message is matched, it sequentially runs the code coupled with the matched case before deferring again, but this time to the POST-RECIEVE function.
\item When a message is matched, it sequentially runs the code coupled with the matched case before deferring again, but this time to the POST-RECEIVE function.
\end{enumerate}

Via this process, messages can trigger deferred processes awaiting messages to continue execution, and can themselves await messages. With this basic behaviour we can implement basic OTP-like server functionality as well as state-machine like functionality.
Expand Down Expand Up @@ -363,7 +363,7 @@ \subsubsection{The JavaScript AST}
\subsubsection{estree.erl and json.erl}
\textit{estree.erl} is an implementation of the JavaScript AST interface as defined by the Mozilla Foundation (\citeyear{EStreeMDN}) as well as reverse engineering the AST node structure of newer as of yet not-officially-defined AST nodes.

\textit{estree.erl} went through many changes during the course of the project as our needs grew. It originally simply tried to mimic the format and semantics of JSON by using Maps and Lists in place of JSON objects and arrays. This allowed us to easily implement new nodes into our interface but also meant that standard Erlang tools such as \textit{Dialyzer (static type analysis for Erlang code)} wouldn't work as it doesn't support matching specific entries at certain positions in Lists nor Maps.
\textit{estree.erl} went through many changes during the course of the project as our needs grew. It originally simply tried to mimic the format and semantics of JSON by using Maps and Lists in place of JSON objects and arrays. This allowed us to easily implement new nodes into our interface but also meant that standard Erlang tools such as \textit{Dialyzer (static type analysis for Erlang code)} \citep{dialyzerPdf} wouldn't work as it doesn't support matching specific entries at certain positions in Lists nor Maps.

We tried working around this issue by writing our own naive type checker which we quickly realised was not extensible nor a good idea in the long run. We then heavily refactored \textit{estree.erl} to use a custom datatstructure made up of nested tagged tuples. You can see an example of both pre-factored \textit{estree.erl} code and post-refactored \textit{estree.erl} in Figures \ref{fig:estree_old:erl} \& \ref{fig:estree_new:erl} respectively in Appendix A.

Expand Down Expand Up @@ -396,9 +396,9 @@ \subsubsection{Erlang Module Implementation} \label{sssec:num1}
Module attributes are also encoded as object parameters and are ready to be returned and used by standard compiler generated debug functions though this is disabled by default as generally these attributes aren't used.

\subsubsection{Outputting JavaScript \& Other Tools}
Once we've completely descended through the Core Erlang AST for a given module and have successfully translated it into an equivalent JavaScript AST, we simple write the JavaScript AST out to a temporary file. We then spawn a new shell process which calls NodeJS which is a pre-requesite for this project, which then runs our wrapper around an open-source NodeJS library --- \textit{escodegen.js} --- to convert a JavaScript AST into code.
Once we've completely descended through the Core Erlang AST for a given module and have successfully translated it into an equivalent JavaScript AST, we simple write the JavaScript AST out to a temporary file. We then spawn a new shell process which calls NodeJS which is a pre-requesite for this project, which then runs our wrapper around an open-source NodeJS library --- \textit{escodegen.js} \citep{escodegenGitHub} --- to convert a JavaScript AST into code.

In order to make the user experience of Jarlang better and simpler, we also wrote a free and open source package builder for our project called \textit{Erlpkg} which does things such as handler our command line argument parsing needs, as well and compressing all of our compiled Erlang source code modules into one binary file. This is because while there are official build tools for Erlang, we did not write Jarlang in line with the OTP specification which is required for these official build tools, and it was too late into the project to refactor what does work, and works well.
In order to make the user experience of Jarlang better and simpler, we also wrote a free and open source package builder for our project called \textit{Erlpkg} \citep{erlpkgGitHub} which does things such as handler our command line argument parsing needs, as well and compressing all of our compiled Erlang source code modules into one binary file. This is because while there are official build tools for Erlang, we did not write Jarlang in line with the OTP specification which is required for these official build tools, and it was too late into the project to refactor what does work, and works well.

\blankpage
\section{Conclusions}
Expand Down
36 changes: 34 additions & 2 deletions doc/Technical_Report/jarlang_technical_report.bib
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,35 @@
@online{erlpkgGitHub,
author = {Chris Bailey},
title = {Erlpkg Github Archive},
date = {2018-22-03},
year = {2018},
note = {\url{https://github.com/Vereis/erlpkg}}
}

@online{dialyzerPdf,
author = {{Ericsson AB}},
title = {Dialyzer},
date = {2018-13-03},
year = {2018},
note = {\url{http://erlang.org/doc/apps/dialyzer/dialyzer.pdf}}
}

@online{escodegenGitHub,
author = {{ECMAScript Tooling}},
title = {Escodegen Github Archive},
date = {2018-26-02},
year = {2018},
note = {\url{https://github.com/estools/escodegen}}
}

@online{gulpGitHub,
author = {{Gulp}},
title = {Gulp JS Github Archive},
date = {2018-14-02},
year = {2018},
note = {\url{https://github.com/gulpjs/gulp}}
}

@online{luvvieWeb,
author = {Gordon Guthrie},
title = {Luvvie Script Website},
Expand Down Expand Up @@ -31,9 +63,9 @@ @online{ShenGitHub
}

@online{EStreeMDN,
author = {Mozilla Foundation},
author = {{Mozilla Foundation}},
title = {Parser API},
date = {2017-12-05},
year = {2017},
note = {\url{https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/Parser_API}}
}
}
82 changes: 82 additions & 0 deletions doc/corpus/index.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>CO600 - Project Corpus</title>
<style type="text/css">
* {
font-family: "Verdana", Times, Sans-serif;
}
h1 {
text-align: center;
color: #004091
}
h2 {
text-align: center;
color: #004091
}
table {
margin-left:auto;
margin-right:auto;
border: 2px solid black;
border-collapse:collapse;
}
td, th {
border: 1px solid #666666;
padding: 3px;
}
th.highlight {
background: #004091;
color: white;
}
#logo-kent {
height: 80px;
}
</style>
</head>
<body>
<h1>CO600 - Project Corpus</h1>
<table id="details">
<tbody>
<tr>
<th>Project Title</th>
<td>Jarlang</td>
</tr>
<tr>
<th>Students</th>
<td>Chris Bailey (cb661), Andrew Johnson (apj8) and Nick Laine (nl227)</td>
</tr>
<tr>
<th>Supervisor</th>
<td>Scott Owens (S.A.Owens@kent.ac.uk)</td>
</tr>
<tr>
<th>Date</th>
<td>28/03/2018</td>
</tr>
</tbody>
</table>
<h2>Index of Corpus</h2>
<table id="index">
<tbody>
<tr>
<th>Ref.</th>
<th>Document Title</th>
<th>Author(s)</th>
<th>Quality Assurance</th>
<th>Best Work (High Quality or Intellectually Challenging) *</th>
</tr>
<tr>
<th colspan="5" class="highlight">todo</th>
</tr>
<tr>
<td>todo</td>
<td>todo</td>
<td>todo</td>
<td>todo</td>
<td>todo</td>
</tr>
</tbody>
</table>
</body>
</html>

0 comments on commit 3d3e2a9

Please sign in to comment.