View source for User:Zzo38/FORTAVM

FORTAVM is a specification for a virtual machine based on Forth and Z-machine and TADS and a few other things as well. Version 0.1 of the specification is now complete (possibly there are some mistakes I haven't found yet, though). The standard libraries aren't complete yet though. But the specification should be enough to make a program out of this.

It is designed to be more powerful than [[Inform]]/[[Z-machine]], [[TADS]], [[Hugo]], and it is also more simpler to implement and other stuff. But, you might not understand how to write a program in FORTAVM if you aren't a real programmer, but someone can make other graphical interfaces as well to program it if you want to.

= Notes =
* It is Forth based, and many interpreters can be written (like it is for Z-machine).
* It is ideal for the same program to compile as to execute the compiled game file (because of the way Forth works). But if you don't like Forth, you can possibly make a different program language to compile into it instead.
* Resources (of any type) will not always be available. Some reasons might be: the player has disabled certain types of resources, the resource file does not exist, the interpreter doesn't support it, etc.
* Text is buffered (and properly word-wrapped) but some commands will force the buffer (just like <tt>$0F EMIT</tt> has been executed). Another way to force the buffer could be: <tt>INKEY DROP</tt>
* More-prompts are also automatic, but can be done manually as well. The following commands are treated as breaks where the more-prompt isn't necessary: INPUTSTR MORE-PROMPT INPUTKEY CLEAR-SCREEN
* Metadata can be stored in the story file (optional).
* Virtual key-codes are used: F1 to F7, BACKSPACE, TAB, ENTER, CLEAR, SAVE, RESTORE, RESTART, directions, TRANSCRIPT, REPEAT, UNDO, DEBUG, HELP

= Language features =
This section is based on [http://webhome.idirect.com/~dswxyz/compare.html IF Language Compare]

==Overview==

===Hello, World!===
 : MAIN OUTPUT"Q "Hello, World!" ;

===Game template===
You would start by including the standard libraries, like you do in TADS.

==Pre-processing==

===Comments===
Comments start with backslash (with a space before and after), and continue until end of that line.

===Line breaks/line conjoins===
Unimportant in most cases. Each word is separated by white-space is all that matters.

===Include files===
 INCLUDE filename

===Conditionals===
 condition [IF] statements [ELSE] statements [THEN]
This isn't a part of the VM, but can be specified by the standard libraries to do like this.

===Pragmas===
To output a message during compilation, just use OUTPUT" outside of a definition. To generate a fatal error, divide something by zero outside of a definition. Other pragmas don't exist yet but may exist in the future.

==Macros==

==Literals/Constants==

===Binary constants (Booleans)===
0 is false, -1 is true (both of which are single opcodes). You can name them by:
 0 CONSTANT FALSE
 -1 CONSTANT TRUE

===Character constants===
Use <tt>CHAR</tt> command.

===Dictionary words===
Use strings and then add to dictionary using <tt>CREATE-VOCAB</tt> command. This can be done during compile-time or during run-time.

===Integers===
Use decimal notation with no prefix (or - for negative numbers), use $ prefix for hexadecimal numbers.

===Integer range===
Signed 24-bit integers (the cell size).

===Real numbers/floating point===
No native support.

==Strings==

===String constants===
Use "Q for quoted strings. Like in PHP, single-quotes indicate no special codes in the string, while double-quotes allow special codes in the string.

===Character codes in strings===
Nothing is currently defined, although it will be in the future.

===Controls embedded in strings===
The representation in source-code is not currently defined, although it supports codes for the following:
* Capitalize next letter/lowercase next letter
* Margin adjustment (to the right or to the left, like BLOCKQUOTE in HTML)
* Word separator (breaking space, spaces are normally non-breaking unless "F is used)
* Sentence separator
* Tab
* Backspace
* Newline
* Paragraph break
* Text formatting (normal, bold, emphasis, reverse-video, room-title, input)
* Clickable texts (like A tags in HTML TADS)
* Zero-width separator (makes any character a line-break at the end of the line, normally it doesn't word-wrap)

===Variables embedded in strings===
Currently not supported, but possibly the code will work by first putting the values in stack and then using \S (for string values) and \N (for numeric values) in a double-quoted string to take it from the stack and add it into the string. The compiler will convert it to proper codes.

==Variables==

===Case-sentivity of identifiers===
Yes it is case-sensitive.

===Legal identifiers===
Any characters are legal in identifiers except for white-spaces.

===Datatypes===
On the stack only cell-size numbers and strings, but in memory you can have: cell-size numbers, byte-size (unsigned) numbers, strings, lists, objects, and you can create words to work with your own datatypes if you want to, as well.

===Predefined variables===
None, except in standard libraries.

===Reserved words===
None. Any word can be overridden to mean something else.

==Expressions/operators==

===Pre/post increment/decrement===
It might be added to the standard library. Regardless of this, you can define your own words to increment a value of a variable:
 : INCREMENT DUP @ 1+ SWAP ! ;

===Unary negation===
Decimal numbers can be written in negative in the program. To negate something else, use <tt>NEGATE</tt> command.

===Add/subtract/multiply/divide===
 a b +   a b -   a b *   a b /

===Modulo/remainder===
 a b MOD
Note: This uses real modulo where the result is positive if <tt>a</tt> is positive.

===Arrays===
You could access an array like x[y] in C by doing something like:
 x y CELLS +
FORTAVM also supports lists of variable length by using these commands:
 CAR  CDR  ENQUEUE  DEQUEUE

===Property array===
This is not directly supported, although you can still make something like this.

===Assignment===
 value variable !

===Combination assignments===
Not built-in to the VM although the standard library might support it, or you can program it yourself:
 : whateveryouwanttocallit DUP @ ROT + SWAP ! ;

===Bitwise===
 a b AND  a b XOR  a b OR  a NOT

===Instance of===
You could add a property for that if you want to, but there are other more complicated ways as well.

===Check if a property is defined for an object===
Not built-in, but possible to add.

===The property of an object===
 object property FIND-PROP
Note that properties defined by the parent but you want the object to be capable of having its own value (even if the default is the same as the parent), must be defined using <tt>ADD-PROP</tt> first.

===Accessing superclass methods===
You have to tell it which superclass you want to access the methods of.

===Boolean attributes===
Treat it just like properties containing numeric values.

===Is at/in location===
Will be part of the adventure library, but not built-in to FORTAVM directly.

===Children objects===
Will be part of the adventure library, but not built-in to FORTAVM directly.

===Logical operators===
Same as bit-wise. To force logical mode (or lazy evaluation) there are ways to do that too, but there is no built-in command for that. To do logical NOT, another way is:
 a b 0=

===Equal/not-equal===
 a b =  a b <>

===Less/less-or-equal/greater/greater-or-equal===
 a b <  a b > 0=  a b >  a b < 0=
If you don't like this, you can also define them as:
 : <= > 0= ;
 : >= < 0= ;

===Between===
Not built-in but can be defined.

===String concatenation===
 a b STRCAT

===Address of===
No operator is needed for variable addresses.

For property addresses: (note: it returns the address of the property in the parent class if it is not defined in that object)
 object property FINDPROP

For function addresses:
 ' function

===Conditional===
 condition IF truepart ELSE falsepart THEN

===Pointer dereference===
 @

==Functions==

===Statement block===
Not applicable. Separate the commands in your program with white-spaces.

===Break===
Not supported. You could define it, though, or use anonymous (lambda) functions, which also has to be defined (or might be defined in the standard library).

===Call===
Use the function name, or for a dynamic calling, use:
 address EXECUTE

===Clear screen===
 CLEAR-SCREEN

===Continue===
See comment about break statement.

===Do/while===
 BEGIN stmt cond UNTIL
 BEGIN cond WHILE stmt REPEAT

===Goto===
 GOTO label
Can also be used with functions (like it can in Perl). In the standard libraries you would define <tt>LABEL</tt> and <tt>DEFER</tt> You must DEFER all labels first before using them.

===If===
 condition IF truepart ELSE falsepart THEN

===Input===
Wait for a key:
 INPUTKEY
Input a key in real-time:
 INKEY
Input a string:
 INPUTSTR
Input a command-line for a game command:
 INPUTCMD

===Local===
Unsupported. (Support could be added in the standard library or in your own custom libraries if you wanted to, though)

===Move object===
Will be defined in standard adventure library.

===Object loops===
Can depend what you are trying to do.

===Open file===
Unsupported. It is impossible to add support using standard libraries. External resources (similar to TADS 2) are supported, though.

===Play sound/music===
 number RESOURCE

===Print===
 OUTPUT"F 'string'

===Print image/pictures===
 number RESOURCE

===Print newline===
 $0D EMIT

===Quit===
 GAME-QUIT

===Return===
 EXIT
To return a value, just do:
 value EXIT
You can return multiple values as well if you want to.

===Set attribute===
Use numeric value properties.

===Set colors===
FORTAVM doesn't use colors, it uses text-formatting, which can be assigned colors using the interpreter.
 $10 EMIT  $11 EMIT  $12 EMIT  $13 EMIT  $14 EMIT  $15 EMIT

===Set cursor position===
 $06 EMIT row EMIT column EMIT
or:
 column row $06 EMIT EMIT EMIT

==Initialization==

===Initial location===
The standard adventure library will probably define a word <tt>START-HERE</tt> to do this.

===Intro text/setup code===
You can initialize in the <tt>MAIN</tt> subroutine, some things can be initialized during compile-time as well.

==Language==

===Non-English languages===
You would have to modify the standard adventure libraries.

===Meta-verbs===
The standard adventure library should support:
 AGAIN
 BRIEF
 QUIT
 RESTART
 RESTORE
 SAVE
 SCORE
 SCRIPT
 UNDO
 VERBOSE
In addition, the standard library will support the virtual keycodes in FORTAVM for these commands:
 AGAIN (the keycode is called REPEAT)
 QUIT
 RESTART
 RESTORE
 SAVE
 SCRIPT (the keycode is called TRANSCRIPT)
 UNDO

==Output==

===Alignment===
Right-alignment is not supported. Only left-alignment is supported. Manual spacing is supported, though.

===Box quotes===
To begin a block quote:
 $03 EMIT
To end a block quote:
 $04 EMIT
Blockquotes can be nested.

===Colors===
You can't specify colors. Colors are determined by configuration in the interpreter.

===Fonts===
You can load fonts as resources, but this is not guaranteed to work. You can specify whether or not fixed-width fonts are required for this game or not. (Even if fixed-width fonts aren't required, the player can still select a fixed-width font as the default in the interpreter settings)

===Graphics===
 number RESOURCE

===Panels===
Only status-bar and main window. To set status-bar text:
 SETSTATUS

===Sound===
 number RESOURCE

===Text styles===
Normal, Bold, Emphasis, Reverse-video, Room-title, Input.

= External links =
* [http://zzo38computer.cjb.net/textadv/fortavm/ FORTAVM Specifications]

[[Category:Authoring system|Fortavm]]