Link enables users of Dyalog to store their APL source code in text files. This is the documentation for Link Version 3.0, which will be released in the autumn of 2021 and included with the next release of Dyalog APL. If you have an earlier version of APL or Link, you might want to read one or more of the following pages before continuing:
- Link version 2.0 If you are actually looking for documentation of the version which was distributed with Dyalog APL versions 17.1 and 18.0.
- Migrating to Link 3.0 from Link 2.0: Dyalog recommends migrating to version 3.0 at your earliest convenience.
- Migrating to Link 3.0 from SALT: If you have APL source in text files managed by SALT that you want to migrate to Link.
- Installation instructions: If you want to download and install Link from the GitHub repository rather than use the version installed with APL, for example if you want to use Link 3.0 with Dyalog version 18.0.
- The historical perspective: Link is a step on a journey which begins more than a decade ago with the introduction of SALT for managing source code in text files, as an alternative to binary workspaces and files, and will hopefully end with the interpreter handling everything itself.
It is assumed the reader has a reasonable understanding of Dyalog and in particular workspaces and namespaces.
What is Link?
Link allows you to use Unicode text files to store APL source code, rather than "traditional" binary workspaces. The benefits of using Link and text files include:
- It is easy to use source code management tools like Git or Subversion to manage your code.
Although an SCM is not a requirement for Link, if you are not already using a source code management system, we highly recommend making the effort to learn about and install Git.
If you choose not to use an SCM then you just need your own strategy for taking suitable copies of your source files, as you would with workspaces.
Changes to your code are immediately written to file: there is no need to remember to save your work. The assumption is that you will make the record permanent with a commit to your source code management system, when the time is right.
Unlike binary workspaces, text source can be shared between different versions of APL - or even with human readers or writers who don't have APL installed at all.
Source code stored in external files is preserved exactly as typed, rather than being reconstructed from the tokenised form.
Link is NOT...
- A source code management system: unlike it's predecessor SALT, Link has no source code management features. You will need to use a separate tool like Git to manage the text files that Link will maintain for you as you work with Dyalog APL.
- A database management system: although Link is able to store APL arrays using a pre-release of the literal array notation, this is only intended to be used for constants which you consider to be part of the source code of your applications. Although all functions and operators that you define using the editor will be written to source files by default, source files are only created for arrays by explicit calls to Link.Add or by specifying optional parameters to Link.Export. Application data should be stored in a database management system or files managed by the application.
Link establishes links between one or more namespaces in the active APL workspace and corresponding directories containing APL source code in Unicode test files. For example, the following user command invocation will link a namespace called
myapp to the folder
]LINK.Create myapp /home/sally/myapp
A set of API functions is available in the session namespace
⎕SE, for performing Link operations under programme control. Using the API, the above would be written:
⎕SE.Link.Create 'myapp' '/home/sally/myapp'
myapp contains sub-directories, a namespace hierarchy corresponding to the directory structure will be created within the
myapp namespace. By default, the link is bi-directional, which means that Link will:
- Keep source files up-to-date: Any changes made to code in the active workspace using the tracer and editor are immediately replicated in the corresponding text files.
- Keep the workspace up-to-date: If .NET Framework or .NET Core is available, then any changes made to the external files using a text editor, or resulting from an SCM action such as rolling back or switching to a different branch, will immediately be reflected in the active workspace.
For Dyalog to automatically update workspace contents due to file changes requires Microsoft .NET.
The .NET Framework is included with Microsoft windows. For other platforms, .NET can be downloaded from dotnet.microsoft.com/download.
To find out which versions are supported, see section 2.1 of the .NET Core Interface Guide and under the heading "Prerequisites" in chapter 1 of the Dyalog for Microsoft Windows .NET Framework Interface Guide.
You can invoke Link.Create several times to create multiple links, and you can also use Link.Import or Link.Export to import source code into the workspace or export code to external files without creating links that will respond to subsequent changes.
Functions vs. User Commands
With a few exceptions, each Link API function has a corresponding User Command, designed to make the functionality slightly easier to use interactively in the session.
The user commands have the general syntax
]LINK.CmdName arg1 [arg2] [-name[=value] ...]
arg2's presence depends on the specific command,
-name is a flag enabling the specific option and
-name=value sets that option to a specific value. Some options (like
typeExtensions) require an array of values: in these cases the user commands typically take the name of a variable containing that array.
For a list of installed user commands, type:
The API is designed for use under program control, and options are provided in an optional namespace passed as the left argument. The general syntax of the utility functions is
options FnName arguments
options is a namespace with variables, named according to the option they set, containing their corresponding values. The
-name=value option can be set by
options.name←value, and switches with values (e.g.
-name) can be set by
options.name←1. Unset options will assume their default value.
Options can also be provided as a character vector with the literal array representation of the option workspace, for example:
'(name: 1)' FnName arguments
The details of the arguments and options can be found in the API Reference.
To get started using Link, please read:
- Basic Usage to see how to set up your first links, and learn about exporting existing application code to source files.
- Setting Up Your Environment for a discussion of how to set up Link-based development and runtime environments.
- Technical Details and Limitations if you want to know about the full range of APL objects that are supported, and some of the edge cases that are not yet supported by Link.
If you have an existing APL application that you want to move to Link, you might want to read one of the following texts first:
- Converting Your Workspace to Text Source: if you already have an existing body of APL code in binary workspaces.
- Migrating to Link 3.0 from SALT: if you are already managing text source using Link's predecessor SALT.