-h

Usage information

-c

SeL object code output on standard output (Compile-Only-Modus)

-r <filename>

Execution of a SeL object code file (Runtime-Only-Modus)

-e

Output of internal configuration options

-f=<fieldname> <file>

Returns the content of field fieldname (SeL source code) in file file. No other output. The field output always contains the complete declaration including the last (semicolon) character.

Interpreter, compile- and runtime mode

sel -c file.sel

sel -c datei.sel > datei.sco

Compiled SeL files have a couple of nice features:

• They are smaller than regular source code
• They are executed significantly faster, especially where large or very long masterfiles are involved
• All contained lib commands are alredy resolved. This means, they will execute without the referred external resources
• Nevertheless, the previous advantage results in the disadvantage that compiled files do not respond to Master Override calls. Therefore, if you want to offer several masterfiles, you have to offer additional object files compiled with each of them.
• Object files can be executed by very simple interpreters (SeL stack machines). Currently, there is only the interpreter which is included in the SeL distribution. Nevertheless, it should be easily possible to implement a SeL stack machine in Java to run compiled object files on the client side within the readers' browsers. This would result in less server load as well as the possibility to read documents offline.

  (The stack machine's specification is available from the author.)

sel -r datei.sco

can be used to run compiled files.

The following is a comparison of a SeL object file execution to a full SeL source code compilation. The tests were run on the same file (the GhK homepage). This is the output of UNIX "time".

Timings for SeL source code: real 0m0.603s user 0m0.430s sys 0m0.100s real 0m0.570s user 0m0.440s sys 0m0.060s real 0m0.577s user 0m0.450s sys 0m0.060s real 0m0.557s user 0m0.420s sys 0m0.090s real 0m0.563s user 0m0.450s sys 0m0.070s real 0m0.572s user 0m0.450s sys 0m0.080s real 0m0.565s user 0m0.430s sys 0m0.080s real 0m0.567s user 0m0.440s sys 0m0.060s real 0m0.562s user 0m0.430s sys 0m0.080s real 0m0.555s user 0m0.430s sys 0m0.070s

Timings for compiled object file: real 0m0.204s user 0m0.100s sys 0m0.030s real 0m0.188s user 0m0.090s sys 0m0.050s real 0m0.172s user 0m0.090s sys 0m0.040s real 0m0.168s user 0m0.090s sys 0m0.050s real 0m0.168s user 0m0.100s sys 0m0.040s real 0m0.186s user 0m0.090s sys 0m0.060s real 0m0.170s user 0m0.100s sys 0m0.040s real 0m0.168s user 0m0.100s sys 0m0.050s real 0m0.164s user 0m0.090s sys 0m0.050s real 0m0.183s user 0m0.090s sys 0m0.040s

Data types

Variables do not have to be declared before usage but a value has to be assigned before variable evaluation. Referring to an uninitialized variable will cause the interpreter to stop with an error message.

Strings can have arbitrary lengths and arbitrary numbers of lines.

Zuweisungen

=GRUSS "Hello";

In this example the value "Hello" is assigned to the variable GRUSS. Variable names are case sensitive. Therefore, "gruss", "Gruss" and "GRUSS" are different variables. All three are allowed, but we suggest (for a more user friendly style) to use masterfile variables in a consistent way entirely in uppercase letters as shown above. In GhK WWW documents only upper case variable names are used.

Every declaration ends with a semicolon (";"). The semicolon is required as SeL allows declaration nesting (see below). Forgetting a semicolon after a declaration may not necessarily cause syntax errors, as SeL will probably still see a legal synatx. But this syntax contains unexpected declaration nestings which will cause consequent errors or strange behaviour. Please make sure to finish every declaration by a semicolon.

More than one value may be assigned to a variable. Old values will be overwritten by new ones::

=GRUSS "Hello"; =GRUSS "Good morning";

After this sequence, the variable GRUSS will contain the value "Good morning".

Quotation marks and SQD

=GRUSS "He said "Hello"";

This is wrong because SeL will interpret the quotation mark before "Hello" as the end of a string "He said ". To use quotation marks, the HTML like string delimiters sequence <SQD> can be used for declarations instead of normal quotation marks.:

=GRUSS <SQD>He said "Hello"</SQD>;

SQD stands for "SeL Quoted Data" and works like an HTML tag. The beginning of a string is marked by <SQD> and the end by </SQD>. Within an SQD sequence quotation marks may be used freely, just as SQD sequences may be used freely within quotation marks (Quotation marks within SQD sequences are very useful to process HTML text constants: While in document contents quotation marks can be encoded in HTML syntax, HTML element attributes are declared with quotation marks.):

=GRUSS "SeL strings can be delimited by <SQD> sequences!";

Stings may contain new line charactes. They are interpreted as part of the string:

=GRUSS "first line second line third line" ;

This string contains three lines. In cases like this, the closing semicolon should be written to an extra line to avoid confusion. The interpreter doesn't mind line feeds within source code. Please note that HTML browsers will not display strings as declared above with line feeds. Of course, HTML <BR> new line commands are required for this purpose.

In SeL, quotation marks always have the same meaning. The only exception are HTML triggers (see below).

Comments

The comment syntax is C like. As is C, comments may not be nested. Comments start with /*and end with */:

/* The following is a declatation of a three line string. BTW: This is a comment. */ =GRUSS "first line second line third line" ;

Comments may have arbitrary length and may contain an arbitrary number of lines.

Another way to comment source code is the "#if 0" syntax. As nesting of "/* foo */"-like comments is illegal, this (also C-like) construct allows to out-comment entire source blocks including contained comments. This is especially useful to de-activate parts of SeL code during development. It works like this:

#if 0 /* The following is a declaration of a three line string. BTW: This is a comment. */ =GRUSS "first line second line third line" ; #endif =GRUSS "Hallo";

Everything between "#if 0" and "#endif" is ignored. The source block between "#if 0" and "#endif" may have arbitrary length and may contain comments (but no "#endif" sequence!). To activate the out-commented source, 0 only has to be replaced by 1.

#if 1 /* The following is a declaration of a three line string. BTW: This is a comment. */ =GRUSS "first line second line third line" ; #endif =GRUSS "Hello";

In this case the whole code is active as if the #if construct was not there.

In contrast to C, after "#if" no other expressions are evaluated. Only "0" and "1" are legal.

Variable references

$GRUSS

This expression is replaced by the current value of the variable GRUSS.

Implicit linking of values

=NAME "Andreas"; =GRUSS "Hello, my name is "$NAME;

The value of variable GRUSS is now "Hello, my name is Andreas".

Declarations by implicit variable/value linkage can become very long and complex. Within the right side of declarations, further declarations, function calls, loops etc. may occur (these are discussed below). All these constructs return values which are included into the superior declaration. The following is an example of a complex declaration. In detail, it might be incomprehensible at this point of this reference, but it can give an impression of the possible complexity of declarations in SeL:

=c if ($a!=$b) then "not equal" else "equal" fi " " $_env("PATH") " " <SQD>Now a substring of "Hello", starting with character 1 with a length of 3 characters: </SQD> $_copy( "Hello", 1, 3 ) <SQD> The same with a length of 99 characters: </SQD> $_copy( "Hello", 1, 99 ) " Character No. 4 (should be o): " $_copy( "Hello", 4, 1 ) " Let's see where de matches uni-kassel.de: " $_match( "uni-kassel.de", "de" ) " Let's see where com matches uni-kassel.de: " $_match( "uni-kassel.de", "com" ) " Let's see where kassel matches uni-kassel.de: " $_match( "uni-kassel.de", "kassel" ) " And now again the last four characters of Hello: " =startpos $_len("Hello")-4; $_copy( "Hallo", $startpos, 999 ) ;

One last important thing: a declaration's value is an empty string:

=a "A"; =b =b1 "B1"; =b2 "B2"; ; =c $a$b;

In this example, the value of c is "A" (nothing else) because variable b only contains two declarations which return nothing (two empty strings). b1 and b2 contain non-empty strings and d is declared, but nevertheless contains an empty string ("").

Start symbols

Formally, the runtime control in SeL is probably a bit confusing. It was designed in a way that appears most natural in its application field (the creation of hierarchically designed WWW documents). At this point, let's have a look at a very simple example. Later, we will discuss the execution order of variables and functions with and without masterfiles.

Syntactically, a start symbol is a variable reference or function call followed by a dot character ("."). This is a first example of a complete SeL program:

=a "Hello "; =b "world"; =c $a$b; $c.

Here, "$c" is the start symbol. Until the start symbol, the program runs without any output. The only output of every SeL program is the value of its start symbol.

The program begins its visible execution at the expression "$c". "$c" is evaluated and expanded to "$a$b". $a is "Hello " and $b contains the value "world". Therefore, $c is "Hello World" and as $c is the start symbol, its content is returned as this SeL program's output.

Actually, a SeL program does not need a start symbol. The following example is syntactically correct:

=a "Hello "; =b "world"; =c $a$b;

This program returns as much as a C program without a main() function would: nothing. SeL programs without a start symbol are not particularly helpful :) but in some cases they can be useful, for example when the start symbol occurs in a library or the SeL program is a library itself (see below). In WWW environments this will typically be the case.

