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 27 as of 2015-04-04 08:50:51 → 
  Size: 3813
  Editor: KaiJaeger
  Comment:
+   ← 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 7:
-By default Dyalog is looking for any User Commands in a sub folder `Salt\Spice` within the Dyalog installation folder.
+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:
-Therefore the easiest way to get your own User Commands recognized and dealt with is putting them into that directory. Easy may it be but it also has a couple of serious disadvantages: messing up Dyalog scripts with your own scripts is not a good idea because ...
+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:
- * 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. Which shall go into the new version?
+ * 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.
 Line 14:
-It's certainly a much better idea to keep Dyalog's User Commands separate from others.
+It's certainly a much better idea to keep Dyalog's user commands separate from your own ones.
 Line 18:
-To achieve that is not too difficult:
+To separate your own user commands from the Dyalog user commands is not too difficult.
 Line 20:
-. Create a folder somewhere which is going to host all your User Commands.
 1. Add the folder to the SALT search path.
+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:
-Of course the folder can have any name you like but in this document we refer to this folder as `MyUserCommands\`.
+. 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"

Note that the forth step can be easily forgotten.

Now either restart Dyalog or execute the user command `]ureset`.
-Line 27:
+Line 36:
-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 somewhere else.
+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 29:
+Line 38:
-Again it's not a good idea to put it into `MyUserCommands\`: name clashes and difficulties to tell User Command scripts from work horses are looming.
+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 31:
+Line 40:
-For that reason I am  proposing to have another folder for hosting the "real thing" - let's call it `MyUserCommandCode\`. This name should go into the Windows Registry with the key name:

`HKCU\Software\Dyalog\Dyalog APL/W 12.1 Unicode\SALT\CodeFolder`

Of course you need to change the Dyalog version number to the version you are actually using.

||<tablestyle="background:magenta; both; font-size:large;"> /!\ Watch out: `MyUserCommandCode\` '''must not''' be a sub-folder of `MyUserCommands\`. The reason is that Dyalog searches the folder '''''recursively''''' for User Commands! ||

Now your script needs to honor this. There are two possibilities:

=== A Script ===

Your User Command script needs to find out where to find the workhorse. For this it needs a function which can read the Registry key. It then needs to read the script file and fix it.

For this you can use the [[UserCommands/Adoc | ADOC User Command]] as a role model: it has two private methods, `ReadRegKey` and `ReadUtf8File` solving these two problems.

The `Run` method makes use of these two private methods:
+This will give you the folder name that hosts the current user command:
-Line 50:
+Line 42:
-∇ r←Run(Cmd Args);browser;cmdparser;cs;ref;⎕IO;⎕ML;path;regKey
      :Access Shared Public
      ⎕IO←⎕ML←1
      regKey←'HKCU\Software\Dyalog\Dyalog APL/W 12.1 Unicode\SALT\CodeFolder'
      path←ReadRegKey regKey
      path,←'\adoc.dyalog'
      ⎕FIX ReadUtf8File path
      ....
+{⎕IO←1 ⋄ ⍵↓⍨-⌊/'\/'⍳⍨⌽⍵} ##.SourceFile
-Line 60:
+Line 45:
-=== A workspace ===
+== Scripts ==
-Line 62:
+Line 47:
-Your User Command script needs to find out where to find the workspace hosting the application. For this it needs a function which can read the Registry key. It then needs to read the script file and fix it.
+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 64:
+Line 49:
-For this you can use the [[UserCommands/fire | Fire User Command]] as a role model: it has a private method `ReadRegKey` which is solving this problem.

The `Run` method makes use of this method:

{{{
∇ r←Run(Cmd Args);browser;cmdparser;cs;ref;⎕IO;⎕ML;path;regKey
      :Access Shared Public
      ⎕IO←⎕ML←1
      r←''
      regKey←'HKCU\Software\Dyalog\Dyalog APL/W 12.1 Unicode\SALT\CodeFolder'
      path←ReadRegKey regKey
      path,←'\ScriptManager.DWS'
     
      ref←⎕NS''
      ref.⎕CY path
      ref.ScriptManager.Run'' 
∇
}}}
+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 87:
+Line 54:
+Last update: 2016-07-14.