shithub: lpa

ref: 8dc7c659e34ad5d244477e01b1ebf4def63be24d
dir: /lpa.ms/

.FP lucidasans
.TL
LPA: A new APL system for Plan 9 (WORK IN PROGRESS)
.AU
Peter Mikkelsen
.AB
LPA is an implementation of APL for Plan 9, which aims to be a playground for experimenting with many new ideas, such as a file system for debugging, and constraint based programming.
It implements most of the APL language as defined in the Extended APL standard, but with a fair amount of extensions as well.
LPA draws inspiration from other programming languages such as Prolog and Erlang.

.FS
The name LPA was choosen due to an early idea, which was to provide some form of
.B L ogic
.B P rogramming
in
.B A PL.
Even though logic programming in the Prolog sense is no longer a goal, and has been replaced with constraints, the name stuck.
It is also APL spelled backwards.
.FE
.FS
.B1
This document is work in progress, and probably already out of date.
.B2
.AE

.NH 1
Introduction

.NH 1
Running LPA
.LP
LPA uses a file system to present objects (such as functions and arrays), such that it becomes possible to edit them using the standard tools.
Unlike other APL systems, that means there is no need for an IDE at all.
The system is started by running
.P1
lpafs
.P2
A single instance of LPA supports multiple
.I sessions ,
represented by different subdirectories in the filesystem.
An advantage of letting a single instance of LPA handle multiple sessions is that memory can be shared between them, thereby lowering overall memory usage.
By default, LPA mounts itself under
.CW /mnt/lpa
and presents the following structure:
.P1
/mnt/lpa
	clone
	1/
		ctl
		cons
		modules/
			main/
				computeSums
				years
				...
				prices
				names
			test/
				assert
				log
				...
			...
		threads/
			...
	2/
		ctl
		...
	...
.P2
The filesystem provides a full view of the running system.
The structure under
.CW threads/
is primarily useful for debugging, and it is described in more detail in section 3.
.PP
In the top-level directory, we find a
.CW clone
file, and a directory for each active session, numbered automatically.
New sessions are created by opening
.CW clone
and reading an integer, which is the number for the newly created session (and the name of the relevant subdirectory).
After that, the session can be controlled and deleted by writing commands to the session's
.CW ctl
file.
.PP
Each session directory has a
.CW ctl
which understands messages that control the entire session, such as deletion, creating/importing new modules (see section 4.4), and saving/re-loading the session's state to disk.
.FS
The messages written to a session's
.CW cons
file are exactly those supported by the system-command syntax in the interpreter, such as
.CW ")save /tmp/dump" ,
.CW ")module ..."
and
.CW ")off"
.FE
The
.CW cons
file provides access to the
.I REPL
of the session, and can be accessed using:
.P1
con -C /mnt/apl/1/cons
.P2
or by running the
.CW lpa
script which automatically starts
.CW lpafs
if it isn't already running, creates a new session, and connects to it.
The
.CW lpa
script accepts some optional arguments, to connect to an existing running session.
It is only possible to have one active connection to a session's REPL, although there is no limit on the number of readers or writers to the other parts of a session's filesystem structure.
.PP
Each of the directories in the
.CW modules/
directory represents a module in the session.
The one named
.CW main
is always present, and it is created when a session is created.
In each of the module's directories, there are a file for each globally named object (array, function, etc.), which can be edited in any way the user wants.
For example, to edit the function
.CW computeSums
in the
.CW main
module of session 1, taking advantage of the plumber:
.P1
B /mnt/lpa/1/modules/main/computeSums
.P2
Creating a new file is also allowed, and it introduces a new globally named object.
Alternatively, new objects can be created by control messages to the
.CW ctl
file, and some control messages cause plumb messages to be sent as well.
The definition of the object is updated once the file is written, and a write error is produced in case the syntax wasn't valid.
Reading the file will return the text representation of the object at the time the file was opened.
Deleting a file causes the corresponding object to be deleted as well.
Access to non-global objects, such as local variables on the stack of a specific thread, is possible via the
.CW threads/
directory described in section 3.

.NH 1,
Debugging

.NH 1
Language extensions
.LP

.NH 2
Array notation

.NH 2
Constraints

.NH 2
Concurrency features

.NH 2
Modules

.NH 2
Dictionaries

.NH 1
Implementation

.NH 2
Overview

.NH 2
Parsing and compiling

.NH 2
The VM instruction set

.NH 2
The workspace format/memory management