Basic To Application Converter v0.5 for the TI-83+
Coded by Greg Femec

  This program is a conversion tool that generates assembly code from TI-Basic with the hope of providing faster execution.   
Instead of parsing the program on the fly like the onboard TI-Basic interpreter, this program pre-parses expressions and commands.  
Faster execution comes at the expense of size.  A compression tool is provided but requires additional time to generate the code.  
Multi-page application support is a possibility for the future but not likely.  This early build contains support for fundamental 
basic commands and has the possibility to be expanded to include more advanced functions. The nature of the converter requires that
the basic program be written literally.  Ways of reducing the size of a basic program by removing unnecessary characters make no
impact on the size of the generated code and may prevent conversion.  Before compiling your basic code please read the list of 
supported basic syntax and check your program does not use an unsupported function.

Instructions:
	1. You need to have a compiler installed.  "ZiLOG Developer Studio" is free at
	http://www.zilog.com/tools/software.asp (scroll past ZiLOG Developer Studio 2).
	2. To test your code you need the TI-83 Plus SDK.  This is available on TI's web
	site. If you want to take programs off your calculator you also need linking software
	and TI-GRAPH LINK. Go to "http://education.ti.com".  (You may need to create an 
	account to download files.)  Click on Downloads.  Scroll down and select "Pick-Up 
	Window" on the right.  The SDK is under Free SDK.  In Free Computer Software you
	can select TI-GRAPH LINK for the 83+.  Follow the instructions and install the software.
	3. Run the installer (setup.exe) for "Basic to Application Converter".  After it is installed
	you can delete the folder it came in.  The Read Me is also in the program directory.
	4. Open the program you wish to convert in TI-GRAPH LINK.
	5. Run "Basic to Application Converter" then copy and paste your program from TI-GRAPH LINK
	into "Basic to Application Converter".
	6. Type in a Program Name, select Compressed or Not Compressed (don't compress
	unless you have to), and press Compile.
	7. If you have lists or matrices in your program you will be prompted to input
	their default settings.  (See Differences Between Basic and Assembly)
	8. Compiling should be quick unless the program is being compressed.  When finished
	save you application code.  (Because building the project requires the TI-83+ include file
	it is recommended that you save it in the "Projects" directory created during installation.)
	9. If you are using ZiLOG Developer Studio, press Save ZiLOG Project and select the
	application code you just saved.
	10. Close "Basic to Application Converter" and open the new ZiLOG project (.zws) with the
	same name as your program (in the Projects folder).
	11. If the Invalid Emulator message appears select ok, then build the ZiLOG project (press F7).
	12. If an error occurs check your basic code for unsupported characters, function usage, ect.
	13. Now you have a application (.hex) file.  To test it using the TI-83 Plus Flash Debugger
	run the debugger, create a new file, chose your calculator, and load the .hex file.  Run the simulation
	and do a thorough test run of your application.  (The speed of the simulation is dependent on your
	computer.  I have a dual-core Pentium D running at 2.8 and my calculator is still faster than the
	simulations.)
	14. You can turn the .hex file into an signed application with TI's Wappsign (installed with
	the TI-83 Plus Flash Debugger).  Make sure you use the 0104 key (included).
	15. Once signed and tested, your application is ready for use.

Errors:
	Don't be surprised if you get an error in the converter or when testing.  This is the first release
	and is bound to have many problems.  If you receive a error message when converting you will have to fix
	the code before you try to test the application.  Many errors you may encounter are due to the nature
	of the converter.  For example, in Basic you can have a jump that goes to nowhere as long as you never try
	to execute it.  That won't work in the converter, speed is gained by pre-compiling the basic code and the
	converter can't tell what statements will end up being executed.  Along those same lines, all loops must
	have a corresponding "End" statement even if they will never be reached.  Some unrecognized errors could
	be a result of black lines or commands such as "Pause " without the final space.  If you have checked your
	program and read this entire file and still can't figure out the problem, it is likely you have found a bug.  I
	would appreciate an email so I can fix it for future editions.  If you ask for a capability that is not
	currently available be sure to tell me why it would be useful.

