Skip to content

API functions

With the Cider API you can write DevOps scripts in APL.

The API functions are similar to the user-commands, but not identical. Not all have equivalent user commands.

AddAlias GetMyUCMDsFolder AddNuGetDependencies GetNuGetDependencies AddTatinDependencies GetProgramFilesFolder CloseProject GetTatinDependencies CreateCreateProjectParms HasDotNet CreateOpenParms ListNuGetDependencies CreateProject ListOpenProjects DropAlias ListTatinDependencies GetCiderAliasFileContent OpenProject GetCiderAliasFilename ProjectConfig GetCiderGlobalConfigFileContent ReadProjectConfigFile GetCiderGlobalConfigFilename WriteProjectConfigFile GetCiderGlobalConfigHomeFolder Version

Unlike user commands, API function names are case-sensitive.

The API is exposed in ⎕SE.Cider so, for example, call AddAlias as ⎕SE.Cider.AddAlias.

API code cache

The Cider code package is loaded into ⎕SE._Cider, but the API is exposed via ⎕SE.Cider.

Do not call functions in ⎕SE._Cider.

Add alias

{r}←AddAlias(projectpath alias)

Where

  • projectpath is a project path
  • alias is a string with no punctuation or spaces

if the project folder exists the alias is registered in the file returned by GetCiderAliasFilename. The shy result is an error message, empty if successful.

If the alias is already in use Cider asks you to confirm the change.

Add NuGet dependencies

list←AddNuGetDependencies(packages project)

Where

  • packagesis one or more NuGet packages
  • project is an alias or project path

Cider installs NuGet packages in the (single) NuGet dependency folder defined in the project config and returns their names as a list of strings.

Specify packages as either a list of strings or a comma-separated string.

NuGet package names

NuGet package names are not case sensitive when they are loaded so, for example, you can load Clock by the name clock.

However, the correct name is returned, and is required for using a package.

]CIDER.AddNugetDependencies

Add Tatin dependencies

r←AddTatinDependencies(packages project dev)

Where

  • packages is one or more Tatin packages
  • project is a project path
  • dev is a flag

Cider installs the packages in one of the Tatin dependency folders and returns as a list of strings the names of the packages installed.

Specify packages as either a list of strings or a comma-separated string.

Any errors are reported to the session.

Setting the dev flag switches the installation folder from dependencies (default) todependencies_dev.

      pkgs←'rikedyp-TinyTest,boobly-boo'
      proj←'/Users/sjt/Projects/dyalog/examples/stat'
      ⍴⎕←⎕SE.Cider.AddTatinDependencies pkgs proj 1
Not found: boobly-boo
┌──────────────────────┐
│rikedyp-TinyTest-1.0.1│
└──────────────────────┘
1
Dependency folders

The dependency folders are defined in the project’s configuration file.

The default project configuration file name is dependencies.tatin.

]CIDER.AddTatinDependencies.

Close project

r←{performChecks} CloseProject projects

Where

  • performChecks (optional) is whether to check for Dropbox conflicts (default is 1)
  • projects is
    • one or more open projects
    • an empty vector (all open projects)

Cider closes the projects (unlinks the source files) and returns the number of projects closed.

Identify projects as (any of)

  • fully qualified namespace names
  • aliases
  • project paths

Example: close all open projects. 

⎕SE.Cider.CloseProject ⍬
Example: close three projects without checking for Dropbox conflicts. 
0 ⎕SE.Cider.CloseProject 'path/to/project' #.util '[test]'

CheckForDropboxConflicts
]CIDER.CloseProject

Create CreateProject parms

parms←{parms} CreateCreateProjectParms folder

Where

  • parms (optional) is a namespace of parameters
  • folder is a project path

Cider returns a namespace with parameters required by CreateProject, by default:

acceptConfig   - 0
folder         - project path
ignoreUserExec - 0
namespace      - name of the project folder

Defaults are overwritten by any specified in the parms argument.

]CIDER.CreateProject

Create Open parms

parms←CreateOpenParms y

Where y is either an empty vector or a namespace of parameters, returns a namespace of parameters required by the OpenProject function.

Parameters in y overwrite the defaults, which are:

