1. Oct 2011 1 SALT in Dyalog Doc v1.18

2. Oct 2011 2 Introduction SALT is a Simple APL Library Toolkit It is a source code management system for objects with a representation in Dyalog APL.

3. Oct 2011 3 Basics -SALT consists in a series of functions stored in []SE to manipulate the source ([]SRC/[]CR) of objects. -The source code for each object (function or namespace) is stored in a single Unicode text file with a file extension of “.dyalog”. -All functions take a string to do their work. -This string describes the arguments and possibly some -modifiers for the function

4. Oct 2011 4 Commands All SALT functions are monadic. They -Save objects in files -Load them -List files -Explore them -and more…

5. Oct 2011 5 SALT stores source in Unicode (UTF-8) files whose extension is.Dyalog.Dyalog files are configured to be opened automatically with Notepad under Windows upon installation Under Unix, the naming of the files is case sensitive. Storage

6. Oct 2011 6 Requirements There are NO special requirements (not even.Net) V11 is the minimum version SALT will run under SALT is packaged and comes in already available with APL.

7. Oct 2011 7 Enabling SALT in V12 By default SALT is enabled when V12 is installed. To disable SALT you can use the configuration menu.

8. Oct 2011 8 Enabling SALT in V13 The configuration menu:

9. Oct 2011 9 Some SALT registry keys The registry key HKEY_CURRENT_USER\Software\Dyalog\Dyalog APL/W 12.0\SALT contains some keys which must be specified a value: ValueDefault SettingWhat is it? AddSALT0Controls whether SALT is initialized when the session file is loaded. CompareCmdAPLSpecifies how to call a file comparison utility. SourceFolder[Dyalog]\SALTSpecifies folders for source files separated by ";". Default folder is located below the main Dyalog folder. EditorCMDnotepad.exeSpecifies which program to run to edit script files outside APL

10. Oct 2011 10 Enabling SALT The registry key HKEY_CURRENT_USER\Software\Dyalog\Dyalog APL/W 12.0\SALT\AddSALT MUST have the value ‘1’ for SALT to be enabled. Once this key is set all subsequent sessions will have SALT enabled until this key is changed back to ‘0’ (not ‘1’)

11. Oct 2011 11 Enabling SALT You can also use the included SALT workspace to enable or disable SALT: )load SALT enableSALT disableSALT

12. Oct 2011 12 Starting SALT Upon starting Dyalog SALT will identify itself:

13. Oct 2011 13 Storing using SALT We can now store any sourced object:

14. Oct 2011 14 The Save function Save takes a string as argument. To find its syntax give it a single ‘?’:

15. Oct 2011 15 The Save function Ask SALT to store it in a specific path:

16. Oct 2011 16 The Save function Ask SALT to store it in a relative path: mine\test’ C:\Program Files\Dyalog\V12\SALT\mine\test.Dyalog

17. Oct 2011 17 Storing using SALT By default SALT will store the source under [Dyalog]\SALT where [Dyalog] is the installation location. SALT will replace [Dyalog] by whatever location Dyalog is installed.

18. Oct 2011 18 Storing using SALT Here Dyalog was installed under C:\Program Files\Dyalog\V12 and the installation location was [Dyalog]\SALT so the sources will all be stored under C:\Program Files\Dyalog\V12\SALT Since we asked to store test under mine\test the final path, after adding the extension, is C:\Program Files\Dyalog\V12\SALT\mine\test.Dyalog

19. Oct 2011 19 Storing using SALT If a different location is desired the workdir setting must be modified to specify the location. For example you could decide that all scripts go under \CMS\DYW instead of the default

20. Oct 2011 20 Viewing the file in Notepad Double click the file opens with Notepad

21. Oct 2011 21 Listing folder contents List takes a pathname as argument and displays its contents:

22. Oct 2011 22 Listing folder contents Example, list the contents of study\GUI:

23. Oct 2011 23 Listing folder contents Example, list Samples recursively:

24. Oct 2011 24 Explore Explore allows you to look at a script with an external editor or to browse using the OS’ explorer:

25. Oct 2011 25 Exploring folders Exploring a folder merely opens up the disk Explorer. Example, exploring folder Samples:

26. Oct 2011 26 Exploring folders Example, exploring folder Samples\GUI:

