ARVO User Documentation 
ARVO
An AGI tool to generate "defines.txt" by John Nickerson (Mokalus of Borg), mokalus@yahoo.com.au
(c) John Nickerson (Mokalus of Borg), June 2002

-- License Agreement --
You are hereby granted the right to do whatever you like with this software and it's source code, including redistribution and alteration, on the following conditions: The author's name and contact details ( John Nickerson (Mokalus of Borg), mokalus@yahoo.com.au) are not removed or hidden. The author accepts no responsibility for any damage that may be caused to your hardware, other software, or wetware, through use of the program. No warranty is given, either express or implied, including, but not limited to, usability or fitness for a particular purpose, except where prohibited by law, and on the planet Neptune ('coz we all know what they're like about warranties). 

-- Executive Summary of License Agreement --
Go nuts, but don't bother me. 

-- Current Version --
0.9.2b


-- Using the Program --

(The file " arvo.exe" has been compiled from " arvo.py" with "py2exe", available from Starship Python, and requires "python22.dll" to run.) 
(The file " arvo.py" requires the Python interpreter, which can be downloaded for free at www.python.org for a variety of platforms.) 

The program can be run with either command-line arguments, or user input. The command-line syntax is as follows: 

arvo sourcefile [targetfile] 
where 'sourcefile' is the name of the ARVO script file, 
and 'targetfile' is the name of the file to write (defaults to "defines.txt" if not present). 
If no arguments are given on the command line, then the program will prompt for file names during execution. If you have  problems getting the program to open files, try specifying the path in full. 
There is no command for online help. 


-- Further Information/Programs --
AGI Studio: http://members.ozemail.com.au/~ptrkelly/agi/agistudio.html
The Python interpreter and language: http://www.python.org


-- Source File Format --

Scopes 


A scope is enclosed by braces {}, and is used to define separate sections of the source file, and, by extension, sections of the game. Say, for instance, you have a very short game, with two separate "chapters", and two rooms in each, which each have a couple of variables that are only relevant within that room. You might feed ARVO a source file segment like this: 
var current_chapter 
{ 
	flag night_time 
	{ 
		flag seen_owl 
	} 
	{ 
		flag tripped 
	} 
} 
{ 
	var mushrooms_found 
	{ 
		flag caught_moth 
	} 
	{ 
		var glow_worms 
	} 
} 

This would result in both "seen_owl" and "tripped" to be assigned to the same machine-level flag, because the independent scopes indicate that the use of these two flags never overlaps. 
Declarations 

A declaration is what tells the program that a variable, flag or numerical constant should have a definition in the output file. It's very simple. 
To define a variable: var my_var 
To define a flag: flag my_flag 
To define a numerical constant: const my_const 0  (where '0' can be replaced by any integer) 

Manually Setting Variable/Flag Numbers 

You can manually set the current variable or flag number with a "set" command in the source file. For example, set var 35  will make the next variable in the current or contained scope v35. Similarly, set flag 42  will make the next flag f42. 
Copy Sections 

A copy section is just a section of the source file that you want to copy directly to the target file. Any text surrounded by {% and %} will be copied, without change, to the target file. Use this feature to define names for components that are unsupported by ARVO. 
Comments 

Comments in the source file are not currently directly supported by ARVO, but you can use line comments (starting with two forward slashes: '//') within a copy section, and they will be copied to the target file, later to be ignored by your AGI compiler. 

-- Known Issues --
Braces and commands must be on lines by themselves. 
This is an issue that will be addressed in versions 1.0.0 and above, when I intend to move to a full compiler frontend. Comments are not supported directly. 
A later version will include direct support for comments, plus (probably) an option specifying whether or not to copy them to the target file. 

-- Bug Reporting --

To report a bug, please email me at mokalus@yahoo.com.au, with the following format: 
Name: 
Date: 
Program version: 
Command line used: 
Description of error: 
Error message (if any): 
