[Logo] Atlantis English Documentation

Atlantis RunTime Library ver. 1.02
Written by RedHog (Egil Möller), Copyright(C), 1996 by Octagon SoftWare.

Index

Introduction

Why use Atlantis instead of other, more commonly used programming/script-languages? First, Atlantis supports functions that most of the other languages don't support, such as self-modifying functions and net-structured variables (It uses the BSP-NFD data base handler to manage variables). And second, it is a very structured and logical language, so, if you are (As I am) a logic-loveing person, you would explore that you would like this language very mush.
Ok, that's so far. What about the filosophy behind the language? In 'normal' programming/script-languages, you make a big difference between functions/procedure and variables. In Atlantis, there is no differnce, between them. If a variable contains executable Atlantis-code, you would be able to call it like a function, or a procedure, with some parameters. In fact, there are no 'functions' in Atlantis, only variables and constants (It is not only possible to execute a variable, it is also possible to execute a constant in the same way as a variable).
There is also a big difference between the way which Atlantis stores variables in the memmory and the way other languages store their variables. In all other languages I know (And I know a lots languages, but, of course, not all, so I can't be totaly shore that all of them do so), the variables is stored either as dimensions (1, 2, 3 or in some extreeme languages, in 4 dimesions) as arrays, or as a tree (As the files on a harddisk). But in Atlantis, they are stored in a net-style way. You could think of it like pages on the Internet. The only difference between the way Internet-Pages is linked to each other and the way the variables in Atlantis are linked, is that if you create a link between A and B in Atlantis, you also create a link in the opposit direction, from B to A at the same time. But if you do the same with two internet-pages, a opposit-direction-link would not automaticly be created.
An other difference is that there are no statements in Atlantis but function-call and variable asignementes, such as IF, NOT, LOOP UNTIL, WHILE-statements.

Mention variable names

As it says in the introduction, the variables in Atlantis is stored in a net-styled way. To acces a variable, you must either have its ID-number, or know a path to it. The path is relative to either yhe variable with a specific ID-number, or, if no such 'root'-variable is specified, to the 0-variable, i.e. the variable with the ID-number 0. The path is given in a format there the link from the root-variable is specified first, and then a slash (/), and the link from that variable to the next, and so on, until the variable which you want to specify. To specify a ID-number (Either as a root, or as a link), type a number-character (#) and then the number.

Examples

This will specify a variable which is pointed at by a link called 'Sir' from an other variable which is pointed at by a link called 'Name' from the 0-variable:
Name/Sir The following will specify a variable which is linked with the name 'Boat_type' from the variable with ID-number 272:
#272/Boat_Type

Roules for variable names

Variable names are allowed to include alla alpha-nbumeric characters, plus spaces and some special characters. These special characters are divided up into two groups; characters which could be placed everywhere in the name, and those who can't be plased as the firs (The begginning) character of a name.
Can be place everywhere ASCII Can't be placed as the firs character ASCII
å, Å 134, 143 (space) 32
ä, Ä 132, 142 _ 95
ö, Ö 148, 153 (Return) 13
ü, Ü 129, 154

Get a variable name from an other variable

In Atlnatis, it is possible to store the name of one variable as a value in an other one. To do so, simply put the name into a variable by a variable allotation (Type for example A := <test_var>;). When, then you want to specify the variable with that name type as following:
X := (<A>);
This will allot the value of the variable which name is stored in the variable named A to the variable with the path X. It is also possible to store a part of a variable name in a variable. Let's look at this example:
name1 := <red_hat>;
name2 := <man>;
X := the (<name2>)_s (<name1>);
That is the same as:
X := the man_s red_hat;
But why the brackets around the variable? This is becouse it is an 'Enclosed Function', se Execute a function for more information.

Constants

To specify a constant, only type the text/value it should contain, enclosed by brackets (< and >). For example, if you want to specify a constant which should contain the text 'Hello world!', you type <Hello world!>. Note that you are able to include a constant in an other constant. This is becouse you are able to use the character < and > inside a constant, but only if there are exactly the same number of < as >.

Writing the code

As in most of the common programming/script-languages, a CR/LF (ASCII 13, 10), enter soesn't affect to the execution of the program, instaed, to tell the intepreter that the line (Function call or alltation) is finnished/ended, a cemi-colon (;) is used. This mean that yue could have a CR/LF in the middle of a line, or haveing two lines on the same line in the text-editor. It is also allowed to insert a space (ASCII 32) somewhere. The only restriction to this is inside a variable path. That's becouse both the CR/LF- and the space- characters are allowed as characters in a variable link-name.

Comments

In Atlantis, in opposit to other languages, you can not have both a comment and a command (Variable allotation or function call) on the same line. But that only means that it is inpossible to have these two at tha same program-line. It is, of course, possible to have them on tha same line in the text-editor. A Comment-line is a line which beginns with an aterisk (*) and, as all other lines, end with a cemi-colon (;). Everything between these two characters is ignored by the intepreter.

Alloting values to variables

The way of alloting values or texts to variables in Atlantis is simmilar to the way you do it in Pascal. First, specify the destination-variable, then the source. Th source could either be an other variable or a constant. There should also be an 'alloting-sing' between the source and the destination. In both Pascal and Atlantis, the alloting-sign is concatenated by a colon (:) and a eaquel-sign(=), i.e. colon-eaquel (:=).

Examples

Allot the text 'Hello world!' to a variable with the path #01/Text/Test/First:
#01/Text/Test/First := <Hello world!>;

Allot the text in the variable #01/Text/Test/First (Used in the preceeding example) to the variable with the path texts/World demo/1:
texts/World demo/1 := #01/Text/Test/First;

Execute a function

As it says in the text abow, a variable and a function is the same thing in Atlantis. So, how do the system figure out if you want to allot the value of a the variable A to variable B, or, if you want to allot the result (returned) value of the function A? This problem is solved in Atlantis, by that all function-calls start with an underscore (_). So, if you, for example want to allot the returned value of the function A to the variable B, you simply type B:=_A. But that's not enought. All function-calls also need something called 'Function header'. That is the part of the function-call, which include the parameters which should be passed to the function. But there is also another part included in the header; The start/continue-parameters. In Atlantis, in oposit to in all other Languages I know, where is no 'If'-statement and no 'Repeat'-statement. Instaed, Atlantis have the start/continue-parameters. The start-parameter is a parameter wich is passed to the function. If the start-parameter is set to logical true, the function will be executed. If not, the function call will be ignored. The continue parameter is used in the same way. As long as it is set to logical true, the function will execute again and again, until it sets to logical false.
But, how does this 'function header' look? Here's the pettern for a alloting of the value returned by function A, which is runned if c is set to true, and which continues running until d is set to false , to the variable B:
B := _A[<:=c>||<:=d>];
But why is c and d enclosed by bracets? The should not be constants, they should be variables. That's becouse the are something called 'Enclosed Functions'. An Enclosed Function, is a function which does not requere neither a function haeder, nor a beginning underscore. In such a function, the last line should not be ended by the normal cemi-colon. So, that's so far. The c and d are variable-allotations. As you could se (They are started with a allotation-sign), they are allotations, but there is no variable specified wihich will be alloted the value... And that's another variation of allotation: Returning values. If there is an allotation without any variable which could be alloted the new value, the value is passed to the function which is currently running, it will return that value when it exits.
It is also possible to execute a constant. That is very usefoul when you want to repeat a specific part of a program a number of times, or if you want to run that part, only if an expression is true. To execute a constant; Atlantis use the same way as then executing a variable. First type an underscore (_), then the constant (A value enclosed by bracets (< and >)), and last, a function-header. For exmple, in the following will execute the constant four times if the variable with the path 'run_param/start' is set to true: 
Cou:=<4>;
:= _<

 *Place some usefoul code here;

 Cou := _Sub[<True>|<Cou>,<<1>>|<False>];
>[<run_param/start>||<:= _ValEaquel[<True>|<Cou>,<<0>>|<False>]>];

Passing parameters to a function

Abow, we called a function, and let it return a value to a variable. But now, we are going to do the opposit to returning values; Passing values to the function. To do so, we use the middle part of the function-header (Which is unused and empty in the abow eaxamples). Teh following will execute the function A and pass two parameters to it; one from a constant, and one from a variable with the path System/MYGE/Texts:
_A[<:=True>|<:=System/MYGE/Texts>,<:=<Hello world>>|<:=False>];
Note that the two parameters are separated by a coma. If you want more than two parameters, it is only to type them in, in the order you want them, separated by comas. Also note that all parameters is Enclosed Functions.

Event handlers

Atlantis provides something called 'Event Handlers', which only a few programming/script-languages which supports. And the most of them does not have so good functionality of their event handler system as Atlantis.
An event handler is a function which is executed if something happens in the system. For example, you could create an event handler which executes if you make changes to a specific variables value, or which executes when the user does something to a window or an object in a window (For example press a button). All event handlers executes with four parameters: System, Object, SubObject and Event. The System-parameter contains information about which part of Atlantis which coused the event, for example, sMem if it is a changeing to a variable which coused the event or sWin if the user had done something to a window or a window object. The Object then is a handle to the object which coused the event, for example if the user pressed a button in a window, the Object-parameter will contain the handle to the window. If more than one handler is needed, as in the abow example (We also need to tell the event handler the handle to the pressed button), the SubObject is used to store that handle. Note: If no more handle is needed (For example if the event was coused by the window itself), the SubObject is set to -1. The last parameter, Event, contains a number which specify what has happend to the object. For example, if a button i spressed, the Object contains a handle to the window, the SubObject contains the handle to the button, and finaly, the Event contains a value telling us that the button is just pressed (And not anyting else) Note: The meaning of a number depends on which type the object/system which coused the event is.
Until now, we haved talked about event handlers as all of them should execute everytime an event appear and that the event and the object/system is passed to each of them. That is not the hole thing. For each event handler, there is also a sort of mask, a pattern. And only the events maching this pattern will couse the event handler to run.
The pattern contains one field for each parameter which will be passed to the event handler. The first field specify which system the event should come from if the handler should run, the second specify the object, the 3d specify the subobject and the last specify the event. Note: If a field is left empty, all values will mach it.

Apendixes

Built in functions

Function name Parameters Return Description
Compairing functions
Str_Equal Text, Text Boolean Returns True if the firs parameter contains exactly the same as the second one, otherwise it returns False.
Val_Eaquel Value, Value Boolean Returns True if the value of the first parameter is the same as the value of the secon one, else it returns False. Note that if they don't include any number, they would be treated as if they contains a cero!
LongerThan Text, Text Boolean Returns True if the length of the first parameter is bigger than the lengt of the second one, else it returns False.
BiggerThan Value, Value Boolean Returns True if the value of the first parameter is bigger than the value uf the second one, else it returns False.
Logic functions
Not Boolean Boolean Returns the opposit boolean value as the parameter has, i.e, if the parameter is set to True, it returns False, and if it is set to False, it returns True.
And Boolean, Boolean Boolean Returns True if the both parameters contains True, else it returns False.
Or Boolean, Boolean Boolean If the first parameter is set to True, or the second set to True, it returns True, else it returns False. Note: If both of them is set to True, it returns False!
Mathematic functions
Add Value, Value Value Returns the value of the first parameter, plus the value of the second one.
Sub Value, Value Value Returns the value of the first parameter, minus the value of the second one.
Mult Value, Value Value Returns the two parameters, multiplied by each other.
Div Value, Value Value Returns the value of the first parameter divided by the value of the second parameter.
Exp Value, Value Value Returns the value of parameter number one ^ parameter number two.
Root Value, Value Value Returns the parameter number one -root of the value of parameter number two.
Int Value Value Returns the value of the parameter, but without it's decimals. Note: It does not return the rounded value of the parameter, just the value without any decimals.
String functions
ConCat Text, Text Text Returns the contents of the first parameter and the contents of the second one, in order after each other, i.e. it concatenate the two strings to one.
Mid Text, Value, Value Text Returns the text in the first parameter, after the character with the order number which is specified in the last parameter and as many characters as specified in the second parameter.
Length Text Value Simply returns the length of the parameter (The number of characters the parameter contains).
Link functions
CreateLink Value, Text, Value, Text Create a link between two variables which ID-number should be specified in the first and 3:d parameter. The name of the first variable (Which ID is stored in the first parameter) will be the contents of the second parameter, and the name of the second variable, would be the contents of the 4th parameter. Note: This function does not return anything usefoul.
RemoveLink Value, Text Remove the link with the name specified in the second parameter from the variable which ID-number is stored in the first parameter.
Event handler functions
Mk_eHandler Code, Handle, Handle, Handle, Value Handle Creates a event handler with the pattern stored in parameter number 2 to 5 and the code which should be executed when the event apear stored in the first parameter. If the createation succeed, it returns a handle to the event handler (Used when you want to delete the event handler), and a negative number (Normaly -1) if the createation failed.
Rm_eHandler Handle Remove the event handler with the handle specified in parameter number one.

Special characters allowed in variable names

Can be place everywhere ASCII Can't be placed as the firs character ASCII
å, Å 134, 143 (space) 32
ä, Ä 132, 142 _ 95
ö, Ö 148, 153 (Return) 13
ü, Ü 129, 154

Variable prefixes

Character Returns
(No prefix) The value of the variable, i.e. the value or string which the specified variable contains.
$ The ID-number of the variable
% List with all links between this variable and others, separated by CR/LF (ASCII 13).
_ Execute the variable and return the returning-value of the function.
* Comment. Ignore the entire line (Until the next cemi-colon (;).

License agreement for Atlantis RunTime Library ver. 1.02

First, Atlantis is not ShareWare or ComercialWare. You do not have to pay anything for its use. And you are allowed to make changes to its source-code. So is it then PublicDomain? No. It is not PublicDomain. There are a set of rules which you have to agree in if you want to use the software. Here they are:

Adresses