Start of functional draft spec

author: Jed Barber <jjbarber@y7mail.com> 2017-07-11 09:10:53 +1000
committer: Jed Barber <jjbarber@y7mail.com> 2017-07-11 09:10:53 +1000
commit: e6a81730d57d52f5b07c5269d61cfbed4a7e91bb (patch)
tree: 589d6471ac517c444de01a3b70f056401503e53b
1 files changed, 288 insertions, 0 deletions
diff --git a/doc/functional_spec.html b/doc/functional_spec.html
new file mode 100644
index 0000000..855aeee
--- /dev/null
+++ b/doc/functional_spec.html
@@ -0,0 +1,288 @@
+<html>
+<head>
+<title>Mini Ada v1.0 Functional Draft Specification</title>
+</head>
+<body>
+
+<h2>Mini Ada v1.0 Functional Draft Specification</h2>
+
+
+
+
+<h4>Overview</h4>
+
+<p>Mini Ada is a minimalistic, standalone, portable, libre and open source REPL,
+interpreter, JIT, and compiler for the Ada programming language.</p>
+
+<p>This spec is not complete. Nor does it discuss algorithms and data structures
+used. For those, see the technical spec.</p>
+
+
+
+
+<h4>Scenarios</h4>
+
+<p>Tim is a university student. He has to learn and use Ada for a unit on parallel
+computation, but doesn't have much programming experience. He uses the Mini Ada
+REPL to get quick feedback, experiment with the language and test what he's
+written so far. Then he uses the Mini Ada Compiler to compile his assignments.</p>
+
+<p>James is an Ada developer who wants to write some software for an architecture that
+doesn't have an Ada compiler targeting it yet. He downloads and uses the Mini Ada
+Interpreter as a stopgap measure, making use of it being written in Forth, which
+is an extremely simple language that has been ported everywhere.</p>
+
+<p>David is a sysadmin. He wants a scripting language that minimises errors. He uses
+the Mini Ada JIT to take advantage of just-in-time compilation speedups and the
+design of the Ada language. He's satisfied that the small size of Mini Ada makes
+it as easy to deploy as any shell interpreter.</p>
+
+
+
+
+<h4>Non Goals</h4>
+
+<p>The following features will never be supported:</p>
+<ul>
+  <li>style checks</li>
+  <li>self hosting</li>
+  <li>error tolerant parser</li>
+  <li>TAC/SSA intermediate format</li>
+  <li>SPARK proof tools</li>
+</ul>
+
+<p>The following will not be supported in version 1:</p>
+<ul>
+  <li>Ada 83, 95, 2005 modes</li>
+  <li>all optional annexes</li>
+  <li>any backend aside from amd64/ELF</li>
+</ul>
+
+<p id="tech_issue">What linking is required for FFI and interfacing with already-compiled units?</p>
+
+
+
+
+<h4>Common Elements</h4>
+
+<p>Command line options recognised by all four utilities:</p>
+<table>
+  <tr>
+    <th>Short</th>
+    <th>Long</th>
+    <th>Argument</th>
+    <th>Arg Type</th>
+    <th>Values</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td></td>
+    <td>--version</td>
+    <td>none</td>
+    <td>N/A</td>
+    <td>N/A</td>
+    <td>Displays the relevant version message then terminates. Any additional options will be ignored.</td>
+  </tr>
+  <tr>
+    <td>-h</td>
+    <td>--help</td>
+    <td>none</td>
+    <td>N/A</td>
+    <td>N/A</td>
+    <td>Displays the relevant help message then terminates. Any additional options will be ignored.</td>
+  </tr>
+  <tr>
+    <td>-x</td>
+    <td></td>
+    <td>none</td>
+    <td>N/A</td>
+    <td>N/A</td>
+    <td>Ignores the first line of file input. Doesn't take effect if input is from standard input.</td>
+  </tr>
+  <tr>
+    <td>-I</td>
+    <td></td>
+    <td>required</td>
+    <td>string</td>
+    <td>any valid path</td>
+    <td>Specify source files search path.</td>
+  </tr>
+  <tr>
+    <td>-L</td>
+    <td></td>
+    <td>required</td>
+    <td>string</td>
+    <td>any valid path</td>
+    <td>Specify library files search path.</td>
+  </tr>
+  <tr>
+    <td>-</td>
+    <td>--</td>
+    <td>none</td>
+    <td>N/A</td>
+    <td>N/A</td>
+    <td>Terminates the option list and forces all further command line items to be evaluated as arguments.</td>
+  </tr>
+</table>
+
+
+
+
+<h4>REPL</h4>
+
+<p>This is a read-eval-print-loop interpreter for the Ada programming language. Minor changes have been made to
+the accepted grammar to accommodate bare declarations, statements, and expressions, similar to how REPL
+interpreters for other languages operate. However the grammar should still accept standard Ada input. This
+program can also be used to create informal Ada scripts.</p>
+
+<p>The REPL executable is:</p>
+<pre>
+marepl
+</pre>
+
+<p>Additional command line options are:</p>
+<table>
+  <tr>
+    <th>Short</th>
+    <th>Long</th>
+    <th>Argument</th>
+    <th>Arg Type</th>
+    <th>Values</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>-i</td>
+    <td>--interactive</td>
+    <td>none</td>
+    <td>N/A</td>
+    <td>N/A</td>
+    <td>Forces interactive mode after interpreting an input file.</td>
+  </tr>
+</table>
+
+<p>The version message is:</p>
+<pre>
+Mini Ada REPL [version number]
+</pre>
+
+<p>The help message is:</p>
+<pre>
+Usage: marepl [options] [arguments]
+
+The first argument specifies a file to interpret and terminates the option list. All additional
+arguments are passed to the interpreted file as command line arguments.
+
+Options:
+         --version        displays the REPL version number
+-h       --help           displays this help message
+-x                        ignores the first line of file input
+-Idir                     specifies source files search path
+-Ldir                     specifies library files search path
+-        --               terminates option list
+-i       --interactive    forces interactive mode after interpreting a file
+</pre>
+
+<p>The first non-option command line item specifies a file to interpret and terminates the option list.
+Any further command line items are passed to the interpreted file as command line arguments. If no file
+is supplied to interpret, input is obtained from standard input.</p>
+
+<p>If no file to interpret is supplied, the following message is displayed:</p>
+<pre>
+Mini Ada REPL [version number]
+Ada [standard in use] mode, [annexes available]
+</pre>
+
+<p>Followed by the prompt for input, which is:</p>
+<pre>
+&gt;
+</pre>
+
+<p>A valid input is a repl_unit, described by the following BNF grammar:</p>
+<pre>
+repl_unit ::= { context_item | library_item | subunit
+              | declarative_item | statement | label | expression }
+</pre>
+
+<p>If a line of input is the beginning part of a valid input, then further prompts for input will be
+supplied until either a syntax error is encountered or a complete valid input is received. The complete
+input is then interpreted and evaluated.</p>
+
+<p>The result of a bare expression is displayed after it is evaluated, similar to other REPLs.</p>
+
+<p>If evaluation is successful, the following message is displayed:</p>
+<pre>
+ok
+</pre>
+
+<p>Otherwise, an appropriate error message is displayed.</p>
+
+<p>If an input file has been supplied to interpret, processing of the file proceeds as above, except without
+any messages or prompts aside from those produced by the interpretation and evaluation of the contents of the
+file.</p>
+
+<p>Interpretation is ended and control returned to the operating system when the REPL encounters the
+EOF character.</p>
+
+
+
+
+<h4>Interpreter</h4>
+
+<p>The interpreter executable is:</p>
+<pre>
+mai
+</pre>
+
+<p>Additional command line options are:</p>
+<table>
+  <tr>
+    <th>Short</th>
+    <th>Long</th>
+    <th>Argument</th>
+    <th>Arg Type</th>
+    <th>Values</th>
+    <th>Description</th>
+  </tr>
+</table>
+
+<p>The first non-option command line item specifies a file to interpret and terminates the option list.
+Any further command line items are passed to the interpreted file as command line arguments.</p>
+
+<p>The version message is:</p>
+<pre>
+Mini Ada Interpreter [version number]
+</pre>
+
+<p>The help message is:</p>
+<pre>
+</pre>
+
+<p>This program expects as file input a valid compilation_unit (RM 10.1.1). The input is interpreted and
+evaluated, then (should the input terminate) control is returned to the operating system. At no point is any
+platform-specific code generated, except as required by the Ada standard itself.</p>
+
+
+
+
+<h4>Just In Time</h4>
+
+<p>The JIT executable will be</p>
+<pre>
+majit
+</pre>
+
+<p>Additional command line options, version message, and help message are all identical to that of the
+Interpreter, with the word "JIT" substituted for "Interpreter".</p>
+
+
+
+
+<h4>Compiler</h4>
+
+<p>The compiler executable will be</p>
+<pre>
+mac
+</pre>
+
+</body>
+</html>
author	Jed Barber <jjbarber@y7mail.com>	2017-07-11 09:10:53 +1000
committer	Jed Barber <jjbarber@y7mail.com>	2017-07-11 09:10:53 +1000
commit	e6a81730d57d52f5b07c5269d61cfbed4a7e91bb (patch)
tree	589d6471ac517c444de01a3b70f056401503e53b