Kernel Instructions

The original is in german. Please use the original documentation in the downloaded pack. This document should only be used to get an overview.

After starting Aleph there is a basic set of instructions (commands). These commands are essential to create programs. This set is called the kernel and should not confound with the kernel of Linux.

If the V2M is used for basic education the kernel should differ from the origin. Simply set the command after “SubEngine Interface (Java-Interface)” in the file V2M.java into comments. Feel free to create your own kernel but keep compatibility in mind.

The following paragraphs describes all commands of the kernel. Most of them have a short example. Before going inside, you have to know that the V2M is a stack machine. Every data transfer from and to functions (commands) is done via the stack.

Out- and Input

There is only one out and one input command. Because Java and V2M have conceptional roots to Forth, the output command is simply

. (dot)

Takes an object from the Top Of the Stack (TOS) and prints it to the V2M output stream; by default the console. The dot-command is consumptive, that means the object is taken away from the stack and then printed.

Really it's simply “.” the dot. Example:

3.14 .

3.14

The V2M dot command is a little smarter than the old one in Forth. If the object has a name property, the name is printed. This is normal for all commands, but there are some immediate commands (see “Flow Control”) which are translated as jump-instructions. If the object is an instance of a valuable Class (Number, String, ...) the method toString() is used. If the object is an instance of V2M internal symbols (analog to valuable Java classes) characters and strings are displayed with “ or '. If the object is none of this the output is “type(...)” where type is the class name.

.S

Displays the stack contents with TOS at first position in line.

This command is non consumptive. It is used to inform the programmer about the actual situation of the data stack. It is not for output it is only for information.

Example:

word

Takes the next sequence of characters with no white spaces and puts it as a String onto the Stack, followed by a boolean true . If there was no sequence like that, only false is on TOS.

Examples:

word 123 .S

Stack = [ true "123" ]

word

Stack = [ false ]

The last example works only if the V2M is started with the word command as the only non white space sequence. After that clear the input field and use the .S command to show the stack content.

Arithmetics

There are 4 basic arithmetic operations in the kernel. More are not necessary, because for mathematics the Math-Package of the underlying machine should be used. Whatever, these operations are a little more complex to handle all contingencies.

To give an outline to arithmetics the bit operations must be included. The following table shows the V2M-types and the usable operations:

Except the “+”-operator for strings all operations are arithmetic. Strings are concatenated with “+”. For boolean types the multiplication is allowed. It is equal to and, because booleans should be strictly set oriented and ow the quantum of a boolean set is 0 or 1. The use of “+” instead of “or” in not correct in this strong interpretation of booleans.

Examples:

3 4 5 * + . " := 3 + 4 * 5" .
newline .
3 4 5 + * . " := 3 * (4 + 5)" .

23 := 3 + 4 * 5
27 := 3 * (4 + 5)

One thing must be mentioned: There is no unary “-” for terms! Because this must be strictly oriented to the neutral element for additional operations in the actual type. The actual type is given by the vector space and matrices, complex numbers, ... are no kernel objects. The early tools for notion transformation use a “neg”-operation, but there is no kernel definition. This must be defined for he actual used vector space.

Boolean Operations

Only three boolean operations are defined in the kernel. Because this operations are defined for boolean objects and simply bit oriented objects (integers) the following examples show both.

and

true false and .
newline .
10 5 and .

false
0

or

true false or .
newline .
10 5 or .

true
15

not

true not .
newline .
10 not .

false
-11

Relations

Not all relations are usable for all types. Again a table shows the V2M-types and the usable relations:

Strings are either equal or not equal. Because unicode is used, a lexical order depends on language environment. To make definitions of lexical orders possible, single characters have complete set of relations.

Stack Manipulation

This operations provoke the first Argument against FP with the V2M.

The V2M is a stack machine! Stack manipulation implies unfunctional programming!

There is only one answer: “No!”

Because the stack is only an object and any object can be used s an argument for any function. There are no “void” returning functions per definition. Any of the following commands take the Stack as an argument and returns a new stack.

This is an attribute of all consumptive commands (most of them are). In this sense the V2M is not even functional oriented, it is strictly functional.

Here are the examples:

dup

3 4 5 .S
newline .
dup .S

Stack = [ 5 4 3 ]
Stack = [ 5 5 4 3 ]

drop

3 4 5 .S
newline .
drop .S

