53
edits
Dyalog User Commands: Difference between revisions
Jump to navigation
Jump to search
Links added & minor improvements
(Link corrected) |
(Links added & minor improvements) |
||
| Line 2: | Line 2: | ||
User commands are useful for the Dyalog APL developer. 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 <syntaxhighlight lang=apl inline>⎕SE</syntaxhighlight>. | User commands are useful for the Dyalog APL developer. 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 <syntaxhighlight lang=apl inline>⎕SE</syntaxhighlight>. | ||
This article assumes that you are familiar with the concept of Dyalog user commands, and that you know what a user command script is, and what specific features and properties it has. If you are not familiar with these topics this article is not for you: study Dyalog's "User Commands User Guide" first. | This article assumes that you are familiar with the concept of Dyalog user commands, and that you know what a user command script is, and what specific features and properties it has. If you are not familiar with these topics this article is not for you: study Dyalog's [https://www.dyalog.com/documentation_182.htm "User Commands User Guide"] first. | ||
Dyalog installs its own set of user commands into <syntaxhighlight lang=apl inline>[DYALOG]/SALT/spice</syntaxhighlight>. Installing third-party user commands into this folder has advantages and disadvantages. | Dyalog installs its own set of user commands into <syntaxhighlight lang=apl inline>[DYALOG]/SALT/spice</syntaxhighlight>. Installing third-party user commands into this folder has advantages and disadvantages. | ||
| Line 27: | Line 27: | ||
* Under Linux and Mac OS it is <syntaxhighlight lang=apl inline>/home/<username>/</syntaxhighlight> | * Under Linux and Mac OS it is <syntaxhighlight lang=apl inline>/home/<username>/</syntaxhighlight> | ||
Note that | Note that <syntaxhighlight lang=apl inline>MyUCMDs/</syntaxhighlight> is created by the Dyalog APL installer under Windows but it won't exist under Linux and Mac OS in versions before 19.0, so you need to create the folder yourself on non-Windows platforms. | ||
If you have Tatin installed, or you are using version 19.0 or later (those come with Tatin automatically) then you can call this Tatin API function: | If you have [https://github.com/aplteam/Tatin Tatin] installed, or you are using version 19.0 or later (those come with Tatin automatically) then you can call this Tatin API function: | ||
<syntaxhighlight lang=apl> | <syntaxhighlight lang=apl> | ||
| Line 68: | Line 68: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
But Cider also offers | But Cider also offers an API (public interface): | ||
<syntaxhighlight lang=apl> | <syntaxhighlight lang=apl> | ||
| Line 91: | Line 91: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
If you want to use any of these API functions without the need of first calling any of the Cider user commands (that would allow the user command script to load the code into <syntaxhighlight lang=apl inline>⎕SE</syntaxhighlight>), then you have to make sure that the code is loaded, ideally at a very early stage: as part of the instantiating process. | If you want to use any of these API functions without the need of first calling any of the Cider user commands (that would allow the user command script to load the code into <syntaxhighlight lang=apl inline>⎕SE</syntaxhighlight>), then you have to make sure that the code is loaded by other means, ideally at a very early stage: as part of the instantiating process. | ||
This brings us to the real topic of this article: how to achieve that! | This brings us to the real topic of this article: how to achieve that! | ||
| Line 103: | Line 103: | ||
* The name of the script must be lowercase because otherwise it won't be found on non-Windows platforms | * The name of the script must be lowercase because otherwise it won't be found on non-Windows platforms | ||
* The script can be a class or a namespace | * The script can be a class or a namespace | ||
* The function <syntaxhighlight lang=apl inline>Setup</syntaxhighlight> must accept a right argument | * The function <syntaxhighlight lang=apl inline>Setup</syntaxhighlight> must accept a right argument. In our case, the right argument will be an <syntaxhighlight lang=apl inline>i</syntaxhighlight> which stands for <syntaxhighlight lang=apl inline>init</syntaxhighlight> | ||
* The function <syntaxhighlight lang=apl inline>Setup</syntaxhighlight> must return a result. The result will be ignored by the caller | |||
* The function <syntaxhighlight lang=apl inline>Setup</syntaxhighlight> must return a result | |||
=== There is no setup.dyalog yet === | === There is no setup.dyalog yet === | ||
| Line 165: | Line 163: | ||
=== There is already a setup.dyalog === | === There is already a setup.dyalog === | ||
Copy the functions <syntaxhighlight lang=apl inline>IfAtLeastVersion</syntaxhighlight>, <syntaxhighlight lang=apl inline>GetMyUCMDsFolder</syntaxhighlight> and < | Copy the functions <syntaxhighlight lang=apl inline>IfAtLeastVersion</syntaxhighlight>, <syntaxhighlight lang=apl inline>GetMyUCMDsFolder</syntaxhighlight> and <syntaxhighlight lang=apl inline>LoadMyUserCommand</syntaxhighlight> from above into your own <syntaxhighlight lang=apl inline>setup.dyalog</syntaxhighlight> script and then make sure that <syntaxhighlight lang=apl inline>LoadMyUserCommand</syntaxhighlight> is called from your <syntaxhighlight lang=apl inline>Setup</syntaxhighlight> function. | ||
This makes sure that the API of your user command is available right after instantiating Dyalog APL. | This makes sure that the API of your user command is available right after instantiating Dyalog APL. | ||
| Line 188: | Line 186: | ||
Notes: | Notes: | ||
* There is no name specified after <syntaxhighlight lang=apl inline>[MyUCMDs]</syntaxhighlight> in the second argument of <syntaxhighlight lang=apl inline>InstallPackages</syntaxhighlight>: this makes the function | * There is no name specified after <syntaxhighlight lang=apl inline>[MyUCMDs]</syntaxhighlight> in the second argument of <syntaxhighlight lang=apl inline>InstallPackages</syntaxhighlight>: this makes the function use the name of the package for the folder to be created in <syntaxhighlight lang=apl inline>MyUCMDs/</syntaxhighlight>, here <syntaxhighlight lang=apl inline>MyUserCommand</syntaxhighlight> | ||
* <syntaxhighlight lang=apl inline>LoadDependencies</syntaxhighlight> will look for a folder <syntaxhighlight lang=apl inline>MyUserCommand</syntaxhighlight> in the <syntaxhighlight lang=apl inline>MyUCMDs/</syntaxhighlight> folder. If there is one, and it contains a file <syntaxhighlight lang=apl inline>apl-dependencies.txt</syntaxhighlight>, then the package will be loaded into <syntaxhighlight lang=apl inline>⎕SE</syntaxhighlight>. | * <syntaxhighlight lang=apl inline>LoadDependencies</syntaxhighlight> will look for a folder <syntaxhighlight lang=apl inline>MyUserCommand</syntaxhighlight> in the <syntaxhighlight lang=apl inline>MyUCMDs/</syntaxhighlight> folder. If there is one, and it contains a file <syntaxhighlight lang=apl inline>apl-dependencies.txt</syntaxhighlight>, then the package will be loaded into <syntaxhighlight lang=apl inline>⎕SE</syntaxhighlight>. | ||
* Usually <syntaxhighlight lang=apl inline>LoadDependencies</syntaxhighlight> loads packages into <syntaxhighlight lang=apl inline>#</syntaxhighlight> in case no second argument is specified, but because the folder was specified as an alias (<syntaxhighlight lang=apl inline>[MyUCMDs]</syntaxhighlight>) the function knows that this is about a user command, and therefore the default target for the load operation is <syntaxhighlight lang=apl inline>⎕SE</syntaxhighlight> | |||
* Usually <syntaxhighlight lang=apl inline>LoadDependencies</syntaxhighlight> loads packages into <syntaxhighlight lang=apl inline>#</syntaxhighlight> in case no second argument is specified, but because the folder was specified as an alias (<syntaxhighlight lang=apl inline>[MyUCMDs]</syntaxhighlight>) the function knows that this is about a user command, and therefore the default target for the load operation is <syntaxhighlight lang=apl inline>⎕SE</syntaxhighlight> rather than <syntaxhighlight lang=apl inline>#</syntaxhighlight>. | |||
* The user command script <syntaxhighlight lang=apl inline>MyUserCommand.dyalog</syntaxhighlight> is moved to the top of the folder hosting the user command, here <syntaxhighlight lang=apl inline>[MyUCMDs]/MyUserCommand</syntaxhighlight> | * The user command script <syntaxhighlight lang=apl inline>MyUserCommand.dyalog</syntaxhighlight> is moved to the top of the folder hosting the user command, here <syntaxhighlight lang=apl inline>[MyUCMDs]/MyUserCommand</syntaxhighlight> | ||
=== Loading all such user commands === | === Loading all such user commands === | ||
If you want to make sure that all user commands that are Tatin packages are loaded into <syntaxhighlight lang=apl inline>⎕SE</syntaxhighlight> at an early stage add this to your <syntaxhighlight lang=apl inline>setup.dyalog</syntaxhighlight> script and make sure that it is called by your <syntaxhighlight lang=apl inline>Setup</syntaxhighlight> function | If you want to make sure that all user commands that are Tatin packages are loaded into <syntaxhighlight lang=apl inline>⎕SE</syntaxhighlight> at an early stage add this to your <syntaxhighlight lang=apl inline>setup.dyalog</syntaxhighlight> script and make sure that it is called by your <syntaxhighlight lang=apl inline>Setup</syntaxhighlight> function: | ||
<syntaxhighlight lang=apl> | <syntaxhighlight lang=apl> | ||