27. Oct 2011 27 Exploring files Exploring a file opens up the file with Notepad. Example, exploring file Samples\GUI\Othello:

28. Oct 2011 28 Exploring files Notepad is the program used by default. To change this use the SALT setting editor, e.g. []SE.SALT.Setting ’editor...\WordPad’ To use another program for just this time use the modifier –use with the name of the program to use e.g. []SE.SALT.Explore’Othello –use=...\WordPad’

29. Oct 2011 29 Loading from file Objects can be brought back from file through the use of Load:

30. Oct 2011 30 Loading from file By default objects are brought in the current namespace. To select a different namespace use the –target modifier:

31. Oct 2011 31 Loading from file By default all the functions and variables in a namespace are kept in their namespace: WS ob1ob2 Target=# ob1ob2

32. Oct 2011 32 Loading from file To bring them separately you can use the –disperse modifier: WS ob1ob2 Target=# ob1ob2 Specific elements can be selected

33. Oct 2011 33 Loading from file You can bring several files at once using a pattern: WS Fn1 Fn2 Target=# fn1fn2 []SE.SALT.Load ‘Fn*’

34. Oct 2011 34 Settings Some functions assume global settings, e.g. Explore assumes Notepad to view files. Settings come from the registry and are brought into the session at start-up. They can be modified for the session or even for the time a function is used. Modifications can be saved back for the next APL session.

35. Oct 2011 35 Settings A particular setting has a name and a value, just like in the registry. The value can only be a string. It may be empty.

36. Oct 2011 36 Settings This function takes ‘’ or ‘a_name’ or ‘a_name followed by a value’. With ‘’ it returns all the settings and their values:

37. Oct 2011 37 Settings With a_name it returns the value associated with that particular setting name. Here the path to the editor to use:

38. Oct 2011 38 Settings With a name & value it associates the value with the name. Here we change the editor setting to use for the session to “WordPad”:

39. Oct 2011 39 Settings RegistryWs The settings can be permanently stored in the registry using the –permanent modifier:

40. Oct 2011 40 Settings The settings can be restored from the registry using the –reset modifier: RegistryWs

41. Oct 2011 41 Settings Settings can also be overridden temporarily for the duration of a statement, for example to use another editor temporarily while exploring:

42. Oct 2011 42 Features SALT has a number of features that make it more interesting than a simple store and retrieve utility. It can -save entire workspaces at once -store several versions of a script -compare them -remove versions -run scripts without fixing them in the ws -start automatically

43. Snapping workspaces Instead of using Save to store each function/namespace in the workspace you can use to do the work: []SE.SALT.Snap ‘\my\location’ Will store everything to \my\location, one script per function/namespace. Oct 2011 43

44. Snapping workspaces sections can be used on a subset: All namespaces: []SE.SALT.Snap ‘\my\scripts –class=9’ All objects starting with the letter ‘U’: []SE.SALT.Snap ‘\my\utils –pattern=U*’ All (remaining) functions: []SE.SALT.Snap ‘\my\fns –class=3 ’ Oct 2011 44

45. Oct 2011 45 Class 3 U* Class 9 Snapping workspaces sections My/scripts My/utils My/fns

46. Snapping workspaces Oct 2011 46 remembers what has been saved and won’t save again what hasn’t been modified. It also remembers where objects have been saved so “Snapping” again will put only changed objects where they belong.

47. Oct 2011 47 Storing several versions of a script SALT can save back a script on file right after it has been modified. After modification you are prompted to confirm saving over the present script file: Modify

48. Oct 2011 48 Storing several versions of a script This also happens if you modify a fn of a class on the stack. After modification you are prompted to confirm saving over the present script file. Once saved both the script and the class are modified and you can resume execution. Error happens Stack shows up Edit the function

49. Oct 2011 49 Keeping several versions of a script You can store and KEEP several versions of a script. By using the –version modifier you tell SALT to start using version numbering:

50. Oct 2011 50 Keeping several versions of a script Every time you modify a script SALT stores the definition in a new file: V0V1

51. Oct 2011 51 Keeping several versions of a script List can show the various versions: To see all the versions you need to supply the –version modifier: If listed without -version the display shows the number of versions The latest (using date) version is always visible and on top 3 3

