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.

A list of available user commands can be viewed in the session with ]LINK -?. Help for a particular user command Cmd is displayed using ]LINK.Cmd -?.

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
Configure	]Configure	target settings		current or previous settings
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 '.')