APL Wiki|
Size: 2127
Comment:
|
Size: 2743
Comment: New version
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | 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 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 7: | Line 9: |
| Obviously it makes sense to make ADOCs services available as a User Command. | 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 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. It's certainly a much better idea to keep Dyalog's user commands separate from your own ones. |
| 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. This means that the script `ADOC.dyalog` attached to this page must go into this directory. Only then the User Commd "ADOC" is recognized. | To separate your own user commands from the Dyalog user commands is not too difficult. |
| Line 15: | Line 20: |
| That script, which represents the ADOC User Command, assumes that there is a sibling folder of `SALT` available 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`. | 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 17: | Line 22: |
| == Samples == | 1. 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 19: | Line 30: |
| Given that the two different ADOC scripts went into the right folders, this would be a sample session: | Note that the forth step can be easily forgotten. |
| Line 21: | Line 32: |
| 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: |
|
| Line 22: | 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.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, compiles an HTML page with these pieces of information and displays it in a browser. Use the -b flag to specify a browser different from your default browser. ]?ADOC.List Command "ADOC.List". Script location: ........\SALT\Spice\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.Browse ADOC -b=Opera Watch your browser |
{⎕IO←1 ⋄ ⍵↓⍨-⌊/'\/'⍳⍨⌽⍵} ##.SourceFile |
| Line 50: | Line 45: |
| Author: KaiJaeger | == 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 <<DateTime(2015-04-04T08:50:51Z)>> Last update: 2016-07-14. |
| Line 52: | Line 57: |
| CategoryDyalogUserCommands |
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:
- Call "Configuration" from the "Options" menu.
- Activate the "User Commands" tab.
Press the "Browse" button and browse to C:\MyUserCommands.
- Press the "Add" button.
- 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.