Stack = [ 5 4 3 ]
Stack = [ 4 3 ]

swap

3 4 5 .S
newline .
swap .S

Stack = [ 5 4 3 ]
Stack = [ 4 5 3 ]

ndup

3 4 5 .S
newline .
1 ndup .S

Stack = [ 5 4 3 ]
Stack = [ 4 5 4 3 ]

nswap

3 4 5 .S
newline .
1 nswap .S

Stack = [ 5 4 3 ]
Stack = [ 3 4 5 ]

Creative or defining Words

New commands, build of existing command are called secondaries. To create a new command the first question to be answered is: “What's the name?”. For all creative words applies a simple rule. Always the following sequence of non white space characters is the name. All creative word are compiling words and so it is impossible to use them inside a creation.

There are a special kind of other commands that only can be used inside a creation. This must be mentioned here, because the V2M executes this words immediately inside a creation. This kind of commands is attributed “immediate”.

The most used creative command is

: (colon)

Every word between colon and semicolon “;” will be compiled.

A simple example:

: Three3
 333 .
;

What happened is the following:

1. A new secondary command with the next character sequence for its name is created.

2. Get the next character sequence and compile an integer symbol into the command sequence.

3. Get the next character sequence and compile the dot command into the command sequence.

4. Get the next character sequence and stop creation.

This creation is only a synonym for 333. The only reason is to show the easiest use of the colon command. One importand thing is the semicolon. This is not a command, this is not compiled this is only a delimiter to stop compilation.

Attention!

Creations like : 3 "three" ; or : : ":" ; are problematic. At least the last one disallow all further creations.

variable

Used to contain any object.

Example:

variable var // creation
1234 put var // some content
var . // use
"XYZ" put var // some other content
var . // use

The command put is used. This is described in the next section. Importand are two things. First, the variable command creates a new entry in the V2M vocabulary, just like the colon command. Second, the created object is passive for allocation (put is the active part) and active for returning its content. Using the name of a variable, the content is pushed onto the stack.

The stored objects in the example are V2M symbols. That means identity functions of valuable objects are stored and only values are returned. This is the way to store program sequences into variables and start them only by using the name of the variable.

Flow Control

Since the structural programming paradigm flow control works without “goto” commands. So the V2M too. But here some more is scratched. There is only one loop construction, no “switch-case” and of course no labels.

if else endif

Basic conditionals in programming.

The normal notation in programming the V2M is postfix. So it might be helpful to show an example for these normally simple instructions.

Example:

: test
 if "one"
 else "no"
 endif
 . " " .
 "true word." .
;

2 3 > test

Trivial but easy to understand.

loop leave endloop

Loop constructors for any kind of loops like do-while, while-do, repeat-until, for-next.

Example:

: test_loop
 loop // index on TOS
 dup . " " . // print index and space
 dup 3 = leave // leave if limit reached
 1 + // increment index
 endloop
;
0 test_loop " done with " . .S

To realize other loop constructions, simply modify the line with the leave command. Additional an other relation should be tested.

exit

Works like the return statement in classical programming languages.

Example:

: test
 if
 "Ok, get out here!" . exit
 endif
 "Not ok something to do." .
;

true test
newline .
false test

Objects and Classes

Any class is an object in V2M terminology. So all reachable Java classes can be used as an instance or even a class. This pool is the real instruction set of the V2M. Before describing the commands an example with a very simple predefined class is helpful:

public class xyz { // CLASS

public int value = -99; // FIELD

 public void test() { // METHOD
 System.out.println( "Funktioniert!");
 }

 public int add( int a, int b) {
 return a+b;
 }
}

It is assumed that this compiled Java program is in the same directory as the V2M. So the file xyz.class is reachable without additional paths.

classify

Puts a specified class onto the stack. The class name must be at TOS.

Continued example:

"xyz" classify

Stack situation before and after the command:

Stack = [ "xyz" ]

classify

Stack = [ (class xyz) ]

To make it clear, that there is a class object and not an object called class followed by an object xyz, the .S command uses parenthesis around a class object.

instantiate

Puts an instance of a class onto the stack. The class must be at TOS.

Continuous example:

Stack = [ (class xyz) ]

instantiate

Stack = [ xyz@1385660 ]

The red colored number in the right cell is system depending. It is the physical address of the instance and is only informative.

If a special creator method is defined, this command is unable to make an instance. Please use creator and build instead of this command. This commands are described later in this section.

