AutoClBr (auto close brackets) for TI-89/92+ by Kevin Kofler - v.2.22
=====================================================================

I) Use
This program automatically closes all open parentheses in the home screen
and in the Y= editor when pressing [ENTER] or [Diamond]+[ENTER].

Example:
--------
If you enter:
2^(3*(4+5
and press [ENTER], it will turn it to:
2^(3*(4+5))
which will evaluate correctly to 134 217 728.

II) Installation / Uninstallation

1) Installation:
To install AutoClBr, simply type autoclbr() from the home screen and press
[ENTER]. Make sure you have uninstalled any previous versions before
installing v.2.22.
Don't worry if the calculator changes the current application twice between
a short period of time during the installation process; it is required to
support the Y= editor.

2) Uninstallation:
To uninstall AutoClBr, simply use the UnInEvHk uninstaller: Type uninevhk()
from the home screen, select AutoClBr in the list of event hooks (see IV) it
displays and press [ENTER]. This uninstaller is called UnInEvHk (uninstall
event hook) because it is already common to many programs (AutoClBr,
XtraKeys, Auto Alpha-Lock Off, Dave Watson's ON Key Express and Samuel
Stearley's event hooks, including Complete) and could in the future
uninstall other memory resident (see IV) programs as well, as long as they
follow the same conventions as AutoClBr (see evhkconv.txt).

3) Emergency uninstallation:
This allows you to uninstall AutoClBr if the home screen entry line doesn't
work (if it always adds too many parentheses etc.). Note that this procedure
should NEVER EVER be necessary.
(i) Use the Var-Link menu to rename the uninevhk program to kbdprgm1.
(ii) Press [DIAMOND]+[1] to run the uninstall program.

4) Emergency uninstallation if (3) doesn't work or if there is a lockup:
Unfortunately, in this case, you will have to reset your calculator. Press
[2nd]+[Left]+[Right]+[ON] on a TI-89 or [2nd]+[Hand]+[ON] on a TI-92+. This
will cause you to LOSE all data in RAM and on old software versions also in
archive. (The newest Advanced Mathematics Software versions - 2.04 and 2.05 -
currently have the best archive recovery.)
This should NEVER EVEN happen. I'm really sorry if this should happen. Note
that I cannot assume legal responsibility for data loss (see section VI.a).

III) History

Current version:
v.2.22: Recompiled with v.1.12 of my HW2 AMS 2.0x TSR Support, which fixes
        support for the TI-89 Titanium.

Previous versions:
v.1.00: This version was the first public release.
v.1.01: * This fixes a bug where AutoClBr crashed when not enough RAM was
          available. (Thanks to the TI Chess Team for their oncalc tool for
          simulating low mem conditions, which is part of the TIGCC Tools
          Suite and which allowed me to become aware of this bug.)
        * It also fixes the incompatibility with TeOS. (Thanks to GuiYom for
          reporting this.) (TeOS directly reads the event structure from a2
          instead of popping it from a7, which is not conform with TI's
          calling convention. AutoClBr now copies the pointer to a2 before
          calling the previous event hook.)
        I hope AutoClBr is now finally "idiot-proof".
v.1.02: Bugfix: This release uses the correct keycode for DIAMOND+ENTER on a
        TI-92+, so this keypress will now also be recognized on the TI-92+.
        (This bug was non-fatal, but AutoClBr 1.01 didn't do anything if
        DIAMOND+ENTER was used on a TI-92+.)
v.1.03: * Now really runs stable on HW2 with AMS 2.0x and without HW2Patch.
        * Added support for AMS 2.02.
v.1.04: Recompiled with v.1.01 of my HW2 AMS 2.0x TSR Support, a bugfixed
        version which does not install itself on patched HW2, where it is
        not needed.
