A Guide to the S-Lang Language
John E. Davis, davis@space.mit.edu
Sat Feb 3 01:58:05 2001
____________________________________________________________
Table of Contents
Preface
1. A Brief History of S-Lang
2. Acknowledgements
2. Introduction
3. Language Features
4. Data Types and Operators
5. Statements and Functions
6. Error Handling
7. Run-Time Library
8. Input/Output
9. Obtaining S-Lang
9. Overview of the Language
10. Variables and Functions
11. Strings
12. Referencing and Dereferencing
13. Arrays
14. Structures and User-Defined Types
15. Namespaces
15. Data Types and Literal Constants
16. Predefined Data Types
16.1 Integers
16.2 Floating Point Numbers
16.3 Complex Numbers
16.4 Strings
16.5 Null_Type
16.6 Ref_Type
16.7 Array_Type and Struct_Type
16.8 DataType_Type Type
17. Typecasting: Converting from one Type to Another
17. Identifiers
17. Variables
17. Operators
18. Unary Operators
19. Binary Operators
19.1 Arithmetic Operators
19.2 Relational Operators
19.3 Boolean Operators
19.4 Bitwise Operators
19.5 Namespace operator
19.6 Operator Precedence
19.7 Binary Operators and Functions Returning Multiple Values
20. Mixing Integer and Floating Point Arithmetic
21. Short Circuit Boolean Evaluation
21. Statements
22. Variable Declaration Statements
23. Assignment Statements
24. Conditional and Looping Statements
24.1 Conditional Forms
24.1.1 if
24.1.2 if-else
24.1.3 !if
24.1.4 orelse, andelse
24.1.5 switch
24.2 Looping Forms
24.2.1 while
24.2.2 do...while
24.2.3 for
24.2.4 loop
24.2.5 forever
24.2.6 foreach
25. break, return, continue
25. Functions
26. Declaring Functions
27. Parameter Passing Mechanism
28. Referencing Variables
29. Functions with a Variable Number of Arguments
30. Returning Values
31. Multiple Assignment Statement
32. Exit-Blocks
32. Name Spaces
32. Arrays
33. Creating Arrays
33.1 Range Arrays
33.2 Creating arrays via the dereference operator
34. Reshaping Arrays
35. Indexing Arrays
36. Arrays and Variables
37. Using Arrays in Computations
37. Associative Arrays
37. Structures and User-Defined Types
38. Defining a Structure
39. Accessing the Fields of a Structure
40. Linked Lists
41. Defining New Types
41. Error Handling
42. Error-Blocks
43. Clearing Errors
43. Loading Files: evalfile and autoload
43. File Input/Output
44. Input/Output via stdio
44.1 Stdio Overview
44.2 Stdio Examples
45. POSIX I/O
46. Advanced I/O techniques
46.1 Example: Reading /var/log/wtmp
46.1 Debugging
46.1 Regular Expressions
47. S-Lang RE Syntax
48. Differences between S-Lang and egrep REs
48. Future Directions
48. Copyright
A. The GNU Public License
B. The Artistic License
______________________________________________________________________
1. Preface
S-Lang is an interpreted language that was designed from the start to
be easily embedded into a program to provide it with a powerful
extension language. Examples of programs that use S-Lang as an
extension language include the jed text editor, the slrn newsreader,
and sldxe (unreleased), a numerical computation program. For this
reason, S-Lang does not exist as a separate application and many of
the examples in this document are presented in the context of one of
the above applications.
S-Lang is also a programmer's library that permits a programmer to
develop sophisticated platform-independent software. In addition to
providing the S-Lang extension language, the library provides
facilities for screen management, keymaps, low-level terminal I/O,
etc. However, this document is concerned only with the extension
language and does not address these other features of the S-Lang
library. For information about the other components of the library,
the reader is referred to the The S-Lang Library Reference.
1.1. A Brief History of S-Lang
I first began working on S-Lang sometime during the fall of 1992. At
that time I was writing a text editor (jed), which I wanted to endow
with a macro language. It occured to me that an application-
independent language that could be embedded into the editor would
prove more useful because I could envision embedding it into other
programs. As a result, S-Lang was born.
S-Lang was originally a stack language that supported a postscript-
like syntax. For that reason, I named it S-Lang, where the S was
supposed to emphasize its stack-based nature. About a year later, I
began to work on a preparser that would allow one to write using a
more traditional infix syntax making it easier to use for those
unfamiliar with stack based languages. Currently, the syntax of the
language resembles C, nevertheless some postscript-like features still
remain, e.g., the `%' character is still used as a comment delimiter.
1.2. Acknowledgements
Since I first released S-Lang, I have received a lot feedback about
the library and the language from many people. This has given me the
opportunity and pleasure to interact with several people to make the
library portable and easy to use. In particular, I would like to
thank the following individuals:
Luchesar Ionkov <lionkov@sf.cit.bg> for his comments and criticisms of
the syntax of the language. He was the person who made me realize
that the low-level byte-code engine should be totally type-
independent. He also improved the tokenizer and preparser and
impressed upon me that the language needed a grammar.
Mark Olesen <olesen@weber.me.queensu.ca> for his many patches to
various aspects of the library and his support on AIX. He also
contributed a lot to the pre-processing (SLprep) routines.
John Burnell <j.burnell@irl.cri.nz> for the OS/2 port of the video and
keyboard routines. He also made value suggestions regarding the
interpreter interface.
Darrel Hankerson <hankedr@mail.auburn.edu> for cleaning up and
unifying some of the code and the makefiles.
Dominik Wujastyk <ucgadkw@ucl.ac.uk> who was always willing to test
new releases of the library.
Michael Elkins <me@muddcs.cs.hmc.edu> for his work on the curses
emulation.
Ulli Horlacher <framstag@belwue.de> and Oezguer Kesim <kesim@math.fu-
berlin.de> for the S-Lang newsgroup and mailing list.
Hunter Goatley, Andy Harper <Andy.Harper@kcl.ac.uk>, and Martin P.J.
Zinser <zinser@decus.decus.de> for their VMS support.
Dave Sims <sims@usa.acsys.com> and Chin Huang <cthuang@vex.net> for
Windows 95 and Windows NT support.
Lloyd Zusman <ljz@asfast.com> and Rich Roth <rich@on-the-net.com> for
creating and maintaining www.s-lang.org.
I am also grateful to many other people who send in bug-reports and
bug-fixes, for without such community involvement, S-Lang would not be
as well-tested and stable as it is. Finally, I would like to thank my
wife for her support and understanding while I spent long weekend
hours developing the library.
2. Introduction
S-Lang is a powerful interpreted language that may be embedded into an
application to make the application extensible. This enables the
application to be used in ways not envisioned by the programmer, thus
providing the application with much more flexibility and power.
Examples of applications that take advantage of the interpreter in
this way include the jed editor and the slrn newsreader.
2.1. Language Features
The language features both global and local variables, branching and
looping constructs, user-defined functions, structures, datatypes, and
arrays. In addition, there is limited support for pointer types. The
concise array syntax rivals that of commercial array-based numerical
computing environments.
2.2. Data Types and Operators
The language provides built-in support for string, integer (signed and
unsigned long and short), double precision floating point, and double
precision complex numbers. In addition, it supports user defined
structure types, multi-dimensional array types, and associative
arrays. To facilitate the construction of sophisticated data
structures such as linked lists and trees, a `reference' type was
added to the language. The reference type provides much of the same
flexibility as pointers in other languages. Finally, applications
embedding the interpreter may also provide special application
specific types, such as the Mark_Type that the jed editor provides.
The language provides standard arithmetic operations such as addition,
subtraction, multiplication, and division. It also provides support
for modulo arithmetic as well as operations at the bit level, e.g.,
exclusive-or. Any binary or unary operator may be extended to work
with any data type. For example, the addition operator (+) has been
extended to work between string types to permit string concatenation.
The binary and unary operators work transparently with array types.
For example, if a and b are arrays, then a + b produces an array whose
elements are the result of element by element addition of a and b.
This permits one to do vector operations without explicitly looping
over the array indices.
2.3. Statements and Functions
The S-Lang language supports several types of looping constructs and
conditional statements. The looping constructs include while,
do...while, for, forever, loop, foreach, and _for. The conditional
statements include if, if-then-else, and !if.
User defined functions may be defined to return zero, one, or more
values. Functions that return zero values are similar to `procedures'
in languages such as PASCAL. The local variables of a function are
always created on a stack allowing one to create recursive functions.
Parameters to a function are always passed by value and never by
reference. However, the language supports a reference data type that
allows one to simulate pass by reference.
Unlike many interpreted languages, S-Lang allows functions to be
dynamically loaded (function autoloading). It also provides
constructs specifically designed for error handling and recovery as
well as debugging aids (e.g., function tracebacks).
Functions and variables may be declared as private belonging to a
namespace associated with the compilation unit that defines the
function or variable. The ideas behind the namespace implementation
stems from the C language and should be quite familiar to any one
familiar with C.
2.4. Error Handling
The S-Lang language defines a construct called an error-block that may
be used for error handling and recovery. When a non-fatal run-time
error is encountered, any error blocks that have been defined are
executed as the run-time stack unwinds. An error block can optionally
clear the error and the program will continue running after the
statement that triggered the error. This mechanism is somewhat
similar to try-catch in C++.
2.5. Run-Time Library
Functions that compose the S-Lang run-time library are called
intrinsics. Examples of S-Lang intrinsic functions available to every
S-Lang application include string manipulation functions such as
strcat, strchop, and strcmp. The S-Lang library also provides
mathematical functions such as sin, cos, and tan; however, not all
applications enable the use of these intrinsics. For example, to
conserve memory, the 16 bit version of the jed editor does not provide
support for any mathematics other than simple integer arithmetic,
whereas other versions of the editor do support these functions.
Most applications embedding the languages will also provide a set of
application specific intrinsic functions. For example, the jed editor
adds over 100 application specific intrinsic functions to the
language. Consult your application specific documentation to see what
additional intrinsics are supported.
2.6. Input/Output
The language supports C-like stdio input/output functions such as
fopen, fgets, fputs, and fclose. In addition it provides two
functions, message and error, for writing to the standard output
device and standard error. Specific applications may provide other
I/O mechanisms, e.g., the jed editor supports I/O to files via the
editor's buffers.
2.7. Obtaining S-Lang
Comprehensive information about the library may be obtained via the
World Wide Web from http://www.s-lang.org.
S-Lang as well as some programs that embed it are freely available via
anonymous ftp in the United States from
o ftp://space.mit.edu/pub/davis.
It is also available outside the United States from the following
mirror sites:
o ftp://ftp.uni-stuttgart.de/pub/unix/misc/slang/
o ftp://ftp.fu-berlin.de/pub/unix/news/slrn/
o ftp://ftp.ntua.gr/pub/lang/slang/
The Usenet newsgroup alt.lang.s-lang was created for S-Lang
programmers to exchange information and share macros for the various
programs the embed the language. The newsgroup comp.editors can be a
useful resource for S-Lang macros for the jed editor. Similarly, slrn
users will find news.software.readers to be a valuable source of
information.
Finally, two mailing lists dealing with the S-Lang library have been
created:
o slang-announce@babayaga.math.fu-berlin.de
o slang-workers@babayaga.math.fu-berlin.de
The first list is for announcements of new releases of the library,
while the second list is intended for those who use the library for
their own code development. To subscribe to the announcement list,
send an email to slang-announce-subscribe@babayaga.math.fu-
berlin.de and include the word subscribe in the body of the
message. To subscribe to the developers list, use the address
slang-workers-subscribe@babayaga.math.fu-berlin.de.
3. Overview of the Language
This purpose of this section is to give the reader a feel for the S-
Lang language, its syntax, and its capabilities. The information and
examples presented in this section should be sufficient to provide the
reader with the necessary background to understand the rest of the
document.
3.1. Variables and Functions
S-Lang is different from many other interpreted languages in the sense
that all variables and functions must be declared before they can be
used.
Variables are declared using the variable keyword, e.g.,
variable x, y, z;
declares three variables, x, y, and z. Note the semicolon at the end
of the statement. All S-Lang statements must end in a semi-colon.
Unlike compiled languages such as C, it is not necessary to specify
the data type of a S-Lang variable. The data type of a S-Lang
variable is determined upon assignment. For example, after execution
of the statements
x = 3;
y = sin (5.6);
z = "I think, therefore I am.";
x will be an integer, y will be a double, and z will be a string. In
fact, it is even possible to re-assign x to a string:
x = "x was an integer, but now is a string";
Finally, one can combine variable declarations and assignments in the
same statement:
variable x = 3, y = sin(5.6), z = "I think, therefore I am.";
Most functions are declared using the define keyword. A simple
example is
define compute_average (x, y)
{
variable s = x + y;
return s / 2.0;
}
which defines a function that simply computes the average of two num-
bers and returns the result. This example shows that a function con-
sists of three parts: the function name, a parameter list, and the
function body.
The parameter list consists of a comma separated list of variable
names. It is not necessary to declare variables within a parameter
list; they are implicitly declared. However, all other local
variables used in the function must be declared. If the function
takes no parameters, then the parameter list must still be present,
but empty:
define go_left_5 ()
{
go_left (5);
}
The last example is a function that takes no arguments and returns no
value. Some languages such as PASCAL distinguish such objects from
functions that return values by calling these objects procedures.
However, S-Lang, like C, does not make such a distinction.
The language permits recursive functions, i.e., functions that call
themselves. The way to do this in S-Lang is to first declare the
function using the form:
define function-name ();
It is not necessary to declare a parameter list when declaring a func-
tion in this way.
The most famous example of a recursive function is the factorial
function. Here is how to implement it using S-Lang:
define factorial (); % declare it for recursion
define factorial (n)
{
if (n < 2) return 1;
return n * factorial (n - 1);
}
This example also shows how to mix comments with code. S-Lang uses
the `%' character to start a comment and all characters from the com-
ment character to the end of the line are ignored.
3.2. Strings
Perhaps the most appealing feature of any interpreted language is that
it frees the user from the responsibility of memory management. This
is particularly evident when contrasting how S-Lang handles string
variables with a lower level language such as C. Consider a function
that concatenates three strings. An example in S-Lang is:
define concat_3_strings (a, b, c)
{
return strcat (a, strcat (b, c));
}
This function uses the built-in strcat function for concatenating two
strings. In C, the simplest such function would look like:
char *concat_3_strings (char *a, char *b, char *c)
{
unsigned int len;
char *result;
len = strlen (a) + strlen (b) + strlen (c);
if (NULL == (result = (char *) malloc (len + 1)))
exit (1);
strcpy (result, a);
strcat (result, b);
strcat (result, c);
return result;
}
Even this C example is misleading since none of the issues of memory
management of the strings has been dealt with. The S-Lang language
hides all these issues from the user.
Binary operators have been defined to work with the string data type.
In particular the + operator may be used to perform string
concatenation. That is, one can use the + operator as an alternative
to strcat:
define concat_3_strings (a, b, c)
{
return a + b + c;
}
See section ??? for more information about string variables.
3.3. Referencing and Dereferencing
The unary prefix operator, &, may be used to create a reference to an
object, which is similar to a pointer in other languages. References
are commonly used as a mechanism to pass a function as an argument to
another function as the following example illustrates:
define compute_functional_sum (funct)
{
variable i, sum;
sum = 0;
for (i = 0; i < 10; i++)
{
sum += @funct (i);
}
return sum;
}
variable sin_sum = compute_functional_sum (&sin);
variable cos_sum = compute_functional_sum (&cos);
Here, the function compute_functional_sum applies the function speci-
fied by the parameter funct to the first 10 integers and returns the
sum. The two statements following the function definition show how
the sin and cos functions may be used.
Note the @ operator in the definition of compute_functional_sum. It
is known as the dereference operator and is the inverse of the
reference operator.
Another use of the reference operator is in the context of the fgets
function. For example,
define read_nth_line (file, n)
{
variable fp, line;
fp = fopen (file, "r");
while (n > 0)
{
if (-1 == fgets (&line, fp))
return NULL;
n--;
}
return line;
}
uses the fgets function to read the nth line of a file. In particu-
lar, a reference to the local variable line is passed to fgets, and
upon return line will be set to the character string read by fgets.
Finally, references may be used as an alternative to multiple return
values by passing information back via the parameter list. The
example involving fgets presented above provided an illustration of
this. Another example is
define set_xyz (x, y, z)
{
@x = 1;
@y = 2;
@z = 3;
}
variable X, Y, Z;
set_xyz (&X, &Y, &Z);
which, after execution, results in X set to 1, Y set to 2, and Z set
to 3. A C programmer will note the similarity of set_xyz to the fol-
lowing C implementation:
void set_xyz (int *x, int *y, int *z)
{
*x = 1;
*y = 2;
*z = 3;
}
3.4. Arrays
The S-Lang language supports multi-dimensional arrays of all
datatypes. For example, one can define arrays of references to
functions as well as arrays of arrays. Here are a few examples of
creating arrays:
variable A = Integer_Type [10];
variable B = Integer_Type [10, 3];
variable C = [1, 3, 5, 7, 9];
The first example creates an array of 10 integers and assigns it to
the variable A. The second example creates a 2-d array of 30 integers
arranged in 10 rows and 3 columns and assigns the result to B. In the
last example, an array of 5 integers is assigned to the variable C.
However, in this case the elements of the array are initialized to the
values specified. This is known as an inline-array.
S-Lang also supports something called an range-array. An example of
such an array is
variable C = [1:9:2];
This will produce an array of 5 integers running from 1 through 9 in
increments of 2.
Arrays are passed by reference to functions and never by value. This
permits one to write functions which can initialize arrays. For
example,
define init_array (a)
{
variable i, imax;
imax = length (a);
for (i = 0; i < imax; i++)
{
a[i] = 7;
}
}
variable A = Integer_Type [10];
init_array (A);
creates an array of 10 integers and initializes all its elements to 7.
There are more concise ways of accomplishing the result of the
previous example. These include:
variable A = [7, 7, 7, 7, 7, 7, 7, 7, 7, 7];
variable A = Integer_Type [10]; A[[0:9]] = 7;
variable A = Integer_Type [10]; A[*] = 7;
The second and third methods use an array of indices to index the
array A. In the second, the range of indices has been explicitly
specified, whereas the third example uses a wildcard form. See sec-
tion ??? for more information about array indexing.
Although the examples have pertained to integer arrays, the fact is
that S-Lang arrays can be of any type, e.g.,
variable A = Double_Type [10];
variable B = Complex_Type [10];
variable C = String_Type [10];
variable D = Ref_Type [10];
create 10 element arrays of double, complex, string, and reference
types, respectively. The last example may be used to create an array
of functions, e.g.,
D[0] = &sin;
D[1] = &cos;
The language also defines unary, binary, and mathematical operations
on arrays. For example, if A and B are integer arrays, then A + B is
an array whose elements are the sum of the elements of A and B. A
trivial example that illustrates the power of this capability is
variable X, Y;
X = [0:2*PI:0.01];
Y = 20 * sin (X);
which is equivalent to the highly simplified C code:
double *X, *Y;
unsigned int i, n;
n = (2 * PI) / 0.01 + 1;
X = (double *) malloc (n * sizeof (double));
Y = (double *) malloc (n * sizeof (double));
for (i = 0; i < n; i++)
{
X[i] = i * 0.01;
Y[i] = 20 * sin (X[i]);
}
3.5. Structures and User-Defined Types
A structure is similar to an array in the sense that it is a container
object. However, the elements of an array must all be of the same
type (or of Any_Type), whereas a structure is heterogeneous. As an
example, consider
variable person = struct
{
first_name, last_name, age
};
variable bill = @person;
bill.first_name = "Bill";
bill.last_name = "Clinton";
bill.age = 51;
In this example a structure consisting of the three fields has been
created and assigned to the variable person. Then an instance of this
structure has been created using the dereference operator and assigned
to bill. Finally, the individual fields of bill were initialized.
This is an example of an anonymous structure.
A named structure is really a new data type and may be created using
the typedef keyword:
typedef struct
{
first_name, last_name, age
}
Person_Type;
variable bill = @Person_Type;
bill.first_name = "Bill";
bill.last_name = "Clinton";
bill.age = 51;
The big advantage of creating a new type is that one can go on to cre-
ate arrays of the data type
variable People = Person_Type [100];
People[0].first_name = "Bill";
People[1].first_name = "Hillary";
The creation and initialization of a structure may be facilitated by a
function such as
define create_person (first, last, age)
{
variable person = @Person_Type;
person.first_name = first;
person.last_name = last;
person.age = age;
return person;
}
variable Bill = create_person ("Bill", "Clinton", 51);
Other common uses of structures is the creation of linked lists,
binary trees, etc. For more information about these and other
features of structures, see section ???.
3.6. Namespaces
In addition to the global namespace, each compilation unit (e.g., a
file) is given a private namespace. A variable or function name that
is declared using the static keyword will be placed in the private
namespace associated with compilation unit. For example,
variable i;
static variable i;
defines two variables called i. The first declaration defines i in
the global namespace, but the second declaration defines i in the
private namespace.
The -> operator may be used in conjunction with the name of the
namespace to access objects in the name space. In the above example,
to access the variable i in the global namespace, one would use
Global->i. Unless otherwise specified, a private namespace has no
name and its objects may not be accessed from outside the compilation
unit. However, the implements function may be used give the private
namespace a name, allowing access to its objects. For example, if the
file t.sl contains
implements ("A");
static variable i;
then another file may access the variable i via A->i.
4. Data Types and Literal Constants
The current implementation of the S-Lang language permits up to 256
distinct data types, including predefined data types such as integer
and floating point, as well as specialized applications specific data
types. It is also possible to create new data types in the language
using the typedef mechanism.
Literal constants are objects such as the integer 3 or the string
"hello". The actual data type given to a literal constant depends
upon the syntax of the constant. The following sections describe the
syntax of literals of specific data types.
4.1. Predefined Data Types
The current version of S-Lang defines integer, floating point,
complex, and string types. It also defines special purpose data types
such as Null_Type, DataType_Type, and Ref_Type. These types are
discussed below.
4.1.1. Integers
The S-Lang language supports both signed and unsigned characters,
short integer, long integer, and plain integer types. On most 32 bit
systems, there is no difference between an integer and a long integer;
however, they may differ on 16 and 64 bit systems. Generally
speaking, on a 16 bit system, plain integers are 16 bit quantities
with a range of -32767 to 32767. On a 32 bit system, plain integers
range from -2147483648 to 2147483647.
An plain integer literal can be specified in one of several ways:
o As a decimal (base 10) integer consisting of the characters 0
through 9, e.g., 127. An integer specified this way cannot begin
with a leading 0. That is, 0127 is not the same as 127.
o Using hexadecimal (base 16) notation consisting of the characters 0
to 9 and A through F. The hexadecimal number must be preceded by
the characters 0x. For example, 0x7F specifies an integer using
hexadecimal notation and has the same value as decimal 127.
o In Octal notation using characters 0 through 7. The Octal number
must begin with a leading 0. For example, 0177 and 127 represent
the same integer.
Short, long, and unsigned types may be specified by using the
proper suffixes: L indicates that the integer is a long integer, h
indicates that the integer is a short integer, and U indicates that
it is unsigned. For example, 1UL specifies an unsigned long
integer.
Finally, a character literal may be specified using a notation
containing a character enclosed in single quotes as 'a'. The value
of the character specified this way will lie in the range 0 to 256
and will be determined by the ASCII value of the character in
quotes. For example,
i = '0';
assigns to i the character 48 since the '0' character has an ASCII
value of 48.
Any integer may be preceded by a minus sign to indicate that it is a
negative integer.
4.1.2. Floating Point Numbers
Single and double precision floating point literals must contain
either a decimal point or an exponent (or both). Here are examples of
specifying the same double precision point number:
12. 12.0 12e0 1.2e1 120e-1 .12e2 0.12e2
Note that 12 is not a floating point number since it contains neither
a decimal point nor an exponent. In fact, 12 is an integer.
One may append the f character to the end of the number to indicate
that the number is a single precision literal.
4.1.3. Complex Numbers
The language implements complex numbers as a pair of double precision
floating point numbers. The first number in the pair forms the real
part, while the second number forms the imaginary part. That is, a
complex number may be regarded as the sum of a real number and an
imaginary number.
Strictly speaking, the current implementation of the S-Lang does not
support generic complex literals. However, it does support imaginary
literals and a more generic complex number with a non-zero real part
may be constructed from the imaginary literal via addition of a real
number.
An imaginary literal is specified in the same way as a floating point
literal except that i or j is appended. For example,
12i 12.0i 12e0j
all represent the same imaginary number. Actually, 12i is really an
imaginary integer except that S-Lang automatically promotes it to a
double precision imaginary number.
A more generic complex number may be constructed from an imaginary
literal via addition, e.g.,
3.0 + 4.0i
produces a complex number whose real part is 3.0 and whose imaginary
part is 4.0.
The intrinsic functions Real and Imag may be used to retrieve the real
and imaginary parts of a complex number, respectively.
4.1.4. Strings
A string literal must be enclosed in double quotes as in:
"This is a string".
Although there is no imposed limit on the length of a string, string
literals must be less than 256 characters in length. It is possible
to go beyond this limit by string concatenation, e.g.,
"This is the first part of a long string"
+ "and this is the second half"
Any character except a newline (ASCII 10) or the null character (ASCII
0) may appear explicitly in a string literal. However, these charac-
ters may be used implicitly using the mechanism described below.
The backslash character is a special character and is used to include
other special characters (such as a newline character) in the string.
The special characters recognized are:
\" -- double quote
\' -- single quote
\\ -- backslash
\a -- bell character (ASCII 7)
\t -- tab character (ASCII 9)
\n -- newline character (ASCII 10)
\e -- escape character (ASCII 27)
\xhhh -- character expressed in HEXADECIMAL notation
\ooo -- character expressed in OCTAL notation
\dnnn -- character expressed in DECIMAL
For example, to include the double quote character as part of the
string, it must be preceded by a backslash character, e.g.,
"This is a \"quote\""
Similarly, the next illustrates how a newline character may be
included:
"This is the first line\nand this is the second"
4.1.5. Null_Type
Objects of type Null_Type can have only one value: NULL. About the
only thing that you can do with this data type is to assign it to
variables and test for equality with other objects. Nevertheless,
Null_Type is an important and extremely useful data type. Its main
use stems from the fact that since it can be compared for equality
with any other data type, it is ideal to represent the value of an
object which does not yet have a value, or has an illegal value.
As a trivial example of its use, consider
define add_numbers (a, b)
{
if (a == NULL) a = 0;
if (b == NULL) b = 0;
return a + b;
}
variable c = add_numbers (1, 2);
variable d = add_numbers (1, NULL);
variable e = add_numbers (1,);
variable f = add_numbers (,);
It should be clear that after these statements have been executed, c
will have a value of 3. It should also be clear that d will have a
value of 1 because NULL has been passed as the second parameter. One
feature of the language is that if a parameter has been omitted from a
function call, the variable associated with that parameter will be set
to NULL. Hence, e and f will be set to 1 and 0, respectively.
The Null_Type data type also plays an important role in the context of
structures.
4.1.6. Ref_Type
Objects of Ref_Type are created using the unary reference operator &.
Such objects may be dereferenced using the dereference operator @.
For example,
variable sin_ref = &sin;
variable y = @sin_ref (1.0);
creates a reference to the sin function and assigns it to sin_ref.
The second statement uses the dereference operator to call the func-
tion that sin_ref references.
The Ref_Type is useful for passing functions as arguments to other
functions, or for returning information from a function via its
parameter list. The dereference operator is also used to create an
instance of a structure. For these reasons, further discussion of
this important type can be found in section ??? and section ???.
4.1.7. Array_Type and Struct_Type
Variables of type Array_Type and Struct_Type are known as container
objects. They are much more complicated than the simple data types
discussed so far and each obeys a special syntax. For these reasons
they are discussed in a separate chapters. See ???.
4.1.8. DataType_Type Type
S-Lang defines a type called DataType_Type. Objects of this type have
values that are type names. For example, an integer is an object of
type Integer_Type. The literals of DataType_Type include:
Char_Type (signed character)
UChar_Type (unsigned character)
Short_Type (short integer)
UShort_Type (unsigned short integer)
Integer_Type (plain integer)
UInteger_Type (plain unsigned integer)
Long_Type (long integer)
ULong_Type (unsigned long integer)
Float_Type (single precision real)
Double_Type (double precision real)
Complex_Type (complex numbers)
String_Type (strings, C strings)
BString_Type (binary strings)
Struct_Type (structures)
Ref_Type (references)
Null_Type (NULL)
Array_Type (arrays)
DataType_Type (data types)
as well as the names of any other types that an application defines.
The built-in function typeof returns the data type of its argument,
i.e., a DataType_Type. For instance typeof(7) returns Integer_Type
and typeof(Integer_Type) returns DataType_Type. One can use this
function as in the following example:
if (Integer_Type == typeof (x)) message ("x is an integer");
The literals of DataType_Type have other uses as well. One of the
most common uses of these literals is to create arrays, e.g.,
x = Complex_Type [100];
creates an array of 100 complex numbers and assigns it to x.
4.2. Typecasting: Converting from one Type to Another
Occasionally, it is necessary to convert from one data type to
another. For example, if you need to print an object as a string, it
may be necessary to convert it to a String_Type. The typecast
function may be used to perform such conversions. For example,
consider
variable x = 10, y;
y = typecast (x, Double_Type);
After execution of these statements, x will have the integer value 10
and y will have the double precision floating point value 10.0. If
the object to be converted is an array, the typecast function will act
upon all elements of the array. For example,
variable x = [1:10]; % Array of integers
variable y = typecast (x, Double_Type);
will create an array of 10 double precision values and assign it to y.
One should also realize that it is not always possible to perform a
typecast. For example, any attempt to convert an Integer_Type to a
Null_Type will result in a run-time error.
Often the interpreter will perform implicit type conversions as
necessary to complete calculations. For example, when multiplying an
Integer_Type with a Double_Type, it will convert the Integer_Type to a
Double_Type for the purpose of the calculation. Thus, the example
involving the conversion of an array of integers to an array of
doubles could have been performed by multiplication by 1.0, i.e.,
variable x = [1:10]; % Array of integers
variable y = 1.0 * x;
The string intrinsic function is similar to the typecast function
except that it converts an object to a string representation. It is
important to understand that a typecast from some type to String_Type
is not the same as converting an object to its string operation.
That is, typecast(x,String_Type) is not equivalent to string(x). The
reason for this is that when given an array, the typecast function
acts on each element of the array to produce another array, whereas
the string function produces a a string.
The string function is useful for printing the value of an object.
This use is illustrated in the following simple example:
define print_object (x)
{
message (string (x));
}
Here, the message function has been used because it writes a string to
the display. If the string function was not used and the message
function was passed an integer, a type-mismatch error would have
resulted.
5. Identifiers
The names given to variables, functions, and data types are called
identifiers. There are some restrictions upon the actual characters
that make up an identifier. An identifier name must start with a
letter ([A-Za-z]), an underscore character, or a dollar sign. The
rest of the characters in the name can be any combination of letters,
digits, dollar signs, or underscore characters. However, all
identifiers whose name begins with two underscore characters are
reserved for internal use by the interpreter and declarations of
objects with such names should be avoided.
Examples of valid identifiers include:
mary _3 _this_is_ok
a7e1 $44 _44$_Three
However, the following are not legal:
7abc 2e0 #xx
In fact, 2e0 actually specifies the real number 2.0.
Although the maximum length of identifiers is unspecified by the
language, the length should be kept below 64 characters.
The following identifiers are reserved by the language for use as
keywords:
!if _for do mod sign xor
ERROR_BLOCK abs do_while mul2 sqr public
EXIT_BLOCK and else not static private
USER_BLOCK0 andelse exch or struct
USER_BLOCK1 break for orelse switch
USER_BLOCK2 case foreach pop typedef
USER_BLOCK3 chs forever return using
USER_BLOCK4 continue if shl variable
__tmp define loop shr while
6. Variables
A variable must be declared before it can be used, otherwise an
undefined name error will be generated. A variable is declared using
the variable keyword, e.g,
variable x, y, z;
declares three variables, x, y, and z. This is an example of a vari-
able declaration statement, and like all statements, it must end in a
semi-colon.
Variables declared this way are untyped and inherit a type upon
assignment. The actual type checking is performed at run-time. For
example,
x = "This is a string";
x = 1.2;
x = 3;
x = 2i;
results in x being set successively to a string, a float, an integer,
and to a complex number (0+2i). Any attempt to use a variable before
it has acquired a type will result in an uninitialized variable error.
It is legal to put executable code in a variable declaration list.
That is,
variable x = 1, y = sin (x);
are legal variable declarations. This also provides a convenient way
of initializing a variable.
Variables are classified as either global or local. A variable
declared inside a function is said to be local and has no meaning
outside the function. A variable is said to be global if it was
declared outside a function. Global variables are further classified
as being public, static, or private, according to the name space where
they were defined. See chapter ??? for more information about name
spaces.
The following global variables are predefined by the language and are
mainly used as convenience variables:
$0 $1 $2 $3 $4 $5 $6 $7 $8 $9
An intrinsic variable is another type of global variable. Such
variables have a definite type which cannot be altered. Variables of
this type may also be defined to be read-only, or constant variables.
An example of an intrinsic variable is PI which is a read-only double
precision variable with a value of approximately
3.14159265358979323846.
7. Operators
S-Lang supports a variety of operators that are grouped into three
classes: assignment operators, binary operators, and unary operators.
An assignment operator is used to assign a value to a variable. They
will be discussed more fully in the context of the assignment
statement in section ???.
An unary operator acts only upon a single quantity while a binary
operation is an operation between two quantities. The boolean
operator not is an example of an unary operator. Examples of binary
operators include the usual arithmetic operators +, -, *, and /. The
operator given by - can be either an unary operator (negation) or a
binary operator (subtraction); the actual operation is determined from
the context in which it is used.
Binary operators are used in algebraic forms, e.g., a + b. Unary
operators fall in one of two classes: postfix-unary or prefix-unary.
For example, in the expression -x, the minus sign is a prefix-unary
operator.
Not all data types have binary or unary operations defined. For
example, while String_Type objects support the + operator, they do not
admit the * operator.
7.1. Unary Operators
The unary operators operate only upon a single operand. They include:
not, ~, -, @, &, as well as the increment and decrement operators ++
and --, respectively.
The boolean operator not acts only upon integers and produces 0 if its
operand is non-zero, otherwise it produces 1.
The bit-level not operator ~ performs a similar function, except that
it operates on the individual bits of its integer operand.
The arithmetic negation operator - is the most well-known unary
operator. It simply reverses the sign of its operand.
The reference (&) and dereference (@) operators will be discussed in
greater detail in section ???. Similarly, the increment (++) and
decrement (--) operators will be discussed in the context of the
assignment operator.
7.2. Binary Operators
The binary operators may be grouped according to several classes:
arithmetic operators, relational operators, boolean operators, and
bitwise operators.
All binary and unary operators may be overloaded. For example, the
arithmetic plus operator has been overloaded by the String_Type data
type to permit concatenation between strings.
7.2.1. Arithmetic Operators
The arithmetic operators include +, -, *, /, which perform addition,
subtraction, multiplication, and division, respectively. In addition
to these, S-Lang supports the mod operator as well as the power
operator ^.
The data type of the result produced by the use of one of these
operators depends upon the data types of the binary participants. If
they are both integers, the result will be an integer. However, if
the operands are not of the same type, they will be converted to a
common type before the operation is performed. For example, if one is
a floating point value and the other is an integer, the integer will
be converted to a float. In general, the promotion from one type to
another is such that no information is lost, if possible. As an
example, consider the expression 8/5 which indicates division of the
integer 8 by the integer 5. The result will be the integer 1 and not
the floating point value 1.6. However, 8/5.0 will produce 1.6 because
5.0 is a floating point number.
7.2.2. Relational Operators
The relational operators are >, >=, <, <=, ==, and !=. These perform
the comparisons greater than, greater than or equal, less than, less
than or equal, equal, and not equal, respectively. The result of one
of these comparisons is the integer 1 if the comparison is true, or 0
if the comparison is false. For example, 6 >= 5 returns 1, but 6 == 5
produces 0.
7.2.3. Boolean Operators
There are only two boolean binary operators: or and and. These
operators are defined only for integers and produce an integer result.
The or operator returns 1 if either of its operands are non-zero,
otherwise it produces 0. The and operator produces 1 if and only if
both its operands are non-zero, otherwise it produces 0.
Neither of these operators perform the so-called boolean short-circuit
evaluation. For example, consider the expression:
(x != 0) and (1/x > 10)
Here, if x were to have a value of zero, a division by zero error
would occur because even though x!=0 evaluates to zero, the and opera-
tor is not short-circuited and the 1/x expression would still be eval-
uated. Although these operators are not short-circuited, S-Lang does
have another mechanism of performing short-circuit boolean evaluation
via the orelse and andelse expressions. See below for information
about these constructs.
7.2.4. Bitwise Operators
The bitwise binary operators are defined only with integer operands
and are used for bit-level operations. Operators that fall in this
class include &, |, shl, shr, and xor. The & operator performs a
boolean AND operation between the corresponding bits of the operands.
Similarly, the | operator performs the boolean OR operation on the
bits. The bit-shifting operators shl and shr shift the bits of the
first operand by the number given by the second operand to the left or
right, respectively. Finally, the xor performs an EXCLUSIVE-OR
operation.
These operators are commonly used to manipulate variables whose
individual bits have distinct meanings. In particular, & is usually
used to test bits, | can be used to set bits, and xor may be used to
flip a bit.
As an example of using & to perform tests on bits, consider the
following: The jed text editor stores some of the information about a
buffer in a bitmapped integer variable. The value of this variable
may be retrieved using the jed intrinsic function getbuf_info, which
actually returns four quantities: the buffer flags, the name of the
buffer, directory name, and file name. For the purposes of this
section, only the buffer flags are of interest and can be retrieved
via a function such as
define get_buffer_flags ()
{
variable flags;
(,,,flags) = getbuf_info ();
return flags;
}
The buffer flags is a bitmapped quantity where the 0th bit indicates
whether or not the buffer has been modified, the first bit indicates
whether or not autosave has been enabled for the buffer, and so on.
Consider for the moment the task of determining if the buffer has been
modified. This can be determined by looking at the zeroth bit, if it
is 0 the buffer has not been modified, otherwise it has. Thus we can
create the function,
define is_buffer_modified ()
{
variable flags = get_buffer_flags ();
return (flags & 1);
}
where the integer 1 has been used since it has all of its bits set to
0, except for the zeroth one, which is set to 1. (At this point, it
should also be apparent that bits are numbered from zero, thus an 8
bit integer consists of bits 0 to 7, where 0 is the least significant
bit and 7 is the most significant one.) Similarly, we can create
another function
define is_autosave_on ()
{
variable flags = get_buffer_flags ();
return (flags & 2);
}
to determine whether or not autosave has been turned on for the
buffer.
The shl operator may be used to form the integer with only the nth bit
set. For example, 1 shl 6 produces an integer with all bits set to
zero except the sixth bit, which is set to one. The following example
exploits this fact:
define test_nth_bit (flags, nth)
{
return flags & (1 shl nth);
}
7.2.5. Namespace operator
The operator -> is used to in conjunction with the name of a namespace
to access an object within the namespace. For example, if A is the
name of a namespace containing the variable v, then A->v refers to
that variable.
7.2.6. Operator Precedence
7.2.7. Binary Operators and Functions Returning Multiple Values
Care must be exercised when using binary operators with an operand the
returns multiple values. In fact, the current implementation of the
S-Lang language will produce incorrect results if both operands of a
binary expression return multiple values. At most, only one of
operands of a binary expression can return multiple values, and that
operand must be the first one, not the second. For example,
define read_line (fp)
{
variable line, status;
status = fgets (&line, fp);
if (status == -1)
return -1;
return (line, status);
}
defines a function, read_line that takes a single argument, a handle
to an open file, and returns one or two values, depending upon the
return value of fgets. Now consider
while (read_line (fp) > 0)
{
text = ();
% Do something with text
.
.
}
Here the relational binary operator > forms a comparison between one
of the return values (the one at the top of the stack) and 0. In
accordance with the above rule, since read_line returns multiple val-
ues, it occurs as the left binary operand. Putting it on the right as
in
while (0 < read_line (fp)) % Incorrect
{
text = ();
% Do something with text
.
.
}
violates the rule and will result in the wrong answer.
7.3. Mixing Integer and Floating Point Arithmetic
If a binary operation (+, -, * , /) is performed on two integers, the
result is an integer. If at least one of the operands is a float, the
other is converted to float and the result is float. For example:
11 / 2 --> 5 (integer)
11 / 2.0 --> 5.5 (float)
11.0 / 2 --> 5.5 (float)
11.0 / 2.0 --> 5.5 (float)
Finally note that only integers may be used as array indices, loop
control variables, and bit operations. The conversion functions, int
and float, may be used convert between floats and ints where appropri-
ate, e.g.,
int (1.5) --> 1 (integer)
float(1.5) --> 1.5 (float)
float (1) --> 1.0 (float)
7.4. Short Circuit Boolean Evaluation
The boolean operators or and and are not short circuited as they are
in some languages. S-Lang uses orelse and andelse expressions for
short circuit boolean evaluation. However, these are not binary
operators. Expressions of the form:
expr-1 and expr-2 and ... expr-n
can be replaced by the short circuited version using andelse:
andelse {expr-1} {expr-2} ... {expr-n}
A similar syntax holds for the orelse operator. For example, consider
the statement:
if ((x != 0) and (1/x > 10)) do_something ();
Here, if x were to have a value of zero, a division by zero error
would occur because even though x!=0 evaluates to zero, the and opera-
tor is not short circuited and the 1/x expression would be evaluated
causing division by zero. For this case, the andelse expression could
be used to avoid the problem:
if (andelse
{x != 0}
{1 / x > 10}) do_something ();
8. Statements
Loosely speaking, a statement is composed of expressions that are
grouped according to the syntax or grammar of the language to express
a complete computation. Statements are analogous to sentences in a
human language and expressions are like phrases. All statements in
the S-Lang language must end in a semi-colon.
A statement that occurs within a function is executed only during
execution of the function. However, statements that occur outside the
context of a function are evaluated immediately.
The language supports several different types of statements such as
assignment statements, conditional statements, and so forth. These
are described in detail in the following sections.
8.1. Variable Declaration Statements
Variable declarations were already discussed in chapter ???. For the
sake of completeness, a variable declaration is a statement of the
form
variable variable-declaration-list ;
where the variable-declaration-list is a comma separated list of one
or more variable names with optional initializations, e.g.,
variable x, y = 2, z;
8.2. Assignment Statements
Perhaps the most well known form of statement is the assignment
statement. Statements of this type consist of a left-hand side, an
assignment operator, and a right-hand side. The left-hand side must
be something to which an assignment can be performed. Such an object
is called an lvalue.
The most common assignment operator is the simple assignment operator
=. Simple of its use include
x = 3;
x = some_function (10);
x = 34 + 27/y + some_function (z);
x = x + 3;
In addition to the simple assignment operator, S-Lang also supports
the assignment operators += and -=. Internally, S-Lang transforms
a += b;
to
a = a + b;
Similarly, a -= b is transformed to a = a - b. It is extremely impor-
tant to realize that, in general, a+b is not equal to b+a. This means
that a+=b is not the same as a=b+a. As an example consider
a = "hello"; a += "world";
After execution of these two statements, a will have the value "hel-
loworld" and not "worldhello".
Since adding or subtracting 1 from a variable is quite common, S-Lang
also supports the unary increment and decrement operators ++, and --,
respectively. That is, for numeric data types,
x = x + 1;
x += 1;
x++;
are all equivalent. Similarly,
x = x - 1;
x -= 1;
x--;
are also equivalent.
Strictly speaking, ++ and -- are unary operators. When used as x++,
the ++ operator is said to be a postfix-unary operator. However, when
used as ++x it is said to be a prefix-unary operator. The current
implementation does not distinguish between the two forms, thus x++
and ++x are equivalent. The reason for this equivalence is that
assignment expressions do not return a value in the S-Lang language as
they do in C. Thus one should exercise care and not try to write C-
like code such as
x = 10;
while (--x) do_something (x); % Ok in C, but not in S-Lang
The closest valid S-Lang form involves a comma-expression:
x = 10;
while (x--, x) do_something (x); % Ok in S-Lang and in C
S-Lang also supports a multiple-assignment statement. It is discussed
in detail in section ???.
8.3. Conditional and Looping Statements
S-Lang supports a wide variety of conditional and looping statements.
These constructs operate on statements grouped together in blocks. A
block is a sequence of S-Lang statements enclosed in braces and may
contain other blocks. However, a block cannot include function
declarations. In the following, statement-or-block refers to either a
single S-Lang statement or to a block of statements, and integer-
expression is an integer-valued expression. next-statement represents
the statement following the form under discussion.
8.3.1. Conditional Forms
8.3.1.1. if
The simplest condition statement is the if statement. It follows the
syntax
if (integer-expression) statement-or-block next-statement
If integer-expression evaluates to a non-zero result, then the state-
ment or group of statements implied statement-or-block will get exe-
cuted. Otherwise, control will proceed to next-statement.
An example of the use of this type of conditional statement is
if (x != 0)
{
y = 1.0 / x;
if (x > 0) z = log (x);
}
This example illustrates two if statements where the second if state-
ment is part of the block of statements that belong to the first.
8.3.1.2. if-else
Another form of if statement is the if-else statement. It follows the
syntax:
if (integer-expression) statement-or-block-1 else statement-or-block-2
next-statement
Here, if expression returns non-zero, statement-or-block-1 will get
executed and control will pass on to next-statement. However, if
expression returns zero, statement-or-block-2 will get executed before
continuing with next-statement. A simple example of this form is
if (x > 0) z = log (x); else error ("x must be positive");
Consider the more complex example:
if (city == "Boston")
if (street == "Beacon") found = 1;
else if (city == "Madrid")
if (street == "Calle Mayor") found = 1;
else found = 0;
This example illustrates a problem that beginners have with if-else
statements. The grammar presented above shows that the this example
is equivalent to
if (city == "Boston")
{
if (street == "Beacon") found = 1;
else if (city == "Madrid")
{
if (street == "Calle Mayor") found = 1;
else found = 0;
}
}
It is important to understand the grammar and not be seduced by the
indentation!
8.3.1.3. !if
One often encounters if statements similar to
if (integer-expression == 0) statement-or-block
or equivalently,
if (not(integer-expression)) statement-or-block
The !if statement was added to the language to simplify the handling
of such statements. It obeys the syntax
!if (integer-expression) statement-or-block
and is functionally equivalent to
if (not (expression)) statement-or-block
8.3.1.4. orelse, andelse
These constructs were discussed earlier. The syntax for the orelse
statement is:
orelse {integer-expression-1} ... {integer-expression-n}
This causes each of the blocks to be executed in turn until one of
them returns a non-zero integer value. The result of this statement
is the integer value returned by the last block executed. For exam-
ple,
orelse { 0 } { 6 } { 2 } { 3 }
returns 6 since the second block is the first to return a non-zero
result. The last two block will not get executed.
The syntax for the andelse statement is:
andelse {integer-expression-1} ... {integer-expression-n}
Each of the blocks will be executed in turn until one of them returns
a zero value. The result of this statement is the integer value
returned by the last block executed. For example,
andelse { 6 } { 2 } { 0 } { 4 }
returns 0 since the third block will be the last to execute.
8.3.1.5. switch
The switch statement deviates the most from its C counterpart. The
syntax is:
switch (x)
{ ... : ...}
.
.
{ ... : ...}
The `:' operator is a special symbol which means to test the top item
on the stack, and if it is non-zero, the rest of the block will get
executed and control will pass out of the switch statement. Other-
wise, the execution of the block will be terminated and the process
will be repeated for the next block. If a block contains no : opera-
tor, the entire block is executed and control will pass onto the next
statement following the switch statement. Such a block is known as
the default case.
As a simple example, consider the following:
switch (x)
{ x == 1 : print("Number is one.");}
{ x == 2 : print("Number is two.");}
{ x == 3 : print("Number is three.");}
{ x == 4 : print("Number is four.");}
{ x == 5 : print("Number is five.");}
{ print ("Number is greater than five.");}
Suppose x has an integer value of 3. The first two blocks will termi-
nate at the `:' character because each of the comparisons with x will
produce zero. However, the third block will execute to completion.
Similarly, if x is 7, only the last block will execute in full.
A more familiar way to write the previous example used the case
keyword:
switch (x)
{ case 1 : print("Number is one.");}
{ case 2 : print("Number is two.");}
{ case 3 : print("Number is three.");}
{ case 4 : print("Number is four.");}
{ case 5 : print("Number is five.");}
{ print ("Number is greater than five.");}
The case keyword is a more useful comparison operator because it can
perform a comparison between different data types while using == may
result in a type-mismatch error. For example,
switch (x)
{ (x == 1) or (x == "one") : print("Number is one.");}
{ (x == 2) or (x == "two") : print("Number is two.");}
{ (x == 3) or (x == "three") : print("Number is three.");}
{ (x == 4) or (x == "four") : print("Number is four.");}
{ (x == 5) or (x == "five") : print("Number is five.");}
{ print ("Number is greater than five.");}
will fail because the == operation is not defined between strings and
integers. The correct way to write this to use the case keyword:
switch (x)
{ case 1 or case "one" : print("Number is one.");}
{ case 2 or case "two" : print("Number is two.");}
{ case 3 or case "three" : print("Number is three.");}
{ case 4 or case "four" : print("Number is four.");}
{ case 5 or case "five" : print("Number is five.");}
{ print ("Number is greater than five.");}
8.3.2. Looping Forms
8.3.2.1. while
The while statement follows the syntax
while (integer-expression) statement-or-block next-statement
It simply causes statement-or-block to get executed as long as inte-
ger-expression evaluates to a non-zero result. For example,
i = 10;
while (i)
{
i--;
newline ();
}
will cause the newline function to get called 10 times. However,
i = -10;
while (i)
{
i--;
newline ();
}
would loop forever (or until i wraps from the most negative integer
value to the most positive and then decrements to zero).
If you are a C programmer, do not let the syntax of the language
seduce you into writing this example as you would in C:
i = 10;
while (i--) newline ();
The fact is that expressions such as i-- do not return a value in S-
Lang as they do in C. If you must write this way, use the comma oper-
ator as in
i = 10;
while (i, i--) newline ();
8.3.2.2. do...while
The do...while statement follows the syntax
do statement-or-block while (integer-expression);
The main difference between this statement and the while statement is
that the do...while form performs the test involving integer-expres-
sion after each execution of statement-or-block rather than before.
This guarantees that statement-or-block will get executed at least
once.
A simple example from the jed editor follows:
bob (); % Move to beginning of buffer
do
{
indent_line ();
}
while (down (1));
This will cause all lines in the buffer to get indented via the jed
intrinsic function indent_line.
8.3.2.3. for
Perhaps the most complex looping statement is the for statement;
nevertheless, it is a favorite of many programmers. This statement
obeys the syntax
for (init-expression; integer-expression; end-expression) statement-
or-block next-statement
In addition to statement-or-block, its specification requires three
other expressions. When executed, the for statement evaluates init-
expression, then it tests integer-expression. If integer-expression
returns zero, control passes to next-statement. Otherwise, it exe-
cutes statement-or-block as long as integer-expression evaluates to a
non-zero result. After every execution of statement-or-block, end-
expression will get evaluated.
This statement is almost equivalent to
init-expression; while (integer-expression) { statement-or-block end-
expression; }
The reason that they are not fully equivalent involves what happens
when statement-or-block contains a continue statement.
Despite the apparent complexity of the for statement, it is very easy
to use. As an example, consider
sum = 0;
for (i = 1; i <= 10; i++) sum += i;
which computes the sum of the first 10 integers.
8.3.2.4. loop
The loop statement simply executes a block of code a fixed number of
times. It follows the syntax
loop (integer-expression) statement-or-block next-statement
If the integer-expression evaluates to a positive integer, statement-
or-block will get executed that many times. Otherwise, control will
pass to next-statement.
For example,
loop (10) newline ();
will cause the function newline to get called 10 times.
8.3.2.5. forever
The forever statement is similar to the loop statement except that it
loops forever, or until a break or a return statement is executed. It
obeys the syntax
forever statement-or-block
A trivial example of this statement is
n = 10;
forever
{
if (n == 0) break;
newline ();
n--;
}
8.3.2.6. foreach
The foreach statement is used to loop over one or more statements for
every element in a container object. A container object is a data
type that consists of other types. Examples include both ordinary and
associative arrays, structures, and strings. Every time through the
loop the current member of the object is pushed onto the stack.
The simple type of foreach statement obeys the syntax
foreach (container-object) statement-or-block
Here container-object can be an expression that returns a container
object. A simple example is
foreach (["apple", "peach", "pear"])
{
fruit = ();
process_fruit (fruit);
}
This example shows that if the container object is an array, then suc-
cessive elements of the array are pushed onto the stack prior to each
execution cycle. If the container object is a string, then successive
characters of the string are pushed onto the stack.
What actually gets pushed onto the stack may be controlled via the
using form of the foreach statement. This more complex type of
foreach statement follows the syntax
foreach ( container-object ) using ( control-list ) statement-or-block
The allowed values of control-list will depend upon the type of con-
tainer object. For associative arrays (Assoc_Type), control-list
specified whether keys, values, or both are pushed onto the stack.
For example,
foreach (a) using ("keys")
{
k = ();
.
.
}
results in the keys of the associative array a being pushed on the
list. However,
foreach (a) using ("values")
{
v = ();
.
.
}
will cause the values to be used, and
foreach (a) using ("keys", "values")
{
(k,v) = ();
.
.
}
will use both the keys and values of the array.
Similarly, for linked-lists of structures, one may walk the list via
code like
foreach (linked_list) using ("next")
{
s = ();
.
.
}
This foreach statement is equivalent
s = linked_list;
while (s != NULL)
{
.
.
s = s.next;
}
Consult the type-specific documentation for a discussion of the using
control words, if any, appropriate for a given type.
8.4. break, return, continue
S-Lang also includes the non-local transfer functions return, break,
and continue. The return statement causes control to return to the
calling function while the break and continue statements are used in
the context of loop structures. Consider:
define fun ()
{
forever
{
s1;
s2;
..
if (condition_1) break;
if (condition_2) return;
if (condition_3) continue;
..
s3;
}
s4;
..
}
Here, a function fun has been defined that contains a forever loop
consisting of statements s1, s2,...,s3, and three if statements. As
long as the expressions condition_1, condition_2, and condition_3
evaluate to zero, the statements s1, s2,...,s3 will be repeatedly exe-
cuted. However, if condition_1 returns a non-zero value, the break
statement will get executed, and control will pass out of the forever
loop to the statement immediately following the loop which in this
case is s4. Similarly, if condition_2 returns a non-zero number, the
return statement will cause control to pass back to the caller of fun.
Finally, the continue statement will cause control to pass back to the
start of the loop, skipping the statement s3 altogether.
9. Functions
A function may be thought of as a group of statements that work
together to perform a computation. While there are no imposed limits
upon the number statements that may occur within a function, it is
considered poor programming practice if a function contains many
statements. This notion stems from the belief that a function should
have a simple, well defined purpose.
9.1. Declaring Functions
Like variables, functions must be declared before they can be used.
The define keyword is used for this purpose. For example,
define factorial ();
is sufficient to declare a function named factorial. Unlike the vari-
able keyword used for declaring variables, the define keyword does not
accept a list of names.
Usually, the above form is used only for recursive functions. In most
cases, the function name is almost always followed by a parameter list
and the body of the function:
define function-name (parameter-list) { statement-list }
The function-name is an identifier and must conform to the naming
scheme for identifiers discussed in chapter ???. The parameter-list
is a comma-separated list of variable names that represent parameters
passed to the function, and may be empty if no parameters are to be
passed. The body of the function is enclosed in braces and consists
of zero or more statements (statement-list).
The variables in the parameter-list are implicitly declared, thus,
there is no need to declare them via a variable declaration statement.
In fact any attempt to do so will result in a syntax error.
9.2. Parameter Passing Mechanism
Parameters to a function are always passed by value and never by
reference. To see what this means, consider
define add_10 (a)
{
a = a + 10;
}
variable b = 0;
add_10 (b);
Here a function add_10 has been defined, which when executed, adds 10
to its parameter. A variable b has also been declared and initialized
to zero before it is passed to add_10. What will be the value of b
after the call to add_10? If S-Lang were a language that passed
parameters by reference, the value of b would be changed to 10. How-
ever, S-Lang always passes by value, which means that b would retain
its value of zero after the function call.
S-Lang does provide a mechanism for simulating pass by reference via
the reference operator. See the next section for more details.
If a function is called with a parameter in the parameter list
omitted, the corresponding variable in the function will be set to
NULL. To make this clear, consider the function
define add_two_numbers (a, b)
{
if (a == NULL) a = 0;
if (b == NULL) b = 0;
return a + b;
}
This function must be called with two parameters. However, we can
omit one or both of the parameters by calling it in one of the follow-
ing ways:
variable s = add_two_numbers (2,3);
variable s = add_two_numbers (2,);
variable s = add_two_numbers (,3);
variable s = add_two_numbers (,);
The first example calls the function using both parameters; however,
at least one of the parameters was omitted in the other examples. The
interpreter will implicitly convert the last three examples to
variable s = add_two_numbers (2, NULL);
variable s = add_two_numbers (NULL, 3);
variable s = add_two_numbers (NULL, NULL);
It is important to note that this mechanism is available only for
function calls that specify more than one parameter. That is,
variable s = add_10 ();
is not equivalent to add_10(NULL). The reason for this is simple: the
parser can only tell whether or not NULL should be substituted by
looking at the position of the comma character in the parameter list,
and only function calls that indicate more than one parameter will use
a comma. A mechanism for handling single parameter function calls is
described in the next section.
9.3. Referencing Variables
One can achieve the effect of passing by reference by using the
reference (&) and dereference (@) operators. Consider again the add_10
function presented in the previous section. This time we write it as
define add_10 (a)
{
@a = @a + 10;
}
variable b = 0;
add_10 (&b);
The expression &b creates a reference to the variable b and it is the
reference that gets passed to add_10. When the function add_10 is
called, the value of a will be a reference to b. It is only by deref-
erencing this value that b can be accessed and changed. So, the
statement @a=@a+10; should be read `add 10' to the value of the object
that a references and assign the result to the object that a refer-
ences.
The reader familiar with C will note the similarity between references
in S-Lang and pointers in C.
One of the main purposes for references is that this mechanism allows
reference to functions to be passed to other functions. As a simple
example from elementary calculus, consider the following function
which returns an approximation to the derivative of another function
at a specified point:
define derivative (f, x)
{
variable h = 1e-6;
return (@f(x+h) - @f(x)) / h;
}
It can be used to differentiate the function
define x_squared (x)
{
return x^2;
}
at the point x = 3 via the expression derivative(&x_squared,3).
9.4. Functions with a Variable Number of Arguments
S-Lang functions may be defined to take a variable number of
arguments. The reason for this is that the calling routine pushes the
arguments onto the stack before making a function call, and it is up
to the called function to pop the values off the stack and make
assignments to the variables in the parameter list. These details
are, for the most part, hidden from the programmer. However, they are
important when a variable number of arguments are passed.
Consider the add_10 example presented earlier. This time it is
written
define add_10 ()
{
variable x;
x = ();
return x + 10;
}
variable s = add_10 (12); % ==> s = 22;
For the uninitiated, this example looks as if it is destined for dis-
aster. The add_10 function looks like it accepts zero arguments, yet
it was called with a single argument. On top of that, the assignment
to x looks strange. The truth is, the code presented in this example
makes perfect sense, once you realize what is happening.
First, consider what happened when add_10 is called with the the
parameter 12. Internally, 12 is pushed onto the stack and then the
function called. Now, consider the function itself. x is a variable
local to the function. The strange looking assignment `x=()' simply
takes whatever is on the stack and assigns it to x. In other words,
after this statement, the value of x will be 12, since 12 will be at
the top of the stack.
A generic function of the form
define function_name (x, y, ..., z)
{
.
.
}
is internally transformed by the interpreter to
define function_name ()
{
variable x, y, ..., z;
z = ();
.
.
y = ();
x = ();
.
.
}
before further parsing. (The add_10 function, as defined above, is
already in this form.) With this knowledge in hand, one can write a
function that accepts a variable number of arguments. Consider the
function:
define average_n (n)
{
variable x, y;
variable sum;
if (n == 1)
{
x = ();
sum = x;
}
else if (n == 2)
{
y = ();
x = ();
sum = x + y;
}
else error ("average_n: only one or two values supported");
return sum / n;
}
variable ave1 = average_n (3.0, 1); % ==> 3.0
variable ave2 = average_n (3.0, 5.0, 2); % ==> 4.0
Here, the last argument passed to average_n is an integer reflecting
the number of quantities to be averaged. Although this example works
fine, its principal limitation is obvious: it only supports one or two
values. Extending it to three or more values by adding more else if
constructs is rather straightforward but hardly worth the effort.
There must be a better way, and there is:
define average_n (n)
{
variable sum, x;
sum = 0;
loop (n)
{
x = (); % get next value from stack
sum += x;
}
return sum / n;
}
The principal limitation of this approach is that one must still pass
an integer that specifies how many values are to be averaged.
Fortunately, a special variable exists that is local to every function
and contains the number of values that were passed to the function.
That variable has the name _NARGS and may be used as follows:
define average_n ()
{
variable x, sum = 0;
if (_NARGS == 0) error ("Usage: ave = average_n (x, ...);");
loop (_NARGS)
{
x = ();
sum += x;
}
return sum / _NARGS;
}
Here, if no arguments are passed to the function, a simple message
that indicates how it is to be used is printed out.
9.5. Returning Values
As stated earlier, the usual way to return values from a function is
via the return statement. This statement has the simple syntax
return expression-list ;
where expression-list is a comma separated list of expressions. If
the function does not return any values, the expression list will be
empty. As an example of a function that can return multiple values,
consider
define sum_and_diff (x, y)
{
variable sum, diff;
sum = x + y; diff = x - y;
return sum, diff;
}
which is a function returning two values.
It is extremely important to note that the calling routine must
explicitly handle all values returned by a function. Although some
languages such as C do not have this restriction, S-Lang does and it
is a direct result of a S-Lang function's ability to return many
values and accept a variable number of parameters. Examples of
properly handling the above function include
variable sum, diff;
(sum, diff) = sum_and_diff (5, 4); % ignore neither
(sum, ) = sum_and_diff (5, 4); % ignore diff
(,) = sum_and_diff (5, 4); % ignore both sum and diff
See the section below on assignment statements for more information
about this important point.
9.6. Multiple Assignment Statement
S-Lang functions can return more than one value, e.g.,
define sum_and_diff (x, y)
{
return x + y, x - y;
}
returns two values. It accomplishes this by placing both values on
the stack before returning. If you understand how S-Lang functions
handle a variable number of parameters (section ???), then it should
be rather obvious that one assigns such values to variables. One way
is to use, e.g.,
sum_and_diff (9, 4);
d = ();
s = ();
However, the most convenient way to accomplish this is to use a
multiple assignment statement such as
(s, d) = sum_and_diff (9, 4);
The most general form of the multiple assignment statement is
( var_1, var_2, ..., var_n ) = expression;
In fact, internally the interpreter transforms this statement into the
form
expression; var_n = (); ... var_2 = (); var_1 = ();
for further processing.
If you do not care about one of return values, simply omit the
variable name from the list. For example,
(s, ) = sum_and_diff (9, 4);
assigns the sum of 9 and 4 to s and the difference (9-4) will be
removed from the stack.
As another example, the jed editor provides a function called down
that takes an integer argument and returns an integer. It is used to
move the current editing position down the number of lines specified
by the argument passed to it. It returns the number of lines it
successfully moved the editing position. Often one does not care
about the return value from this function. Although it is always
possible to handle the return value via
variable dummy = down (10);
it is more convenient to use a multiple assignment expression and omit
the variable name, e.g.,
() = down (10);
Some functions return a variable number of values instead of a fixed
number. Usually, the value at the top of the stack will indicate the
actual number of return values. For such functions, the multiple
assignment statement cannot directly be used. To see how such
functions can be dealt with, consider the following function:
define read_line (fp)
{
variable line;
if (-1 == fgets (&line, fp))
return -1;
return (line, 0);
}
This function returns either one or two values, depending upon the
return value of fgets. Such a function may be handled as in the fol-
lowing example:
status = read_line (fp);
if (status != -1)
{
s = ();
.
.
}
In this example, the last value returned by read_line is assigned to
status and then tested. If it is non-zero, the second return value is
assigned to s. In particular note the empty set of parenthesis in the
assignment to s. This simply indicates that whatever is on the top of
the stack when the statement is executed will be assigned to s.
Before leaving this section it is important to reiterate the fact that
if a function returns a value, the caller must deal with that return
value. Otherwise, the value will continue to live onto the stack and
may eventually lead to a stack overflow error. Failing to handle the
return value of a function is the most common mistake that
inexperienced S-Lang programmers make. For example, the fflush
function returns a value that many C programmer's never check.
Instead of writing
fflush (fp);
as one could in C, a S-Lang programmer should write
() = fflush (fp);
in S-Lang. (Many good C programmer's write (void)fflush(fp) to indi-
cate that the return value is being ignored).
9.7. Exit-Blocks
An exit-block is a set of statements that get executed when a
functions returns. They are very useful for cleaning up when a
function returns via an explicit call to return from deep within a
function.
An exit-block is created by using the EXIT_BLOCK keyword according to
the syntax
EXIT_BLOCK { statement-list }
where statement-list represents the list of statements that comprise
the exit-block. The following example illustrates the use of an exit-
block:
define simple_demo ()
{
variable n = 0;
EXIT_BLOCK { message ("Exit block called."); }
forever
{
if (n == 10) return;
n++;
}
}
Here, the function contains an exit-block and a forever loop. The
loop will terminate via the return statement when n is 10. Before it
returns, the exit-block will get executed.
A function can contain multiple exit-blocks, but only the last one
encountered during execution will actually get executed. For example,
define simple_demo (n)
{
EXIT_BLOCK { return 1; }
if (n != 1)
{
EXIT_BLOCK { return 2; }
}
return;
}
If 1 is passed to this function, the first exit-block will get exe-
cuted because the second one would not have been encountered during
the execution. However, if some other value is passed, the second
exit-block would get executed. This example also illustrates that it
is possible to explicitly return from an exit-block, although nested
exit-blocks are illegal.
10. Name Spaces
By default, all global variables and functions are defined in the
global namespace. In addition to the global namespace, every
compilation unit (e.g., a file containing S-Lang code) has an
anonymous namespace. Objects may be defined in the anonymous
namespace via the static declaration keyword. For example,
static variable x;
static define hello () { message ("hello"); }
defines a variable x and a function hello in the anonymous namespace.
This is useful when one wants to define functions and variables that
are only to be used within the file, or more precisely the compilation
unit, that defines them.
The implements function may be used to give the anonymous namespace a
name to allow access to its objects from outside the compilation unit
that defines them. For example,
implements ("foo");
static variable x;
allows the variable x to be accessed via foo->x, e.g.,
if (foo->x == 1) foo->x = 2;
The implements function does more than simply giving the anonymous
namespace a name. It also changes the default variable and function
declaration mode from public to static. That is,
implements ("foo");
variable x;
and
implements ("foo");
static variable x;
are equivalent. Then to create a public object within the namespace,
one must explicitly use the public keyword.
Finally, the private keyword may be used to create an object that is
truly private within the compilation unit. For example,
implements ("foo");
variable x;
private variable y;
allows x to be accessed from outside the namespace via foo->x, however
y cannot be accessed.
11. Arrays
An array is a container object that can contain many values of one
data type. Arrays are very useful objects and are indispensable for
certain types of programming. The purpose of this chapter is to
describe how arrays are defined and used in the S-Lang language.
11.1. Creating Arrays
The S-Lang language supports multi-dimensional arrays of all data
types. Since the Array_Type is a data type, one can even have arrays
of arrays. To create a multi-dimensional array of SomeType use the
syntax
SomeType [dim0, dim1, ..., dimN]
Here dim0, dim1, ... dimN specify the size of the individual dimen-
sions of the array. The current implementation permits arrays consist
of up to 7 dimensions. When a numeric array is created, all its ele-
ments are initialized to zero. The initialization of other array
types depend upon the data type, e.g., String_Type and Struct_Type
arrays are initialized to NULL.
As a concrete example, consider
a = Integer_Type [10];
which creates a one-dimensional array of 10 integers and assigns it to
a. Similarly,
b = Double_Type [10, 3];
creates a 30 element array of double precision numbers arranged in 10
rows and 3 columns, and assigns it to b.
11.1.1. Range Arrays
There is a more convenient syntax for creating and initializing a 1-d
arrays. For example, to create an array of ten integers whose
elements run from 1 through 10, one may simply use:
a = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
Similarly,
b = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0];
specifies an array of ten doubles.
An even more compact way of specifying a numeric array is to use a
range-array. For example,
a = [0:9];
specifies an array of 10 integers whose elements range from 0 through
9. The most general form of a range array is
[first-value : last-value : increment]
where the increment is optional and defaults to 1. This creates an
array whose first element is first-value and whose successive values
differ by increment. last-value sets an upper limit upon the last
value of the array as described below.
If the range array [a:b:c] is integer valued, then the interval
specified by a and b is closed. That is, the kth element of the array
x_k is given by x_k=a+ck and must satisfy a<=x_k<=b. Hence, the
number of elements in an integer range array is given by the
expression 1 + (b-a)/c.
The situation is somewhat more complicated for floating point range
arrays. The interval specified by a floating point range array
[a:b:c] is semi-open such that b is not contained in the interval. In
particular, the kth element of [a:b:c] is given by x_k=a+kc such that
a<=x_k<b when c>=0, and b<x_k<=a otherwise. The number of elements in
the array is one greater than the largest k that satisfies the open
interval constraint.
Here are a few examples that illustrate the above comments:
[1:5:1] ==> [1,2,3,4,5]
[1.0:5.0:1.0] ==> [1.0, 2.0, 3.0, 4.0]
[5:1:-1] ==> [5,4,3,2,1]
[5.0:1.0:-1.0] ==> [5.0, 4.0, 3.0, 2.0];
[1:1] ==> [1]
[1.0:1.0] ==> []
[1:-3] ==> []
11.1.2. Creating arrays via the dereference operator
Another way to create an array is apply the dereference operator @ to
the DataType_Type literal Array_Type. The actual syntax for this
operation resembles a function call
variable a = @Array_Type (data-type, integer-array);
where data-type is of type DataType_Type and integer-array is a 1-d
array of integers that specify the size of each dimension. For exam-
ple,
variable a = @Array_Type (Double_Type, [10, 20]);
will create a 10 by 20 array of doubles and assign it to a. This
method of creating arrays derives its power from the fact that it is
more flexible than the methods discussed in this section. We shall
encounter it again in section ??? in the context of the array_info
function.
11.2. Reshaping Arrays
It is sometimes possible to change the `shape' of an array using the
reshape function. For example, a 1-d 10 element array may be reshaped
into a 2-d array consisting of 5 rows and 2 columns. The only
restriction on the operation is that the arrays must be commensurate.
The reshape function follows the syntax
reshape (array-name, integer-array);
where array-name specifies the array to be reshaped to have the dimen-
sions given by integer-array, a 1-dimensional array of integers. It
is important to note that this does not create a new array, it simply
reshapes the existing array. Thus,
variable a = Double_Type [100];
reshape (a, [10, 10]);
turns a into a 10 by 10 array.
11.3. Indexing Arrays
An individual element of an array may be referred to by its index.
For example, a[0] specifies the zeroth element of the one dimensional
array a, and b[3,2] specifies the element in the third row and second
column of the two dimensional array b. As in C array indices are
numbered from 0. Thus if a is a one-dimensional array of ten
integers, the last element of the array is given by a[9]. Using a[10]
would result in a range error.
A negative index may be used to index from the end of the array, with
a[-1] referring to the last element of a, a[-2] referring to the next
to the last element, and so on.
One may use the indexed value like any other variable. For example,
to set the third element of an integer array to 6, use
a[2] = 6;
Similarly, that element may be used in an expression, such as
y = a[2] + 7;
Unlike other S-Lang variables which inherit a type upon assignment,
array elements already have a type. For example, an attempt to assign
a string value to an element of an integer array will result in a
type-mismatch error.
One may use any integer expression to index an array. A simple
example that computes the sum of the elements of 10 element 1-d array
is
variable i, sum;
sum = 0;
for (i = 0; i < 10; i++) sum += a[i];
Unlike many other languages, S-Lang permits arrays to be indexed by
other integer arrays. Suppose that a is a 1-d array of 10 doubles.
Now consider:
i = [6:8];
b = a[i];
Here, i is a 1-dimensional range array of three integers with i[0]
equal to 6, i[1] equal to 7, and i[2] equal to 8. The statement b =
a[i]; will create a 1-d array of three doubles and assign it to b.
The zeroth element of b, b[0] will be set to the sixth element of a,
or a[6], and so on. In fact, these two simple statements are equiva-
lent to
b = Double_Type [3];
b[0] = a[6];
b[1] = a[7];
b[2] = a[8];
except that using an array of indices is not only much more conve-
nient, but executes much faster.
More generally, one may use an index array to specify which elements
are to participate in a calculation. For example, consider
a = Double_Type [1000];
i = [0:499];
j = [500:999];
a[i] = -1.0;
a[j] = 1.0;
This creates an array of 1000 doubles and sets the first 500 elements
to -1.0 and the last 500 to 1.0. Actually, one may do away with the i
and j variables altogether and use
a = Double_Type [1000];
a [[0:499]] = -1.0;
a [[500:999]] = 1.0;
It is important to understand the syntax used and, in particular, to
note that a[[0:499]] is not the same as a[0:499]. In fact, the latter
will generate a syntax error.
Often, it is convenient to use a rubber range to specify indices. For
example, a[[500:]] specifies all elements of a whose index is greater
than or equal to 500. Similarly, a[[:499]] specifies the first 500
elements of a. Finally, a[[:]] specifies all the elements of a;
however, using a[*] is more convenient.
Now consider a multi-dimensional array. For simplicity, suppose that
a is a 100 by 100 array of doubles. Then the expression a[0, *]
specifies all elements in the zeroth row. Similarly, a[*, 7]
specifies all elements in the seventh column. Finally, a[[3:5][6:12]]
specifies the 3 by 7 region consisting of rows 3, 4, and 5, and
columns 6 through 12 of a.
We conclude this section with a few examples.
Here is a function that computes the trace (sum of the diagonal
elements) of a square 2 dimensional n by n array:
define array_trace (a, n)
{
variable sum = 0, i;
for (i = 0; i < n; i++) sum += a[i, i];
return sum;
}
This fragment creates a 10 by 10 integer array, sets its diagonal ele-
ments to 5, and then computes the trace of the array:
a = Integer_Type [10, 10];
for (j = 0; j < 10; j++) a[j, j] = 5;
the_trace = array_trace(a, 10);
We can get rid of the for loop as follows:
j = Integer_Type [10, 2];
j[*,0] = [0:9];
j[*,1] = [0:9];
a[j] = 5;
Here, the goal was to construct a 2-d array of indices that correspond
to the diagonal elements of a, and then use that array to index a. To
understand how this works, consider the middle statements. They are
equivalent to the following for loops:
variable i;
for (i = 0; i < 10; i++) j[i, 0] = i;
for (i = 0; i < 10; i++) j[i, 1] = i;
Thus, row n of j will have the value (n,n), which is precisely what
was sought.
Another example of this technique is the function:
define unit_matrix (n)
{
variable a = Integer_Type [n, n];
variable j = Integer_Type [n, 2];
j[*,0] = [0:n - 1];
j[*,1] = [0:n - 1];
a[j] = 1;
return a;
}
This function creates an n by n unit matrix, that is a 2-d n by n
array whose elements are all zero except on the diagonal where they
have a value of 1.
11.4. Arrays and Variables
When an array is created and assigned to a variable, the interpreter
allocates the proper amount of space for the array, initializes it,
and then assigns to the variable a reference to the array. So, a
variable that represents an array has a value that is really a
reference to the array. This has several consequences, some good and
some bad. It is believed that the advantages of this representation
outweigh the disadvantages. First, we shall look at the positive
aspects.
When a variable is passed to a function, it is always the value of the
variable that gets passed. Since the value of a variable representing
an array is a reference, a reference to the array gets passed. One
major advantage of this is rather obvious: it is a fast and efficient
way to pass the array. This also has another consequence that is
illustrated by the function
define init_array (a, n)
{
variable i;
for (i = 0; i < n; i++) a[i] = some_function (i);
}
where some_function is a function that generates a scalar value to
initialize the ith element. This function can be used in the follow-
ing way:
variable X = Double_Type [100000];
init_array (X, 100000);
Since the array is passed to the function by reference, there is no
need to make a separate copy of the 100000 element array. As pointed
out above, this saves both execution time and memory. The other
salient feature to note is that any changes made to the elements of
the array within the function will be manifested in the array outside
the function. Of course, in this case, this is a desirable side-
effect.
To see the downside of this representation, consider:
variable a, b;
a = Double_Type [10];
b = a;
a[0] = 7;
What will be the value of b[0]? Since the value of a is really a ref-
erence to the array of ten doubles, and that reference was assigned to
b, b also refers to the same array. Thus any changes made to the ele-
ments of a, will also be made implicitly to b.
This begs the question: If the assignment of one variable which
represents an array, to another variable results in the assignment of
a reference to the array, then how does one make separate copies of
the array? There are several answers including using an index array,
e.g., b = a[*]; however, the most natural method is to use the
dereference operator:
variable a, b;
a = Double_Type [10];
b = @a;
a[0] = 7;
In this example, a separate copy of a will be created and assigned to
b. It is very important to note that S-Lang never implicitly derefer-
ences an object. So, one must explicitly use the dereference opera-
tor. This means that the elements of a dereferenced array are not
themselves dereferenced. For example, consider dereferencing an array
of arrays, e.g.,
variable a, b;
a = Array_Type [2];
a[0] = Double_Type [10];
a[1] = Double_Type [10];
b = @a;
In this example, b[0] will be a reference to the array that a[0] ref-
erences because a[0] was not explicitly dereferenced.
11.5. Using Arrays in Computations
Many functions and operations work transparently with arrays. For
example, if a and b are arrays, then the sum a + b is an array whose
elements are formed from the sum of the corresponding elements of a
and b. A similar statement holds for all other binary and unary
operations.
Let's consider a simple example. Suppose, that we wish to solve a set
of n quadratic equations whose coefficients are given by the 1-d
arrays a, b, and c. In general, the solution of a quadratic equation
will be two complex numbers. For simplicity, suppose that all we
really want is to know what subset of the coefficients, a, b, c,
correspond to real-valued solutions. In terms of for loops, we can
write:
variable i, d, index_array;
index_array = Integer_Type [n];
for (i = 0; i < n; i++)
{
d = b[i]^2 - 4 * a[i] * c[i];
index_array [i] = (d >= 0.0);
}
In this example, the array index_array will contain a non-zero value
if the corresponding set of coefficients has a real-valued solution.
This code may be written much more compactly and with more clarity as
follows:
variable index_array = ((b^2 - 4 * a * c) >= 0.0);
S-Lang has a powerful built-in function called where. This function
takes an array of integers and returns a 2-d array of indices that
correspond to where the elements of the input array are non-zero.
This simple operation is extremely useful. For example, suppose a is a
1-d array of n doubles, and it is desired to set to zero all elements
of the array whose value is less than zero. One way is to use a for
loop:
for (i = 0; i < n; i++)
if (a[i] < 0.0) a[i] = 0.0;
If n is a large number, this statement can take some time to execute.
The optimal way to achieve the same result is to use the where func-
tion:
a[where (a < 0.0)] = 0;
Here, the expression (a < 0.0) returns an array whose dimensions are
the same size as a but whose elements are either 1 or 0, according to
whether or not the corresponding element of a is less than zero. This
array of zeros and ones is then passed to where which returns a 2-d
integer array of indices that indicate where the elements of a are
less than zero. Finally, those elements of a are set to zero.
As a final example, consider once more the example involving the set
of n quadratic equations presented above. Suppose that we wish to get
rid of the coefficients of the previous example that generated non-
real solutions. Using an explicit for loop requires code such as:
variable i, j, nn, tmp_a, tmp_b, tmp_c;
nn = 0;
for (i = 0; i < n; i++)
if (index_array [i]) nn++;
tmp_a = Double_Type [nn];
tmp_b = Double_Type [nn];
tmp_c = Double_Type [nn];
j = 0;
for (i = 0; i < n; i++)
{
if (index_array [i])
{
tmp_a [j] = a[i];
tmp_b [j] = b[i];
tmp_c [j] = c[i];
j++;
}
}
a = tmp_a;
b = tmp_b;
c = tmp_c;
Not only is this a lot of code, it is also clumsy and error-prone.
Using the where function, this task is trivial:
variable i;
i = where (index_array != 0);
a = a[i];
b = b[i];
c = c[i];
All the examples up to now assumed that the dimensions of the array
were known. Although the intrinsic function length may be used to get
the total number of elements of an array, it cannot be used to get the
individual dimensions of a multi-dimensional array. However, the
function array_info may be used to get information about an array,
such as its data type and size. The function returns three values:
the data type, the number of dimensions, and an integer array
containing the size of each dimension. It may be used to determine
the number of rows of an array as follows:
define num_rows (a)
{
variable dims, type, num_dims;
(dims, num_dims, type) = array_info (a);
return dims[0];
}
The number of columns may be obtained in a similar manner:
define num_cols (a)
{
variable dims, type, num_dims;
(dims, num_dims, type) = array_info (a);
if (num_dims > 1) return dims[1];
return 1;
}
Another use of array_info is to create an array that has the same
number of dimensions as another array:
define make_int_array (a)
{
variable dims, num_dims, type;
(dims, num_dims, type) = array_info (a);
return @Array_Type (Integer_Type, dims);
}
12. Associative Arrays
An associative array differs from an ordinary array in the sense that
its size is not fixed and that is indexed by a string, called the key.
For example, consider:
variable A = Assoc_Type [Integer_Type];
A["alpha"] = 1;
A["beta"] = 2;
A["gamma"] = 3;
Here, A represents an associative array of integers (Integer_Type) and
three keys have been added to the array.
As the example suggests, an associative array may be created using one
of the following forms:
Assoc_Type [type] Assoc_Type [type, default-value] Assoc_Type []
The last form returns an associative array of Any_Type objects allow-
ing any type of object to may be stored in the array.
The form involving a default-value is useful for associating a default
value for non-existent array members. This feature is explained in
more detail below.
There are several functions that are specially designed to work with
associative arrays. These include:
o assoc_get_keys, which returns an ordinary array of strings
containing the keys in the array.
o assoc_get_values, which returns an ordinary array of the values of
the associative array.
o assoc_key_exists, which can be used to determine whether or not a
key exists in the array.
o assoc_delete_key, which may be used to remove a key (and its value)
from the array.
To illustrate the use of an associative array, consider the problem of
counting the number of repeated occurrences of words in a list. Let
the word list be represented as an array of strings given by
word_list. The number of occurrences of each word may be stored in an
associative array as follows:
variable a, word;
a = Assoc_Type [Integer_Type];
foreach (word_list)
{
word = ();
if (0 == assoc_key_exists (a, word))
a[word] = 0;
a[word]++; % same as a[word] = a[word] + 1;
}
Note that assoc_key_exists was necessary to determine whether or not a
word was already added to the array in order to properly initialize
it. However, by creating the associative array with a default value
of 0, the above code may be simplified to
variable a, word;
a = Assoc_Type [Integer_Type, 0];
foreach (word_list)
{
word = ();
a[word]++;
}
13. Structures and User-Defined Types
A structure is a heterogeneous container object, i.e., it is an object
with elements whose values do not have to be of the same data type.
The elements or fields of a structure are named, and one accesses a
particular field of the structure via the field name. This should be
contrasted with an array whose values are of the same type, and whose
elements are accessed via array indices.
A user-defined data type is a structure with a fixed set of fields
defined by the user.
13.1. Defining a Structure
The struct keyword is used to define a structure. The syntax for this
operation is:
struct {field-name-1, field-name-2, ... field-name-N};
This creates and returns a structure with N fields whose names are
specified by field-name-1, field-name-2, ..., field-name-N. When a
structure is created, all its fields are initialized to NULL.
For example,
variable t = struct { city_name, population, next };
creates a structure with three fields and assigns it to the variable
t.
Alternatively, a structure may be created by dereferencing
Struct_Type. For example, the above structure may also be created
using one of the two forms:
t = @Struct_Type ("city_name", "population", "next");
t = @Struct_Type (["city_name", "population", "next"]);
These are useful when creating structures dynamically where one does
not know the name of the fields until run-time.
Like arrays, structures are passed around via a references. Thus, in
the above example, the value of t is a reference to the structure.
This means that after execution of
variable u = t;
both t and u refer to the same structure, since only the reference was
used in the assignment. To actually create a new copy of the struc-
ture, use the dereference operator, e.g.,
variable u = @t;
13.2. Accessing the Fields of a Structure
The dot (.) operator is used to specify the a particular field of
structure. If s is a structure and field_name is a field of the
structure, then s.field_name specifies that field of s. This
specification can be used in expressions just like ordinary variables.
Again, consider
variable t = struct { city_name, population, next };
described in the last section. Then,
t.city_name = "New York";
t.population = 13000000;
if (t.population > 200) t = t.next;
are all valid statements involving the fields of t.
13.3. Linked Lists
One of the most important uses of structures is to create a dynamic
data structure such as a linked-list. A linked-list is simply a chain
of structures that are linked together such that one structure in the
chain is the value of a field of the previous structure in the chain.
To be concrete, consider the structure discussed earlier:
variable t = struct { city_name, population, next };
and suppose that we desire to create a list of such structures. The
purpose of the next field is to provide the link to the next structure
in the chain. Suppose that there exists a function, read_next_city,
that reads city names and populations from a file. Then we can create
the list via:
define create_population_list ()
{
variable city_name, population, list_root, list_tail;
variable next;
list_root = NULL;
while (read_next_city (&city_name, &population))
{
next = struct {city_name, population, next };
next.city_name = city_name;
next.population = population;
next.next = NULL;
if (list_root == NULL)
list_root = next;
else
list_tail.next = next;
list_tail = next;
}
return list_root;
}
In this function, the variables list_root and list_tail represent the
beginning and end of the list, respectively. As long as read_next_city
returns a non-zero value, a new structure is created, initialized, and
then appended to the list via the next field of the list_tail struc-
ture. On the first time through the loop, the list is created via the
assignment to the list_root variable.
This function may be used as follows:
variable Population_List = create_population_list ();
if (Population_List == NULL) error ("List is empty");
We can create other functions that manipulate the list. An example is
a function that finds the city with the largest population:
define get_largest_city (list)
{
variable largest;
largest = list;
while (list != NULL)
{
if (list.population > largest.population)
largest = list;
list = list.next;
}
return largest.city_name;
}
vmessage ("%s is the largest city in the list",
get_largest_city (Population_List)));
The get_largest_city is a typical example of how one traverses a lin-
ear linked-list by starting at the head of the list and successively
moves to the next element of the list via the next field.
In the previous example, a while loop was used to traverse the linked
list. It is faster to use a foreach loop for this:
define get_largest_city (list)
{
variable largest, elem;
largest = list;
foreach (list)
{
elem = ();
if (item.population > largest.population)
largest = item;
}
return largest.city_name;
}
Here a foreach loop has been used to walk the list via its next field.
If the field name was not next, then it would have been necessary to
use the using form of the foreach statement. For example, if the
field name implementing the linked list was next_item, then
foreach (list) using ("next_item")
{
elem = ();
.
.
}
would have been used. In other words, unless otherwise indicated via
the using clause, foreach walks the list using a field named next.
Now consider a function that sorts the list according to population.
To illustrate the technique, a bubble-sort will be used, not because
it is efficient, it is not, but because it is simple and intuitive.
define sort_population_list (list)
{
variable changed;
variable node, next_node, last_node;
do
{
changed = 0;
node = list;
next_node = node.next;
last_node = NULL;
while (next_node != NULL)
{
if (node.population < next_node.population)
{
% swap node and next_node
node.next = next_node.next;
next_node.next = node;
if (last_node != NULL)
last_node.next = next_node;
if (list == node) list = next_node;
node = next_node;
next_node = node.next;
changed++;
}
last_node = node;
node = next_node;
next_node = next_node.next;
}
}
while (changed);
return list;
}
Note the test for equality between list and node, i.e.,
if (list == node) list = next_node;
It is important to appreciate the fact that the values of these vari-
ables are references to structures, and that the comparison only com-
pares the references and not the actual structures they reference. If
it were not for this, the algorithm would fail.
13.4. Defining New Types
A user-defined data type may be defined using the typedef keyword. In
the current implementation, a user-defined data type is essentially a
structure with a user-defined set of fields. For example, in the
previous section a structure was used to represent a city/population
pair. We can define a data type called Population_Type to represent
the same information:
typedef struct
{
city_name,
population
} Population_Type;
This data type can be used like all other data types. For example, an
array of Population_Type types can be created,
variable a = Population_Type[10];
and `populated' via expressions such as
a[0].city_name = "Boston";
a[0].population = 2500000;
The new type Population_Type may also be used with the typeof func-
tion:
if (Population_Type = typeof (a)) city = a.city_name;
The dereference @ may be used to create an instance of the new type:
a = @Population_Type;
a.city_name = "Calcutta";
a.population = 13000000;
14. Error Handling
Many intrinsic functions signal errors in the event of failure. User
defined functions may also generate an error condition via the error
function. Depending upon the severity of the error, it can be caught
and cleared using a construct called an error-block.
14.1. Error-Blocks
When the interpreter encounters a recoverable run-time error, it will
return to top-level by unwinding its function call stack. Any error-
blocks that it encounters as part of this unwinding process will get
executed. Errors such as syntax errors and memory allocation errors
are not recoverable, and error-blocks will not get executed when such
errors are encountered.
An error-block is defined using the syntax
ERROR_BLOCK { statement-list }
where statement-list represents a list of statements that comprise the
error-block. A simple example of an error-block is
define simple (a)
{
ERROR_BLOCK { message ("error-block executed"); }
if (a) error ("Triggering Error");
message ("hello");
}
Executing this function via simple(0) will result in the message
"hello". However, calling it using simple(1) will generate an error
that will be caught, but not cleared, by the error-block and the
"error-block executed" message will result.
Error-blocks are never executed unless triggered by an error. The
only exception to this is when the user explicitly indicates that the
error-block in scope should execute. This is indicated by the special
keyword EXECUTE_ERROR_BLOCK. For example, simple could be recoded as
define simple (a)
{
variable err_string = "error-block executed";
ERROR_BLOCK { message (err_string); }
if (a) error ("Triggering Error");
err_string = "hello";
EXECUTE_ERROR_BLOCK;
}
Please note that EXECUTE_ERROR_BLOCK does not initiate an error
condition; it simply causes the error-block to be executed and control
will pass onto the next statement following the EXECUTE_ERROR_BLOCK
statement.
14.2. Clearing Errors
Once an error has been caught by an error-block, the error can be
cleared by the _clear_error function. After the error has been
cleared, execution will resume at the next statement at the level of
the error block following the statement that generated the error. For
example, consider:
define make_error ()
{
error ("Error condition created.");
message ("This statement is not executed.");
}
define test ()
{
ERROR_BLOCK
{
_clear_error ();
}
make_error ();
message ("error cleared.");
}
Calling test will trigger an error in the make_error function, but
will get cleared in the test function. The call-stack will unwind
from make_error back into test where the error-block will get exe-
cuted. As a result, execution resumes after the statement that makes
the call to make_error since this statement is at the same level as
the error-block that cleared the error.
Here is another example that illustrates how multiple error-blocks
work:
define example ()
{
variable n = 0, s = "";
variable str;
ERROR_BLOCK {
str = sprintf ("s=%s,n=%d", s, n);
_clear_error ();
}
forever
{
ERROR_BLOCK {
s += "0";
_clear_error ();
}
if (n == 0) error ("");
ERROR_BLOCK {
s += "1";
}
if (n == 1) error ("");
n++;
}
return str;
}
Here, three error-blocks have been declared. One has been declared
outside the forever loop and the other two have been declared inside
the forever loop. Each time through the loop, the variable n is
incremented and a different error-block is triggered. The error-block
that gets triggered is the last one encountered, since that will be
the one in scope. On the first time through the loop, n will be zero
and the first error-block in the loop will get executed. This error
block clears the error and execution resumes following the if state-
ment that triggered the error. The variable n will get incremented to
1 and, on the second cycle through the loop the second if statement
will trigger an error causing the second error-block to execute. This
time, the error is not cleared and the call-stack unwinds out of the
forever loop, at which point the error-block outside the loop is in
scope, causing it to execute. This error-block prints out the values
of the variables s and n. It will clear the error and execution
resumes on the statement following the forever loop. The result of
this complicated series of events is that the function will return the
string "s=01,n=1".
15. Loading Files: evalfile and autoload
16. File Input/Output
S-Lang provides built-in supports for two different I/O facilities.
The simplest interface is modeled upon the C language stdio streams
interface and consists of functions such as fopen, fgets, etc. The
other interface is modeled on a lower level POSIX interface consisting
of functions such as open, read, etc. In addition to permitting more
control, the lower level interface permits one to access network
objects as well as disk files.
16.1. Input/Output via stdio
16.1.1. Stdio Overview
The stdio interface consists of the following functions:
o fopen, which opens a file for read or writing.
o fclose, which closes a file opened by fopen.
o fgets, used to read a line from the file.
o fputs, which writes text to the file.
o fprintf, used to write formatted text to the file.
o fwrite, which may be used to write objects to the file.
o fread, which reads a specified number of objects from the file.
o feof, which is used to test whether the file pointer is at the end
of the file.
o ferror, which is used to see whether or not the stream associated
with the file has an error.
o clearerr, which clears the end-of-file and error indicators for the
stream.
o fflush, used to force all buffered data associated with the stream
to be written out.
o ftell, which is used to query the file position indicator of the
stream.
o fseek, which is used to set the position of the file position
indicator of the stream.
o fgetslines, which reads all the lines in a text file and returns
them as an array of strings.
In addition, the interface supports the popen and pclose functions on
systems where the corresponding C functions are available.
Before reading or writing to a file, it must first be opened using the
fopen function. The only exceptions to this rule involves use of the
pre-opened streams: stdin, stdout, and stderr. fopen accepts two
arguments: a file name and a string argument that indicates how the
file is to be opened, e.g., for reading, writing, update, etc. It
returns a File_Type stream object that is used as an argument to all
other functions of the stdio interface. Upon failure, it returns
NULL. See the reference manual for more information about fopen.
16.1.2. Stdio Examples
In this section, some simple examples of the use of the stdio
interface is presented. It is important to realize that all the
functions of the interface return something, and that return value
must be dealt with.
The first example involves writing a function to count the number of
lines in a text file. To do this, we shall read in the lines, one by
one, and count them:
define count_lines_in_file (file)
{
variable fp, line, count;
fp = fopen (file, "r"); % Open the file for reading
if (fp == NULL)
verror ("%s failed to open", file);
count = 0;
while (-1 != fgets (&line, fp))
count++;
() = fclose (fp);
return count;
}
Note that &line was passed to the fgets function. When fgets returns,
line will contain the line of text read in from the file. Also note
how the return value from fclose was handled.
Although the preceding example closed the file via fclose, there is no
need to explicitly close a file because S-Lang will automatically
close the file when it is no longer referenced. Since the only
variable to reference the file is fp, it would have automatically been
closed when the function returned.
Suppose that it is desired to count the number of characters in the
file instead of the number of lines. To do this, the while loop could
be modified to count the characters as follows:
while (-1 != fgets (&line, fp))
count += strlen (line);
The main difficulty with this approach is that it will not work for
binary files, i.e., files that contain null characters. For such
files, the file should be opened in binary mode via
fp = fopen (file, "rb");
and then the data read in using the fread function:
while (-1 != fread (&line, Char_Type, 1024, fp))
count += bstrlen (line);
The fread function requires two additional arguments: the type of
object to read (Char_Type in the case), and the number of such objects
to read. The function returns the number of objects actually read, or
-1 upon failure. The bstrlen function was used to compute the length
of line because for Char_Type or UChar_Type objects, the fread func-
tion assigns a binary string (BString_Type) to line.
The foreach construct also works with File_Type objects. For example,
the number of characters in a file may be counted via
foreach (fp) using ("char")
{
ch = ();
count++;
}
To count the number of lines, one can use:
foreach (fp) using ("line")
{
line = ();
num_lines++;
count += strlen (line);
}
Finally, it should be mentioned that neither of these examples should
be used to count the number of characters in a file when that
information is more readily accessible by another means. For example,
it is preferable to get this information via the stat_file function:
define count_chars_in_file (file)
{
variable st;
st = stat_file (file);
if (st == NULL)
error ("stat_file failed.");
return st.st_size;
}
16.2. POSIX I/O
16.3. Advanced I/O techniques
The previous examples illustrate how to read and write objects of a
single data-type from a file, e.g.,
num = fread (&a, Double_Type, 20, fp);
would result in a Double_Type[num] array being assigned to a if suc-
cessful. However, suppose that the binary data file consists of num-
bers in a specified byte-order. How can one read such objects with
the proper byte swapping? The answer is to use the fread function to
read the objects as Char_Type and then unpack the resulting string
into the specified data type, or types. This process is facilitated
using the pack and unpack functions.
The pack function follows the syntax
BString_Type pack (format-string, item-list);
and combines the objects in the item-list according to format-string
into a binary string and returns the result. Likewise, the unpack
function may be used to convert a binary string into separate data
objects:
(variable-list) = unpack (format-string, binary-string);
The format string consists of one or more data-type specification
characters, and each may be followed by an optional decimal length
specifier. Specifically, the data-types are specified according to the
following table:
c char
C unsigned char
h short
H unsigned short
i int
I unsigned int
l long
L unsigned long
j 16 bit int
J 16 unsigned int
k 32 bit int
K 32 bit unsigned int
f float
d double
F 32 bit float
D 64 bit float
s character string, null padded
S character string, space padded
x a null pad character
A decimal length specifier may follow the data-type specifier. With
the exception of the s and S specifiers, the length specifier indi-
cates how many objects of that data type are to be packed or unpacked
from the string. When used with the s or S specifiers, it indicates
the field width to be used. If the length specifier is not present,
the length defaults to one.
With the exception of c, C, s, S, and x, each of these may be prefixed
by a character that indicates the byte-order of the object:
> big-endian order (network order)
< little-endian order
= native byte-order
The default is native byte order.
Here are a few examples that should make this more clear:
a = pack ("cc", 'A', 'B'); % ==> a = "AB";
a = pack ("c2", 'A', 'B'); % ==> a = "AB";
a = pack ("xxcxxc", 'A', 'B'); % ==> a = "\0\0A\0\0B";
a = pack ("h2", 'A', 'B'); % ==> a = "\0A\0B" or "\0B\0A"
a = pack (">h2", 'A', 'B'); % ==> a = "\0\xA\0\xB"
a = pack ("<h2", 'A', 'B'); % ==> a = "\0B\0A"
a = pack ("s4", "AB", "CD"); % ==> a = "AB\0\0"
a = pack ("s4s2", "AB", "CD"); % ==> a = "AB\0\0CD"
a = pack ("S4", "AB", "CD"); % ==> a = "AB "
a = pack ("S4S2", "AB", "CD"); % ==> a = "AB CD"
When unpacking, if the length specifier is greater than one, then an
array of that length will be returned. In addition, trailing
whitespace and null character are stripped when unpacking an object
given by the S specifier. Here are a few examples:
(x,y) = unpack ("cc", "AB"); % ==> x = 'A', y = 'B'
x = unpack ("c2", "AB"); % ==> x = ['A', 'B']
x = unpack ("x<H", "\0\xAB\xCD"); % ==> x = 0xCDABuh
x = unpack ("xxs4", "a b c\0d e f"); % ==> x = "b c\0"
x = unpack ("xxS4", "a b c\0d e f"); % ==> x = "b c"
16.3.1. Example: Reading /var/log/wtmp
Consider the task of reading the Unix system file /var/log/utmp, which
contains login records about who logged onto the system. This file
format is documented in section 5 of the online Unix man pages, and
consists of a sequence of entries formatted according to the C
structure utmp defined in the utmp.h C header file. The actual
details of the structure may vary from one version of Unix to the
other. For the purposes of this example, consider its definition
under the Linux operating system running on an Intel processor:
struct utmp {
short ut_type; /* type of login */
pid_t ut_pid; /* pid of process */
char ut_line[12]; /* device name of tty - "/dev/" */
char ut_id[2]; /* init id or abbrev. ttyname */
time_t ut_time; /* login time */
char ut_user[8]; /* user name */
char ut_host[16]; /* host name for remote login */
long ut_addr; /* IP addr of remote host */
};
On this system, pid_t is defined to be an int and time_t is a long.
Hence, a format specifier for the pack and unpack functions is easily
constructed to be:
"h i S12 S2 l S8 S16 l"
However, this particular definition is naive because it does not allow
for structure padding performed by the C compiler in order to align
the data types on suitable word boundaries. Fortunately, the intrin-
sic function pad_pack_format may be used to modify a format by adding
the correct amount of padding in the right places. In fact,
pad_pack_format applied to the above format on an Intel-based Linux
system produces the result:
"h x2 i S12 S2 x2 l S8 S16 l"
Here we see that 4 bytes of padding were added.
The other missing piece of information is the size of the structure.
This is useful because we would like to read in one structure at a
time using the fread function. Knowing the size of the various data
types makes this easy; however it is even easier to use the
sizeof_pack intrinsic function, which returns the size (in bytes) of
the structure described by the pack format.
So, with all the pieces in place, it is rather straightforward to
write the code:
variable format, size, fp, buf;
typedef struct
{
ut_type, ut_pid, ut_line, ut_id,
ut_time, ut_user, ut_host, ut_addr
} UTMP_Type;
format = pad_pack_format ("h i S12 S2 l S8 S16 l");
size = sizeof_pack (format);
define print_utmp (u)
{
() = fprintf (stdout, "%-16s %-12s %-16s %s\n",
u.ut_user, u.ut_line, u.ut_host, ctime (u.ut_time));
}
fp = fopen ("/var/log/utmp", "rb");
if (fp == NULL)
error ("Unable to open utmp file");
() = fprintf (stdout, "%-16s %-12s %-16s %s\n",
"USER", "TTY", "FROM", "LOGIN@");
variable U = @UTMP_Type;
while (-1 != fread (&buf, Char_Type, size, fp))
{
set_struct_fields (U, unpack (format, buf));
print_utmp (U);
}
() = fclose (fp);
A few comments about this example are in order. First of all, note
that a new data type called UTMP_Type was created, although this was
not really necessary. We also opened the file in binary mode, but
this too is optional under a Unix system where there is no distinction
between binary and text modes. The print_utmp function does not print
all of the structure fields. Finally, last but not least, the return
values from fprintf and fclose were dealt with.
17. Debugging
The current implementation provides no support for an interactive
debugger, although a future version will. Nevertheless, S-Lang has
several features that aid the programmer in tracking down problems,
including function call tracebacks and the tracing of function calls.
However, the biggest debugging aid stems from the fact that the
language is interpreted permitting one to easily add debugging
statements to the code.
To enable debugging information, add the lines
_debug_info = 1;
_traceback = 1;
to the top of the source file of the code containing the bug and the
reload the file. Setting the _debug_info variable to 1 causes line
number information to be compiled into the functions when the file is
loaded. The _traceback variable controls whether or not traceback
information should be generated. If it is set to 1, the values of
local variables will be dumped when the traceback is generated. Set-
ting this variable to -1 will cause only function names to be reported
in the traceback.
Here is an example of a traceback report:
S-Lang Traceback: error
S-Lang Traceback: verror
S-Lang Traceback: (Error occurred on line 65)
S-Lang Traceback: search_generic_search
Local Variables:
$0: Type: String_Type, Value: "Search forward:"
$1: Type: Integer_Type, Value: 1
$2: Type: Ref_Type, Value: _function_return_1
$3: Type: String_Type, Value: "abcdefg"
$4: Type: Integer_Type, Value: 1
S-Lang Traceback: (Error occurred on line 72)
S-Lang Traceback: search_forward
There are several ways to read this report; perhaps the simplest is to
read it from the bottom. This report says that on line 72, the
search_forward function called the search_generic_search function. On
line 65 it called the verror function, which called error. The
search_generic_search function contains 5 local variables and are rep-
resented symbolically as $0 through $4.
18. Regular Expressions
The S-Lang library includes a regular expression (RE) package that may
be used by an application embedding the library. The RE syntax should
be familiar to anyone acquainted with regular expressions. In this
section the syntax of the S-Lang regular expressions is discussed.
18.1. S-Lang RE Syntax
A regular expression specifies a pattern to be matched against a
string, and has the property that the contcatenation of two REs is
also a RE.
The S-Lang library supports the following standard regular
expressions:
. match any character except newline
* matches zero or more occurences of previous RE
+ matches one or more occurences of previous RE
? matches zero or one occurence of previous RE
^ matches beginning of a line
$ matches end of line
[ ... ] matches any single character between brackets.
For example, [-02468] matches `-' or any even digit.
and [-0-9a-z] matches `-' and any digit between 0 and 9
as well as letters a through z.
\< Match the beginning of a word.
\> Match the end of a word.
\( ... \)
\1, \2, ..., \9 Matches the match specified by nth \( ... \)
expression.
In addition the following extensions are also supported:
\c turn on case-sensitivity (default)
\C turn off case-sensitivity
\d match any digit
\e match ESC char
Here are some simple examples:
"^int " matches the "int " at the beginning of a line.
"\<money\>" matches "money" but only if it appears as a separate word.
"^$" matches an empty line.
A more complex pattern is
"\(\<[a-zA-Z]+\>\)[ ]+\1\>"
which matches any word repeated consecutively. Note how the grouping
operators \( and \) are used to define the text matched by the
enclosed regular expression, and then subsequently referred to \1.
Finally, remember that when used in string literals either in the S-
Lang language or in the C language, care must be taken to "double-up"
the '\' character since both languages treat it as as an escape
character.
18.2. Differences between S-Lang and egrep REs
There are several differences between S-Lang regular expressions and,
e.g., egrep regular expressions.
The most notable difference is that the S-Lang regular expressions do
not support the OR operator | in expressions. This means that "a|b"
or "a\|b" do not have the meaning that they have in regular expression
packages that support egrep-style expressions.
The other main difference is that while S-Lang regular expressions
support the grouping operators \( and \), they are only used as a
means of specifying the text that is matched. That is, the expression
"@\([a-z]*\)@.*@\1@"
matches "xxx@abc@silly@abc@yyy", where the pattern \1 matches the text
enclosed by the \( and \) expressions. However, in the current imple-
mentation, the grouping operators are not used to group regular
expressions to form a single regular expression. Thus expression such
as "\(hello\)*" is not a pattern to match zero or more occurances of
"hello" as it is in e.g., egrep.
One question that comes up from time to time is why doesn't S-Lang
simply employ some posix-compatible regular expression library. The
simple answer is that, at the time of this writing, none exists that
is is available across all the platforms that the S-Lang library
supports (Unix, VMS, OS/2, win32, win16, BEOS, MSDOS, and QNX) and can
be distributed under both the GNU and Artistic licenses. It is
particularly important that the library and the interpreter support a
common set of regular expressions in a platform independent manner.
19. Future Directions
Several new features or enhancements to the S-Lang language are
planned for the next major release. In no particular order, these
include:
o An interactive debugging facility.
o Function qualifiers. These entities should already be familiar to
VMS users or to those who are familiar with the IDL language.
Basically, a qualifier is an optional argument that is passed to a
function, e.g., plot(X,Y,/logx). Here /logx is a qualifier that
specifies that the plot function should use a log scale for x.
o File local variables and functions. A file local variable or
function is an object that is global to the file that defines it.
o Multi-threading. Currently the language does not support multiple
threads.
A. Copyright
The S-Lang library is distributed under two copyrights: the GNU Genral
Public License, and the Artistic License. Any program that uses the
interpreter must adhere to rules of one of these licenses.
A.1. The GNU Public License
GNU GENERAL PUBLIC LICENSE
Version 2, June 1991
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
675 Mass Ave, Cambridge, MA 02139, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The licenses for most software are designed to take away your freedom
to share and change it. By contrast, the GNU General Public License
is intended to guarantee your freedom to share and change free soft-
ware--to make sure the software is free for all its users. This Gen-
eral Public License applies to most of the Free Software Foundation's
software and to any other program whose authors commit to using it.
(Some other Free Software Foundation software is covered by the GNU
Library General Public License instead.) You can apply it to your
programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if
you distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have. You must make sure that they, too, receive or can get the
source code. And you must show them these terms so they know their
rights.
We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software. If the software is modified by someone else and passed on,
we want its recipients to know that what they have is not the
original, so that any problems introduced by others will not reflect
on the original authors' reputations.
Finally, any free program is threatened constantly by software
patents. We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary. To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at
all.
The precise terms and conditions for copying, distribution and
modification follow.
GNU GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License applies to any program or other work which contains a
notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License. The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language. (Hereinafter, translation is included without limitation in
the term "modification".) Each licensee is addressed as "you".
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the Program
(independent of having been made by running the Program). Whether
that is true depends on what the Program does.
1. You may copy and distribute verbatim copies of the Program's source
code as you receive it, in any medium, provided that you conspicuously
and appropriately publish on each copy an appropriate copyright notice
and disclaimer of warranty; keep intact all the notices that refer to
this License and to the absence of any warranty; and give any other
recipients of the Program a copy of this License along with the
Program.
You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a
fee.
2. You may modify your copy or copies of the Program or any portion of
it, thus forming a work based on the Program, and copy and distribute
such modifications or work under the terms of Section 1 above,
provided that you also meet all of these conditions:
a) You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.
b) You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.
c) If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License. (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If identi-
fiable sections of that work are not derived from the Program, and can
be reasonably considered independent and separate works in themselves,
then this License, and its terms, do not apply to those sections when
you distribute them as separate works. But when you distribute the
same sections as part of a whole which is a work based on the Program,
the distribution of the whole must be on the terms of this License,
whose permissions for other licensees extend to the entire whole, and
thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.
In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:
a) Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,
b) Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,
c) Accompany it with the information you received as to the offer
to distribute corresponding source code. (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
The source code for a work means the preferred form of the work for
making modifications to it. For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to con-
trol compilation and installation of the executable. However, as a
special exception, the source code distributed need not include any-
thing that is normally distributed (in either source or binary form)
with the major components (compiler, kernel, and so on) of the operat-
ing system on which the executable runs, unless that component itself
accompanies the executable.
If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.
4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.
5. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Program or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.
6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.
7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all. For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded. In such case, this License incorporates
the limitation as if written in the body of this License.
9. The Free Software Foundation may publish revised and/or new
versions of the General Public License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation. If the Program does not specify a
version number of this License, you may choose any version ever
published by the Free Software Foundation.
10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the
author to ask for permission. For software which is copyrighted by
the Free Software Foundation, write to the Free Software Foundation;
we sometimes make exceptions for this. Our decision will be guided by
the two goals of preserving the free status of all derivatives of our
free software and of promoting the sharing and reuse of software
generally.
NO WARRANTY
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
END OF TERMS AND CONDITIONS
Appendix: How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) 19yy <name of author>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
Also add information on how to contact you by electronic and paper
mail.
If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) 19yy name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appro-
priate parts of the General Public License. Of course, the commands
you use may be called something other than `show w' and `show c'; they
could even be mouse-clicks or menu items--whatever suits your program.
You should also get your employer (if you work as a programmer) or
your school, if any, to sign a "copyright disclaimer" for the program,
if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
`Gnomovision' (which makes passes at compilers) written by James Hacker.
<signature of Ty Coon>, 1 April 1989
Ty Coon, President of Vice
This General Public License does not permit incorporating your program
into proprietary programs. If your program is a subroutine library,
you may consider it more useful to permit linking proprietary applica-
tions with the library. If this is what you want to do, use the GNU
Library General Public License instead of this License.
A.2. The Artistic License
The "Artistic License"
Preamble
The intent of this document is to state the conditions under which a
Package may be copied, such that the Copyright Holder maintains some
semblance of artistic control over the development of the package,
while giving the users of the package the right to use and distribute
the Package in a more-or-less customary fashion, plus the right to
make reasonable modifications.
Definitions:
"Package" refers to the collection of files distributed by the
Copyright Holder, and derivatives of that collection of files
created through textual modification.
"Standard Version" refers to such a Package if it has not been
modified, or has been modified in accordance with the wishes
of the Copyright Holder as specified below.
"Copyright Holder" is whoever is named in the copyright or
copyrights for the package.
"You" is you, if you're thinking about copying or distributing
this Package.
"Reasonable copying fee" is whatever you can justify on the
basis of media cost, duplication charges, time of people involved,
and so on. (You will not be required to justify it to the
Copyright Holder, but only to the computing community at large
as a market that must bear the fee.)
"Freely Available" means that no fee is charged for the item
itself, though there may be fees involved in handling the item.
It also means that recipients of the item may redistribute it
under the same conditions they received it.
1. You may make and give away verbatim copies of the source form of
the Standard Version of this Package without restriction, provided
that you duplicate all of the original copyright notices and associ-
ated disclaimers.
2. You may apply bug fixes, portability fixes and other modifications
derived from the Public Domain or from the Copyright Holder. A
Package modified in such a way shall still be considered the Standard
Version.
3. You may otherwise modify your copy of this Package in any way,
provided that you insert a prominent notice in each changed file
stating how and when you changed that file, and provided that you do
at least ONE of the following:
a) place your modifications in the Public Domain or otherwise make them
Freely Available, such as by posting said modifications to Usenet or
an equivalent medium, or placing the modifications on a major archive
site such as uunet.uu.net, or by allowing the Copyright Holder to include
your modifications in the Standard Version of the Package.
b) use the modified Package only within your corporation or organization.
c) rename any non-standard executables so the names do not conflict
with standard executables, which must also be provided, and provide
a separate manual page for each non-standard executable that clearly
documents how it differs from the Standard Version.
d) make other distribution arrangements with the Copyright Holder.
4. You may distribute the programs of this Package in object code or
executable form, provided that you do at least ONE of the following:
a) distribute a Standard Version of the executables and library files,
together with instructions (in the manual page or equivalent) on where
to get the Standard Version.
b) accompany the distribution with the machine-readable source of
the Package with your modifications.
c) give non-standard executables non-standard names, and clearly
document the differences in manual pages (or equivalent), together
with instructions on where to get the Standard Version.
d) make other distribution arrangements with the Copyright Holder.
5. You may charge a reasonable copying fee for any distribution of
this Package. You may charge any fee you choose for support of this
Package. You may not charge a fee for this Package itself. However,
you may distribute this Package in aggregate with other (possibly com-
mercial) programs as part of a larger (possibly commercial) software
distribution provided that you do not advertise this Package as a
product of your own. You may embed this Package's interpreter within
an executable of yours (by linking); this shall be construed as a mere
form of aggregation, provided that the complete Standard Version of
the interpreter is so embedded.
6. The scripts and library files supplied as input to or produced as
output from the programs of this Package do not automatically fall
under the copyright of this Package, but belong to whomever generated
them, and may be sold commercially, and may be aggregated with this
Package. If such scripts or library files are aggregated with this
Package via the so-called "undump" or "unexec" methods of producing a
binary executable image, then distribution of such an image shall
neither be construed as a distribution of this Package nor shall it
fall under the restrictions of Paragraphs 3 and 4, provided that you
do not represent such an executable image as a Standard Version of
this Package.
7. C subroutines (or comparably compiled subroutines in other
languages) supplied by you and linked into this Package in order to
emulate subroutines and variables of the language defined by this
Package shall not be considered part of this Package, but are the
equivalent of input as in Paragraph 6, provided these subroutines do
not change the language in any way that would cause it to fail the
regression tests for the language.
8. Aggregation of this Package with a commercial distribution is
always permitted provided that the use of this Package is embedded;
that is, when no overt attempt is made to make this Package's
interfaces visible to the end user of the commercial distribution.
Such use shall not be construed as a distribution of this Package.
9. The name of the Copyright Holder may not be used to endorse or
promote products derived from this software without specific prior
written permission.
10. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
Table of Contents
1. Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. A Brief History of S-Lang . . . . . . . . . . . . . . . . . . 4
1.2. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 4
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1. Language Features . . . . . . . . . . . . . . . . . . . . . . 6
2.2. Data Types and Operators . . . . . . . . . . . . . . . . . . 6
2.3. Statements and Functions . . . . . . . . . . . . . . . . . . 6
2.4. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 7
2.5. Run-Time Library . . . . . . . . . . . . . . . . . . . . . . 7
2.6. Input/Output . . . . . . . . . . . . . . . . . . . . . . . . 7
2.7. Obtaining S-Lang . . . . . . . . . . . . . . . . . . . . . . 8
3. Overview of the Language . . . . . . . . . . . . . . . . . . . 9
3.1. Variables and Functions . . . . . . . . . . . . . . . . . . . 9
3.2. Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.3. Referencing and Dereferencing . . . . . . . . . . . . . . . . 11
3.4. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.5. Structures and User-Defined Types . . . . . . . . . . . . . . 15
3.6. Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . 16
4. Data Types and Literal Constants . . . . . . . . . . . . . . . 18
4.1. Predefined Data Types . . . . . . . . . . . . . . . . . . . . 18
4.1.1. Integers . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.1.2. Floating Point Numbers . . . . . . . . . . . . . . . . . . 19
4.1.3. Complex Numbers . . . . . . . . . . . . . . . . . . . . . . 19
4.1.4. Strings . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.1.5. Null_Type . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.1.6. Ref_Type . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.1.7. Array_Type and Struct_Type . . . . . . . . . . . . . . . . 22
4.1.8. DataType_Type Type . . . . . . . . . . . . . . . . . . . . 22
4.2. Typecasting: Converting from one Type to Another . . . . . . 23
5. Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6. Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
7. Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
7.1. Unary Operators . . . . . . . . . . . . . . . . . . . . . . . 28
7.2. Binary Operators . . . . . . . . . . . . . . . . . . . . . . 28
7.2.1. Arithmetic Operators . . . . . . . . . . . . . . . . . . . 29
7.2.2. Relational Operators . . . . . . . . . . . . . . . . . . . 29
7.2.3. Boolean Operators . . . . . . . . . . . . . . . . . . . . . 29
7.2.4. Bitwise Operators . . . . . . . . . . . . . . . . . . . . . 30
7.2.5. Namespace operator . . . . . . . . . . . . . . . . . . . . 31
7.2.6. Operator Precedence . . . . . . . . . . . . . . . . . . . . 31
7.2.7. Binary Operators and Functions Returning Multiple Val-
ues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
7.3. Mixing Integer and Floating Point Arithmetic . . . . . . . . 32
7.4. Short Circuit Boolean Evaluation . . . . . . . . . . . . . . 33
8. Statements . . . . . . . . . . . . . . . . . . . . . . . . . . 34
8.1. Variable Declaration Statements . . . . . . . . . . . . . . . 34
8.2. Assignment Statements . . . . . . . . . . . . . . . . . . . . 34
8.3. Conditional and Looping Statements . . . . . . . . . . . . . 36
8.3.1. Conditional Forms . . . . . . . . . . . . . . . . . . . . . 36
8.3.1.1. if . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
8.3.1.2. if-else . . . . . . . . . . . . . . . . . . . . . . . . . 36
8.3.1.3. !if . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
8.3.1.4. orelse, andelse . . . . . . . . . . . . . . . . . . . . . 38
8.3.1.5. switch . . . . . . . . . . . . . . . . . . . . . . . . . 38
8.3.2. Looping Forms . . . . . . . . . . . . . . . . . . . . . . . 40
8.3.2.1. while . . . . . . . . . . . . . . . . . . . . . . . . . . 40
8.3.2.2. do...while . . . . . . . . . . . . . . . . . . . . . . . 41
8.3.2.3. for . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
8.3.2.4. loop . . . . . . . . . . . . . . . . . . . . . . . . . . 42
8.3.2.5. forever . . . . . . . . . . . . . . . . . . . . . . . . . 42
8.3.2.6. foreach . . . . . . . . . . . . . . . . . . . . . . . . . 42
8.4. break, return, continue . . . . . . . . . . . . . . . . . . . 44
9. Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
9.1. Declaring Functions . . . . . . . . . . . . . . . . . . . . . 46
9.2. Parameter Passing Mechanism . . . . . . . . . . . . . . . . . 46
9.3. Referencing Variables . . . . . . . . . . . . . . . . . . . . 48
9.4. Functions with a Variable Number of Arguments . . . . . . . . 48
9.5. Returning Values . . . . . . . . . . . . . . . . . . . . . . 51
9.6. Multiple Assignment Statement . . . . . . . . . . . . . . . . 52
9.7. Exit-Blocks . . . . . . . . . . . . . . . . . . . . . . . . . 54
10. Name Spaces . . . . . . . . . . . . . . . . . . . . . . . . . 56
11. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
11.1. Creating Arrays . . . . . . . . . . . . . . . . . . . . . . 58
11.1.1. Range Arrays . . . . . . . . . . . . . . . . . . . . . . . 58
11.1.2. Creating arrays via the dereference operator . . . . . . . 59
11.2. Reshaping Arrays . . . . . . . . . . . . . . . . . . . . . . 60
11.3. Indexing Arrays . . . . . . . . . . . . . . . . . . . . . . 60
11.4. Arrays and Variables . . . . . . . . . . . . . . . . . . . . 63
11.5. Using Arrays in Computations . . . . . . . . . . . . . . . . 65
12. Associative Arrays . . . . . . . . . . . . . . . . . . . . . . 68
13. Structures and User-Defined Types . . . . . . . . . . . . . . 70
13.1. Defining a Structure . . . . . . . . . . . . . . . . . . . . 70
13.2. Accessing the Fields of a Structure . . . . . . . . . . . . 71
13.3. Linked Lists . . . . . . . . . . . . . . . . . . . . . . . . 71
13.4. Defining New Types . . . . . . . . . . . . . . . . . . . . . 74
14. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . 76
14.1. Error-Blocks . . . . . . . . . . . . . . . . . . . . . . . . 76
14.2. Clearing Errors . . . . . . . . . . . . . . . . . . . . . . 77
15. Loading Files: evalfile and autoload . . . . . . . . . . . . . 79
16. File Input/Output . . . . . . . . . . . . . . . . . . . . . . 80
16.1. Input/Output via stdio . . . . . . . . . . . . . . . . . . . 80
16.1.1. Stdio Overview . . . . . . . . . . . . . . . . . . . . . . 80
16.1.2. Stdio Examples . . . . . . . . . . . . . . . . . . . . . . 81
16.2. POSIX I/O . . . . . . . . . . . . . . . . . . . . . . . . . 82
16.3. Advanced I/O techniques . . . . . . . . . . . . . . . . . . 83
16.3.1. Example: Reading /var/log/wtmp . . . . . . . . . . . . . . 84
17. Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . 87
18. Regular Expressions . . . . . . . . . . . . . . . . . . . . . 88
18.1. S-Lang RE Syntax . . . . . . . . . . . . . . . . . . . . . 88
18.2. Differences between S-Lang and egrep REs . . . . . . . . . 89
19. Future Directions . . . . . . . . . . . . . . . . . . . . . . 90
A. Copyright . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
A.1. The GNU Public License . . . . . . . . . . . . . . . . . . . 91
A.2. The Artistic License . . . . . . . . . . . . . . . . . . . . 97