Differences Between Basic and Assembly:
	1. The main differences between basic and assembly are speed and size.  Converted assembly programs
	are much larger and, on average, twice as fast as their basic counterparts.  Because of the way
	applications are handled on the TI-83+ the size of all single page applications in memory is the same.
	Because this converter does not support multi-paged applications, your application must fit inside one
	page.  Most basic programs fit just fine.  If yours is too big you can try the compressing tool provided.
	It recognizes redundant code and condenses it.

	2. While Basic can handle reading a value from a variable that doesn't exist, assembly can't.  Therefore,
	all variables are initialized before execution.  That means values in variables are usually not passed into
	the application from outside.  There are some exceptions.  All pictures and some lists and matrices are
	only initialized if they don't exist.  If you use lists or matrices you will be prompted to enter the dimensions
	they are to start with and if you want them initialized at the start.  If you select no then that
	variable will not be altered when the program starts (if it exists).  Because you have already selected the
	dimensions of regular lists and matrices you do not need to have Basic code setting them unless you have chosen
	not to initialize one of them.  If you have, you need to include a basic statement setting the dimension for that
	one (or ones) to ensure it is the right size.

	Example: To compile "Indy500" I chose not to initialize the high score custom-list because I wanted
	it to be saved between executions.  In the program is a statement setting the dimension of that list.
	1dim(INDY)

	3. Characters that can be displayed and used in string constants are limited.
		Character set: A-Z, a-z, 0-9, " "
		+ - / * , " [ ] { } ( ) ! .   = < >    ' ?   ^       | \ ~ ;   

	4. When the application starts the home screen is cleared and when the application finishes the home screen is
	cleared.  Therefore, if you want the user to see a line your program displays just before it ends, you need to
	have a "Pause " statement before the end.

	5. Automatic power down can only occur when the program is waiting for user input.

	6. Subroutines are not supported.  All the code to be converted must be in the main program.
	
	7. There is no friendly error handler.  If your program encounters an error it likely will crash the calculator.
	YOU MUST TEST YOUR PROGRAMS BEFORE DESTRIBUTING!  One error that is not necessarily your fault is a memory error
	when there is not enough RAM left on the calculator to create the variables.  This usually results in a harmless exiting
	of the application.


Basic Code Supported: To help in determining what the converter can handle, I have encluded two examples of applications
	created by the converter and the Basic code they came from.

-Variables
   Numeric: A-Z and Theta
   Lists: 1-6
   Matrices: A-J
   Custom Named Lists
   Strings: 0-9
   Pictures: 0-9
   System: Xmin,Xmax,Ymin,Ymax
   Answer: Ans
-Arithmetic
   addition, subtraction, multiplication, division, square, cube, factorial, reciprocal
