Similar presentations

2
Agenda This tutorial is divided into 4 steps: -Why UCMDs -Dyalog's UCMDs -Implementation of the UCMD framework -Your UCMDs: how to write them

3
Why The idea is to provide a mechanism for accessing tools anywhere by -separating utilities from the workspace -make them available at any time

4
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

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

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

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

9
User Commands - syntax This is Dyalog's implementation. UCMDs could take any format. WE decide what is acceptable.

11
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 APLDyalog’11 - Boston11

12
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 APLDyalog’11 - Boston12

14
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 1 st argument to, if present, the location named in the 2 nd argument. Ex: ]save myfn \my\location\myfn To bring the object back use the command ]LOAD: ]load my\location\myfn

15
User Commands - Help General help can be obtained with ]?? Or ]help 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

19
Group svn This 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

20
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

21
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

22
Groups Tools & WSutils These 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

23
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’

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

25
UCMDs - implementation The whole framework is based on 2 things: -SALT: used to read/write Unicode text files -Spice: used to implement the rules of UCMDs

34
UCMDs – Parsing If 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 2 nd argument to the function. To request parsing simply put in 'Parse' (in function ) the rules to follow, e.g. '3' to ensure 3 arguments. If no parsing is desired simply leave 'Parse' empty.

35
UCMDs – Parsing If we wish the system to check the number of arguments (here 1) for us we say it in : ∇ r←List :Access Shared Public r← ⎕ NS¨1 ⍴⊂⍬ ⍝ Name, group, short description and parsing rules r.Name← ⊂ 'cal' r.Group← ⊂ 'dates' r.Desc← ⊂ 'returns the calendar for a given month' r.Parse← '1' ∇ In that case the 2nd argument of will contain a namespace but only AFTER the framework has ensured only ONE argument has been supplied.

40
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

41
UCMDs location You 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

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

45
UCMDs – Advanced Topics Debugging code ]udebug ON|OFF When debugging is OFF errors are reported in the calling environment: Command Execution Failed: DOMAIN ERROR When debugging is ON errors are reported in the class: DOMAIN ERROR calendar[4] r←n÷month ∧

46
UCMDs – Advanced Topics Switches Those 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 /)

47
UCMDs – Advanced Topics Switches A set of possible values may be specified, e.g. /animal=cat monkey giraffe A set of possible characters can also be specified: /vowel ∊ aeiou Or /vowel [ ∊ ] aeiou If the switch can be specified without a value

49
UCMDs – Advanced Topics Switches – Examples Switches 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='

50
UCMDs – Advanced Topics Arguments Arguments 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

51
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'

52
UCMDs – Advanced Topics Short Arguments If 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.

53
UCMDs – Exercices 1.Write a UCMD to display the time, formatted 2.Write a UCMD to display the time in another city