v.2.00: * Added support for the Y= editor
        * Added support for the store arrow character (->): The parentheses
          will be closed both before and after the store character. For
          example,
          2^(3*(4+5->#("x"&"y"
          will be turned into:
          2^(3*(4+5))->#("x"&"y")
        * Fixed an initialization bug (which activated itself when sending
          AutoClBr from a calculator with AMS 1.05 or higher to one with AMS
          1.00 or 1.01 after running it unarchived)
        * Internal change: Using now official ROM calls to add the closing
                           parentheses
v.2.01: * Removed a redundant (useless) call to HeapLock in the installer.
        * Recompiled with v.1.02 of my HW2 AMS 2.0x TSR Support, which
          fixes a nasty bug which might cause random crashes or corrupt the
          mathematical functions of the calculator. If you are using HW2
          with AMS 2.0x and WITHOUT HW2Patch, and if you had installed
          v.1.03-2.00 of AutoClBr, then I strongly recommend you to reset
          your calculator before updating. I am really sorry for this. Read
          h220xtsr.txt for information about how to update without
          resetting (NOT recommended!).
v.2.10: * Added support for the colon (:) character: The parentheses will
          now also be closed before a colon (except if it is in a string).
        * Fixed a bug which caused AutoClBr to falsely treat AMS 1.00 and
          1.01 as "incompatible". Thanks to Alkher for reporting this.
        * The package now includes the updated version 2.02 of the UnInEvHk
          event hook uninstaller, which fixes a memory leak bug when running
          UnInEvHk without a compatible event hook installed.
v.2.11: Recompiled with v.1.03 of the HW2 AMS 2 TSR support, which fixes a
        crash bug when changing the batteries of the calculator. This crash
        bug ONLY affects HW2 calculators with AMS 2 and WITHOUT the HW2Patch.
        See h220xtsr.txt for more information about this bug. To upgrade, the
        most straightforward way is to uninstall and reinstall AutoClBr, as
        explained in section II.
v.2.12: Recompiled with v.1.04 of the HW2 AMS 2 TSR support, which fixes a
        few minor problems. This ONLY affects HW2 calculators with AMS 2 and
        WITHOUT the HW2Patch. See h220xtsr.txt for more information about the
        HW2 AMS 2 TSR support. To upgrade, the most straightforward way is
        to uninstall and reinstall AutoClBr, as explained in section II.
v.2.13: Recompiled with v.1.05 of the HW2 AMS 2 TSR support, which fixes an
        upgrading problem. This ONLY affects HW2 calculators with AMS 2 and
        WITHOUT the HW2Patch. See h220xtsr.txt for more information about the
        HW2 AMS 2 TSR support. To upgrade, the most straightforward way is
        to uninstall and reinstall AutoClBr, as explained in section II. If
        you had problems installing AutoClBr 2.11-2.12 or upgrading from
        v.2.11 to v.2.12, try again now.
v.2.13a: Recompiled with v.1.05a of the HW2 AMS 2 TSR support, which fixes a
         minor glitch which could happen very rarely during installation.
         Note that you need NOT upgrade if you are using v.2.13, since this
         problem could only happen during installation. There were NO changes
         in the memory resident part.
v.2.20: * Added support for AMS 2.07 and the Voyage 200.
        * Recompiled with v.1.10 of the HW2 AMS 2 TSR support, which adds
          support for AMS 2.07.
        * The program now returns to the home screen rather than to the icon
          desktop on AMS 2.07.
        * Using now AMS-independent methods to detect the required memory
          addresses. Thanks to Samuel Stearley for one of the 2 required
          routines. Exotic (for example AMS 2.00) and future AMS versions
          should now (hopefully) be supported without changes.
v.2.21: Recompiled with v.1.11 of my HW2 AMS 2.0x TSR Support, which fixes
        a bug.
v.2.21a: * Recompiled with v.1.11a of my HW2 AMS 2.0x TSR Support, which adds
           support for the TI-89 Titanium.
         * The package now includes the updated version 4.00 of the UnInEvHk
           event hook uninstaller, which adds support for the TI-89 Titanium.
         * Added _nostub comments.
         * Note that you need NOT upgrade if you are using v.2.21, since this
           is an update of the installation routine only. There were NO
           changes in the memory-resident part.

IV) How AutoClBr works

It is a TSR (terminate but stay resident) program, which installs itself in
a higher zone (at the end) of the RAM (using the HeapAllocHigh function).
This means: it will be active after installation even after returning to the
home screen and it should not consume any system memory (the RAM wich is used
for calculations), which is located the lower RAM zones (at the beginning).
It installs an event hook which captures all events, but without disabling
TI's event handling routine. In case of other installed event hooks, the
AutoClBr event handler calls them after having processed the event. The event
handler only processes the CM_KEYPRESS event with the keys [ENTER] and
[diamond]-[ENTER]. All other calls are simply ignored. It then checks if the
home screen or the Y= editor is active, and if one of them is, it counts the
number of parentheses left open and closes them automatically. The counting
is very complicated because AutoClBr has to ignore parentheses located in
strings, but take in account those located between DMS (degrees, minutes,
seconds) numbers, which use quotes as a sign for seconds. The automatic
closing has to be done in 2 parts: AutoClBr has to move the cursor at the end
of the entry line or before the store arrow character and to insert the
closing parentheses by sending a CM_STRING event to the running application.

This program uses and includes my TI-89/92+/V200 Hardware 2.00 AMS 2.0x TSR
support v.1.12 in its installation routine. See h220xtsr.txt for details
about it. It is installed ONLY on HW2 with AMS 2.0x and without HW2Patch.

The program size is about 2 1/2 KB:
- 1 1/2 KB installing routine
- 1 KB memory resident routine

V) Bugs