fetch

Makes an instance variable usable in V2M programs.

Continuous example:

"value" swap fetch

Stack situation before and after the command:

Stack = [ "value" xyz@1385660 ]

swap fetch

Stack = [ -99 ]

The fetch command is binary (two arguments are needed). The first argument (TOS) must be the instance, the second is the name of the field.

store

Stores an object from TOS into a field.

This example looks more complex,but it is easier to understand. It can be used for own experiments with classes and instances.

variable instance
"xyz" classify instantiate
put instance
1234
"value"
instance
store
"value"
instance
fetch
.S

Stack = [ 1234 ]

Here a variable is used to store an instance of the class xyz. So it is easier to keep the correct order of stack elements. For more and useful examples see the description of the simple GUI.

call

Starts a specified method of an object.

The predefined class xyz contains two methods. Both of them are called in the following examples:

"xyz" classify instantiate
"test{}" call

Funktioniert!

13 -7
"xyz" classify instantiate
"add{int int}" call 
.S

Stack = [ 6 ]

Attention – the object order differs from fetch and store.

In this examples the types must be defined. It doesn't matter if there are some arguments or not, a list must be defined in every case. The object order on the stack is from top to down, the oder in the argument list is from left to right.

creator

If a class of the sub engine has one or more special creator methods, this command must be used to get an instance.

Example:

"Window from V2M" // Title
"javax.swing.JFrame" // class name
classify // class is available
"{String}" // Type of craetor argument
creator // Creator is available

This example is part of the simple GUI description.

build

Simply uses the creator object (method) to create an instance.

A union of the last two commands is in discussion, we hope in the next version the problem is cleared.

method

Makes a name specified method permanent usable for V2M programming.

The method is started just like a variable only by name. No more statements are necessary, all arguments are taken form the stack in the correct order.

Example:

"java.lang.Math" classify
"sqrt{double}" method root

4 root .

2.0

Here a static method is used, no instantiation is necessary. If a static method from an instance is ordered, V2M always uses the class depending compilation. Though there is no reason to keep a class reference if static methods are needed.

field

Makes a name specified field permanent usable for V2M programming.

Example:

"java.lang.Math" classify
"PI" field pi
pi .

3.141592653589793

To store an object into a field defined variable, the put instead the store command is used. This is because this kind of variables are part of the V2M. Keep in mind that some typecasting could be necessary.

More Commands

There are some more commands defined in the kernel. All of then are described here. Because there is no classification for more then one this section is used.

find

Searches for a command with the same name as the string on TOS.

If found the a true flag followed by the command are pushed onto the stack. If not found, only a false flag is on TOS.

execute

The command on TOS is executed.

It is assumed that needed objects are on the stack in correct order.

symbol

Tests if the String on TOS is a V2M symbol.

If the String on TOS can be interpreted as a symbol, a true flag and the symbol are pushed onto the stack. If the string represents no symbol, only a false flag is pushed.

V2M symbols are similar to literals in other languages. Known symbols are

• Numercal character sequences are number symbols.

• Character sequences between double quotation marks are string symbols.

• Caracter(sequences) between single quotation marks are character symbols('\u00F6' as 'Ä').

• true/false are boolean symbols.

It is possible to define own symbols. To keep this symbols compatible it is necessary o use the predefined primitive _sym(...).

type (sorry it must be changed into type? Next version – promised!)

The sub-engine-type of the object on TOS is pushed as a string.

This command is only significant for development at the V2M. In practical programming it should be ignored.

(double), (float), (long), (int), (short), (byte)

Simple typecasting to make arithmetics faster.

Not useful except there are methods with strictly types. This can be useful if float JOGL-methods and double symbols are used.

commands

Lists all commands.

forget

Erases all commands from the specified to the last created.

This drastic procedure is necessary, because newer commands are build of older commands. If a single Command is erased, there could be one or more witch use the erased one.

load

Loads one or more file(s) with V2M sequences.

The files may have commands to be executed and/or to be compiled. If one of the executable commands is load the specified file will be loaded first. After that the loading of the origin file continues. There is no limit for nesting load commands.

environment

Puts a reference of the actual V2M onto TOS.

It can be seen as a synonym for self reference. This command is useful if more than one V2M instances are in use. The machines may communicate directly without pipes or something else.

newline

The most hated characters since CR/LF for end_of_line is alive.

No comment!