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

Oct 2011 1

SALT in Dyalog

Doc v1.18

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.

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

Oct 2011 4

CommandsAll SALT functions are monadic. They

- Save objects in files- Load them- List files- Explore them- and more…

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

Oct 2011 6

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

Oct 2011 7

Enabling SALT in V12By default SALT is enabled when V12 is

installed.

To disable SALT you can use the configuration menu.

Oct 2011 8

Enabling SALT in V13The configuration menu:

Oct 2011 11

Enabling SALTYou can also use the included SALT

workspace to enable or disable SALT:)load SALTenableSALTdisableSALT

Oct 2011 13

Storing using SALTWe can now store any sourced object:

Oct 2011 14

The Save functionSave takes a string as argument. To find

its syntax give it a single ‘?’:

Oct 2011 15

The Save functionAsk SALT to store it in a specific path:

Oct 2011 16

The Save functionAsk SALT to store it in a relative path:

mine\test’

C:\Program Files\Dyalog\V12\SALT\mine\test.Dyalog

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.

Oct 2011 18

Storing using SALTHere Dyalog was installed underC:\Program Files\Dyalog\V12 and the installation

location was [Dyalog]\SALT so the sources will all be stored under

C:\Program Files\Dyalog\V12\SALTSince we asked to store test under mine\test the

final path, after adding the extension, isC:\Program Files\Dyalog\V12\SALT\mine\test.Dyalog

Oct 2011 19

Storing using SALTIf 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

Oct 2011 20

Viewing the file in Notepad

Double click the file opens with Notepad

Oct 2011 21

Listing folder contentsList takes a pathname as argument and displays its contents:

Oct 2011 22

Listing folder contentsExample, list the contents of study\GUI:

Oct 2011 23

Listing folder contentsExample, list Samples recursively:

Oct 2011 24

ExploreExplore allows you to look at a script with an

external editor or to browse using the OS’ explorer:

Oct 2011 25

Exploring foldersExploring a folder merely opens up the disk

Explorer.Example, exploring folder Samples:

Oct 2011 26

Exploring foldersExample, exploring folder Samples\GUI:

Oct 2011 27

Exploring filesExploring a file opens up the file with Notepad.Example, exploring file Samples\GUI\Othello:

Oct 2011 28

Exploring filesNotepad 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’

Oct 2011 29

Loading from fileObjects can be brought back from filethrough the use of Load:

Oct 2011 30

Loading from fileBy default objects are brought in the current

namespace. To select a different namespace use the –target modifier:

Oct 2011 31

Loading from fileBy default all the functions and variables in a

namespace are kept in their namespace:

WS

ob1 ob2

Target=#

ob1 ob2

Oct 2011 32

Loading from fileTo bring them separately you can use the –

disperse modifier:

WS

ob1 ob2

Target=#

ob1 ob2

Specific elements can be selected

Oct 2011 33

Loading from fileYou can bring several files at once using a

pattern:

WS

Fn1

Fn2

Target=#

fn1 fn2

[]SE.SALT.Load ‘Fn*’

Oct 2011 34

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

Oct 2011 35

SettingsA particular setting has a name and a value,

just like in the registry.

The value can only be a string. It maybe empty.

Oct 2011 36

SettingsThis function takes ‘’ or ‘a_name’ or ‘a_name

followed by a value’. With ‘’ it returns all the settings and their values:

Oct 2011 37

SettingsWith a_name it returns the value associated

with that particular setting name. Here the path to the editor to use:

Oct 2011 38

SettingsWith a name & value it associates the value

with the name. Here we change the editor setting to use for the session to “WordPad”:

Oct 2011 39

Settings

RegistryWs

The settings can be permanently stored in the registry using the –permanent modifier:

Oct 2011 40

SettingsThe settings can be restored from the registry using the –reset modifier:

RegistryWs

Oct 2011 41

SettingsSettings can also be overridden temporarily for the duration of a statement, for example to use another editor temporarily while exploring:

Oct 2011 42

FeaturesSALT 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

Snapping workspacesInstead of using Save to store each

function/namespace in the workspace you can use <Snap> to do the work:

[]SE.SALT.Snap ‘\my\location’

Will store everything to \my\location, one script per function/namespace.

Oct 2011 43

Snapping workspaces sections

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

Oct 2011 45

Class 3

U*

Class 9

Snapping workspaces sections

My/scripts

My/utils

My/fns

Snapping workspaces

Oct 2011 46

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

Oct 2011 47

Storing several versions of a scriptSALT can save back a script on file right