alias                 ''
batch                 0
checkPackageVersions  ⍬
folder                ''
ignoreUserExec        0
importFlag            0
noPkgLoad             0
parent                ''
projectSpace          ''
quietFlag             0
suppressInit          0
verbose               0
watch                 0

Setting watch to 0 shows Cider you have not set it. Eventually 0 becomes both, the default.

Create project

r←CreateProject parms

Where parms is a namespace of parameter values, typically the result of CreateCreateProjectParms, Cider creates a project.

]CIDER.CreateProject

Drop alias

{flag}←DropAlias alias

Where alias is a project alias, Cider removes it from the file named by GetCiderAliasFilename and returns a flag indicating success.

Get alias file content

r←{filename} GetCiderAliasFileContent dummy

Cider ignores dummy and returns as a matrix of strings the contents of the file named by GetCiderAliasFilename.

      ⍴⎕←⎕SE.Cider.GetCiderAliasFileContent 'blah'
┌───┬──────────────────┐
│bar│/Users/sjt/tmp/foo│
└───┴──────────────────┘
1 2

If the file is empty the result has zero rows.

]CIDER.ListAliases

Get alias filename

filename←GetCiderAliasFilename

Returns the path to the file used to record alias names and their paths.

Get global config file content

parms←GetCiderGlobalConfigFileContent

Cider returns the global config – if found – as a parameter namespace; otherwise the result is ⍬.

]CIDER.Config

Get global config filename

path←GetCiderGlobalConfigFilename

Returns the path to Cider’s global config file.

Get global config home folder

path←GetCiderGlobalConfigHomeFolder

Returns the path to the parent folder of Cider’s global config file.

On Windows, this is typically C:/Users/<⎕AN>/.cider/config.json

Get MyUCMDs folder

path←GetMyUCMDsFolder

Returns the path to the MyUCMDs/ folder.

The folder might not exist

On Windows, this folder is created by the installer. Not so on other platforms.

Get NuGet dependencies

r←name GetNuGetDependencies config

Where

  • name is 'development' or 'development_dev'
  • config is a parameter namespace

returns either the value of nuget in the given branch or an empty vector if nuget is not defined.

The config argument is typically derived from a project’s configuration file.

]CIDER.ListNuGetDependencies

Get Program Files folder

path←{current}GetProgramFilesFolder suffix

Where

  • current (optional) is a flag
  • suffix is a suffix to the folder filepath

returns the path to the Dyalog files folder with any suffix specified.

The current flag (default 0) specifies whether the result is specific to the currently running version of Dyalog.

      ⍝ Version agnostic
      ⎕SE.Cider.GetProgramFilesFolder ''
C:\Users\kai\Documents\Dyalog APL Files
      Cider.GetProgramFilesFolder 'CiderTatin'
C:\Users\kai\Documents\Dyalog APL Files/CiderTatin

      ⍝ Version specific
      1 ⎕SE.Cider.GetProgramFilesFolder ''
C:\Users\kai\Documents\Dyalog APL-64 18.2 Unicode Files

Get TatinD dependencies

r←name GetTatinDependencies config

Where

  • name is 'development' or 'development_dev'
  • config is a parameter namespace

returns either the value of tatin in the given branch or an empty vector if tatin is not defined.

The config argument is typically derived from the project config.

Has DotNet

flag←HasDotNet

Result indicates whether .NET Core or .NET is available and the bridge DLL was successfully loaded.

List NuGet dependencies

r←ListNuGetDependencies projectPath

Where projectPath is a project path, returns a matrix of names and versions of its NuGet dependencies.

List open projects

r←ListOpenProjects verbose

Where verbose is a flag, returns the open projects as a matrix of 2 or 4 columns:

  1. Fully qualified project namespace
  2. Path the project was loaded from
  3. Number of objects belonging to the project
  4. Alias (if any)
      ⎕SE.Cider.ListOpenProjects 0
 #.Cider  /path/to/Cider

      ⎕SE.Cider.ListOpenProjects 1
 #.Cider  /path/to/Cider  32  cider

]CIDER.ListOpenProjects.

List Tatin dependencies

r←ListTatinDependencies projectpath

