User Commands - where should they go?

Overview

By default Dyalog is looking for any User Commands in a sub folder Salt\Spice within the Dyalog installation folder.

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 ...

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?

It's certainly a much better idea to keep Dyalog's User Commands separate from others.

Solution

To achieve that is not too difficult:

Create a folder somewhere which is going to host all your User Commands.
Add the folder to the SALT search path.

Of course the folder can have any name you like but in this document we refer to this folder as MyUserCommands\.

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 somewhere else.

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.

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.

$/!\$ 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 need 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 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:

∇ 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
      ....

A workspace

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.

For this you can use the ScriptManager 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'' 
∇

Author: KaiJaeger

-  ⇤ ← Revision 1 as of 2009-10-20 19:38:59 → 
  Size: 1781
  Editor: KaiJaeger
  Comment:
+   ← Revision 26 as of 2015-02-03 17:06:05 → ⇥
  Size: 3788
  Editor: KaiJaeger
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 1:
-= User Command ADOC (Dyalog) =
+<<TableOfContents>>

= User Commands - where should they go?  =
-Line 5:
+Line 7:
-[[ADOC]] is a utility useful to generate documentation (semi-) automatically from class scripts as well as namespace scripts.
+By default Dyalog is looking for any User Commands in a sub folder `Salt\Spice` within the Dyalog installation folder.
-Line 7:
+Line 9:
-Obviously it makes sense to make ADOCs services available as a User Command.
+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 ...
-Line 9:
+Line 11:
-This page offers a small class script `ADOC` which is designed to do exactly that.
+ * 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?
 
It's certainly a much better idea to keep Dyalog's User Commands separate from others.
-Line 11:
+Line 16:
-== Assumptions ==
+== Solution ==
-Line 13:
+Line 18:
-When User Commands got introduced in Dyalog with version 12.1, the User Commands where expected to reside in a sub folder `Salt\Spice` inside the Dyalog installation folder.
+To achieve that is not too difficult:
-Line 15:
+Line 20:
-The ADOC User Command assumes that there is a sibling folder of `SALT` named `UserCommands`. Please make sure that the [[ADOC]] script is copied into this folder `UserCommands`. This enables the User Command script to address the real ADOC script as `..\UserCommands\ADOC`.
+. Create a folder somewhere which is going to host all your User Commands.
 1. Add the folder to the SALT search path.
-Line 17:
+Line 23:
-The script '''ADOC''' attached to this page needs to go into `SALT\SPICE`
+Of course the folder can have any name you like but in this document we refer to this folder as `MyUserCommands\`.
-Line 19:
+Line 25:
-== Samples ==
+== Complex User Commands ==
-Line 21:
+Line 27:
-Given that the two different ADOC scripts went into the right folders, this would be a sample session:
+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.

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.

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 need 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:
-Line 24:
+Line 50:
-      ]?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.List    Prints syntax of all public stuff to the session

      ]?ADOC.Browse
Command "ADOC.Browse". Syntax: 1 arguments; accepts switches -b=
Script location: ........\SALT\Spice\ADOC
Gathers all sort of information from a class script

      ]?ADOC.List
Command "ADOC.List".
Script location: ........\SALT\Spice\ADOC
Prints a list with all sorts of information to the session

]ADOC.Browse ADOC -b=Opera
Watch your browser
+∇ 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
      ....
-Line 46:
+Line 60:
+=== A workspace ===

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.

For this you can use the [[UserCommands/ScriptManager | ScriptManager 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'' 
∇
}}}
-Line 47:
+Line 86:
-Line 48:
+Line 88:
-CategoryDyalogUserCommands