There are currently NO known bugs.
I had to add a huge detection routine for DMS (degrees, minutes, seconds)
numbers because of TI using the same character for quotes and for seconds.
That routine is the reason of the relatively large size (about 3 KB for the
file, about 1 KB kept in RAM after installation) for a program which seems
quite simple. However, this was necessary in order to fix all bugs (actually
rather "missing features" than "bugs", but the effect is the one of a bug)
with DMS numbers which were in my private test versions.
If you have to report a bug to me, see section VIII. PLEASE report any bugs
you find, or else I cannot correct them.

VI) License

The following is the minimum of legal sentences I have to write to avoid
getting into trouble:

-----------------------------------------------------------------------------

Kevin Kofler's TI-89 Program License
====================================

This license applies to all TI-89 programs by Kevin Kofler, unless otherwise
stated. Note that CHEMISLV is NOT an exception since the following is a
generalized copy of the CHEMISLV-License (readme point 8).

a.I CAN'T BE HELD RESPONSIBLE FOR ANYTHING! NO WARRANTY!
b.YOU CAN'T SELL MY PROGRAM OR CLAIM IT IS YOURS!
c.IF YOU TRANSMIT ONLY PARTS OF THIS PROGRAM, YOU MUST SAY THAT IT'S A PART
  OF THE (package name) PACKAGE AND ONLY A PART!
d.NORMAL RIGHT APPLIES TO THE THINGS I'VE FORGOTTEN!

-----------------------------------------------------------------------------

If anything is not clear, just ask me for my permission (notably for matters
of distribution on websites and/or modified versions).

VII) Credits

Thanks to:
* The TIGCC Team (http://tigcc.ticalc.org) for TIGCC. Especially:
  - Zeljko Juric for documenting some important operating system functions
  - Sebastian Reichelt for the TI-GCC IDE (integrated developer environment),
    which was used for this program
* Samuel Stearley for his help and his suggestions
* Rusty Wagner for the Virtual TI emulator
* Brian Anderson, Charlie Gibbs and David Ellsworth for the A68K assembler
* Paul Froissart and Julien Muchembled for helping me maintain the current
  versions of the A68k assembler
* my beta-tester Williewien for testing the program (v.1.00)

VIII) Contact me

Homepage: http://kevinkofler.cjb.net or
          http://members.chello.at/gerhard.kofler/kevin/
E-Mail: kevin.kofler@chello.at or Kevin@tigcc.ticalc.org