52. Oct 2011 52 Comparing versions Compare is used for that. You must give it the name of the script(s) and the versions to compare. If no version is specified the 2 highest versions are used. If a single number is specified it is compared with the highest version. Ex: []SE.SALT.Compare ‘fileA –version=5’ will compare version 5 of with its highest version (probably also most recent) =?

53. Oct 2011 53 Comparing versions Normally, Compare will use its own code to perform the comparison. If a different program is wanted it should either be specified on the statement line with the –use modifier or in the settings. The Setting to use then is compare It should specify the path of the program to use or ‘APL’ if SALT is to do it itself. =?

54. Oct 2011 54 Comparing versions externally For example, to use Compare It!, a third party program available from the net, you can use the SALT command Settings to set it to [ProgramFiles]\Compare It! or the full pathname to its location =?

55. Oct 2011 55 Comparing versions externally You can also insert -use=pathnameToProgram to call said program in the statement, e.g: =?

56. Oct 2011 56 Comparing versions externally =? External program pops up automatically

57. Oct 2011 57 =? Showing differences between versions If ‘APL’ is the method chosen to compare, the output will appear in the session like this: lines inserted lines modified → is used to denote inserted lines ← is used to denote deleted lines

58. Oct 2011 58 =? Showing differences between versions If the object to be compared is already in the workspace you can use ws as value to the –version switch: []SE.SALT.Compare 'script\file –version=ws'

59. Oct 2011 59 Cleaning up (removing versions) After a while many versions may clutter a folder and some versions may get ridden of. SALT allows to selectively erase files. RemoveVersion is the function to use, like this:

60. Oct 2011 60 Cleaning up (removing versions) To remove less than a version (e.g.7) you can use -version=, etc) To remove them all instead use -all Note that -all leaves 1 version (the highest version) around which it renames to remove the version number. If 4 is the highest mine\test.4.dyalog becomes mine\test.dyalog

61. Oct 2011 61 Cleaning up (removing versions) The collapsing effect of -all can be achieved with higher versions by using -collapse: The last file of the group deleted has been given the next version number and renamed accordingly.

62. Oct 2011 62 Running code When files are Loaded into the ws their objects become ready to be used. For example, if file mine\testB contains class TB then this class can be used immediately as in

63. Oct 2011 63 Running scripts Sometimes a different name is needed. Load can be instructed to return a class instead of fixing it in the ws by using the -noname modifier:

64. Oct 2011 64 Running code Sometimes it is unnecessary to bring in the class when only an instance is needed. New uses internally Load’s -noname modifier to achieve that:

65. Oct 2011 65 Automatic start SALT also supports the loading and starting of applications from an “application file” with an extension of “.dyapp”.

66. Oct 2011 66 Automatic start You put in the dyapp file the instructions to perform the task: all the loads and 1 run statement. e.g.:

67. Oct 2011 67 Other goodies -SALT allows to have multiple working directories -can perform the required loads automatically -has external utilities -works with Spice

68. Oct 2011 68 Multiple workdirs You can have several working directories to split work into logical areas. For ex: you could put all utilities in a separate tree. To tell SALT to use different directories you use the SALT settings workdir with each directory separated by ;, e.g. [Dyalog]\SALT;\CMS\DYW

69. Oct 2011 69 Multiple workdirs When using Load, SALT searches directories in the order specified until it finds the file You can also make this Settings permanent:

70. Oct 2011 70 Required Loads SALT allows required loads to be done automatically. For example, if script A needs script B to be present, A can specify in the code that B be Loaded before A is loaded

71. Oct 2011 71 Required Loads Example:

72. Oct 2011 72 Utilities These are not part of SALT but were created with SALT. They are located under Tools:

73. Oct 2011 73 Utilities: CallingTree This utility allows to view the calling tree of a fn in a namespace or to cross-reference all the functions and their references. To use do z← ⎕ new CallingTree ‘file\class -options’ z.Calls ‘ctor -view’ ⍝ show calls from or z.View ⍝ to view → z.Xref ⍝ produce a cross-reference

74. Oct 2011 74 Utilities: fileUtils This file contains a namespace with fns to e.g. traverse a directory tree using.Net Fn allows to show regular expressions in text (& Unicode) files, e.g. ‘\temp -type=php -rec’ showExpr ‘\bA.*= *123\b’ will show names starting with ‘A’ being assigned the number 123 in PHP files under \temp, recursively.

