Cross APL Transfer functions
Introduction
The transfer functions in workspace 'xfrpc'
allow transferring objects, workspaces and files between major APLs. The
following text applies to version 3.0 rolled out April 2003.
This can come in handy when porting code from
one APL to another or to go back to a previous version of the same APL.
Conventions
In the following text, italicized
words have a special meaning. The character '^' represents the APL character delta,
'%' represents the APL character delta underscored, the sequence '[]'
represents the APL character quad and examples of lines of code are
written in evenly spaced font like "Courier New".
Some acronyms are used: SAPL is SHARP
APL, SAM is SAPL on the mainframe, SAX is SAPL under UNIX.
History
The code was originally written in 1984 to
port functions and variables between APL PLUS/PC and SHARP APL when workspaces
were of very small size and only simple types were available. It has then
evolved and been rewritten to support some of the more popular APLs with their
newer data types.
Syntax
They use a common syntax consisting of a list
of arguments followed by some switches. The arguments are separated by spaces
and the switches start with a forward slash (‘/’) as in
[arg0] Function
'arg1 arg2 /switchA /switchB'
The use of the switches is strict. Some
switches take a value, some may and some don't. The order in which they are
specified is unimportant. Only the minimum number of letters needed to describe
uniquely a switch can be used.
For example, if both '/replace' and '/range'
are possible switches, then '/re' is sufficient to mean '/replace'. '/r' isn't
as it could also mean '/range'. If there is any conflict of any sort the parser
will signal an error.
Method
The method used consists of writing out to a
native file, without ANY translation, a representation of variables and
functions in ravel order.
The variables' information includes total
length of the representation, class, name length, name, rank, shapes and data.
Functions and operators are first put in canonical representation then written
to file in the same format as a variable.
Classes
At present the transfer functions will accept
variables of type strictly character (C), strictly numeric (N),
both or mixed (M), any element enclosed (E), undefined ('?'), packages,
namespaces or overlays (P), operators, functions and dynamic functions
(F).
[]AV mapping
Upon reading back the native file the stream
is first translated to account for the source APL's []AV positions. Characters
that do not exist in one APL have been attributed another character in all
other APL in order for the mapping to work. Some of these attributions are
arbitrary.
Code translation
As functions are read back some code
modifications can be performed, if this was specified on the command line, and
an attempt is made at redefining it. If this fails the function's definition is
stored in a variable of the same name as the desired function, preceded by a
‘delta underscored’ (%). For example, a failure to produce function <FOO>
would produce variable '%FOO' which can be inspected later.
Usage
There are basically two functions to perform
the transfer, one to write out the objects to file and one to read them back.
They both will write and read a subset of a file or workspace.
These functions exist for the following APLs:
[nl] ^xfrto
'target'
This function takes a string argument
describing the name of native file to write to, including any path where access
is granted to write, and some switches to modify its behavior. These switches
are
/file |
the source will be an APL file of the same name as the native file |
/file=xy /lock= |
the source will be an APL file named
<xy> the file lock to use, if any |
/range=n |
the APL file component to transfer is 'n' |
/range=n1,n2 |
the APL file components to transfer range from 'n1' to 'n2' |
/q |
quiet, do not display version number message |
If /file is not specified the contents
of the current workspace is used. If the left argument describing the names to
transfer is not specified (for workspaces only) then all objects in the
workspace, including []io, []ct, []lx and []pw, are used. This namelist
can be specified as a space-delimited string or as a table (matrix) of names.
The function will always try to write the
access matrix of a file.
The function will return a string indicating
the number of objects put on file.
^xfrfrom
'source'
This function takes a string argument
describing the name of native file to read from, including any path where
access is granted to read, and some switches to modify its behavior. These
switches are
/apl= |
the source APL. Valid values are SAM, SAX, DYW (Dyalog APL), APX (AplX) and A2K (APL2000 family). If not specified, the file extension is used to determine the source (see Technicalities, below). Case insensitive. |
/list |
show what would be changed only. Do not make any changes. |
/objs= |
for workspaces only: the object classes to define. The value can be any of 'pmencfo' (Packages, Mixed, Enclosed, Numeric, Character, Function and Operator). Case insensitive. |
/file |
the target will be an APL file of the same name as the native file (without the extension) |
/file=xzy |
the target will be an APL file named <xyz> |
/noam |
the access matrix is NOT to be transferred |
/range=n |
the APL file component to transfer is 'n' |
/range=n1,n2 |
the APL file components to transfer range from 'n1' to 'n2' |
/replace |
objects (variables or components) will be replaced if they already exist. |
/trans |
same as /trans=1 |
/trans=X |
perform code translation. X=0 means do NOT translate. This is the same as not using the /trans switch. X=1 means perform translation and X=2 means perform translation, produce a '^AV' variable containing the source []AV and replace all occurrences of []AV by ^AV. |
/q |
quiet, do not display version number message |
The function will return how many objects
were defined.
NOTE: if a file containing a workspace was
used (extension ends with 'w') then all the transfer code will be expunged
automatically at the end of the function call to create a 'clean' workspace
(except for SAM, see below) unless '/list' was specified in the argument or no
objects were defined.
Examples
Export 3 objects under any APL:
'abc def zzzzz'
^xfrto 'my3objs'
Move an entire workspace under Windows (or DOS):
^xfrto
'c:\apl\temp\myws'
Transfer quietly components 12 to 99 of file
<myfile> to (DOS) diskette using lock 314159:
^xfrto
'a:exportfile /q /range=12,99 /f=myfile /lock=314159'
Read back 3 objects produced under SAX and
erase the transfer code:
^xfrfrom
'\usr\home\danb\my3objs.xuw (note backward slash same as Windows/DOS)'
List what would defined if we were to
replace:
^xfrfrom
'my3objs.xuw /rep /l'
Read back all functions in <myws>
produced under APL+Win and erase the transfer code:
^xfrfrom
'c:\apl\temp\myws.xsw /obj=fns /rep'
Read back components 50 to 150 in backup.xmf
(SAM) into APL file <dir>. Apply special translation 2. Do not bring back
the access matrix. Do not show the version number:
^xfrfrom
'e:\danb\backup.xmf/ra=50 150/f=dir/tr=2/n/re/q'
Other functions
^all |
returns a list of names excluding the transfer group's names but including some system variables like []lx |
^forme |
takes an object name and produces a representation for it |
^create |
takes a representation and produces an object from it |
^xfr |
calls ^forme for each of the names given as argument and returns them all together |
Restrictions and notes
Locked functions cannot be transferred. They
go out as {locked del}.
Dyalog APL’s dynamic fns, inline functions (ex:
sum {is} +/) and []or of fns will be recreated but function reassignment (fn1
{is} fn2) will not. []OR of windows objects are written out as variables
containing the string ‘GUI object’. They will create problems in any APL.
System variables in namespaces are NOT
written out.
All the code specific to an interpreter
cannot be automatically translated (ex: Windows' calls).
System variables will crash (often with a
syntax error) the redefining code if they are not supported in the target
environment.
Under SAM (SHARP APL for the mainframe) the
automatic expunge of the translation code will miss the <^xfrfrom>
function because '[]ex' doesn’t work on fns on the stack in that APL. A
message reminding you of this fact appears after the function call.
Some representations cannot be honored. For
example, in SHARP APL a variable containing an enclosed simple scalar like
<42 will end up as the scalar 42 under any APL using strand notation (like
APL+Win). Also, the vector (9 'dsa') under APL+Win will end up as (<9),<'dsa'
under SAM. Complex numbers will also crash the code in non SAM.
This version does not make any difference
between a function and an operator. Both are classified as 'F'.
This version does not allow to specify a path
in Unix with '/' as it conflicts with the switches' leading '/'. Instead you
must use '\' as in DOS/Windows.
This version uses []CR to represent
functions. This usually means more space is required but it is supported by all
APLs
Technicalities
To minimize name clashing all functions start
with a delta. Where relevant, the source code has been modified to
remove labels and change locals to follow a naming convention. The resulting
generated code is quite unreadable at this point.
The code has been tested under all supported
APLs (SAM, SAX, Dyalog APL, AplX and APL+Win) using code coverage where
possible and a suite of tests to validate the above claims.
Under SHARP APL for the mainframe (SAM) two
options for transferring the code out exist: write the code to a PC if a proper
terminal emulator or session manager allows it (like PC328 or RC108) or use
TSIO to produce a file on the mainframe which can then copied elsewhere. All
workspaces contain code to write character strings out of APL.
The name of the native file produced will
have a 3-letter extension describing its contents:
.xuw is
a file containing a Unix (SAX) Workspace
.xmw is
a file containing a Mainframe (SAM) Workspace
.xdw is
a file containing a Dyalog APL Workspace
.xsw is
a file containing a APL+Win Workspace (former STSC)
.xpw is
a file containing a AplX Workspace
.xuf is
a file containing a Unix (SAX) File
.xmf is
a file containing a Mainframe (SAM) File
.xdf is
a file containing a Dyalog APL File
.xsf is
a file containing a APL+Win File (former STSC)
.xpf is
a file containing a AplX APL File
This extension is used to determine the
source APL and the translation to apply. If this extension is wrong or
non-existent you can specify the source APL with the /apl= switch.
NOTE: there is little checking done throughout the code. If wrong arguments
are provided (for ex: bad object name or file) the code will fail ungracefully.
Code Translation
The code translation method consists in
listing expressions to be replaced by another. There is a variable in the
workspace, '^equivalence', which describes what these expressions are.
Its format is a series of sections of this format:
:APLCODE
text1%replace1
test2%replace2
etc.
The first line describes the APL (SAM, SAX,
DYW or A2K) it applies to. The other lines are one-to-one non-overlapping
replacements. For example, '[]DEF', under APL+Win would become '3 []fd' under
SAPL (SAM or SAX). This variable can be edited to suit better your needs.
Sometimes the translation produces a statement that will interpret properly but
cause problems further down the code. For example, APL+Win's '[]elx'
will be translated into SAPL's '[]trap'. This will allow functions to be
fixed if it appears in the header but won't make error trapping work later in
the code.
Enhancements
There is a project in the works to include
code specified in curly bracket syntax notation using only ASCII characters. At
present (2003-04-12) this has not been completed.
Disclaimer
Although this code has been widely used and a
lot of testing done on it there is no warranty of any sort that it will perform
as described. Read this for details.
DanB 2002.