after it has been modified.

After modification you are promptedto confirm saving over the present

script file:

Modify <test>

Oct 2011 48

Storing several versions of a scriptThis also happens if you modify a fn of a

class on the stack.

After modification you are prompted toconfirm 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 upEdit the function

Oct 2011 49

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

Oct 2011 50

Keeping several versions of a scriptEvery time you modify a script SALTstores the definition in a new file:

V0 V1

Oct 2011 51

Keeping several versions of a scriptList can show the various versions:

To see all the versions you need to supply the –version modifier:

If listed without -versionthe display shows thenumber of versions

The latest (using date) versionis always visible and on top

3

3

Oct 2011 52

Comparing versionsCompare 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 <fileA> with its highest

version (probably also most recent)

=?

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 compareIt should specify the path of the program to

use or ‘APL’ if SALT is to do it itself.

=?

Oct 2011 54

Comparing versions externallyFor 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

=?

Oct 2011 55

Comparing versions externallyYou can also insert -use=pathnameToProgram to call said

program in the statement, e.g:

=?

Oct 2011 56

Comparing versions externally=?

External program pops up automatically

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 denoteinserted lines

← is used to denotedeleted lines

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

…

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:

Oct 2011 60

Cleaning up (removing versions)To remove less than a version (e.g.7) you can use-version=<7 (or >, etc)To remove them all instead use-allNote 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 becomesmine\test.dyalog

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 thenext version number and renamed accordingly.

Oct 2011 62

Running codeWhen 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

Oct 2011 63

Running scriptsSometimes 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:

Oct 2011 64

Running codeSometimes it is unnecessary to bring in the

class when only an instance is needed.New uses internally Load’s -noname modifier

to achieve that:

Oct 2011 65

Automatic start

SALT also supports the loading and starting of applications from an “application file” with an extension of “.dyapp”.

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

Oct 2011 67

Other goodies

- SALT allows to have multiple working directories

- can perform the required loads automatically

- has external utilities- works with Spice

Oct 2011 68

Multiple workdirsYou 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

Oct 2011 69

Multiple workdirsWhen using Load, SALT searches

directories in the order specified until it finds the file

You can also make this Settings permanent:

Oct 2011 70

Required LoadsSALT 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

Oct 2011 71

Required LoadsExample:

Oct 2011 72

UtilitiesThese are not part of SALT but were created

with SALT. They are located under Tools:

Oct 2011 73

Utilities: CallingTreeThis 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 <ctor> or⍝z.View to view →⍝z.Xref produce a ⍝

cross-reference

Oct 2011 74

Utilities: fileUtilsThis file contains a namespace with fns to e.g.

traverse a directory tree using .NetFn <showExpr> 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.

Oct 2011 75

Utilities: RegexThis 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

Oct 2011 76

Utilities: compareThis namespace contains functions to perform

comparison.Function <compecv> 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

Oct 2011 77

Utilities: NStoScriptThis namespace found in Lib contains

functions to perform conversion of namespaces to []SRC format.

Function <Convert> 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

Oct 2011 78

AKA

Oct 2011 79

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

User commandsUser 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

Oct 2011 84

Spice UtilitiesTo get a list of all available commands you

enter ]? in the session:

Oct 2011 85

Spice Utilities: File FIND textfind 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.

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

Oct 2011 87

Spice Utilities: SALT commandsAll 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

Oct 2011 88

Spice Utilities: fndiffThis command compare 2 functions in the

workspace. This is the Dfn <fndiff> implemented as a SPICE command:

]fndiff fnA fnB

Oct 2011 89

Spice Utilities: fncallsThis 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.

Oct 2011 90

Spice Utilities: fncalls exampleShow the details of

calls made by fn Run in file spice\Props.

o is local! is unused localG is globalF is function

Oct 2011 91

Spice Utilities: fncalls example

Same example viewed in a tree objects by adding -tree to the command

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.

Oct 2011 93

Spice Utilities: xrefThis command shows a cross-reference of

all the objects made by all the fns in a script, e.g.:

]xref fileThe symbols arethe same as infncalls

Oct 2011 94

Spice Utilities: compareThere are 3 commands to compare objects:]fncompare : compare 2 functions ]varcompare : compare 2 variables ]wscompare : compare 2 workspaces They all have similar switches

Oct 2011 95

Spice Utilities: wslocThis command allows you to locate text in

the workspace. It can also perform replacements.

For full details see ]??wsloc

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.

Oct 2011 97

Short Final

More information can be found in the SALT document.

Dyalog 2011