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