5.2 Program Flow and Scoop's code structure

First things first: where is everything? Scoop is set up in a type of heirarchy, with everthing in the lib/ directory of your Scoop distribution. You'll notice 2 directories there, Bundle and Scoop, and one file, Scoop.pm. Don't worry about Bundle, unless you like messing with CPAN. Scoop.pm has all the main initialization routines, and all of the other perl modules that make up Scoop fall under the lib/Scoop directory.

The file layout within the Scoop directory is pretty easy to understand. Polls stuff is in Polls.pm and under the Polls/ directory, Comments stuff is in Comments.pm and Comments/ directory, etc. The Admin/ directory is the exception; for the most part it contains all the code for the admin tools, but it also contains stuff like user creation, story submission, and so on. Basically the kinds of ``administrative'' things that users can do.

If you're adding a new module, and it starts to get bigger than about 1000 lines, think hard about splitting it up into its own subdirectory like some of the other modules.

All of Scoop's modules have some degree of POD (run 'perldoc perldoc' if you're not familiar with POD), so a lot of information about how they work and how to use them can be gleaned from typing 'perldoc Scoop.pm' or any other .pm file.

It can be tricky to trace what happens in what order--Scoop jumps from its backend code to boxes in the database and back again many times in every page request.

To find out which function generates the |CONTENT| part of a given page, first look at what op the page is generated for--the first pseudo-directory, or `main' for the main page. In the Ops Admin Tool, the ops each have a function associated with them, and an indication of whether or not the function is a box. That function, plus the functions it may call, generates the central portion of each page. Additional code is run from box calls on the op's page template; the box name is found in the |BOX,boxname| keys.

You pretty much want to figure out where the part you're interested in is being generated (often based on some key strings in the display or, sometimes from those strings, the name of a block that's displayed) then follow the program either forward or back through Scoop's code and boxes. grep -r helps a lot with the former, and the admin tools search helps with the latter.

If you want to trace program execution, either in part or in full, ctags are handy for jumping around between subroutines in Scoop's modules and tracing program flow (in a text editor that understands ctags). From the base scoop directory: 'ctags -R lib/' will create a file called tags that your text editor can use. Add a -e flag if you use emacs.


janra
2004-03-26