$Id: 3-UnderTheHood.txt,v 1.1 2001/07/14 06:17:00 tundra Exp $
UNDER THE HOOD: COMMENTARY ON HOW HB WORKS
==========================================
The hb.py source file is full of (hopefully) helpful comments. You'll
probably get the most help from reading that source. Just so you can
kind of see the overall picture, this document is intended to give you
more of a "Thousand Foot View" of the code. At the end, I talk a bit
about some of the design decisions I made, and why.
Code Structure
--------------
The code is laid out like this:
Variables Available For User Modification
Imports
Aliases & Redefinitions
Constants & Literal Strings
Prompts & Strings Used In The Application
The Command Table
This is where all available commands are described in
tabular fashion. This is the heart of how the Command
Interpreter knows what to do when the user presses a key.
Global Variables & Data Structures
Class Definitions
Main Handler Function Definitions
There is one of these for each feature the user can
select. So there is a Main Handler for Print, Transfer,
Save, and so on.
Support Function Definitions
Functions we need to do the "housekeeping" inside HB.
Startup Code
(This is where the program actually begins execution.)
This initializes some variables and objects, loads the
default budget and generally gets things ready to go.
Command Interpreter Loop
Sits and waits for the user to key in a command and
then does something about it.
Comments On The Command Interpreter
-----------------------------------
The Command Interpreter is the most complicated part of hb.py, but
it's pretty well commented in the code. Here's the Big Picture:
Setting Up The Command Interpreter
----------------------------------
The Options table at the top of the program has a description
for each feature (like Save or Transfer) that the user can invoke.
This "description" consists of two parts:
1) The feature *name*, and the *name* of the Main Handling Function
for that feature.
2) A list (a tuple, really) of all the functions that need to
be run to gather arguments from the user in order for
the feature's Main Handling Function to actually be run.
For example, before we can run Transfer(), we have to discover
the "From Account", the "To Account", and "How Much".
When you want to add a new feature you have to:
1) Write a Main Handler Function for it
2) Write any needed Support Functions
3) Put an entry in Options for it.
These descriptions are all ***STRINGS***. Every time HB loads a new
budget, it reads these strings to dynamically construct a so-called
"Jump Table" (sometimes these are called "Dispatch Tables"). This
Jump Table is what the Command Interpreter uses to figure out what to
do when the user asks for something.
You would think that you only need to build the Jump Table once and be
done with it, but that won't work. Some features may only be available
if certain accounts are present in a given budget. For example,
Balancing an account depends on the presence of another account
named by the BALACCT variable (in the user variable section at the
top of the code). If this account is not present in a new budget,
then HB is smart enough to suppress showing that option on the toolbar.
That's why you have to build the JumpTable every time you Load a budget.
Running The Command Interpreter
-------------------------------
Here, roughly, is what the Command Intepreter is doing in pseudo-code:
If we're not done:
Display the state of the budget to the user.
Wait for the user to keyin a legitimate hotkey requesting a feature.
A blank line just means to skip it and go back to the top of this
whole Command Interpreter loop.
Use the hotkey to index into the Jump Table (a Python dictionary)
and retrieve the dispatch information for that feature.
From this dispatch information we get:
The name of the Main Handler Function that is responsible
for that feature.
The names of all the Support Functions (and their user
prompts, if any) that we have to run to build a list of
arguments to send to the Main Handler Function.
Run each of the Support Functions we found and add their return
values to args list.
Create an Invocation Record - a list consisting of two things,
a reference to the Main Handler Function, and the args we're sending
it - and push it onto the UnDo stack. We skip this step if the
requested feature was UnDo - you cannot UnDo and Undo in HB.
Now, call the Main Handler Function and pass it the args list we
just built.
Why The Two Step Process From Options-> JumpTable ->Command Interpreter?
Why Not Just Code The Jump Table Directly?
------------------------------------------------------------------------
Actually that's how I started out. I directly encoded a Jump Table
something like this:
JumpTable = {
"B" : ("<B>alance", Balance, ((BalAmount, ""),))
... And so on
}
There were several reasons I didn't like this approach:
1) Minor Issue: With a static Jump Table, I'd have to add a flag to
determine whether the feature was enabled or not (To supress things
like Balance when BALACCT is not present in the budget). Not a big
deal and, in retrospect, probably a little cleaner than the way
I ended up doing it.
2) Major Issue: Notice that in this version of reality Balance and
BalAmount are *object references* NOT strings. (A function in
Python is an object - *everything* in Python is an object. So a
function reference is really an object reference.) This means that
the JumpTable would have to appear in the code *after* these
functions were defined. (Python hates forward references - there's
probably some way around this, but I've not bothered to figure it
out.) This would have meant having literal strings in two places
in the code - at the top, where most of the literals are defined
and right after all the function definitions. I take this
Destringing and Maintenance stuff pretty seriously - it is the way
things are gonna be from here forward. Putting stuff that needs to
be changed in different places in the code it just begging for
trouble later on.
3) I wanted to play around with the 'eval' feature of Python.
It works very nicely, BTW ;))
Why Bother With All This Hocus-Pocus?
-------------------------------------
Yeah! Why not just have a bunch of nested if-elif pairs to do the same thing.
Several reasons, Grasshopper:
1) This way keeps all the literal strings out of the code. Destringing is
pretty important as the globe gets smaller and smaller. Not everyone
speaks and reads English (which is one of the reasons Python has Unicode
character support). If you code is littered with strings, translating it
to another language is a real pain and likely to be buggy. This way, every
string you may ever have to change sits happily at the top of the code
before even the first class definition. Repeat after me:
SEPARATE & ISOLATE LITERALS FROM LOGIC
SEPARATE & ISOLATE PRESENTATION FROM COMPUTATION
SEPARATE & ISOLATE DATABASE FROM DATA STORAGE INFRASTRUCTURE
SEPARATE & ISOLATE APPLICATIONS FROM SYSTEMS INFRASTRUCTURE
SEPARATE & ISOLATE SYNCHRONOUS EXECUTION SEMANTICS
The failure to do these things is why the Internet is such a buggy mess,
why scale is so hard to achieve, why security is tough to do....
(Ooops, I just regressed back into Systems Architect mode. Sorry 'bout
that, I'm all better now.)
2) Changing things and general maintenance is much simpler. It's relatively
easy to maintain a table and some functions. It is VERY painful to maintain
nested conditionals as the program logic evolves.
3) Adding new features is a snap. Try it and see. Just add a trivial feature
that, say, displays how many accounts are in the current budget. Once you
understand what's going on here, it takes about 5 minutes.
4) More structure means less bugs, means less testing (hopefully).
5) This style of event-driven, table-lookup coding is well suited for
GUIs. Someday, I'm gonna break down and learn Tkinter and/or
wxPython. When I do, this code structure should change very little.
I'll have to go to new routines for keyboard input and display, but
the rest of it should pretty much stay the same way.
tundra