Dyalog User Commands

Overview
User commands play a crucial role for Dyalog APL developers. Dyalog comes with a rich set of user commands, but independent parties also develop and maintain user commands. This article discusses how and where to install third-party user commands, and how to load them into.

Prerequisite Knowledge
This article assumes that you are familiar with the concept of Dyalog user commands, and understand what a user command script is, along with its specific features and properties. If you are new to these topics, it is recommended to first study Dyalog's "User Commands User Guide".

Installing user command
Dyalog installs its own set of user commands into. Installing third-party user commands into this folder comes with both advantages and disadvantages.

Advantages of installing into the  folder:


 * User commands cannot be modified by ordinary users; admin rights are required
 * Every version of Dyalog has its own set of user commands

On the other hand, installing user commands in a different folder, such as, has its own advantages:


 * Users have write permission to this folder, making updates easier
 * Anything installed into this folder will be available in all installed versions of Dyalog APL
 * Each user has their own  folder, which can be seen as an advantage or disadvantage based on individual preferences

Both the  folder and the    folder are scanned for user command scripts at startup.

Location of the MyUCMDs/ folder
The location of the MyUCMDs/ folder depends on the operating system used:


 * On Windows it's usually
 * On Linux it is
 * On Mac OS it is

Note that   is created by the Dyalog APL installer on Windows, but you need to manually create it on non-Windows platforms before version 19.0.

If you have Tatin installed, or you are using version 19.0 or later (those come with Tatin) then you can call this Tatin API function:

Availability of user commands
Once a user command script is moved into the  folder (or a sub-folder of it), the user command becomes available across all versions of APL.

For simple user commands where all the code resides in the script itself, this is the end of the process. However, if a user command relies on a larger set of code files that need to be loaded into  for execution, additional steps are required.

The user command script could of course check whether the code is already available in  and if not load it, and that would work just fine.

User commands with an API
It has become increasingly popular to add an API to user commands. For example, the Dyalog APL project manager Cider offers a rich set of user commands:

But Cider also offers an API (public interface):

If you want to use any of the API functions without the need of first calling one of the Cider user commands (that would force the user command loading the code into ), then you have to make sure that the code is loaded by other means, ideally at an early stage: as part of the bootstrapping process.

Introducing setup.dyalog in MyUCMDs/
To address this, a script named  is introduced in the   folder. When Dyalog encounters this script, it checks for the presence of a function called  and executes it.

Notes:


 * The script name must be lowercase to ensure compatibility with non-Windows platforms
 * The script can be a class or a namespace
 * The  function must accept a right argument


 * The function  must return a result

There is no setup.dyalog yet
Create one that looks like this:

Note that this also checks the version of Dyalog APL and whether it's "Classic" or not. Please customize the script to fit your specific needs. Ensure to modify the  function, if necessary.

If your user command is not a Tatin package then this will do.

There is already a setup.dyalog
Copy the functions,   and   from above into your own   script.

Make sure that  is called from your   function.

This makes sure that the API of your user command is available right after instantiating Dyalog APL.

User commands that are Tatin packages
Since version 0.86. 0 a Tatin package can be marked as a user command: by specifying the path to a user command script with a project.

Example:

With this line in the file  such a  package can be installed and loaded with Tatin:

Notes:


 * There is no name specified after  in the second argument of  : this makes the function use the name of the package for the folder to be created in , here


 * will look for a folder  in the   folder. If there is one, and it contains a file , then the package will be loaded into.


 * Usually  loads packages into   in case no second argument is specified, but because the folder was specified as an alias  the function knows that this is about a user command, and therefore the default target for the load operation is   rather than.


 * The user command script  is moved to the top of the folder hosting the user command by , here

Loading all such user commands
If you want to make sure that all user commands that are Tatin packages are loaded into  at an early stage then add this code to your   script and make sure that it is called by your   function:

Conclusion

 * Every user command that relies on code that is not part of the user command script as such should check whether that code is already in  and load it into   if not
 * There are good reasons to load all user commands, packaged or otherwise, at an early stage as part of the Dyalog bootstrapping process
 * If you have specific user commands that consume a significant amount of memory and are infrequently executed, you can request Dyalog to introduce a mechanism that allows a package to indicate its preference for loading its own code.