75. Oct 2011 75 Utilities: Regex This regexMatch class allows to create a Regex.Net instance given a pattern and possibly options. The options are m=multiline (default), s=singleline, i=case insensitive The pattern accepts ⍺ as APL name and ⍵ as a number, e.g. ⍺ ⍺ ← ⍵ ⍵ means 2 names assigned 2 numbers

76. Oct 2011 76 Utilities: compare This namespace contains functions to perform comparison. Function produces a report of the differences between 2 lists of strings, e.g. ([]NR ‘Fa’) compecv ([]NR ‘Fb’) will compare 2 functions and show where lines have been deleted, inserted and changed

77. Oct 2011 77 Utilities: NStoScript This namespace found in Lib contains functions to perform conversion of namespaces to []SRC format. Function takes the name of a namespace and changes it into sourced mode, e.g. NStoScript.Convert mynamespace will convert it. You can then edit it and store it using SALT

78. Oct 2011 78 AKA

79. Oct 2011 79 Spice Utilities Spice is a utility working in conjunction with SALT. It is the framework of the User Commands It uses SALT to load code (commands) and execute it. Spice is always available.

80. Oct 2011 80 Spice Utilities Spice can also be started automatically by setting SALT registry key AddSPICE to ‘1’

81. Oct 2011 81 Enabling SPICE in V12 The configuration menu:

82. Oct 2011 82 Enabling SALT You can also use the included SALT workspace to enable or disable SPICE: )load SALT enableSPICE disableSPICE

83. User commands User commands are called using a right bracket syntax like system commands which use a right parenthesis syntax, e.g. )load workspaceX ]load scriptX Oct 2011 83

84. Oct 2011 84 Spice Utilities To get a list of all available commands you enter ]? in the session:

85. Oct 2011 85 Spice Utilities: File FIND text find regex strings in SALT files, e.g.: ]ffind abc>0 ]ff \bd\w*g\b to find where are found names starting with ‘d’ and ending with ‘g’ in the files managed by SALT ]freplace does the replacement.

86. Oct 2011 86 Spice Utilities: props ]props f returns the properties of object f and their values It also shows its ChildList and its EventList

87. Oct 2011 87 Spice Utilities: SALT commands All the SALT commands but New can be issued here, e.g.: ]save name file ]compare file1 -ver=4 ]list mine ]settings ]load myfile ]removeversions filex -v=<9

88. Oct 2011 88 Spice Utilities: fndiff This command compare 2 functions in the workspace. This is the Dfn implemented as a SPICE command: ]fndiff fnA fnB

89. Oct 2011 89 Spice Utilities: fncalls This command shows the calls made by a fn in a namespace or a script, e.g.: ]fncalls myfile fn -file The output can be simple (fns only) or detailed showing if elements are local, global, glocal, labels, used, etc. It takes into account ⍎, []TRAP strings, etc. The output can be viewed in a tree object.

90. Oct 2011 90 Spice Utilities: fncalls example Show the details of calls made by fn Run in file spice\Props. o is local ! is unused local G is global F is function

91. Oct 2011 91 Spice Utilities: fncalls example Same example viewed in a tree objects by adding -tree to the command

92. Oct 2011 92 Spice Utilities: summary This command allows to see the scope (Public, Shared, Ctor, Dtor), size and syntax of functions in a class or file.

93. Oct 2011 93 Spice Utilities: xref This command shows a cross-reference of all the objects made by all the fns in a script, e.g.: ]xref file The symbols are the same as in fncalls

94. Oct 2011 94 Spice Utilities: compare There are 3 commands to compare objects: ]fncompare : compare 2 functions ]varcompare : compare 2 variables ]wscompare : compare 2 workspaces They all have similar switches

95. Oct 2011 95 Spice Utilities: wsloc This command allows you to locate text in the workspace. It can also perform replacements. For full details see ]??wsloc

96. Oct 2011 96 Final SALT & SPICE are tools. They can be used as a start point to maintain code and small applications. Scripted namespaces and classes provide new ways to make code sharing easier. SALT provides a way to do this.

97. Oct 2011 97 Short Final More information can be found in the SALT document. Dyalog 2011