diff --git a/HTML/Appendix-02_User-commands.html b/HTML/Appendix-02_User-commands.html index 58a7bae..20b0083 100644 --- a/HTML/Appendix-02_User-commands.html +++ b/HTML/Appendix-02_User-commands.html @@ -4,70 +4,39 @@ User CMDs - - - - - - + + + -
-
-
-

Chapters

-
-
    -
  1. Introduction
    2. -
  2. Structure
    3. -
  3. Packaging
    4. -
  4. Logging
    5. -
  5. Configuration
    6. -
  6. Debugging EXEs
    7. -
  7. Handling errors
    8. -
  8. Testing
    9. -
  9. Documentation
    10. -
  10. Make
    11. -
  11. Providing help
    12. -
  12. Scheduled Tasks
    13. -
  13. Windows Services
    14. -
  14. Windows Event Log
    15. -
  15. Windows Registry
    16. -
  16. Creating SetUp.exe
    17. -
  17. Regular Expressions
    18. -
  18. Acre
    19. -
  19. GUI
    20. -
  20. Git
    21. -
-
-

Appendices

-
-
    -
  1. Windows environment vars
    2. -
  2. User commands
    3. -
  3. aplcores & WS integrity
    4. -
  4. Development environment
    5. -
  5. Special characters
    6. -
-
-

Misc

-
+
- -
-
+
- -

22. Appendix 2 — User commands

+ +

Appendix 2 — User commands
@@ -82,27 +51,32 @@

Overview

"C:\Program Files\Dyalog\Dyalog APL-64 17.0 Unicode\SALT\spice\"

The above is the default folder for the 64-bit Unicode version of Dyalog 17.0 for all Dyalog user commands available within that version.

+ +

Where to put user commands

+ +
+
-

Using the default folder

+

Using the default folder
-

If you want to keep life simple the obvious choice seems to be this folder: you just copy your user command into this folder and it becomes available straight away.

-

Simple may it be, but this is not recommended:

+

If you want to keep life simple the obvious choice is to copy your user command into the folder Dyalog has reserved for this very purpose starting with version 17.0.

+

It's in %HOMEDRIVE%%HOMEPATH%\Documents\MyUCMDs[2]. This folder is scanned automatically by Dyalog at start-up time and when ]URESET is executed. Any script with the extension .dyalog is expected to be a user command class or user command script. This is also true for any sub folders.

+

Notes:

    -
  • When a new version of Dyalog comes along you need to copy your own stuff over.
    • -
  • When you use more than one version of Dyalog in parallel you have to maintain several copies of your user commands.
    • -
  • Because of Microsoft's security measures, writing to that folder requires admin rights.
    • +
  • User commands in that folder are only available for that specific user, not all users. Naturally it depends on the circumstances whether that's a good thing or a bad thing for you.
    • +
  • From version 17.0 onwards every version will look into the same folder, so the user command must check itself whether it is compatible with the version it is called from.
-

For these reasons you are advised to use a different folder.

+

For these reasons you might decide to go for a different folder.

-

Use your own dedicated folder

+

Use your own dedicated folder

Let's assume that you have a folder C:\MyUserCommands that's supposed to hold all non-Dyalog user commands.

Via the Options > Configure command you can select the User Commands dialog and add that folder to the search path; remember to press the Add button once you have browsed to the right directory.

If you use several versions of Dyalog in parallel then you are advised not to add that folder via the configuration dialog box in each of those versions.

-

Instead we recommend writing an APL function that adds the folder to all versions of Dyalog currently installed. See the chapter The Windows Registry where this scenario is used as an example.

+

Instead we recommend writing an APL function that adds the folder to all versions of Dyalog currently installed. See the chapter The Windows Registry where this scenario is used as an example. The reason is that you can solve the problem for all installed versions with a single function call, and you can repeat that in case you have to re-install any of the versions.

Name clashes

@@ -112,8 +86,8 @@

Name clashes