-Logic
   and, or, xor, not(
-Comparisions
   =,<,>,,,
-Constants
   String: "..."
   List: {...}
   Matrix: [[...]...]
Note: Matrix constants can be huge in assembly.
-Other
   Parenthesis
   Store as: 


-Functions and accepted numbers of arguments

function([number of arguments]) : description 
_____________________________________________
     dim([1]) : can be used to read the dimension(s) of an list or matrix
              : can also be used to set the dimension(s) of an array or matrix
     min([2]) : returns the minimum of two numbers
     min([1]) : returns the minimum of a list
     max([2]) : returns the maximum of two numbers
     max([1]) : returns the maximum of a list
     lcm([2]) : returns the lowest common multiple of two numbers
     gcd([2]) : returns the greatest common denominator of two numbers
     abs([1]) : returns the absolute value of a number
   iPart([1]) : returns the integer component of a number (truncates it)
   fPart([1]) : returns the fraction component of a number   
     sin([1]) : returns the sine of a number
     cos([1]) : returns the cosine of a number
     tan([1]) : returns the tangent of a number
     log([1]) : returns the logarithm of a number
      ln([1]) : returns the natural logarithm of a number
    sin([1]) : returns the arc sine of a number
    cos([1]) : returns the arc cosine of a number
    tan([1]) : returns the arc tangent of a number
       ([1]) : returns the square root of a number
      ^([1]) : returns ten raised to a number
      ^([1]) : returns the constant e raised to a number
         rand : returns a random number between 1 and 0
 randInt([2]) : returns a random integer between two numbers
     sum([1]) : returns the sum of all the elements of a list
     sum([3]) : returns the sum of three numbers
     int([1]) : returns the integer closest to zero not farther than 1 away from a number
inString([2]) : searches a string for a substring and returns the index where it is found
     sub([3]) : returns a sub-string starting at an index and with a size
pxl-Test([2]) : returns true if the pixel specified by the coordinates is on

-Program Structures

 -"If" structures
    1. Simple construction: only a Then case with one statement, no use of "Then",
 	"Else", or "End"
	
	If [condition]
	action (only one line!)

    2. Traditional construction: "If ", "Then", "Else", "End" set up. ("Else" optional)
	
	If [condition]
	Then
 	...
	[actions]
	...
	Else
	...
	[actions]
	...
	End

	[or]

	If [condition]
	Then
 	...
	[actions]
	...
	End

  -"While " Loop: simple loop that first evaluates the condition before any iterations
 	are preformed
	
	While [condition]
	...
	[actions]
	...
	End
  
  -"Repeat " Loop: simple loop that first evaluates the condition after one iteration
 	is preformed
	
	Repeat [condition]
	...
	[actions]
	...
	End

  -"For(" Loop: loops until a variable's value is out of the range specified. The
 	variable's value starts at the first value and changes after every
	iteration by the last value. If the last value is not specified it is
	assumed to be 1, independent of the range.
	
	For([variable (numeric)],[starting value],[ending value],[value to add to the
		variable after every iteration])
 	...
	[actions]
	...
	End

	Note: the program may not jump into the middle of a "For(" loop.

  -"Lbl " marker: tags this line so the program may use a "Goto " statement to jump to
 	it referencing its label (an arrangement of characters).
	
	Lbl [label]

  -"Goto " jump: jumps execution of the program to the line with the "Lbl " marker
 	with the corresponding label.

	Goto [label]

-User Input

  -"Pause ": pauses execution until a key is pressed

  -"getKey": returns the key code of the last key pressed (not totally responsive yet)

  -"Menu(" interface: creates a menu onscreen with up to seven entries with 
	corresponding labels.  When the user selects a corresponding number the 
	program jumps to the line with the entry's label.

	Menu([title],[entry 1],[label 1],[entry 2] [label 2], ... )

	Note: The user can only select an option by entering the corresponding number.

  -"Input ": Lets the user to enter information that is then stored to a variable.
	The string preceding the variable will be displayed ("?" if no string). This
	interface only allows the user to type until the bottom of the screen so be
	sure to leave enough room.  While typing the user can clear all the input or 
	backspace one character.  The input will be stored as a string or a number.
	Valid characters include capital letters, numbers, " ", ".", and "".

	Input [string],[variable]

  -"Prompt ": Functions similarly to "Input " except the string displayed is the
	variable's name + "=?".  This function accepts multiple arguments.

	Prompt [variable](,[variable],[variable]...)

-Display Routines
	The current set up does not support a graphing environment.  Most of the
	commands from the graphing and drawing environment are still useable but it is
	not treated as a separate screen.  This should not create many problems. Just
	be sure to clear the main screen when appropriate.

  -"Disp ": Prints to a new line an expression (string or number).  This function
	accepts multiple arguments.
	
	Disp [expression](,[expression],[expression]...)

	Note: Disp "" will just create a new line (as it does in Basic).

  -"ClrHome": Clears the screen.

	ClrHome

	Note: "ClrDraw" is also supported but does not do anything more.

  -"Output(": Displays and expression starting at the specified row and column.

	Output([row],[column],[expression])

  -"Line(": Draws a line between two points.

	Line([X coordinate 1],[Y coordinate 1],[X coordinate 2],[Y coordinate 2])

  -"Horizontal ": Draws a horizontal line at a Y value.

	Horizontal [Y Value]

  -"Vertical ": Draws a vertical line at a X value.

	Vertical [X Value]

  -"Circle(": Draws a circle with center at a point and a defined radius.

	Circle([X coordinate],[Y coordinate],[radius])

  -"Text(": Displays an expression at a pixel position in the small font.

	Text([pixel row],[pixel column],[expression])

  -"Pt-On("
  -"Pt-Off("
  -"Pt-Change(": These routines modify points defined by X and Y coordinates.

	Pt-On([X coordinate],[Y coordinate])

	Note: Examples for the others are similar.

  -"Pxl-On("
  -"Pxl-Off("
  -"Pxl-Change(": These routines modify pixels defined by a pixel location.

	Pxl-On([pixel row],[pixel column])

	Note: Examples for the others are similar.

  -"StorePic ": Copies the current screen to a picture variable.

	StorePic [picture variable]

  -"RecallPic ": Copies the contents of a picture variable to the screen.

	RecallPic [picture variable]

  -"AxesOn": Turns the Axes on and redraws the screen (erases any drawing).

	AxesOn

  -"AxesOff": Turns the Axes off and redraws the screen.

	AxesOff

  -"FnOn ": Turns all functions on and redraws the screen.

	FnOn 

  -"FnOff ": Turns all functions off and redraws the screen.

	FnOff 

  Note: When setting the display window limits the screen is also redrawn.

-Miselcaneous

  -"DelVar ": Deletes a variable.  This routine is provided but should be
	used with caution.  After deleting a variable it is likely the
	program will not be able to access it again until it is run again.
	Only delete if you are sure you will never use the variable again.

	DelVar [variable]

  -"Radian": Sets the system to do trigonometry in radians.

	Radian

  -"Degree": Sets the system to do trigonometry in degrees.

	Degree

  -"Stop": Ends the program.

	Stop

	Note: (All programs will also end after the last line is executed.)

Disclaimer: This is free-ware.  There is no guarantee that it will work or that it will not harm your equipment.











