Mini Ada v1.0 Functional Draft Specification

From e6a81730d57d52f5b07c5269d61cfbed4a7e91bb Mon Sep 17 00:00:00 2001 From: Jed Barber Date: Tue, 11 Jul 2017 09:10:53 +1000 Subject: Start of functional draft spec --- doc/functional_spec.html | 288 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 doc/functional_spec.html 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 @@ + + +Mini Ada v1.0 Functional Draft Specification + + + +

Mini Ada v1.0 Functional Draft Specification

+ + + + +

Overview

+ +

Mini Ada is a minimalistic, standalone, portable, libre and open source REPL, +interpreter, JIT, and compiler for the Ada programming language.

+ +

This spec is not complete. Nor does it discuss algorithms and data structures +used. For those, see the technical spec.

+ + + + +

Scenarios

+ +

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.

+ +

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.

+ +

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.

+ + + + +

Non Goals

+ +

The following features will never be supported:

style checks
self hosting
error tolerant parser
TAC/SSA intermediate format
SPARK proof tools

+ +

The following will not be supported in version 1:

Ada 83, 95, 2005 modes
all optional annexes
any backend aside from amd64/ELF

+ +

What linking is required for FFI and interfacing with already-compiled units?

+ + + + +

Common Elements

+ +

Command line options recognised by all four utilities:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Short	Long	Argument	Arg Type	Values	Description
	--version	none	N/A	N/A	Displays the relevant version message then terminates. Any additional options will be ignored.
-h	--help	none	N/A	N/A	Displays the relevant help message then terminates. Any additional options will be ignored.
-x		none	N/A	N/A	Ignores the first line of file input. Doesn't take effect if input is from standard input.
-I		required	string	any valid path	Specify source files search path.
-L		required	string	any valid path	Specify library files search path.
-	--	none	N/A	N/A	Terminates the option list and forces all further command line items to be evaluated as arguments.

+ + + + +

REPL

+ +

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.

+ +

The REPL executable is:

+marepl
+

+ +

Additional command line options are:

+ + + + + + + + + + + + + + + + + +

Short	Long	Argument	Arg Type	Values	Description
-i	--interactive	none	N/A	N/A	Forces interactive mode after interpreting an input file.

+ +

The version message is:

+Mini Ada REPL [version number]
+

+ +

The help message is:

+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
+

+ +

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.

+ +

If no file to interpret is supplied, the following message is displayed:

+Mini Ada REPL [version number]
+Ada [standard in use] mode, [annexes available]
+

+ +

Followed by the prompt for input, which is:

+>
+

+ +

A valid input is a repl_unit, described by the following BNF grammar:

+repl_unit ::= { context_item | library_item | subunit
+              | declarative_item | statement | label | expression }
+

+ +

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.

+ +

The result of a bare expression is displayed after it is evaluated, similar to other REPLs.

+ +

If evaluation is successful, the following message is displayed:

+ok
+

+ +

Otherwise, an appropriate error message is displayed.

+ +

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.

+ +

Interpretation is ended and control returned to the operating system when the REPL encounters the +EOF character.

+ + + + +

Interpreter

+ +

The interpreter executable is:

+mai
+

+ +

Additional command line options are:

+ + + + + + + + + +

Short	Long	Argument	Arg Type	Values	Description

+ +

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.

+ +

The version message is:

+Mini Ada Interpreter [version number]
+

+ +

The help message is:

+ +

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.

+ + + + +

Just In Time

+ +

The JIT executable will be

+majit
+

+ +

Additional command line options, version message, and help message are all identical to that of the +Interpreter, with the word "JIT" substituted for "Interpreter".

+ + + + +

Compiler

+ +

The compiler executable will be

+mac
+

+ + + -- cgit