User Commands - where should they go?

Overview

By default Dyalog is looking for User Commands in a sub folder Salt\Spice within the Dyalog installation folder. Therefore the easiest way to get your own User Commands recognized by Dyalog is to put put them into that directory.

Easy may it be but it also has a couple of serious disadvantages: messing up Dyalog user commands with your own user commands is not a good idea because ...

Dyalog might introduce a new user command with a name already used by you.
When a new version of Dyalog arrives you are in trouble.

It's certainly a much better idea to keep Dyalog's user commands separate from your own ones.

Solution

To separate your own user commands from the Dyalog user commands is not too difficult.

For this you need a folder that hosts all your user commands. Of course that folder can have any name you like but in this document we refer to this folder as C:\MyUserCommands.

Create the folder C:\MyUserCommands.
Add that folder to the SALT search path:
1. Call "Configuration" from the "Options" menu.
2. Activate the "User Commands" tab.
3. Press the "Browse" button and browse to C:\MyUserCommands.
4. Press the "Add" button.
5. Press "OK"

Note that the forth step can be easily forgotten.

Now either restart Dyalog or execute the user command ]ureset.

Complex User Commands

If the code which is the "real thing" is small it can and probably will go into the script which is defining the User Command as such. If it is a big thing (like ADOC) or a complete application (like Fire) than it will reside in a workspace.

That workspace can be saved along with the user command itself. Within your user command you should not use a real path to copy what it needed from that workspace. Instead you can find out what the path is by checking ##.SourceFile: that gives you the fully qualified name of the user command.

This will give you the folder name that hosts the current user command:

{⎕IO←1 ⋄ ⍵↓⍨-⌊/'\/'⍳⍨⌽⍵} ##.SourceFile

Scripts

Sometimes a user command will be a script file. Note that you cannot save files with the extension dyalog within the folder that hosts user commands because Dyalog assumes that everything that is saved in such a file is a user command.

The solution to the problem is to give the script a different extension. For esxample code would be just fine. You can still load such a script with the SALT commands; you just have to specify the extension.

Author: -- KaiJaeger 2015-04-04 08:50:51

Last update: 2016-07-14.

-  ⇤ ← Revision 16 as of 2011-08-04 19:54:50 → 
  Size: 3730
  Editor: KaiJaeger
  Comment: New version of the User Command script
+   ← Revision 28 as of 2016-07-14 15:09:26 → ⇥
  Size: 2743
  Editor: KaiJaeger
  Comment: New version
-Deletions are marked like this.
+Additions are marked like this.
 Line 3:
-= User Command ADOC (Dyalog) =
+= User Commands - where should they go?  =
-Line 5:
+Line 6:
-[[ADOC]] is a utility useful to generate documentation (semi-) automatically from class scripts as well as namespace scripts.
 Line 7:
-Obviously it makes sense to make ADOC's services available as a User Command.
+By default Dyalog is looking for User Commands in a sub folder `Salt\Spice` within the Dyalog installation folder. Therefore the easiest way to get your own User Commands recognized by Dyalog is to put put them into that directory.
 Line 9:
-This page offers a small class script `ADOC` which is designed to do exactly that.
+Easy may it be but it also has a couple of serious disadvantages: messing up Dyalog user commands with your own user commands is not a good idea because ...
 Line 11:
-== Assumptions ==
In order to make `ADOC` available as a user command the script `ADOC_UC.dyalog`  ("UC" for User Command) attached to this page must go somewhere where Dyalog is able to find it. There are to options:
+ * Dyalog might introduce a new user command with a name already used by you. 
 * When a new version of Dyalog arrives you are in trouble.
 
It's certainly a much better idea to keep Dyalog's user commands separate from your own ones.
-Line 14:
+Line 16:
- * Move it into `Salt\Spice` inside the Dyalog installation folder. That's where the Dyalog User Commands are located.
 * Create a particular folder for your own User Commands.
+== Solution ==
-Line 17:
+Line 18:
-Although the first option is certainly easier, it's actually the second one which is recommended. There are a couple of reasons:
+To separate your own user commands from the Dyalog user commands is not too difficult.
-Line 19:
+Line 20:
- * Messing Dyalog scripts with your scripts is not a good idea.
 * When a new version of Dyalog arrives you are in trouble.
 * Having a separate folder for your own User Commands allows you to overwrite a Dyalog User Command with an improved version you are not going to loose in case of an update or a new version.
