Skip to content

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 '.')