Runtime model with variables and functions

!a(void) "Hello "; !b(void) "world"; =c $a()$b(); $c.

This program generates the same output as the equivalent using variables above: "Hello world". In contrast to variable declaration (introduced by the declaration operator "=") functions are declared with the operator "!". They are called with brackets after the function name. Syntax details can be found in the section on user defined variabes below.

Here, we are interested in the runtime model. Again, at first the start symbol "$c" is evaluated, which calls the functions "a" and "b", which generate the values "Hello " and "world". So far, everything sounds pretty much like the program using plain variable declarations and the program output is the same. Now, where is the difference?

In one sentence: Variable declarations are executed immediately, wherever the interpreter finds a declaration. Functions are only evaluated when they are called. Now both programs again, this time with line numbers. Below we are going to discuss both versions' runtime and the order of line execution.

Variante A: Variablen

A1: =a "Hallo "; A2: =b "world"; A3: =c $a$b; A4: $c.

Variante B: Funktionen

B1: !a(void) "Hello "; B2: !b(void) "world"; B3: =c $a()$b(); B4: $c.

Program A runs like this: A1, A2, A3, A4. After every step the declared values can be used by the following lines. Program B runs like this: B3, B1, B2, B4. The functions are executed when called (not immediately as variable declarations). Values generated and declared within functions are only available after the function was called. On the other hand, a function is able to use values generated "below" itself, if they are available when the function is called. Variable declarations can only process values which have been assigned "above" themselves.