+For this you need a folder that hosts all your user commands. Of course that folder can have any name you like but in this document we refer to this folder as `C:\MyUserCommands`.
-Line 23:
+Line 22:
-To make your own User Command folder work you have to do a couple of things:
+. Create the folder `C:\MyUserCommands`.
 1. Add that folder to the SALT search path:
    1. Call "Configuration" from the "Options" menu.
    2. Activate the "User Commands" tab.
    3. Press the "Browse" button and browse to `C:\MyUserCommands`.
    4. Press the "Add" button.
    5. Press "OK"
-Line 25:
+Line 30:
-. Add the folder to the SALT search path.
 1. Create another folder which is going to host the "real thing". A recommended name is "!UserCommandCode".
 1. Copy the script `ADOC.dyalog` from the [[ADOC]] page into that folder.
 1. Create a registry entry pointing to that new folder with the name `HKEY_CURRENT_USER\Software\Dyalog\Dyalog APL/W 12.1 Unicode\SALT\CodeFolder`
+Note that the forth step can be easily forgotten.
-Line 30:
+Line 32:
-Note that the script attached to this page only deals with two issues:
+Now either restart Dyalog or execute the user command `]ureset`.
-Line 32:
+Line 34:
- * Figure out what command the user wants to invoke, "Browse" or "List".
 * Find the real work horse and call it, see below.
+== Complex User Commands ==
-Line 35:
+Line 36:
-In order to achieve that the script `ADOC_UC.dyalog` reads the `HKEY_CURRENT_USER\Software\Dyalog\Dyalog APL/W 12.1 Unicode\SALT\CodeFolder` from the Windows registry. It then tries to load the "real" ADOC script from that folder.
+If the code which is the "real thing" is small it can and probably will go into the script which is defining the User Command as such. If it is a big thing (like [[ADOC]]) or a complete application (like [[Fire]]) than it will reside in a workspace.
-Line 37:
+Line 38:
-Note that not only our examples given on this page but also the code in `ADOC_UC.dyalog` all refer to version 12.1 Unicode of Dyalog. If your are using a different version of Dyalog of course you must change the script, otherwise it's not going to work.
+That workspace can be saved along with the user command itself. Within your user command you should not use a real path to copy what it needed from that workspace. Instead you can find out what the path is by checking `##.SourceFile`: that gives you the fully qualified name of the user command.
-Line 39:
+Line 40:
-== Samples ==
Given that the two different ADOC scripts went into the right folders, this would be a sample session:
+This will give you the folder name that hosts the current user command:
-Line 43:
+Line 42:
-      ]?ADOC
"??" for general help, "?CMD" for more specific info on command CMD

 Group  Name         Description
 =====  ====         ===========
 ADOC   ADOC.Browse  Creates full documentation and displayes it in the default browser.
        ADOC.HELP    Displays help regarding ADOC.
        ADOC.List    Prints syntax of all public stuff to the session.

      ]?ADOC.Browse
Command "ADOC.Browse". Syntax: 1 arguments; accepts switches -b=
Script location: ........\....\....\ADOC

Gathers information from a class script, compiles
an HTML page with these pieces of information
and displays it in your default browser.

      ]?ADOC.List
Command "ADOC.List".
Script location: ........\...\...\ADOC

Prints a list with all sorts of information to the session
about all public stuff given in the script specified in the right argument

]ADOC.Help
Watch your browser

Shows extensive information about ADOC. It's basically doing `ADOC.Browse ADOC`.
+{⎕IO←1 ⋄ ⍵↓⍨-⌊/'\/'⍳⍨⌽⍵} ##.SourceFile
-Line 73:
+Line 45:
-== Download ==
+== Scripts ==
-Line 75:
+Line 47:
-[[attachment:ADOC_UC.zip | Download]] the script.
+Sometimes a user command will be a script file. Note that you cannot save files with the extension `dyalog` within the folder that hosts user commands because Dyalog assumes that everything that is saved in such a file is a user command.
-Line 77:
+Line 49:
-== Version ==
The script is version 1.2.0 from 2011-08-04
+The solution to the problem is to give the script a different extension. For esxample `code` would be just fine. You can still load such a script with the SALT commands; you just have to specify the extension.
-Line 80:
+Line 51:
-Author: KaiJaeger
-Line 82:
+Line 52:
--- KaiJaeger <<DateTime(2011-08-04T19:54:50Z)>>
+Author: -- KaiJaeger <<DateTime(2015-04-04T08:50:51Z)>>

Last update: 2016-07-14.
-Line 85:
+Line 57:
-CategoryDyalogUserCommands