Note that this format is equivalent to \G specification of the formatted text FT (see below). The number N points how much values will be printed on one line and the line separator is ASCII code 10. This format is usefull for the PDA.
For the compatibility with the Windows desktop other format is possible as well, namely, [form=E<N1>.<N2>.<N3>;]. Here <N1> is a number of values on one line and the line separator consists of two ASCII codes 13 and 10. Then <N2> is the total number of positions per one value, and <N3> is the number of positions for a fractional part.
Note that <N2> must be larger than <N3>+7 because the exponential form with 'E' is used. The point is a decimal delimiter. There is an example: [form=E3.10.3;] leads to the text
1.000E+00 2.000E+00 3.000E+00
4.000E+00 5.000E+00 6.000E+00
and so on. This format is equivalent to \B specification of the formatted text (see below).
The current version can work only with the formats described above. More complicated output can be done with the command #print and op=wt (see below).
The operations "rt" and "wt" can work only with the text array t() of characters.
The operation "rt" fills some part of the text array from the file. The information about this operation is stored in s(). The element s(4) contains the index of the first character for the last record, s(5) contains the number of characters for the last record. At any time s(6) contains the maximum index of character written to the text array.
The text array may be filled also by the command #print (see below).
The operations "rd" and "wd" allows one to read and write the "float" numbers. These are real numbers stored as 4 bytes for one number in the computer format.
The operations "rb" and "wb" will be included later. Now they don't work.
[ back to top ]
DATA
Data (d)#d 6 r(1) 1,2 3,2*5 2 i(1) 1 2
This command allows one to determine quickly the elements of arrays. Of course, one can make it in #calc command but sometimes it looks as cumbersome procedure. Because of variables may be used as arguments of many calculating programs, it is useful to define their values quickly.
Therefore this command makes the same as #calc but in more elegant way.
This command has no parameters but the field of argument may be as long as necessary. It contains a set of blocks. The blocks can be separated by comment having a structure ; ... = where symbols ; and = play a role of brackets.
The structure of one block is <num> <first> <data> where <num> is value which shows how many elements will be determined, <first> shows the kind and first element of the array like the parameter first of #io command, <data> is a set of values separated by blank symbol (note that comma is a decimal delimiter).
The number of values must be just the same as is pointed out by <num>. However, if some value is multiplied by integer, this means that this value must be taken many times just as many as it is pointed by integer.
Note that variable named by letter is also the array where first small letters is ordered then capital letters and then $%&. For example, #d 4 y 1 2 3 4 1 & 67 is the same as # y=1; z=2; A=3; B=4; &=67; The maximum number of values in one block, namely <num>, is limited by 500.
[ back to top ]
PASS
Pass (pas)#pas n r(101) r(501)
This command has evident simple structure. It allows one to pass a set of the array elements to other array or to the same array in another place.
The argument has only one set with the structure <num> <first from> <first to> where <num> shows the number of elements for copying, <first> is the same as the parameter first in #io command. Of course, this work may be done by #calc within the loop.
But this command works faster. When the number is large it is essential.
[ back to top ]
REPEAT
Repeat (re) ... End (en)#re n ... #en
This frame made by two commands makes a simple loop. The command #re has one argument <num> which shows a number of repeat. Then the body of the program between this command and the nearest command #en will be scanned just <num> times. After that the pointer goes further. All count operations like # i=i+1; must be made inside the body of the loop. Inside the loop body there may be other loops up to 25 levels.
[ back to top ]
CASE
Case (cas) ... End (en)#case cod ... #en |
This frame made by two commands makes a more complicated loop. First the command #cas reads the argument cod. Note it is not a parameter and value must always exists. If cod = & , where & is the variable having a current value, the body of loop is fulfilled. If not the body of loop is not fulfilled at all.
In this case the command is equivalent to the execution of procedure. However, the #end command checks the condition cod = & once again where value of cod is always the same but the value of & can be changed. If it is not changed, the loop will repeat infinitely and user will need to stop the program by external tools.
In this loop the command #end may have argument as well. If one use #end | (symbol | after the end) then the #end command changes & to the value 12345 before checking the condition. So if cod is not equal to 12345 the loop will be made only once. Another way is a construction #end (4) where a new value of & is placed in the round brackets.
This command is useful to make a selection. For example, a code
# &=2; #case 1 ... #end | #case 2 ... #end | #case 3 ... #end |
allows one to select a second way of calculation among three possible.
This command can be equivalent to a simple loop if one use [<] or [>] operations. For example, a code
# &=5; a=1; #case 5 ... # a=a+1; &=a>5; #end
will make a body of the loop just 5 times.
Note that a usage of [<] and [>] operations allows one to realize logic of any level. As in the case of simple loop one can use #case inside the #case up to 25 levels.
[ back to top ]
STOP
Stop (sto)#sto
This command stops the execution of the ACL-program. It is not necessary in a pure sense because the program stops automatically when the pointer reaches for the end of the program text. In addition any part of program can be placed inside the procedure frames and will be not executed. However, this command has some advantages because it works like the error but without error warning message.
Namely it return ACLI to the editor with the text of program but now the cursor position shows just on the command #sto which was performed. User can use many such commands and cursor will point on one of them. Note that any error leads to stop the program, showing the error message and placing the cursor at the position of the stop. So the command #sto may be treated as a correct error.
[ back to top ]
EXIT
Exit (exi)#exit
This command has no arguments and parameters. It allows to close the ACLI from the ACL-program. Note that #stop can only stops the ACL-program but not the ACLI. This command just makes the latter. It is necessary if the ACLI works with completely ready ACL-program and the environment is not necessary. In principle the ACLI can work for users who don't know about the ACL and uses only ready ACL-program which must be able to exit from ACLI.
[ back to top ]
READ
Read (rea)#rea [fir= ; num= ; beg= ; len= ;]
This command is somewhat reversal to #print. It allows one to obtain numbers from their text representation. It works like #io [op=rf; ] but takes the text from the text array t() instead of the file.
The parameter [first] defines as usual the kind and the index of numerical array, [num] determines how much numbers must be read, [beg=j;] defines the first element of the text array t(j), and [len] determines the length of the text array to be examine for the numbers. This length is usually known from the procedure of writing the numbers.
For example, #print tells about this in the elements s(4) and s(5). Therefore the part of program
#print \G a b c;\E
#read [fir=i(1); num=3; beg=s(4); len=s(5);]
is equivalent to
# i(1)=a; i(2)=b; i(3)=c;
However, this command can be used with the command #input (see below) and allows one to obtain the numerical values from the input window dynamically.
[ back to top ]
FILE
File (f)#f [op=; num=; beg=; len=; mod=; file=; ...] FT FT ...
This command allows user to perform various operations with the files which are usually a job of operating system. There are also special operations needed for some programs. Currently 11 operations are elaborated with
op == choose | copy | delete | divide | edit | fcat | find | folder | list | line | replace | size
The name of operation can be shortened to 4 symbols. It is useful to consider each operation separately.
#f [op=choo;]
This command runs a special program which is called FileChooser. The FileChooser allows examination of the total file structure of the current computer similar to "File Manager" of Solaris OS or "My Computer" of Windows OS. It begins with the main folder of ACLI. All files are shown. The button [Select] allows one to select the file. The total name of the selected file counted from the main folder of ACLI will be placed in the text array t() from the first element defined by s(3). After the operation s(4) and s(5) shows the beginning and the length of the record. Note that user is able to select the file which is located in the folders out of the main folder of ACLI. If the user makes it, the ACLI will return empty name of file and s(5)=0. So the programmer must be careful to check an existence of the selected file by the operation [op=size;] in addition to check a value of s(5) before to make something with the selected file. If [mod=1;], a special form is used where only graphics files will be shown with preview. After choosing the file its total name will be placed to t() at the same location as above. The obtained name of the file selected by user can be used for further work of ACL-program.
#f [op=copy; num=; file=newtotal;] file1.txt\E file2.txt\E ...
This command makes copying several files to one. The new file will be created with the name defined by the parameter [file]. The list of files which are copied to one is a set of FTs. The list may be arbitrarily long but will be used only n=[num] names.
#f [op=dele; file=any;]
This command allows user to delete the file.
#f [op=divi; file=any; form=any; beg=; len=; num=; xsh=;]
This command allows user to divide the file on the parts and to save one part in the new file. The name of initial file is defined by the parameter [file], the name of new (formed) file is defined by the parameter [form]. The initial file is treated as a matrix of bytes from which some submatrix of bytes is selected. To make this job the four parameters are needed. The parameters [beg] determines the number of bytes which will be skipped at the beginning. After that the part of [len] bytes will be kept into new file and then [xsh] bytes will be skipped. Such len-xsh procedure will be repeated up to [num] parts of [len] bytes will be kept in the new file. The new file will have the size of [len]*[num] bytes. This operation is useful to select small part of large image to the new image.
#f [op=edit; mod=; file=any;]
This command is a simple editor of the file contents. The name of the file to edit is defined by the parameter [file]. If the file is absent it can be created. In this case the editor begins with the empty contents. The new contents of the editor will be saved to the file if [mod=1;] or not saved if [mod=0;]. The latter is used for the files which contents must be only shown to prevent its changing. The file is saved automatically at the exit. The menu has several items: [Page Up] [Page Dn] ... [Exit]. The action of [Find] is standard. [Page Up] and [Page Dn] move the cursor position on N lines up and down. This is useful for PDA. The number of lines N is equal to 10 initially, but it can be changed by menu item [Help/Settings] for one run of ACL shell.
#f [op=fcat; file=any;]
This command allows programmer to obtain the list of folders and file names inside the pointed folder, which name is defined by the parameter [file]. The list will be placed in the text array t() from first element defined by s(3). After the operation s(4) shows the first element of record and s(5) shows the number of elements (symbols).
#f [op=find; beg=; len=; file=any;]
This command makes a search of some set of bytes inside the file which name is defined by the parameter [file]. The set of bytes must be defined by their indices in the array i() from the start element i(ns) where ns=[beg] and just n=[len] bytes. The result of search is placed in the parameter s(2) as a number of byte set repetition. Note that byte values range from -128 to 127 differently from ASCII codes
For example, the code
#d 2 i(11) 13 10
#f [op=find; beg=11; len=2; file=any;]
will give the number of lines inside the DOS file "any.txt" as a value of s(2). If s(2)=0 this file is not a DOS text file.
#f [op=fold; file=any;]
This command changes the working subfolder. This is global command. It makes the same job as the Menu item "Program//Set folder" of the ACL shell. When the folder does not exists it will be created. The name of folder is determined by the parameter file. This name will be kept even if the ACL-program ends and will be used for the next execution. Therefore user must be careful to return the initial folder at the end of current job or to take the new folder into account. It is useful to set the working folder at the beginning of the ACL-program independently of the previous settings or do not use it at all. The subfolder is counted from the main folder of ACLI. If you need to consider subsubfolder, use complex name "subfolder/subsubfolder". There are special cases. If [file=oldf;] the program returns back to preceding folder which used before last change instead of going to folder called "oldf". To avoid problems don't use the folder with this name. If [file=null;] this means that the ACLI will work with its main folder.
#f [op=list; file=any; cod=; beg=;]
This command makes a special work. It reads the file specified by the parameter [file] and creates a special line of text. It takes to this text all symbols from the beginning to the symbol which ASCII code is defined by [cod] including the last symbol. Then it skips all symbols after ASCII code [cod] up to the symbol which ASCII code is equal to [beg] including this symbol (i.e. skips it). Then it takes all symbols up to ASCII code [cod] and so on. This looks like the command takes one part of two parts of some set of records. If the record has name and body the command can make a list of names. The result is the number of names which will be given by the value of parameter s(2) and the line of names which will be written in the text array t() from the first element which is defined by s(3). After the operation first element and number of elements will be determined by s(4) and s(5) similarly to other commands which fill the text array. Note this work can be made by means of other commands but this command works much faster especially for large files.
#f[op=line; file=any; num=; beg=; len=;]
If [num=-n;] is negative, this command takes n-th line of the text file and writes its contents to the text array t() from s(3). After operation s(4) and s(5) show the beginning and size of written text. If [num=n;] is positive, this command writes the part of text array t() from first element defined by [beg] and number of symbols as defined by [len] to the file at n-th line. If the file has more than n lines, the n-th line will be changed. If the file has less than n lines, it will have n lines. The lines between last existed and n-th line will be empty.
#f [op=repl; beg=; len=; mod=; file=any;]
This command makes more complicated operation compared to "find". It finds all copies of one set of bytes and replaces them by other set of bytes. Once again all n=[len] bytes must be determined in the array i() from the start element i(ns) where ns=[beg]. Among them m=[mod] first bytes define the set to be replaced and n-m rest bytes define the set which to be write instead. The new content will be saved in the file with the same name. So to save the initial file it must be previously copied to other name.
For example, the code
#d 2 i(11) 44 46
#f [op=repl; beg=11; len=2; mod=1; file=some.dat;]
will replace all commas by dots.
#f [op=size; file=any;]
This command allows user to determine a size of the file which name is defined by the parameter "file" in the working folder. The size is placed in the parameter s(1). If s(1)=0 the file is absent.
[ back to top ]
TEXT
Text (te)#te [op=; num=; beg=; len=; cod=; mod=;]
The simple commands of ACL allows one to perform any operation on the text array t(). However, there are some standard operations which can be made faster and easy to programming. This command just make such standard operations on the text array t(). Currently there are only three operations [op=xx;] where
xx == find replace trim
The name of operation can be shortened to 4 symbols. As above it is useful to consider each operation separately.
#te [op=find; beg=; len=; num=; cod=;]
This command examines the part of the text array from [beg] and with size [len]. It determines all locations of the symbol which ASCII code is equal to [cod]. The result is written into the integer array i() from the first index [num]. The number of locations can be found in the parameter s(1).
#te [op=repl; beg=; len=; cod=; mod=;]
This command examines the part of the text array from [beg] and with size [len]. It replaces all symbols with ASCII code [cod] by ASCII cod [mode].
#te [op=trim; beg=; len=; num=;]
This command examines the part of the text array from [beg] and with size [len]. It selects the part of the text excluding the blank symbols in front and behind the text without blank symbols. If there are several such texts only first will be return. The result is written into the integer array i() from the first index [num]. Let [num]=k. Then i(k) shows the first element of the text, i(k) >= [beg], and i(k+1) shows the length of the text, i(k+1) <= [len].
[ back to top ]
MATHEMATICS
Mathematics (ma)#math [op=; beg=; nx=; ny=; others]
This command allows user to make some standard mathematical calculations directly, i.e. without coding this work by means of ACL. In this way, on one hand, the ACL code becomes shorter, and, on the other hand, the program runs faster, especially if a large number of values is involved in calculation.
Different operations will be distinguished by the parameter [op=..;]. Currently, 9 operations are implemented with different values of [op]. The order of presentation is historical
[op=mtr;] matrix transpose
[op=fno;] matrix rows normalization
[op=mss;] sum of rows and columns
[op=vmc;] vector scaling
[op=fft;] Fast Fourier Transform
[op=mmi;] matrix interpolation
[op=mcg;] convolution by Gaussian
[op=fis;] interpolation by spline
[op=mii;] matrix indices inversion
Below all operation are described step by step.
#ma [op=mtr; beg=; nx=; ny=;]
means the transpose of matrix. The matrix is placed in the real array r() from the first index which is defined by [beg]. The number of rows is defined by [ny] and the number of columns - by [nx]. As a result of the operation the same part of the array r() will present the transposed matrix which columns become rows and rows become columns. This operation is convenient when one read the numbers from the file in free format (from columns) and then use the array in #win command.
#ma [op=fno; beg=; nx=; ny=; mod=;]
means the special normalization of matrix. The matrix is defined by [beg] [nx] [ny] as above with the ordering 11 21 31 ... 12 ... However, in this case each column of size [nx] is treated as a vector vec(j). The minimum vec_min and the maximum vec_max values of this vector are determined and ny values vec_min and ny values vec_max are placed after the matrix starting from the index [beg]+[nx]*[ny]. Then if [mod] = 0 each vector is normalized according to the formula [vec(j) - vec_min]/[vec_max - vec_min]. The normalized values may be useful for the graphics. If [mod] is nonzero the matrix stays the same and the operation is used only for min and max calculation.
#ma [op=mss; beg=; nx=; ny=;]
means the summation of rows and columns of the matrix which has a form m[nx,ny]. The result is the calculated vector vec[nx] as a sum over all k for m[nx,k] which is placed just after the matrix, then the calculated vector vec[ny] as a sum over all k for m[k,ny] which is placed just after the preceding vector. The next element of the real array is equal to a total sum of all elements. This looks like the integral of the function f(x,y) is performed over y giving A(x), then over x giving B(y) and then over x and y simultaneously. The important particular case if [ny] = 1 is slightly different. In this case only the sum over all elements of the matrix-vector is calculated and is placed just after the matrix-vector. It is equivalent to integration of the function f(x).
#ma [op=vmc; beg=; len=;] after # C=..;
means the multiplication of vector by constant. The result is placed at the same location. The vector is located in the real array r() from [beg] and has length defined by [len]. The constant value must be defined in the variable [C].
#ma [op=fft; beg=; nx=;]
means the Fast Fourier Transformation
fq[n] = sum{m = 0,...,N-1} exp( sign(k)*2*pi*i*n*m/N )*fx[m]
where N = 2^abs(k) with k to be integer, n = 0,...,N-1
The complex array fx[m] is located in r() from the first element defined by [beg] ordered as (real image real image and so on). The parameter k is defined by [nx]. Note that k can be negative but its absolute value cannot be larger than 16. The result fq[n] is located at the same position of r().
#ma [op=mmi; num=; beg=; nx=; ny=; wig=; hei=; sav=; file=; form=;]
means the matrix to matrix interpolation. This is rather complicated operation because the matrix size may be very large. In this case the initial matrix has dimentions defined by [nx] and [ny] whereas the new interpolated matrix has dimensions defined by [wid] and [hei]. It is assumed that initial matrix describes the rectangular region with corners xi1, yi1, xi2, yi2 whereas the interpolated matrix describes the rectangular region with corners xo1, yo1, xo2, yo2. These values must be defined in the real array r() starting from the index defined by parameter [num] in the following order xi1,xi2,yi1,yi2,xo1,xo2,yo1,yo2. Normally the initial matrix is read from the file defined by parameter [file] ordered as 11 21 . . . This is normal order for writing the images. However, in the case [file=here;] the matrix is assumed to be located in the array r() starting from the index defined by [beg]. Normally the resulting matrix is written to the file defined by parameter [form] ordered as 11 21 . . . However, in the case [form=here;] the matrix is assumed to be located in the array r() starting from the index defined by [sav]. It is assumed that the region is described with step like this dx=(x2-x1)/(nx-1). The linear interpolation is performed.
#ma [op=mcg; num=; beg=; nx=; ny=; sav=; file=; form=;]
means the operation of matrix convolution (or deconvolution) by Gaussian. It is assumed that the matrix is calculated by Fast Fourier Transformation and it has dimensions [nx] and [ny] as integer power of 2, i.e. 64, 128, 256, 512, 1024. However [ny] can be equal to 1 (see below). The convolution (or deconvolution) is performed by double FFT as well and the result is the matrix of the same dimensions. The parameters of Gaussian (sigmaX) and (sigmaY) are measured in units which are equal to sizes of one pixel of the image. The Gaussian is defined by its Fourier image as
G(q) = exp( -(sigma*q)^2/2 ).
The convolution is performed if the parameter (epsilon) = 0. In this case Fourier image of matrix is multiplied by G(q). On the contrary, if (epsilon) > 0, the deconvolution is performed with reasonable regularization rule, namely, the Fourier image of matrix is multiplied by
1 / sqrt( G(q)^2 + epsilon^2 )
The values (sigmaX), (sigmaY), (epsilon) must be determined in the elements of real array r(i), r(i+1) and r(i+2) where (i) is defined by [num]. Note that if (sigmaX) = 0 or (sigmaY) = 0 nothing is happened with corresponding coordinate. The initial matrix is read from the file whose name is defined by [file]. If [file=here;] the matrix is read from the real array starting from the index defined by [beg]. The resulting matrix will be written in the file whose name is defined by [form]. If [form=here;] the matrix will be written in the real array r() starting from the index defined by [sav].
The value [ny=1;] is also possible and means one dimensional case where the matrix coincides with the vector of size [nx].
#ma [op=fis; beg=; nx=; ny=; siz=;]
means the operation of matrix rows interpolation by cubic spline. Each row of initial matrix presents the values of one function defined on a set of argument with variable step. The matrix has dimensions [nx] and [ny] and is located in the real array r() starting with the index defined by [beg]. The arguments must precede the matrix and the set of points started from the index [beg] - [nx]. The result of interpolation is a new matrix which has dimensions [siz] and [ny]. It defines the same set of functions but on new set of points with constant step from first old point to last old point. The new matrix is located just after the initial matrix so the first element begins from [beg] + [nx]*[ny]. In other words this operation changes the presentation of the set of functions from variable step to constant step using the cubic spline interpolation.
#ma [op=mii; beg=; nx=; my=; mod=;]
means the operation of matrix indices inversion. As a result of operation the last element of row becomes first and the last row becomes first. The matrix is described by the parameters [nx], [ny] and [beg] as usual. In addition the parameter [mod] defines the modification. If [mod=0;] both indices are inverted, if [mod=1;] only first index is inverted, i.e. columns, if [mod=2;] only second index is inverted, i.e. rows. The resulting matrix is located at the same place.
[ back to top ]
MESSAGE
Message (m)#m [op=;] FT
This command has the same argument as the #print command, but it is different by meaning. During the execution of the program the ACLI opens a new text in a text-window which begins with the message of one line
Work is doing
If the program is rather complicative and works for a rather long time, the program can add some new messages. However, the programmer can add some new records to this text as well which can show a current state of computing. This can be done just by the command
#m [op=txt;] FT
This command puts message on the text window during the execution. When the execution is done such messages disappear and cannot be saved. To save it one needs to copy the messages by #print command. Such command is useful for optimization of the program. For example, one can show the current time after some part of execution process.
In addition, this command can be used in other modifications for creating interface messages.
The command
#m [op=win;] FT
creates a message in a separate window with the button [OK] and stops the program execution. The user must click the button to proceed further.
The more extensive form is the command
#m [op=oce;] FT
This form opens a separate window which has three buttons [OK] [Cancel] and [Edit]. It returns the number of pressed button in the variable & and may be 1, 2 or 3. Then this information can be used in further work. Finally there is alternative form
#m [op=yno;] FT
which opens a separate window with two buttons [Yes] [No]. The number of pressed button is in & and may be 1 ord 2.
[ back to top ]
INPUT
Input (inp)#inp [num=; len=; mod=; ysh=;] FT FT ...
This command creates a new panel which contains several input fields each for line of text. The number of lines is defined by parameter [num]. The panel has a title which must be defined by the first argument FT. Each input field has a label, first label is defined by the second argument FT. Finally, the third argument FT contains the initial text which will be shown in the first input fields.
If [num > 1] there are two modifications of setting the labels and initial texts. In the case of [mod] = 0,2 the 2-d FT defines 1-st label, 3-d FT defines 1-st text, 4-th FT defines 2-d label, 5-th FT defines 2-d text and so on. So in this case each FT defines one label or text. This is correspondent to the old version of ACLI which allows one to use the ACL-programs made with old version. On the contrary, in the case of [mod] = 1,3 the 2-d FT defines all labels which must be separated by the symbol [ | ], and 3-d FT defines all texts which must be separated by the same symbol.
There are also two modifications of appearance of the labels and texts. In the case of [mod] = 0,1 each label and each text will be placed in new line. So label will be above the corresponding input field. On the contrary, in the case of [mod] = 2,3 each pair of label and input text will be placed on the same line. In this case the label can not be long because the first button [OK] (see below) will have the same length as the label.
The bottom line of the panel contains two buttons [OK] and [Cancel]. The parameter [len] specifies the length of empty space from sides of the [OK] [Cancel] buttons. This allows user to define the length of input field because the labels and input fields are ordered vertically (if [mod=0,1]) and the width of panel depents on the maximum length of determined lines. Normally [len] = 50 but can be smaller or larger. The value of [len] can be optimized empirically. Note that panel is always located in such a way that it is centered relative the screen. However, for PDA it is inconvenient because the keyboard takes some place on the bottom of screen. Therefore the input fields must be placed on the top of screen. This can be done by putting large empty space on the bottom of the panel. The vertical size of such empty space is defined by the parameter [ysh]. Its value may be from 0 to infinity. However, unproper value will lead to bad window.
The contents of all input fields can be retyped by user and new texts will be placed into the text array t() like #print command. The contents of different lines will be separated by the ASCII code 10 (line separator). Remind of that the index of the first element for writing to t() can be changed by s(3). After the operation s(4) shows the index of the first element of t() with new text (note that s(3) will be changed) and s(5) shows the length of total record including the line separator after each line. Therefore be careful to obtain a pure text of input window. In the case of [num=1;] it has length s(5)-1.
The panel contains two buttons [OK] and [Cancel]. If the user selects the [Cancel] button the text array t() will not be filled and the variable [&] will be equal to 2. The text array will be filled only if [OK] button is pressed. In this case [&] will be equal to 1. So the ACL programmer has a possibility to know what button was pressed.
[ back to top ]
SELECT
Select (sel)#sel [nx=; ny=; mod=;] FT FT
This command creates a new panel with buttons. The number of buttons in one row is defined by parameter [nx] and the number of rows is defined by parameter [ny]. The command allows user to make a selection of one variant from many variants. The panel has a title which must be defined by the first argument FT.
If [mod=0;] the names of all buttons must be defined by the second argument FT. The names inside the FT are separated by the symbol [ | ]. The order of the buttons is
[1,1] [1,2] [1,3] ... [2,1] ...
When user selects one buttons on the panel, the latter disappears and the variable [&] just becomes equal to the index of selected button. Then this can be used in the following code of the ACL-program.
If [mod=1;] the buttons are images from the files ***.jpg which is stored in the current folder. In this case the names of the buttons are equal to the names of the files but without an extension. For example, the name "1001i" means the file "1001i.jpg" counted from the current folder. As above the variable [&] shows the selected image.
The panel has closing button at the top-right corner which can be used in the case of absence of selection. In this case [&] = -1 and this may be used to stop looping.
[ back to top ]
ZIP
Zip (z)#z [op=; file=; num=; mod=;] FT FT ...
This command realizes zip archive operations which allows programmer to create zip-files and to get the contents of zip files dynamically. The main usage of this command is to keep and use many help files of the ACL-programs inside one archive file. Even the interpreter vkACL contains many help files inside itself that allows to perform the distribution as a one file. There are five operations for this command
op == catalog | sfolders | gfolders | sfiles | gfiles
The name of operation can be shortened to 3 symbols. As usual it is useful to consider each operation separately. However, for all operations the parameter [file] defines the name of zip-file. This name can be arbitrary, i. e. with or without the extention "zip".
#z [op=cat; file=;]
This command allows programmer to obtain a list of files inside the considering zip-file. The total list of files is placed in the text array t() from the element which index if defined by s(3). After the operation s(4) and s(5) show the beginning and the length of the written record. The names inside the string are separated by the symbol " | ". You must keep in mind that the files inside the folders have name like "folder/file" and there may be the name like "folder/" which points on the folder alone.
#z [op=sfo; file=; num=;] FT FT ...
This command allows programmer to create a new zip-file which name is defined by [file] and which contents will have all the files inside the pointed folders. The number of folders is defined by [num] and the names of folders are the arguments of the structure FT. All names are counted from the main folder of the interpreter and can have structure like "folder/subfolder". Note that the poined folders must contain only the files without subfolders. This restriction is a sequence of interpreter creation.
#z [op=gfo; file=; num=; mod=;] FT FT ...
This command, on the contrary, allows programmer to extract all the files inside the pointed folders. The structure of the parameters and arguments is the same as above. However there is additional parameter [mod]. If [mod=0;] , the extracted files will be added to the existing folders or new folders will be created. The existing files with the same names will be replaced. The new files will be kept after the interpreter closing. If [mod=1;] , the extracted files will be removed after the interpreter closing. In this case the extracting files live only when the program lives. Finally, if [mod=2;] the extraction will be performed only for such folders which don't exist and then will exist after the interpreter closing. Therefore the program can made only one extraction of such kind. It is useful for extraction some initial files which later can make to change their contents.
#z [op=sfi; file=; num=;] FT FT ...
This command allows the programmer to create a new zip-file which name is defined by [file] and which contents will have all the files pointed as arguments. If the name of some files has a structure "folder/file" then the new folders will be created inside the zip-file. This command is more general than the [op=sfo;] but the programmer needs to form a long list of names containing all files. As before [num] is number of files.
#z [op=gfi; file=; num=; mod=;] FT FT ...
This command, allows programmer to extract all the files pointed as arguments. The files inside the folders have to have the names like "folder/file". The parameters [mod] and [num] have the same meaning as for [op=gfo;].
[ back to top ]
COLOR
Color (co)#col [beg= ; len= ; fir= ;]
This command allows one to define the colors which will be used later in some graphical operations (see below). The ACLI can work with 256 colors which are kept in color array and have indices from 1 to 256.
Each color is defined by 3 integers (red, green, blue) which can variate from 0 to 255 (one byte for each subcolor). Initially all colors are black (0,0,0).
The command defines the part of colors from the index which is determined by the parameter "beg" and number of colors to define is determined by the parameters "len".
The total number 3*len integer values must be placed previously in the integer i() or real r() arrays from the first element which is determined by the parameter "fir".
This is example.
#d 3 i(1) 255 0 0
#col [beg=2; len=1; fir=i(1);]
These two commands define 2-d color as red. First color is black initially.
[ back to top ]
WINDOW
Window (w)#w [op=; file=; form=; many others ]
This is rather complicated command which allows one to make graphics inside new window. Graphics has many modifications but for all kinds of graphics the figure image is placed inside the control, therefore user must click on the image to close it and let the program to continue its work. Note the position of the window is not defined because the window is located in the central part of the screen. The kind of graphics is determined by the parameter "op". The data for graphics is taken usually from the file which name is determined by the parameter "file". The image saving depends on the parameter [sav]. The image can be only shown if [sav=0;], shown and saves if [sav=-1;] and only saved if [sav=-2;]. The image will be saved to the file "ooo.png" where "ooo" must be defined by the parameter [form]. Note [form] defines only first name of the file without extension. The file will be saved inside the current working folder. The command can have arguments and it depends on the values of many other parameters. The names of parameters are conditional and only approximately are connected with some words near to their sense. It is useful to consider each kind of graphics separately.
op=im (image)
#w [op=im; file=; form=; num=; mod=; beg=; len=; twi=; the=; wid=; hei=; xsh=; ysh=; sty=; bot=; top=; nx=; ny=; sav=;]
This kind of graphics can show images of different types. The kind of source data depends on the parameter [mod].
If [mod=0;] then image is taken from any graphics file with the extensions *.bmp *.gif *.jpg *.png . The contents of the file will be shown completely and the size of the windows is determined by the file. This size will be returned in s(13) and s(14) as width and height in pixels. No other parameters are necessary in this case. If the size of screen is smaller than the size of image, only the central part will be shown.
Other possible values of [mod] are 8, 16 and 32 and 100.
If [mod=8;] the data inside the file are integer numbers of 8 bits size (one byte).
If [mod=16;] the data are integer numbers of 16 bits size (two bytes).
If [mod=32;] the data are floating point numbers of 32 bits size (four bytes).
If [mod=100;] the data are calculated (see below).
In these cases the image is determined by the same set of parameters for all data kinds.
Parameter [len=;] shows the size of header in bytes for the file. The header is some text which can precede the data inside the file.
Parameters [twi=; the=;] show the total sizes of the image in pixels horizontally and vertically.
Parameters [wid=; hei=;] show the sizes of subimage to show. They may be equal to or smaller than [twi], [the].
Parameters [xsh=; ysh=;] show offsets for x and y directions of image. The [ysh] is counted from the bottom of the image.
Parameter [sty=; bot=1; top=99999;] shows the style of presentation of the data. Below the styles are explained. The numerical data have maximum value (Fmax) and minimum value (Fmin). These values are determined automatically.
The value of each point of data is shown by grey pixel within the region from 0 to 255 (8 bits). This region is scaled from the region of data which is from
Fmi = Fmin + Dff*[bot]/100000 to
Fma = Fmin + Dff*[top]/100000 where
Dff = Fmax - Fmin.
Scaling is linear if [sty=1;] and is obtained by the law
gray = 255*(f - Fmi)/(Fma - Fmi).
It is logarithmic if [sty=2;] and is obtained by the law
gray = 255*log(f/Fmi)/log(Fma/Fmi).
If [sty=3;] it is modified by square root, namely,
gray = 255*sqr((f - Fmi)/(Fma - Fmi))
(negative values are replaced by zero).
Normally minimum is black, maximum if white. However, if parameter [sty] is negative the contrast is opposite.
So you see the integer parameters [bot] and [top] show the subregion inside the interval (0,1) in units 0.00001. Therefore they must have values between 1 and 99999. Finally, each pixel of data can be shown by a rectangular of [nxf] and [nyf] pixels of the screen horizontally and vertically.
Note that all these parameters are elements of the subsidiary array s() in the following order
len (10) mod (11) twi (12) the (13) wid (14) hei (15) xsh (16) ysh (17) sty (18) bot (19) top (20) nxf (21) nyf (22) sav (23)
Therefore it is useful to determine all data by the command
#d 14 s(10) 1 2 3 . . .
For example, to show the part of data from the big *.edf file, which is standard in ESRF, one can use the code like this
#d 14 s(10) 3072 16 2048 2048 128 128 1408 968 -2 1 999 4 4 0
#w [file=al-3012.edf;]
In the cases with [mod] = 16 or 32 the minimum and maximum values of function are stored autonatically in r(j) and r(j+1) where j = [beg]. In the case of [mod=32;] and if [file=here;] the data can be found in the real array r() from the first element determined by [len]. Note this parameter determines the header of the file. If the file is not used the same parameter defines the start element of r().
There is special case which is used for automatical preparing the scale of grey levels. If [mod=100;] the data are calculated instead of to be taken from the file or real array r(), therefore to avoid error message one needs to write [file=here;]. The data is an array of n elements where n = [wid]*[hei]. This array decribes one linear curve from Fmin to Fmax where Fmin = r(j) and Fmax = r(j+1) with j=[beg=]. Therefore this array allows one to obtain image of scale of gray levels. The image can be vertical if [wid=1;] or horisontal if [hei=1;]. To avoid error message one of the sizes must be equal to 1. The transverse size of the scale must be done by pixel size.
AXES and TITLES.
Some of other operations allows to draw the axes and titles. The way of drawing the axes and titles is general. The total sizes of such image in the screen pixels are defined by [twi] and [the]. The x and y sizes of the box of axes are equal to [wid] and [hei]. The left-bottom angle of this box will have coordinates [xsh] and [ysh] relative the image field. The axes have short and long ticks. The sizes of these ticks are determined by [bot] and [top] correspondingly. Ticks can see inside or outside the box. In addition each axis can be omitted, can have numbers or can be without numbers. These features are determined by one parameter [sty]. Generally it is number of five digits having a structure "lbrtm". First four digits determine the axes appearance, "l" for the left axis, "b" for the bottom axis "r" fot the right axis and "t" for the top axis. If these digits are equal to 0, these means a standard appearance where left and bottom axes have numbers but right and top axes have no. If they are equal to 2, these means a nonstandard appearance where right and top axes have numbers but left and bottom have no. If they are equal to 1, the corresponding axis will be absent on the figure. The last digit "m" determines the ticks orientation. If "m" = 0 they see inside. If "m"=1 they see outside.
There are examples [sty=1;] is standard form, [sty=11211;] leads to right axis only with numbers. Note that if "m"=0 and [top=max/2;] where max = maximum(wid,hei), the figure will have a grid. Finally the text of numbers at the axes will have size determined by [tsi] in the screen pixels. In addition [tfo] and [tki] allows one to define font and kind of text (see command #graphics for more details).
Note that the values at the ticks must be specified as well. However if the parameter [unit=0;] these values are determined automatically from the minimum and maximum values for x and y axes. Very often it is sufficient. However, sometimes the automatical kind of graphics is unacceptable. In this case the parameter [unit] must specify the index of the first element of the real array r() where the additional information about the axes are stored. Let [unit=i;] where i > 0. Then the user must define
r(i) = fnor ( the unit for the functions, the figure will show f(x)/fnor )
r(i+1) = xmin (minimum value on the x axis)
r(i+2) = xmax (maximum value on the x axis)
r(i+3) = xmf (position of the first long tick on the x axis)
r(i+4) = xms (distance between long ticks on the x axis)
r(i+5) = xni (number of short ticks incide the region between two long ticks on the x axis)
r(i+6) = ymin (minimum value on the y axis)
r(i+7) = ymax (maximum value on the y axis)
r(i+8) = ymf (position of the first long tick on the y axis)
r(i+9) = yms (distance between long ticks on the y axis)
r(i+10) = yni (number of short ticks incide the region between two long ticks on the y axis)
This way allows one to prepare the figure of arbitrary design.
As for the titles, the number of titles is defined by [num] but the titles themselves are the arguments. The structure of these arguments is: x y rts FT for each title. Here x and y determine the position of the left-top corner of the title, FT is the formatted text of the corresponding title (see about the formatted text in the command #print). rts determines the increasing or decreasing the font size for this title relative to [tsi]. Standard values are [tsi=14;] rts=2. Below we will consider various operations.
op=pf (plain figure)
#w [op=pf; file=; form=; beg=; len=; mod=; twi=; the=; wid=; hei=; xsh=; ysh=; sty=; bot=; top=; nx=; ny=; sav=; tsi=; uni=; tfo=; tki=; msi=; mki=;]
This kind of graphics presents the scientific figure where some curves are shown. Each of them is a dependence of one characteristic on another characteristic. The curves are shown inside the box of axes which have scales and titles. The numerical data are taken from the file of name which is determined by the parameter [file]. The data must be written in the file as floating point numbers in computer code (4 bytes per number). Note that data of other format can be previously read and then rewritten by means of the command #io [file=] However, there is an exception. If [file=here;], the numbers will be taken from the real array r() which first index is determined by the parameter [beg]. The values of the array r() can be previously determined by different ways.
As before the file can have the header. The size of the header in bytes must be determined by [len]. The number of dots per one curve in the file is determined by [nxf] and it may be treated as a size of one column of usual text representation. The number of columns in the file is determined by [nyf]. However, the sense of the column may be various and the current realization is dependent on the parameter [mod].
If [mod=0;] all columns are functions. The argument for these functions is taken from Xmin to Xmax with a constant step. The values Xmin and Xmax are the arguments of command which must be placed before other arguments.
If [mod=1;] first column is argument for all functions whereas all other columns are functions. The number of functions is [nyf]-1.
If [mod=2;] then odd columns are arguments and even columns are functions. So each function has its own arguments. The number of functions is [nyf]/2.
In the case [uni=0;] the minimum and maximum values for x and y axes are taken directly from the values of arguments and functions. Othervice they must be specified (see above).
The first curve is drawn by the color line which color is equal to [col] element of the color table. In the case of several curves each subsequent curve is drawn by the color line which color is equal to subsequent elements of the color table. The color table can be defined by the command #col. The kind of presentation depends on the parameter [msi] which defines the size of marker in pixels. If [msi=0;], all curves will be drawn by lines. If [msi] > 0, the parameter [mki] determines the kind of marker for first 5 curves. It is 5-digits integer number in which each digit can have value from 0 to 4. All 5 digits are necessary and left (larger) digit defines first curve, next from the left - second curve and so on. For example, [mki=1234;] means line for first curve (left digit = 0), empty rectangle for second curve, filled rectangle for third curve, empty circle for fourth curve and filled circle for fifth curve. There is the example of the part of possible program
# x=-2; i=102; j=304; k=1; l=203;
#rep 101
# r(i)=100*exp(-x^2); i=i+1;
r(j)=80*exp(-(x-0,5)^2)); j=j+1;
r(k)=x; k=k+1; r(l)=x; l=l+1; x=x+0,04;
#end
#io [num=404; fir=r(1); op=wd; file=test.dat;]
#d 3 i(1) 255 0 0
#col [beg=2; len=1; fir=i(1);]
#d 16 s(10) 0 2 240 320 200 220 30 60 0 3
6 101 4 0 14 0
#w [op=pf; file=test.dat; n=2;tfo=1;tki=0;msi=4;mki=1234;]
100 30 2 Distance (mm)\E
70 305 2 Gaussians (arb. units)\E
This program calculates two gauss functions, save them in the file together with the arguments and then show them in the figure.
op=mm (mathematical map)
#w [op=mm; file=; form=; beg=; sav=; twi=; the=; wid=; hei=; sty=; bot=; top=; tsi=; uni=; tfo=; tki=;]
This kind of graphics shows the image inside the box of axes with titles. The image from the file must be a real image, not a data file. The data must be previously converted to the image using [op=im;]. The image is placed completely being located symmetricaly relative the box of axes. See above how to define the axes. If [unit=0;], the values at the axes are determined automatically from the minimum and maximum values for x and y axes. The latter are taken from r(j),..,r(j+3) where [beg=j;]. The new image can be placed into the file which name is [form].
op=ff (final figure)
#w [op=ff; form=; sav=; num=; beg=;] FT
This kind produces new image as a set of several images. The new image will have the size [twi] and [the] horizontally and vertically. The parameter [num] defines the number of images to show. All images will be taken from the files with names "1.png", "2.png", and so on. The corresponding files must exist or must be created by preceded commands. The images will be shown as is and will be shifted from the origin of the base image on the vector (x,y) which coordinates are taken from integer array i() as i(j),i(j+1) for first image, i(j+2),i(j+3) for next image and so on, where [beg=j;]. To prevent error you must specify [file=here;]. The argument FT specifies the title of the figure.
[ back to top ]
GRAPHICS
Graphics (g)#g [op=; many others] FT
This command allows programmer to make image containing arbitrary figure which is drawn "by hand", i. e. according to the ACL-program. The figure may be composed from many elemental graphical objects like lines, texts, regions, rectangles and so on. The figure is created by applying various operations of this command. The currently possible operations are:
open continue close text line area rectangle oval arc image axes rfunc dfunc axon
It is sufficient to keep only first 3 letters for the name of the operation. Below the operations are first described step by step and then the general transformation are presented.
#g [op=open; twi=; the=; col=;]
This operation opens new figure. The parameters [twi] and [the] define the total width and height of the figure in the screen pixels. The rectangle of the figure will be filled by color of index determined by the parameter [col]. Note that colors are taken from the color array of 256 elements counted from 1 to 256. This array is defined by the command #color. The positions of all elemental graphical object are counted from the left-bottom corner of this rectangle.
#g [op=cont; num=;]
This operation allows one to continue creating the figure which was previously stored in the memory as image of index [num]. It simply opens the image for drawing new objects.
#g [op=close; sav=; form=;] FT
This operation closes the figure and saves it according to value of the parameter [sav] similarly to the command #window. Namely, if [sav] > 0 the image is stored in the memory as an image of index [sav]. Maximum index of the stored image is 100. If [sav] = 0 , the image will be shown as button image inside a separate centered window. In this case if [cod] = 0, the program can work further. If [cod] = 1 the program wait when the user closes the window. If [sav] = -1 , the image will be shown and simultaneously will be written in the file on the current folder which name is defined by the parameter [form]. Note the images are always saved in the files of png-kind therefore [form] determines only name without extension. If [sav] = -2 the image will be only written in the file. The argument FT defines the title of the window when the image is shown.
#g [op=text; nx=; ny=; col=; tfo=; tki=; tsi=; sty=;] FT
This operation draws the text on the figure. The position of the text is defined by the coordinates [nx] and [ny]. The additional condition is determined by the parameter [sty]. If [sty] = 1 the text will placed by left-bottom corner at the position. If [sty] = 2 the text will be placed by center-bottom point at the position. Finally if [sty] = 3 the text will be placed by right-bottom corner at the position. The index of color is defined by [col]. The font of the text is defined by [tfo] which can be equal to 1 to 5. This is an index of one of the five logical fonts. What means each font depends on the computer, therefore simply check all fonts and select one. The parameter [tki] defines the kind of font. It may be equal to 0 [plain] 1 [bold] and 2 [italic]. The parameter [tsi] defines the size of the text in screen pixels. Reasonable values are 12, 14, 16.
#g [op=line; nx=; ny=; col=; num=; beg=;]
This operation draws the line as a sequence of many straight line segments. The color is defined by [col]. The coordinates of start position are defined by [nx] and [ny]. The paramener [num] defines the number of line segments. The parameter [beg] defines the start index of the integer array i() which contains the coordinates of each segment as x1 y1 x2 y2 x3 y3 and so on. These coordinates are coordinates of the vector, i. e. the difference between end and start points.
#g [op=area; nx=; ny=; col=; num=; beg=; mod=;]
This operation draws an area. It is similar to the preceding operation but in this case the additional segment from the end point to the start point is added, so the line describes the area. If [mod] = 0 , the area is filled by the color of index [col]. If [mod] = 1 the area is presented by the line along its border with the color of index [col].
#g [op=rect; nx=; ny=; wid=; hei=; col=; mod=;]
This operation draws a particular case of area, namely, the rectangle of width and height which are defined by [wid] and [hei]. The central point of the rectangle is placed at the position with coordinates [nx] and [ny]. If [mod] = 0 , the rectangle is filled by the color of index [col]. If [mod] = 1 the rectangle is presented by the line along its border with the color of index [col].
#g [op=oval; nx=; ny=; wid=; hei=; col=; mod=;]
This operation is similar to the preceding operation but in this case the ellipse inside the rectangular area is drawn. All the parameters have the same meaning as above.
#g [op=arc; nx=; ny=; wid=; hei=; col=; mod=; beg=; len=;]
This operation is similar to the preceding but in this case only a part of the ellipse is drawn from the start angle defined by [beg] across the angular region defined by [len]. The angles are counted in degrees.
#g [op=image; nx=; ny=; num=; file=;]
This operation allows one to add a ready image on the figure . The central point of the image will have the coordinates [nx] and [ny] counted from left-bottom corner of the graphics area. If [num] > 0 , the image will be taken from the memory as a stored image of the index [num]. If [num] = 0 , the image will be taken from the file which name is defined by the parameter [file].
#g [op=axes; col=; beg=; wid=; hei=; xsh=; ysh=; bot=; top=; sty=; tfo=; tki=; tsi=; uni=; num=;]
This operation allows one to add the box of axes on the figure. The x and y sizes of the box of axes are equal to [wid] and [hei]. The color is defined by [col]. The central point of the box of axes will have coordinates [xsh] and [ysh]. The axes have short and long ticks. The sizes of these ticks are determined by [bot] and [top] correspondingly. Ticks can see inside or outside the box. In addition each axis can be omitted, can have numbers or can be without numbers. These features are determined by one parameter [sty]. Generally it is five digits number having a structure " lbrtm ". First four digits determine the axes appearance, " l " for the left axis, " b " for the bottom axis " r " fot the right axis and " t " for the top axis. If these digits are equal to 0, this means a standard appearance where left and bottom axes have numbers but right and top axes have no. If they are equal to 2, these means a nonstandard appearance where right and top axes have numbers but left and bottom have no. If they are equal to 1, the corresponding axis will be absent on the figure. The last digit " m " determines the ticks orientation. If " m " = 0 they see inside. If " m " = 1 they see outside. There are examples [sty=1;] is standard form, [sty=11211;] is only right axis with numbers. Note that if " m " = 0 and [top = max/2;] where max = maximum(wid,hei), the figure will have a grid. Finally the numbers at the axes will have size, font and kind determined by [tsi], [tfo] and [tki] where size is measured in the screen pixels.
Usually the values at the ticks must be specified as well. However if the parameter [uni] = 0 these values are determined automatically from the minimum and maximum values for x and y axes. These values, namely, xmi xma fmi fma must be specified as the elements of the real array r() from the start index defined by the parameter [beg]. Very often it is sufficient. However, sometimes the automatical kind of graphics is unacceptable. In this case the parameter [uni] must specify the index of the first element of the real array r() where the additional information about the axes are stored. Let [unit=i;] where i > 0. Then the user must define
r(i) = fnor ( the unit for the functions, the figure will show f(x)/fnor ). This parameter does not influence axes but is useful.
r(i+1) = xmin (minimum value on the x axis)
r(i+2) = xmax (maximum value on the x axis)
r(i+3) = xmf (position of the first long tick on the x axis)
r(i+4) = xms (distance between long ticks on the x axis)
r(i+5) = xni (number of short ticks incide the region between two long ticks on the x axis)
r(i+6) = ymin (minimum value on the y axis)
r(i+7) = ymax (maximum value on the y axis)
r(i+8) = ymf (position of the first long tick on the y axis)
r(i+9) = yms (distance between long ticks on the y axis)
r(i+10) = yni (number of short ticks incide the region between two long ticks on the y axis)
Note the axes have the same structure as in the #window command because they are drawn by the same procedure.
The axes will be drawn with titles. Note that titles can be drawn separately by the operation [text]. So one have an alternative way here. The number of titles is defined by [num] but the titles themselves are the arguments. The structure of these arguments is: x y rts FT for each title. Here x and y determine the position of the left-bottom corner of the title, FT is the formatted text of the corresponding title (see about the formatted text in the command #print). rts determines the increasing or decreasing the font size for this title relative to [tsi]. Standard values are [tsi=14;] rts=2.
#g [op=rfun; file=; mod=; num=; len=; nx=; ny=; beg=;]
This operation allows programmer to read the data for the functions which will be shown later on the figure inside the box of axes. The numerical data are taken from the file of name which is determined by the parameter [file]. The data must be written in the file as floating point numbers in computer code (4 bytes per number) curve by curve. Note that data of other format can be previously read and then rewritten by means of the command #io [file=]. However, there is an exception. If [file=here;], the numbers will be taken from the real array r() which first index is determined by the parameter [beg]. The values of the array r() can be previously determined by different ways. As usual, the file can have the header. The size of the header in bytes must be determined by [len]. The number of dots per one curve in the file is determined by [nx] and it may be treated as a size of one column of usual text representation. The number of columns in the file is determined by [ny]. However, the sense of the column may be various and the current realization is dependent on the parameter [mod].
If [mod=0;] all columns are functions. The argument for these functions is taken from Xmin to Xmax with a constant step. The values Xmin and Xmax are the arguments of command which must be placed before other arguments.
If [mod=1;] first column is argument for all functions whereas all other columns are functions. The number of functions is [ny]-1.
If [mod=2;] then odd columns are arguments and even columns are functions. So each function has its own arguments. The number of functions is [ny]/2.
After reading the data the minimum and maximum values for argiments and functions will be transferred to programmer as elements of the real array r() starting from the elements of index [num]. Then this information can be used for drawing axes.
#g [op=dfun; col=; nx=; ny=; mod=; beg=; msi=; mki=;]
This operation allows programmer to draw the functions inside the box of axes. The data for functions must be previously read by operation [rfun]. The color is defined by [col]. The parameters [nx], [ny] and [mod] have the same sense as above. The parameter [beg] defines the index of real array r() where the values xmi, xma, fmi, fma are stored for the axes drawing. Note that these values must be the same as were determined by operation [rfun]. However, [rfun] put them from index [num] but here the same index is defined by [beg]. Unfortunately this difference cannot be improved because [beg] is used in [rfun] for other purpose. Be careful to define all parameters explicitly. Finally, the parameters [msi] and [mki] defines the marker for drawing the function dots. If [msi] = 0 , the function will be shown as lines. If [msi] > 0 , its value defines the marker size in screen pixels. The kind of markers is determined by [mki]. There are 4 cases: empty square ( [mki=1;] ), filled square ( [mki=2;] ), empty circle ( [mki=3;] ) and filled circle ( [mki=4;] ). The combination [rfun] [axes] [dfun] can make the same work as #w [op=pf;] but here additional possibilities exist because one can draw different functions by different colors and markers. In addition the region of axes may be different from the region of functions.
#g [op=axon; col=; num=; cod=; beg=; wid=; hei=; xsh=; ysh=; tsi=; tfo=; tki=;]
This operation allows programmer to draw the axonometrical projection of some 3-D object which is assumed to be described by single-valued function z(x,y) where x, y, z are the 3-D space coordinates. The object is drawn by lines across the x-z and y-z sections simultaneously or separately. The invisible lines are not shown. The object is placed inside the coordinate axes which show the values of x, y and z coordinates. The axonometrical projection is made using the point of view as a direction between (0,0,0) point of the object and point of view and a distance between these points. The algorithm of eliminating invisible lines was elaborated for positive coordinate of direction near the [1,1,1]. Below all parameters are described step by step. The color is defined by [col]. The sizes of the picture are defined by [wid] and [hei]. The position of the left-bottom corner is located at [xsh], [ysh]. The parameters of the font for values are defined by [tfo], [tki], [tsi] similarly the operaion [op=text;]. The function z(x,y) is decribed by real array numbers r() from the first element which is defined by [beg]. The other real parameters must be specified in the real array r() starting from element of index [num]. The array of parameters has the following structure:
xmi, xma, xfm, xdm, ymi, yma, yfm, ydm, zmi, zma, zfm, zdm, vp1, vp2, vp3, vpm, hx, hy.
Here [xmi] and [xma] are the minimum and maximum values on the x-axis; [xfm] is value for the position of the first short tick; [xdm] is the value difference between two short ticks. The parameters which names is starting with y and z mean the same for y and z axes. Values [vp1], [vp2], [vp3] decsribe the direction of the view point for the axonometrical projection. The three coordinates are used for convenience, really this vector is normalized to unity length. Separately, the distance is described by the value [vpm] which is decimal logarithm of the distance to avoid inputting large values. Be carefull to input not very large values because 3 means 1000, 5 means 100000 and so on. Normally [hx]=1 and [hy]=1. These parameters are convenient if instead of the real space object one like to draw some dependence f(a,b) where [f], [a] and [b] can have arbirtrary values. In this case to obtain the acceptable figure one must input the real values of arguments and then to choose the scaling coeffcients for x and y axes [hx] and [hy] in such a way that [da]*[hx] [db]*[hy] will have values close to [df] where da = [a]max - [a]min and the same for [b] and [f]. There are integer parameters as well. These parameters must be determined in the integer array i() starting from the index [cod]. The array of parameters has the following structure:
nx, ny, ngv, bot, top, nxfm, nxsm, nyfm, nysm, nzfm, nzsm, nax
Here [nx] is number of dots for x axis; [ny] is the same for y axis. The array of the function must contain only values without arguments as a matrix of [nx][ny]. The parameter [ngv] must be equal to 1 (for xz sections) 2 (for yz sections) 3 (for both sections simultaneously). The parameters [bot] and [top] describe the length of short and long ticks in units which are equal to 0.001 part of the diagonal for x and y axes correspondingly projected. Some correction will be made if [vp1] differs from [vp2]. The parameter [nxfm] is index of the first short tick which will be transformed to long tick and will have number. The parameters [nxsm] is number of short ticks between two long ticks. Other parameters mean the same for y and z axes. The last parameter [nax] describes the appearance of vertical axes. If [nax] = 0, the left and the right vertical axes will appear togethter with the middle axis and horizontal lines of levels. If [nax] = 1, only the right vertical axis appears near the x-axis. If [nax] = 2, only the left axis appears near the y-axis.
There is an example of ready program to show the object
#p [trx=0; try=0; sca=100;]
#d 6 i(1) 255 255 255 0 0 0
#col [b=1;le=2;fir=i(1);]
#g [op=open; twi=800; the=600; col=1;]
#d 12 i(1) 91 91 3 3 5 2 3 2 3 1 1 0
#d 18 r(1) -0,9 0,9 -0,9 0,1 -0,9 0,9 -0,9 0,1 0 1 0 0,1 1 1 1 3 1 1
#io [op=rd; n=91*91; file=surface.dat; fir=r(21);]
#g [op=axon; n=1; cod=1; beg=21; wid=600; hei=500; xsh=100; ysh=100; tfo=3; tki=0; tsi=14; col=2;]
#g [op=close; sav=0;] Test of Graphics\E
There are possibilities to change the whole figure without a change of the ACL-program. The figure can be translated and scaled. The translation distances for each elements are defined by the parameters [trx] and [try]. The real position of elements are defined by their coordinates plus the vector of transition. If this vector is nonzero the elements will be shifted. The parameter [sca] allows one to scale the sizes of elements. This parameter is measured in percents so [sca=100;] means unchanged objects. If [sca] < 100 all distances will be decreased including the sizes and the nominal positions (i. e. without translation). If [sca] > 100 they will be increased. However, if [sca] is negative, the absolute value will be used but only the sizes of the object will be scaled whereas the nominal positions will be unchanged. Note that such objects as [image] and [axes] cannot be scaled (at least today) by size. The images are used as is. As for the size of axes it must be changed explicitly. Very often the axes are made on images. So it is inconvenient to change one without other.
[ back to top ]
OTHERS
#%This is very simple but sometimes useful command. Since the ACL is a position insensitive language the ACLI uses the pointer which scans the text of the program and can operate with the character position inside the program text.
This command just puts the integer value which is equal to the position of its symbol [%] plus 2 inside the program text to the variable [%]. Then this information can be used by programmer.
One of the useful application of this command consists of checking some interactive code for the error. For this purpose there is the parameter [err]. Normally [err=0;]. In this case any error in the ACL-program which is checked by ACLI will lead to interruption of the program as it is described in general information. However, if programmer put #p [err=1;] then in the case of error in some subsequent command the program simply go to the location which is defined by current value of variable [%] and simultaneously [&]=10101. Therefore the combination
#p [err=1;] #% #case 10101 ... #end |
allows one to organized the specific error response when the program continues the work. For example, it is useful in interactive code when some input field allows user to input code dynamically and there is a possibility to improve code without stopping the program.
GOTO
goto (go)
#go n
This is command of unconditional transition. In old languages it was very popular. However, modern languages do not contain it at all or contain but give advice not to use it. The same in ACL. It is not necessary to use this command because all can be done without it. In addition to make a transition one must have a mark of location where the program must continue its work. In ACL marks are absent. Therefore the argument [n] of the command has a sense of absolute number of character of the program text counting from the beginning. It must be integer or letter of integer value including [$],[%],[&]. Of course, it is very difficult to count the characters. However, ACL has command #% which put the location of command to the variable [%]. This may be used to create marks. Many locations may be determined and saved in the array elements and then used for the transition. The transition may be done not only in the back direction but also in the forward direction. In this case user needs to print first the location and then to use numerical value. This command may be used in very complicated interactive program to realize some difficult situation.
INIT
init (ini)
#ini
This is rather simple command which can be used in some special cases. The second version of ACLI has a possibility to interrupt an execution of all loops if the user makes a click of menu item [Exec // Stop execution]. Without a possibility to make loops the program quickly runs to finish. However, just this command restore a normal possibility to make loops. So if the program has this command, only the loop before it will be interrupted but all other will work. This command is made for a future application of animation graphics. However it may be used when the program has two parts and second part is independent of the first part.
COMMENTS
Comments. The text of the comment may be written in any place of the program between the commands with the fixed length, namely, all commands except #calc #data #exec. If it is necessary to write the comment after these commands one may write before the comment the most simple operator of fixed length #% . The user should remember that for converting the command into the comment it is sufficient to erase one symbol [#] .
Other method to make some commands out of the program consists of opening the new procedure with these commands having any name. Then the commands will work only after call by the operator #exec.
The comment both between the parameters in the FPD and between the values in the field of arguments must begin with the sign [;] and end by the sign [=] (the signs [;] and [=] are the brackets for comment).
[ back to top ]
TABLES
Commands alphabetically=========
# a=..; i(1)=..; r(1)=..; s(1)=..; t(1)=..;
#cas cod ... #end |
#col [beg= ; len= ; fir= ;]
#d 5 r(1) 1,2 3,4 5,6 7,8*2 2 i(1) 1 2
#e [cod=..;] NAME NAME ...
#e _NAME
#e [cod=..; file=..;] file
#e [cod=..; beg=..; len==;] text
#exit
#f [op=choo;]
#f [op=copy; num=; file=newtotal;] file1.txt\E file2.txt\E ...
#f [op=dele; file=any;]
#f [op=divi; file=any; form=any; beg=; len=; num=; xsh=;]
#f [op=edit; mod=; file=any;]
#f [op=fcat; file=any;]
#f [op=find; beg=; len=; file=any;]
#f [op=fold; file=any;]
#f [op=list; file=any; cod=; beg=;]
#f[op=line; file=any; num=; beg=; len=;]
#f [op=repl; beg=; len=; mod=; file=any;]
#f [op=size; file=any;]
#g [op=open; twi=; the=; col=;]
#g [op=cont; num=;]
#g [op=close; sav=; form=;] FT
#g [op=text; nx=; ny=; col=; tfo=; tki=; tsi=; sty=;] FT
#g [op=line; nx=; ny=; col=; num=; beg=;]
#g [op=area; nx=; ny=; col=; num=; beg=; mod=;]
#g [op=rect; nx=; ny=; wid=; hei=; col=; mod=;]
#g [op=oval; nx=; ny=; wid=; hei=; col=; mod=;]
#g [op=arc; nx=; ny=; wid=; hei=; col=; mod=; beg=; len=;]
#g [op=image; nx=; ny=; num=; file=;]
#g [op=axes; col=; beg=; wid=; hei=; xsh=; ysh=; bot=; top=; sty=; tfo=; tki=; tsi=; uni=; num=;]
#g [op=rfun; file=; mod=; num=; len=; nx=; ny=; beg=;]
#g [op=dfun; col=; nx=; ny=; mod=; beg=; msi=; mki=;]
#g [op=axon; col=; num=; cod=; beg=; wid=; hei=; xsh=; ysh=; tsi=; tfo=; tki=;]
#go n
#inp [n=..; len=..; mo=..; ysh=..;] FT FT FT -> [&]
#io [op=..; fir=..; n=..; file=..; form=..;]
#m [op=txt;] FT
#m [op=win;] FT
#m [op=oce;] FT -> [&]
#m [op=yno;] FT -> [&]
#ma [op=mtr; beg=; nx=; ny=;]
#ma [op=fno; beg=; nx=; ny=; mod=;]
#ma [op=mss; beg=; nx=; ny=;]
#ma [op=vmc; beg=; len=;] after # C=..;
#ma [op=fft; beg=; nx=;]
#ma [op=mmi; num=; beg=; nx=; ny=; wig=; hei=; sav=; file=; form=;]
#ma [op=mcg; num=; beg=; nx=; ny=; sav=; file=; form=;]
#ma [op=fis; beg=; nx=; ny=; siz=;]
#ma [op=mii; beg=; nx=; my=; mod=;]
#p [...]
#pas n r(101) r(501)
#pri FT
#pro NAME ... @
#read [fir=..; n=..; beg=..; len=..;]
#rep n ... #end
#sel [nx=..;ny=..;mod=..;] FT FT -> [&]
#stop
#te [op=find; beg=..; len=..; n=..; cod=..;]
#te [op=repl; beg=..; len=..; cod=..; mod=..;]
#te [op=trim; beg=..; len=..;]
#w [op=im; file=; form=; num=; mod=; beg=; len=; twi=; the=; wid=; hei=; xsh=; ysh=; sty=; bot=; top=; nx=; ny=; sav=;]
#w [op=pf; file=; form=; beg=; len=; mod=; twi=; the=; wid=; hei=; xsh=; ysh=; sty=; bot=; top=; nx=; ny=; sav=; tsi=; uni=; tfo=; tki=; msi=; mki=;]
#w [op=mm; file=; form=; beg=; sav=; twi=; the=; wid=; hei=; sty=; bot=; top=; tsi=; uni=; tfo=; tki=;]
#w [op=ff; form=; sav=; num=; beg=;] FT
#z [op=cat; file=;]
#z [op=sfo; file=; num=;] FT FT ...
#z [op=gfo; file=; num=; mod=;] FT FT ...
#z [op=sfi; file=; num=;] FT FT ...
#z [op=gfi; file=; num=; mod=;] FT FT ...
#%
Parameters by name
==================
f [first] // text 8 bytes
o [operation] // text 4 bytes
fil [file] // text 42 bytes
fo [format] // text 42 bytes
b (begin) == s(9)
bo (bottom) == s(19)
c (code) == s(8)
col )color) == s(29)
er (error) == s(26)
hei (height) == s(15)
le (length) == s(10)
mk (mkind) == s(33)
mo (mode) == s(11)
ms (msize) == s(32)
n (number) == s(7)
nx (nxfunc) == s(21)
ny (nyfunc) == s(22)
sa (save) == s(23)
sc (scale) == s(36)
siz (size) == s(38)
st (style) == s(18)
tf (tfont) == s(30)
th (theight) == s(13)
tk (tkind) == s(31)
to (top) == s(20)
trx (trx) == s(34)
try (try) == s(35)
ts (tsize) == s(24)
tw (twidth) == s(12)
wid (width) == s(14)
xs (xshift) == s(16)
ys (yshift) == s(17)
un (units) == s(25)
Dynamical parameters
====================
s(1) - size of file in bytes in #f [op=size;], if s(1)=0, file is absent
---- number of locations in #te [op=find;]
s(2) - number of repetititon in #f [op=find;]
---- number of names in #f [op=list;]
s(3) - beginning of next record in #pri #inp
s(4) - beginning of made last record in #pri #file #input ...)
s(5) - size of last made record in #pri #file #input ...)
s(6) - size of filled part of textarr t() for saving to file and showing
Formatted text
==============
FT == ...\b ...\t ...\n ...\r
...\" ...\' ...\\ ...\- ...\# ...\@
...\[ ...\] ...\D ...\T<ifc> <nc>
...\U n n n*m ; ...\N<nt> <nf> n n n ;
...\G n n n ; ...\B<nt> <nf> n n n ; ...\E
[ back to top ]
PROGRAMMING
There are ready programs in the folger "proc" which can be examined and used as examples. These programs contain commands of interactive form of working. This form is convenient for ready and well done programs. However, for many simple tasks it is sufficient to use an internal environment with menu items "Execute program" and "Show textarr". For short i will call them as [Ep] and [St].The most simple program looks like this
#pri Hello World\E #stop
You can type it, then make [Ep] and then [Sp]. You will see "Hello world".
More complicated program can be like this
# a=2; b=a^2; c=sin(a/b);
#pri a =\N2 0 a;\n b =\N2 0 b;\n\-
c =\G c;\n\E #stop
Type it, then make [Ep] and then [Sp]. Note that on desktop you can make Copy and then Paste in the program editor.
This program uses the calculations and more complicated form of printing. The formatted text (FT) begins with any symbol (not blanck) and ends with \E. Note a necessity of the expression \- before end of line when the FT is not over. See description to understand what means the argument of the operator print (#pri). Of course if you want to calculate some function on the array of points you need to use cycle. This may be done like this # x=-2; N=101; #% first argument and number of points
#rep N #% repeat N times
# f=100*exp(-x^2); g=80*exp(-(x-0,5)^2); #% calculate two functions
#pri \G x f g;\n\E #% print current argument and two functions
# x=x+0,04; #% change argument
#end #stop #% end of cycle and stop
Type it, then make [Ep] and then [Sp].
You will see a table of three columns. Such table is ready for many graphical program. However there is a problem. Format \G is unacceptable for many standard programs due to absence of E before degree of ten and comma instead of point. Of course, you can use other format like this
#pri \B11 3 x f g;\n\E
This format will give standard representation of the values. The table is saved in the file (textarr.txt) on the main folder of program. You can use this file. But there is other way to save the data in the file. You calculate first array r() and then save it. The program may look like this.
# x=-2; N=101; i=1;
#rep N
# r(i)=x; i=i+1;
r(i)=100*exp(-x^2); i=i+1;
r(i)=80*exp(-(x-0,5)^2); i=i+1;
# x=x+0,04;
#end
#f [op=folder; file=myfold;]
#io [op=wf;n=N*3;fir=r(1);file=myfile;form=E3.11.3;]
#stop
Now the table will be saved in the file (myfile) inside the folder (myfold). If the folder or file were absent, they will be created.
The data may be shown directly on figure created by ACL itself. This may be done by additional code like this
#math [op=mtr;beg=1;nx=3;ny=N;]
#d 3 i(1) 255 0 0
#col [beg=2; len=1; fir=i(1);]
#d 16 s(10) 0 1 240 320 200 220 30 60 0 3
6 101 4 0 14 0
#w [op=pf; file=here; num=2; beg=1;]
100 30 Argument (a. u.)\E
70 305 Gaussians (arb. units)\E
In the code above the first command rearrange the array so that first there are all values of argument, then all values of the first function and then the same for the second function. It is necessary for the graphics program.
Next two command define the color of line for the second function as red. Then the arguments for the graphics are defined. Finally the last command makes the graphics.
You can always write the total code command by command. However, sometimes it is not convenient. There is a possibility to make procedure previously and then use it. However, you cannot write the code where the procedure is used first and then it is defined as in some compiled languages. There is a simple example.
# &=2;
#pro aaaa # x=1; @
#pro aaab # x=2; @
#pro aaac # x=3; @
#e [cod=1;] aaaa
#e [cod=2;] aaab
#e [cod=3;] aaac
As a result of this code we obtain x=2 because only the second procedure will be executed. The variable [&] has special meaning and it replaces all the logic in ACL.
The main difference of ACL from other languages is an absence of logical variables and logical operator. All other languages have three operators
if( condition ){ operations } in C and Java
if( condition ) then
operations
endif in Fortran
while( condition ){ operations } in C and Java
do while( condition )
operations
enddo in Fortran
switch(var){case 1: break case 2: break . . .} in C and Java
select case(var)
case()
case()
. . .
endselect in Fortran
In ACL all these operators are absent, instead of them only one command
#case cod operations #end or #end | or #end()
makes all the work. This command makes operations only if cod=& condition is fulfilled where cod is fixed value but & can change its value. Of course, this condition cannot replace all logic in a pure sense. However mathematical operation are added by two new operations [<] and [>] and this allows one to obtain all logic.
For example, command in Fortran like this
if( a .eq. 1 ) then
something
endif
can be written in ACL as
# &=a; #case 1 somethind #end |
The more complicated command in Fortran like this
if( a .le. 1 .and. b .ge. 2 )then
something
endif
can be written in ACL as
# &=(a-1)>0+(2-b)>0; #case 0 somethind #end |
Another condition
( a .le. 1 .or. b .ge. 2 )
is equivalent to
# &=(a-1)>0*(2-b)>0; #case 0 ...
In principle all conditions in "if()" operator can be written as equality to zero of some expression. The command #end | will change & to 12345 and then the body of cycle will be fulfilled only once or not fulfilled. To obtain the form "do while()" one has to use the form #end and calculate the variable & incide the cycle once again. The form "select case" is most simple. You define & once and then use many commands #case ... #end | with different cod. For example,
# &=2;
#case 1 ... #end |
#case 2 ... #end |
#case 3 ... #end |
and so on. This form is especially useful for creating the interface between program and user when the user select some button from the table of buttons.
The commands of any language can be divided on primitive commands which are a base of language and complex command which can be created from primitive commands as a procedure and are not necessary in a pure sense. However, in languages which are used without compiling there is difference between the procedure and ready command because the latter works much faster. The number of primitive commands is usually restricted, but the number of ready procedures can be as much as it is wanted by the language creators. That is why the number of such commands is not large in ACL but it will be increased when i will have time for this work.
The typical examples of very complicated command are #w and #f [op=edit;]. To use such command you need to read a description with attention and try it to use. The absence of compilation make the work fast and simple.