In other words, the full name of a user command is compiled by the group name (say foo) and the user-command name (say goo): ]foo.goo. However, as long as there is only one user command goo this will do nicely:

      ]goo
- -

Group name

+ +

Group names

Group names are not only useful to avoid name clashes, they also allow user commands to be, well, grouped in a sensible way. Whether you should add your own user commands to any of the groups Dyalog comes with is a diffult question to answer. There are pros and cons:

@@ -204,17 +178,8 @@

Writing your own user commands

Footnotes

  1. Dyalog user commands from the APL wiki http://aplwiki.com//CategoryDyalogUserCommands

    +

  2. See Appendix 01 - Windows environment vars for details regarding the environment variables used here.

-
-
- \ No newline at end of file diff --git a/manuscript/Appendix-02_User-commands.md b/manuscript/Appendix-02_User-commands.md index a5d6236..625a3fe 100644 --- a/manuscript/Appendix-02_User-commands.md +++ b/manuscript/Appendix-02_User-commands.md @@ -21,20 +21,24 @@ The default folder depends on your version of Dyalog of course, but you can alwa The above is the default folder for the 64-bit Unicode version of Dyalog 17.0 for all Dyalog user commands available within that version. -## Using the default folder +## Where to put user commands -If you want to keep life simple the obvious choice seems to be this folder: you just copy your user command into this folder and it becomes available straight away. -Simple may it be, but this is _not_ recommended: +### Using the default folder -* When a new version of Dyalog comes along you need to copy your own stuff over. -* When you use more than one version of Dyalog in parallel you have to maintain several copies of your user commands. -* Because of Microsoft's security measures, writing to that folder requires admin rights. +If you want to keep life simple the obvious choice is to copy your user command into the folder Dyalog has reserved for this very purpose starting with version 17.0. -For these reasons you are advised to use a different folder. +It's in `%HOMEDRIVE%%HOMEPATH%\Documents\MyUCMDs`[^envvars]. This folder is scanned automatically by Dyalog at start-up time and when `]URESET` is executed. Any script with the extension `.dyalog` is expected to be a user command class or user command script. This is also true for any sub folders. + +Notes: + +* User commands in that folder are only available for that specific user, not all users. Naturally it depends on the circumstances whether that's a good thing or a bad thing for you. +* From version 17.0 onwards every version will look into the same folder, so the user command must check itself whether it is compatible with the version it is called from. + +For these reasons you might decide to go for a different folder. -## Use your own dedicated folder +### Use your own dedicated folder Let's assume that you have a folder `C:\MyUserCommands` that's supposed to hold all non-Dyalog user commands. @@ -42,7 +46,7 @@ Via the _Options > Configure_ command you can select the User Commands dialog an If you use several versions of Dyalog in parallel then you are advised _not_ to add that folder via the configuration dialog box in each of those versions. -Instead we recommend writing an APL function that adds the folder to all versions of Dyalog currently installed. See the chapter [The Windows Registry](./15 The Windows Registry) where this scenario is used as an example. +Instead we recommend writing an APL function that adds the folder to all versions of Dyalog currently installed. See the chapter [The Windows Registry](./15 The Windows Registry) where this scenario is used as an example. The reason is that you can solve the problem for all installed versions with a single function call, and you can repeat that in case you have to re-install any of the versions. ## Name clashes @@ -56,7 +60,7 @@ In other words, the full name of a user command is compiled by the group name (s ~~~ -## Group name +## Group names Group names are not only useful to avoid name clashes, they also allow user commands to be, well, grouped in a sensible way. Whether you should add your own user commands to any of the groups Dyalog comes with is a diffult question to answer. There are pros and cons: @@ -147,6 +151,7 @@ The workspace `Goo` can be tested independently from the user command framework, [^wiki]:Dyalog user commands from the APL wiki +[^envvars]: See _Appendix 01 - Windows environment vars_ for details regarding the environment variables used here. *[HTML]: Hyper Text Mark-up language *[DYALOG]: File with the extension 'dyalog' holding APL code