As a conclusion: The most secure way to write a SeL program is using functions. Under all conditions, they are more likely to work as expected. But they are a bit less handy to program and their runtime might be slower (as multiple calls will result in multiple executions whereas multiple variable references are based on single assignments). Authors who have understood this, will be able to optimize their code by replacing functions by variable assignments where it makes sense.

In SeL programs libraries are included with the command lib, e.g.:

lib "ghk.mas";

Let's examine another simple example to understand the collaboration of masterfile (library) and content file (including SeL program):

Library test.mas

fwd NAME; !main(void) "Your name is: "$NAME ; $main().

Content file test.sel

lib "test.mas"; =NAME "Andreas";

The output of the SeL program test.sel is "Your name is: Andreas". The SeL program itself contains no start symbol, but the library: "main()". This symbol is called, the referred function is executed and the string shown above is written as the program's output. It is important to understand that in this case the start symbol has to be a function! It wouldn't have worked, if if the symbol "main" had been a variable, because it would have been evaluated before a value for the symbol "NAME" was available! Only the fact that functions are executed when called allows the processing of variables which are declared later within a function.

In this case we also need a "forward" declaration (fwd) for the symbol NAME (first line in masterfile). A detailed discussion of forward declarations can be found in the following section.

It is possible (not unlike C) to include libraries in order to use functions which are not built into SeL. An example of such a library is percentbars.lib. It is part of this distribution. After including this library using the "lib" command, in the following part of the program the function $percentbar is available (please note the function name does not start with "$_" as this is not a built-in function). This function is implemented in percentbars.lib and based on function call arguments it returns HTML code, which graphic HTML browsers render as nice percent bars.

lib "percentbars.lib"; =BAR $percentbar("42","0","CENTER");

Result:

42%

Copying the form of the example library it should be easily possible for you to develop your own libraries and to share them with other users. Please document your library's syntax and functionality within a comment in the library's top part and follow the naming converntion for library variable names shown in the example: Variable names in libraries always start with "lib.", then follows the name of the library, a "." and then an arbitrary string (see percentbars.lib). If you wrote a useful library you want to share with other users and developers, you may send it to us as an eMail and we will include it into the SeL distribution and publish it (eMail addresses at the start of this Documentation).

Forward declarations

