User Commands in Dyalog APL By Dan Baronet A programmer's tool - V1.03.
-
Upload
andrea-sullivan -
Category
Documents
-
view
225 -
download
0
description
Transcript of User Commands in Dyalog APL By Dan Baronet A programmer's tool - V1.03.
User Commands in Dyalog APL
By Dan Baronet
A programmer's tool - V1.03
ProcedureThis tutorial is divided into 4 areas:- Why UCMDs and introduction- Dyalog's UCMDs- implementation of the UCMD
framework- Your UCMDs: how to write them
WhyThe idea is to provide a mechanism
for accessing tools anywhere by- separating utilities from the
common workspace- make them available at any time
HistoryThe concept of user commands
(UCMDs) is not new.APL/PC had them in the 90s.Some IPSharp users had them
(through S-Tasks)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.
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]
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.
In fact, UCMDs could take any format
WE decide what is acceptable
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
]??The 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 some 7 groups:- SALT- Spice (UCMD)- Svn- Sysmon- Tools- Transfer- wsutils
Group SALTThese are the same as their SALT functions:- Save object [tolocation]- Loadlocation- Compare file1 [file2]- Settings [type [value]]- Explore [folder|file]- List [folder]- Snap tolocation- Removeversions file
Group SpiceThese are commands used to manage the
User commands system:- Uload command - Udebug ON|OFF- Uclean- Unew- Ureset- Uversion - 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 SysMonThis group is used to monitor the system:- APLMON: used to monitor expressions by primitive, ex:
]aplmon {+/1=⍵∨⍳⍵}¨⍳1000 –file=\tmp\data)LOAD APLMONInitMon '\tmp\data.csv'
- CPUtime: used to find CPU used for expressions, ex:]cputime {+/1=⍵∨⍳⍵}¨⍳1000
- Monitor: used to find lines consuming the most CPU
Group TransferThis 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 \babc[∧\w]← -pattern -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 Mars
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 exampleWe need to create a class with the 3 basic functions, the <List> function:
:Class dates⎕IO←1 ⋄ ⎕ML←1∇ r←List:Access Shared Public 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 exampleThe HELP function:
∇ r←Help dummy:Access Shared Public r←'Enter a month as argument' ∇
UCMDs – an exampleThe RUN function:
∇ r←Run(a1 a2):Access Shared Public 'calendar' ⎕CY 'myutils' r←calendar ⍎a2∇ :endclass
UCMDs – an exampleBecause each class may contain
more than one UCMD the HELP and RUN functions should really account for that.
UCMDs – an example• HELP function for more than one command:∇ r←Help Cmd:Access Shared Public:Select Cmd:Case 'cal'r← 'Enter a month as argument':Case 'other'… :EndSelect∇
UCMDs – an example• The RUN function for more than one
command:∇ r←Run(Cmd Args):Access Shared Public:Select Cmd:Case 'cal''calendar' ⎕CY 'myutils'r←calendar ⍎Arguments: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 tell 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 in <Run> will contain a namespace:
UCMDs – Parsing∇ r←Run(Cmd a2):Access Shared Public:Select Cmd:Case 'cal''calendar' ⎕CY 'myutils'r←calendar ⍎1⊃a2.Arguments:EndSelect∇Function <calendar> can also/should be defined in
the class.
UCMDs – an example ]cal 3 Mars
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 exampleIf Parsing is enabled, entering the wrong
number of arguments will be refused:]cal
Command Execution Failed: too few arguments
]cal 2 3 Command Execution Failed: too many arguments
UCMDs locationThe 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 locationThe 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=- Maybe with a value: /sw[=]The specification for each includes the
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 Arguments
If 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 – Exercices1. Write a UCMD to display the time,
formatted2. Write a UCMD to display the time
in another city
]END