API Overview

API function syntax

The Link API functions all reside in ⎕SE.Link.

The general syntax for Link API functions is as follows:

      message ← options ⎕SE.Link.FnName args

where:

message is a simple character vector or nested array containing messages related to the effects of the function call.
options is a namespace containing optional parameters. Only certain functions accept an options namespace.
FnName is the name of the API function
args is either a character vector or a nested vector as described in the help section for that API function.

Option Namespaces

Some API functions accept an option namespace as the left argument. For example, to create a link with non-default source and flatten options, you would write:

      options←⎕NS ⍬                                     ⍝ create empty namespace
      options.(source flatten)←'dir' 1                  ⍝ set two named options
      options ⎕SE.Link.Create 'myapp' '/sources/myapp'  ⍝ namespace and director name on the right, options on left

Creating option namespaces will become more elegant once Dyalog APL is enhanced with a notation for namespaces. Until that time (no definite schedule has yet been set), Link API functions will accept a character vector left argument which represents an array in the proposed Literal Array Notation, for example:

        '(source:''dir'' ⋄ flatten:1)' ⎕SE.Link.Create 'myapp' '/sources/myapp'

User commands

Most API functions have a corresponding user command, to make them a little easier to use interactively. The API functions with user command covers are indicated with ^] in the function reference tables. These user commands all take exactly the same arguments and options as the API functions, specified using user command syntax. The Link.Create call above would thus be written:

      ]LINK.Create myapp /sources/myapp -source=dir -flatten

Lowercase option names: Although option names are case sensitive and some of them contain uppercase letters when provided to API functions via option namespaces, the user command option names are entirely lowercase, to make interactive use more convenient.

Specifying extensions: Two options require arrays identifying file extensions: codeExtensions, customExtensions and typeExtensions. For convenience, the ]LINK.Create user command accepts the name of a variable containing the array, rather than the array values.

Basic API Function reference

The following functions cover the vast majority of normal use-cases:

Function	User Command	Right Argument(s)	Left Argument(s)	Result
Add	`]Add`	items		message
Break	`]Break`	namespaces	options: `all` `recursive`	message
Create	`]Create`	namespace directory	options: `source` `watch` `arrays` (and many more)	message
Export	`]Export`	namespace directory	options: `overwrite` `caseCode` `arrays` `sysVars`	message
Expunge	`]Expunge`	items		boolean array
Import	`]Import`	namespace directory	options: `overwrite` `flatten` `fastLoad`	message
LaunchDir		none	none	directory name
Refresh	`]Refresh`	namespace	options: `source`	message
Resync	`]Resync`	namespace	options: `proceed` `arrays` `sysvars`	message
Status	`]Status`	namespace	options: `extended`	message
Version				version number as string

Note

The currently active version of Link is reported by ⎕SE.Link.Version and found in the output of ]TOOLS.Version

Advanced API Function reference

The "advanced" functions are typically used when building your own tools on top of Link, rather than simply using Link to maintain the source of an application:

Function	User Command	Right Argument(s)	Left Argument(s)	Result
CaseCode		filename	<none>	case-coded filename
Fix		source	array: namespace name oldname	boolean
GetFileName	`]GetFileName`	items	<none>	filenames
GetItemName	`]GetItemName`	filenames	<none>	items
Notify		event filename oldfilename	<none>	<none>
StripCaseCode		filename	<none>	filename without case code
TypeExtension		name class	option namespace used for Create	file extension (without leading `'.'`)