User Commands (UCMDs)

in Dyalog APL

A programmer's tool

V1.04

Dan Baronet

Agenda

This tutorial is divided into 4 steps:

- Why UCMDs

- Dyalog's UCMDs

- Implementation of the UCMD framework

- Your UCMDs: how to write them

Why

The idea is to provide a mechanism for accessing tools anywhere by

- separating utilities from the workspace

- make them available at any time

History

The concept of user commands (UCMDs) is not new.

APL/PC had them in the 90s.

Their implementation was different but the idea was the same

User Commands A user command (UCMD) is similar to a

system command like )LOAD or )WSID.

It is a call to an independent routine written by a user, not a routine provided by the system.

It can be used anytime.

User Commands

System commands start with a ), e.g.

)SAVE

User commands start with a ], e.g.

]WSLOC

User Commands - syntax Like their system commands

counterpart, user commands may take arguments, e.g.)WSID [newname]

And]FNSLIKE [pattern]

Just like system commands they are not case sensitive.

User Commands - syntax Unlike system commands, in the

actual implementation, they can also take modifiers, e.g.]FNSLIKE [Pattern] –format

Modifiers are preceded by a specific character (here –)

Modifiers ARE case sensitive.

User Commands - syntax This is Dyalog's implementation.

UCMDs could take any format.

WE decide what is acceptable.

User Commands - syntax

UCMDs are based on SALT.

SALT

• SALT is basically a pair of programs to write and read Unicode text files

• UCMDs make use of these 2 functions to write out and read back their code

• SALT has many other features that are irrelevant with UCMDs (but nonetheless useful)

WPF and APL Dyalog’11 - Boston 11

SALT

• When an object is saved using SALT it is tagged

• That tag is used afterwards when resaving the object, e.g. after editing it

• That tag remains with the object unless removed, even when the workspace is saved

WPF and APL Dyalog’11 - Boston 12

User Commands

Dyalog comes pre-packaged with a set of user commands divided into groups.

Groups exist for SALT, workspace utilities, code utilities, user commands management, etc.

User Commands For example the command ]SAVE , which saves an

OBJECT (not a workspace),takes up to 2 arguments, saving the object named in the 1st argument to, if

present,the location named in the 2nd argument. Ex:

]save myfn \my\location\myfn

To bring the object back use the command ]LOAD:

]load my\location\myfn

User Commands - Help General help can be obtained with

]?? Or ]helpThe list of all commands can be obtained with

]? And ]?+Specific help for a command can be obtained

with]?cmdx

Or more detailed help, if any, with]??cmdx

Or]?\path\to\file\containing\a\user\cmd

User Commands availableDyalog comes pre-packaged with some

already defined UCMDsThey are divided into groups:- SALT Samples- Spice (UCMD) svn- Sysmon System- Tools Transfer- wsutils

Group SALTThese are the same as their SALT

functions:- Save object [tolocation]- Load location- Compare file1 [file2]- Settings [type [value]]- List [folder]- Snap tolocation- Removeversions file

Group SpiceThese are commands used to manage the

User commands system:- Uload command - Udebug [ON|OFF]- Uclean- Unew [name]- Ureset- Uupdate [SALT]- Uversion [wsname]- Umonitor

Group svnThis group contains commands to mimic

SubVersion's commands:- svnci: commit changes- Svnco: check out- Svnadd/delete: add/delete new files- Svnstatus/resolve- Svndiff: show changes to a file- Svnimport/export- Svnupdate: bring in most recent changes

Group SysMon

This group is used to monitor the system:- APLMON: used to monitor expressions by primitive,

ex:]aplmon {+/1=⍵∨⍳⍵}¨⍳1000 –file=\tmp\

data

- CPUtime: used to find CPU used for expressions, ex:]cputime {+/1=⍵∨⍳⍵}¨⍳1000

- Monitor: used to find lines consuming the most CPU

- Profile: used to profile an application

Group Transfer