File ./test.mas Line 3: Error: Reference to undefined symbol /main/NAME at `NAME'

This is exactly the error produced after deleting the "fwd" line in the previously presented masterfile and executing it. What happend? The interpreter at first reads the SeL file test.sel and finds a "lib" command. Then it searches for the library test.mas and starts reading. At some stage, it reads the following line:

"Your name is: "$NAME

and finds a reference to the yet undeclared variable "NAME". This is not really a problem as the variable is not needed at this time. The start symbol will be called after the entire file is read. By then, the symbol "NAME" will exist. Unluckily, to translate the program, the interpreter needs a memory address for every variable name. This address is created when a variable is implicitly declared at its first value assignment. As this has not yet happened, the reference cannot be translated because at this stage the variable has never occurred to the interpreter.

Therefore, we need the "fwd" command. Using

fwd NAME;

we can instruct SeL to already create a memory address for this variable, though a value assingment will happen later. This is a declaration without an assignment which is always required before referring to a value that was assigned to a variable. Alternatively, it is possible to write:

=NAME "";

in the first line of the masterfile. This assignment of an empty string would create a valid variable as well and the error would not occur. Anyway, the "fwd" command is a bit more handy as it allows the pre-declaration of many variables with one single command:

fwd LAYOUT INDEX URL KEYWORDS TITLE AUTHOR MAILTO DATE INSTITUTION INSTLOGO ADDRESS WIDTH UPLINK HELP HELPURL SEARCH SEARCHURL REMINDER SCRIPT CONTENT LANGUAGE LOCATION ADDTOBODY;

(this is a sample of the GhK masterfile). All variable names, referred to in the masterfile, which will be declared later in the SeL file are declared with one single "fwd". "fwd", as most SeL commands, is finished with a semicolon.

If you know Turbo-Pascal, you will recognize "fwd" as a FORWARD declaration. In C there is a similar construct: the extern declaration of variables.

=GRUSS if ($NAME=="Andreas") then "Hello" else "Good morning" fi ;

To understand this example, it is essential to remember that any SeL command returns a result value. So does the "if" command. This entire "if" block evaluates to the output "Hello" if the variable NAME has the value "Andreas". Otherwise it evaluates to "Good morning". This if block retun value is then assigned to the variable GRUSS (of course, NAME must have been declared somewhere else in the program). Therefore, as most other SeL commands "if" constructs only make sense within declarations.

The else-branch is optional (not required):

=GRUSS if ($NAME=="Andreas") then "Hello" fi ;

In this case, if NAME had the content "Andreas", the value "Hello" would be assigned to GRUSS. If NAME had any other value, an empty string would be assigned to GRUSS. In the following section we will discuss a couple of operators which can be used in "if" commands.

=NUMBERS
	for (i,1,9) do
	    $i" "
	done 
;

In order to count with iterations other than 1, a fourth (optional) argument declaring the iteration (step) is required:

=NUMBERS for (i,9,1,"-2") do $i" " done ;

In this case, the string "9 7 5 3 1 " was assigned to the variable NUMBERS. "-2" has to be expressed in quotation marks which is because of a SeL error (see section on known bugs) which requires the expression of negative numeric literals in quotation marks. If the fourth argument is not given, value +1 is assumed.

Simulating a while loop with goto

=RESULT :again "loop content..." if ($repeat()!="no") then goto again fi ;

This loop will assign a value like "loop content...loop content..." to the variable RESULT until repeat() returns "no".

A position label (anchor) is defined like this:

:jumphere

Using:

goto jumphere

it is possible to jump to the label.

In order to avoid naming conflicts between user defined and builtin functions, the names of all builtin functions start with an underscore "_". By avoiding the underscore as the first character of function names, user defined and builtin function names will not collide.

Arithmetic functions

String funktions

System and file functions

HTTP functions

Miscellaneous functions

Additional Preprocessor Commands

References to invalid array elements

User defined functions

References to functions as variables

HTML-Trigger

Triggers are defined with the command html_trigger:

html_trigger tag;

whereas tag is to be replaced by the HTML (without brackets < >) tag which has to be replaced. In order to replace the tag <H1> the trigger syntax must be:

html_trigger H1;

More than one trigger may occur in a sequence of html_trigger commands:

html_trigger H1; html_trigger H2; html_trigger BODY;

For each tag which is to be replaced by an html_trigger, one or two SeL functions have to be defined. These have names of the following form:

html_start_tag( attributes )

and

html_end_tag( attributes )

whereas tag is to be replaced by the tag mentioned in the html_trigger command, e.g.:

!html_start_H1( attributes ) ... ... ;

The interpreter runs the start function when the (opening) trigger tag is found, and the end function then the closing trigger tag is found. For tags which are not followed by a closing tag (e.g. (z.B. <LI>) it should be sufficient to only define a start function. But as it is possible that user files contain non-required closing tags (which are tolerated by browsers) it is a good idea to always define an empty closing function as well.

Trigger functions are automatically called with the tag attributes as a parameter (e.g. BGCOLOR in BODY). If no attrubutes are given, the parameter string is empty.

Trigger function return values always replace the original trigger tag in the SeL source file before the compilation continues. Therefore, trigger tags can be replaced by SeL command sequences of arbitrary comlexity.

Important note:

Please note also, that SeL has no knowledge of HTML tags. Therefore trigger tags are also executed by non-standard pseudo tags and arbitrary XML tags. You may freely invent tags to trigger SeL functions.

An example for trigger usage is included in the SeL distribution as test19.sel.