Where projectpath is a project path, returns as a 5-column matrix the dependencies installed in the Tatin installation folders.

  1. dependency folder
  2. full package ID
  3. flag: whether the package is a principal or a dependency
  4. URL from which the package was loaded
  5. (reserved)
      ⍉r←⎕SE.Cider.ListTatinDependencies '[stat]'
┌───────────────────┬───────────────────────┐
│tatin-dependencies/│tatin-dependencies_dev/│
├───────────────────┼───────────────────────┤
│ davin-Tester-1.1.0│ rikedyp-TinyTest-1.0.1│
├───────────────────┼───────────────────────┤
│1                  │1                      │
├───────────────────┼───────────────────────┤
│https://tatin.dev/ │https://tatin.dev/     │
├───────────────────┼───────────────────────┤
│                   │                       │
└───────────────────┴───────────────────────┘
      r[;5]≡' ' ' '
1

Until Cider version 0.34.0 this was named ListTatinPackages

]CIDER.ListTatinDependencies.

Open project

(flag log)←OpenProject y

Where y is either

  • an alias or project path
  • a parameter namespace (typically created by CreateOpenParms)

Cider opens the project, and returns a 2-item result: a flag for success, and a log string as printed to the session.

      (flag log)←⎕SE.Cider.OpenProject '[stat]'
The current directory is now ...
      flag
1
      (≡log)(≢log)
1 388

If y is a parameter space, all parameters are optional except folder.

folder

String. Alias or project path. May not be empty, but could be ./ indicating the current directory.

alias

String. An alias by which you can refer to the project.

Special syntax for alias

If alias is just a dot, the name of the project folder becomes the alias. Example:

p←⎕SE.Cider.CreateOpenParms
p.folder←'/path/2/projects/foo'
p.alias←'.'  ⍝ `foo` becomes the (new) alias

Side effect Cider will register the new alias for the project.

Example: Open project aliased as foo and reregister its alias as bar: 

p←⎕SE.Cider.CreateOpenParms
p.folder←'[foo]'
p.alias←'bar'

checkPackageVersions

By default Cider proposes to check principal packages for later versions and, if found, to update them.

⍬ - Ask me whether to check (default)
0 - Do not check at all
1 - Check and report findings but prompt for updating
2 - Check and update without consulting me

This parameter is ignored if the project has no Tatin installation folder, or if importFlag is set.

ignoreUserExec

Flag to stop Cider executing at the end of opening a project a function named in the global ExecuteAfterProjectOpen setting. Defaults to 0.

importFlag

Flag to stop Cider from linking APL objects to their source files. Defaults to 0.

watch

Setting this flag has implications for how Cider deals with Tatin packages.

noPkgLoad

Flag to stop Cider from loading Tatin dependencies as specifed in the config file’s dependencies and dependencies_dev settings. Defaults to 0.

parent

String. Defaults to # but could be something like ⎕SE or #.Foo.Goo.Boo. All namespaces listed must exist.

parent

projectSpace

String. The name of the namespace the project is injected into. If this is empty it is going to be # or ⎕SE, depending from where the function was called from.

projectSpace

quietFlag

Flag to stop Cider printing messages to the session. (They are still returned in the function‘s result.)

suppressInit

Flag to stop Cider executing the project’s initialisation function. Defaults to 0.

For example, an automated build process might open a project without initialising it.

watch

String. See watch in the project config for setting values.

How Link watches for changes

]CIDER.OpenProject

Project config

{r}←ProjectConfig projectpath

Where projectpath is a project path, Cider displays the project config for editing.

Asks your permission before writing changes back to file, and performs checks before doing so.

Read project config file

config←ReadProjectConfigFile projectpath

Where projectpath is a project path, Cider returns its project config as a parameter namespace.

The path may or may not terminate in the filename cider.config.

Side effect If the function does not find the sub-keys dependency.tatin and dependency.nuget in the file it creates them and writes them there.

]CIDER.ProjectConfig.

Write project config file

{r}←config WriteProjectConfigFile project

Where

  • config is a parameter namespace
  • project is a project path

Cider writes the contents of config as the project’s configuration file.

The path may or may not terminate in the filename cider.config.

Version

r←Version

Returns a string with major and minor versions, patch number and timestamp, e.g.

      ⎕SE.Cider.Version
0.44.0+835

This could be just e.g. 1.2.3, but might be something like 1.2.3-beta-1+113.