This group is used to move code in and out of ATF files with

- in/out

And move code in and out of "extended" files with code translation with

- inx/outx

Groups Tools & WSutilsThese 2 groups contain various utilities

e.g. to show a subset of names following a specific pattern or do function call analysis or search the workspace for strings of code/text:]fnslike GUI* -date=>20090307

]fncalls MainProgram -details -treeview]wsloc abc -exclude=ct -recursive

UCMDs - implementation

• The code to run a UCMD is contained in a class or namespace in a SALT (text, Unicode)file.

• That file may be host to several UCMDs• Command names are case insensitive, e.g.

‘find’ and ‘FIND’ call the same code• Switches names are case sensitive• UCMDs are grouped together, e.g. utilities

can be grouped under the group ‘wsutils’• The class or namespace must contain at least

3 public functions: ‘List’, ‘Run’ and ‘Help’

UCMDs - implementation• The ‘List’ function is used to gather

basic info displayed when using ]?+

• The ‘Help’ function is used to display more complete info when using ]?cmdx or ]??cmdx

• The ‘Run’ function is the one doing the work.

UCMDs - implementationThe whole framework is based on 2

things:

- SALT: used to read/write Unicode text files

- Spice: used to implement the rules of UCMDs

UCMDs – an exampleLet’s assume we have a simple function

we wish to call once in a while without having to copy/call/erase it each time:

calendar 3 March

S M T W T F S 1 2 3 4 5 6 7 8 9 10 11 12 1214 15 16 17 18 19 2021 22 23 24 25 26 2728 29 30 31

UCMDs – an example

Let’s create a user command named CAL that we will call with a single argument like this:

]cal 3

UCMDs – an exampleWe need to create a class with the 3 basic functions, the <List>

function:

:Namespace dates ⎕IO←1 ⋄ ⎕ML←1∇ r←List r←⎕NS ⍬⍝ Name, group, short description and parsing rules

r.Name← 'cal' r.Group←'dates' r.Desc← 'returns the calendar for a given month' r.Parse←'' ∇

UCMDs – an example

The HELP function:

∇ r←Help dummy r←'Enter a month as argument'

∇

UCMDs – an exampleThe RUN function:

∇ r←Run(a1 a2) 'calendar' ⎕CY 'myutils' r←calendar ⍎a2∇ :endnamespace

UCMDs – an example

Because each class may contain more than one UCMD the HELP and RUN functions should really account for that.

UCMDs – an exampleHELP function for more than one command:

∇ r←Help Cmd :Select Cmd :Case 'cal' r← 'Enter a month as argument' :Case 'other'… :EndSelect∇

UCMDs – an exampleThe RUN function for more than one

command:∇ r←Run(Cmd Args) :Select Cmd :Case 'cal' 'calendar' ⎕CY 'myutils' r←calendar ⍎Args :Case 'other'… :EndSelect∇

UCMDs – ParsingIf automatic parsing of the arguments is desired the

system will look at the line given as argument, split the tokens on spaces and put the resulting vector of text vectors in variable 'Arguments’ in a namespace.

That namespace will be given as the 2nd argument to the function <Run>.

To request parsing simply put in 'Parse' (in function <List>) the rules to follow, e.g. '3' to ensure 3 arguments.

If no parsing is desired simply leave 'Parse' empty.

UCMDs – Parsing• If we wish the system to check the

number of arguments (here 1) for us we say it in <List>:

∇ r←List:Access Shared Publicr←⎕NS¨1⍴⊂⍬⍝ Name, group, short description and parsing rulesr.Name← ⊂ 'cal' r.Group←⊂ 'dates' r.Desc← ⊂ 'returns the calendar for a given month'r.Parse← '1' ∇

In that case the 2nd argument of <Run> will contain a namespace but only AFTER the framework has ensured only ONE argument has been supplied.

UCMDs – Parsing∇ r←Run(Cmd a2) :Select Cmd :Case 'cal' 'calendar' ⎕CY 'myutils' r←calendar ⍎1⊃a2.Arguments :EndSelect∇Function <calendar> can also/should be defined

in the class instead of being copied in.

UCMDs – an example. ]cal 3

March

S M T W T F S

1 2 3 4 5 6

7 8 9 10 11 12 12

14 15 16 17 18 19 20

21 22 23 24 25 26 27

28 29 30 31

UCMDs – an exampleIf Parsing is enabled, entering the

wrong number of arguments will be refused:

]calCommand Execution Failed: too few arguments

]cal 2 3 Command Execution Failed: too many arguments

UCMDs location

The location of user commands is preset to Dyalog's folder SALT\spice under APL's location, e.g.

C:\program files\Dyalog\V121\SALT\spice

UCMDs location

The location of UCMDs is one of SALT's settings.

To know what they are:

[]SE.SALT.Settings 'cmddir'

Or, as a UCMD:

]settings cmddir

UCMDs locationYou can reset it too.It follows the same rule as SALT's workdir setting, i.e.

it is a series of paths separated by semicolons, e.g.

\my\own\path;C:\program files\Dyalog\V121\SALT\Spice

For example, to add "\my\own\path" to the existing path:

(note the comma)

]settings cmddir ,\my\own\path

UCMDs location

You can set them manually or in Options/Configure…

UCMDs location

UCMDs locationSome commands are always there: Spice's

and SALT's

Doing (note NO comma)]settings cmddir \my\own\path

Will keep Spice and SALT's commands even though they have not been specified.

UCMDs – Advanced Topics

Debugging code]udebug ON|OFF

When debugging is OFF errors are reported in the calling environment:

Command Execution Failed: DOMAIN ERRORWhen debugging is ON errors are reported in the

class:DOMAIN ERRORcalendar[4] r←n÷month ∧

UCMDs – Advanced Topics

SwitchesThose can be specified in the Parse variable:They come in different forms:- Without a value: /sw- With a value: /sw=- Possibly with a value: /sw[=]The specification for each includes the

(same) switch delimiter (here /)

UCMDs – Advanced Topics

SwitchesA set of possible values may be specified, e.g./animal=cat monkey giraffeA set of possible characters can also be

specified:/vowel ∊ aeiouOr/vowel [∊] aeiouIf the switch can be specified without a value

UCMDs – Advanced Topics

Switches – Examples1. Switch time takes a value, switch PM

does not, switch delimiter is /:Parse ← '/time= /PM'2. Switch Prime may accept values 2, 3, 5

and 7, switch Octal accepts values made out of '01234567', delimiter is +:

Parse ←'+Prime[=]2 3 5 7 +Octal∊01234567'

UCMDs – Advanced Topics

Switches – ExamplesSwitches and number of arguments

are specified together. A command accepting 2 arguments and a switch-offset with a value would be specified as:

Parse ←'2 -offset='

UCMDs – Advanced Topics

ArgumentsArguments are delimited by spaces.If an argument must contain spaces, or the

switch delimiter character or a quote, it should be surrounded by quotes. For example, if the switch delimiter is /, the following call will contain 4 arguments:]mycmd 'arg 1' '2001/4/5' OK "I'm" /lights=on

UCMDs – Advanced Topics

Long ArgumentsIf a command accepts N arguments and the last

argument may contain spaces then it may be unnecessary to quote the last argument simply by stating the command as "long". For ex, if command addrec accepts 3 arguments it could accept]addrec Joe Blow 42 main str

With Parse ←'3L'The arguments will be 'Joe' 'Blow' '42 main str'

UCMDs – Advanced Topics

Short ArgumentsIf a command accepts a maximum of

N arguments it can be specified as "short". For ex,

With Parse ←'3S'Any number of argument less than

or equal to 3 will be accepted.

UCMDs – Exercices

1. Write a UCMD to display the time, formatted

2. Write a UCMD to display the time in another city

]END