Using the Subroutine Library

There are two directories in the Statistics101 installation that are intended to contain subroutines and are treated specially by Statistics101. Their names are "lib" and "ResamplingStatsSubroutines". You can store subroutines elsewhere, but these two directories are known to Statistics101 and are scanned by the program when it starts up and when you request a refresh. The directories are handled differently by Statistics101:

lib: Every subroutine in this directory is scanned by Statistics101 and added to the "Subroutines From Lib (By Name)" and the "Commands and Subroutines (By Category)" menu item lists of the Edit menu and the Edit Window Popup menu.

  • If a subroutine in lib has a one-line description (introduced by the "?" code in its NEWCMD command), then that description will appear as a tooltip on that subroutine's entry on the menus. The description will also appear in the help bar when the cursor is on a line that invokes the subroutine. Double-clicking on the help bar will open the help browser window to display the file containing the subroutine.

  • If a subroutine in lib has one or more category tags (introduced by the "@" code in its NEWCMD command), then the subroutine will be listed under those categories in the "Commands and Subroutines (By Category)" menu.

ResamplingStatsSubroutines: This directory is created in your user home directory. All the subroutines in this directory are scanned by Statistics101 but they are not added to the lists of commands and subroutines in the program's menus. This directory is for subroutines that you write. Nevertheless, all the subroutines from both directories will always appear in the Subroutine Browser, discussed below.

  • If a subroutine in ResamplingStatsSubroutines has a one-line description (introduced by the "?" code in its NEWCMD command), then that description will appear in the help bar when the cursor is on a line that invokes the subroutine. Double-clicking on the help bar will open the help browser window to display the file containing the subroutine.

  • If a subroutine in ResamplingStatsSubroutines has one or more category tags (introduced by the "@" code in its NEWCMD command), those tags will be ignored. The subroutine will not be added to either menu, "Subroutines From Lib (By Name)" or "Commands and Subroutines (By Category)", but they will be listed in the category tree in the Subroutine Browser.

If you wish, you can create subdirectories within "lib" and "ResamplingStatsSubroutines" to group your subroutine files. Statistics101 will scan all subdirectories recursively to collect the descriptive information of all the subroutines.

The Subroutine Browser

Subroutines can be written by anybody, and are therefore not integrated with Statistics101's help system as fully as are the commands. All the subroutines that are included with Statistics101 have descriptive comments just before each NEWCMD command explaining how to use the subroutine. To use a subroutine, you can read these comments to learn what it's for and how to use it, but to do that, you need to know what file the subroutine is in and then open that file and find the subroutine within it. The Subroutine Browser makes it easy to find any subroutine in lib and ResamplingStatsSubroutines along with its description and code.

There are two ways to access the Subroutine Browser. The first is via the Window>Show Subroutine Browser menu in the Statistics101 main window's menu bar (or by its equivalent keyboard function key, F5). The second is via the popup menu that appears when you right-click in the Statistics101 Edit window. If you select any subroutine name from that popup menu, the Subroutine Browser will appear and will display that subroutine's file scrolled to that subroutine's NEWCMD command.

The Subroutine Browser has three main panels as illustrated below. The left hand panel has two tabs. The "By Category" tab shows subroutines listed by their categories. The categories are set by each subroutine using the "@" keyword. (See NEWCMD.) The second tab, "By Name", lists all the subroutines alphabetically by name. The second panel, labeled "File Index", lists all the subroutines that are in the file currently being browsed. The third panel, labeled "File Contents" shows the entire file containing the declaration of a selected subroutine.


By Category Tab: This tab shows all the categories of subroutines as folders. Choose a category you are interested in. Click on the plus sign or double-click on the folder for that category to open the folder and see the names of the subroutines in that category. A subroutine may be in more than one category. Single-click on one of the subroutine names. The file containing that subroutine will display in the "File Contents" panel with that subroutine's NEWCMD command highlighted in orange. All the subroutines in that file will be listed in the File Index panel. If you pause the mouse pointer over any subroutine name, a tooltip will appear displaying the subroutine's one-line description.

By Name Tab: This tab (hidden behind the By Category tab in the above illustration) shows all the subroutines from both library directories (lib and ResamplingStatsSubroutines) alphabetically. Choose a subroutine name from the list and single-click it. The file containing that subroutine will display in the File Contents panel with that subroutine's NEWCMD command highlighted in orange. All the subroutines in that file will be listed in the File Index panel. If you pause the mouse pointer over any subroutine name, a tooltip will appear displaying the subroutine's one-line description.

File Index Panel: This panel lists all the subroutines that are in the file being displayed in the File Contents window. If you single-click on any subroutine name in the list, the file displayed in the File Contents panel will jump to that subroutine's NEWCMD in the file and highlight it in orange. Here too, if you pause the mouse pointer over any subroutine name, a tooltip will appear displaying the subroutine's one-line description.

File Contents Panel: This panel displays the full contents of a subroutine library file, which may contain any number of subroutines. You can't edit the file in the browser, but it has some powerful browsing features:

  • If you double-click on any subroutine name in the displayed file, even one that is defined in another file, the file containing that subroutine's definition will be displayed with the subroutine's NEWCMD command highlighted.

  • If you double-click on any command name in the file, the command help window will open with the help text for that command displayed.

  • If you double-click on the file path name of an INCLUDE command, that file will be loaded and displayed in the File Contents panel.

  • If you right-click over a command name, a subroutine name or a file path name of an INCLUDE command, a popup menu will appear with these options:

  • Go to <target>, where <target> is the name of the command, subroutine or file path that is under the mouse pointer when you right-clicked.

  • Back, which is an alternative to the Back button.

  • Forward, which is an alternative to the Forward button.

  • Copy, which copies any selected text into the system clipboard so you can paste it elsewhere.

You can use the Back and Forward buttons to access files that you have already viewed similarly to the way the same buttons work in an Internet browser. The location of the file currently being displayed is given in the Subroutine Browser's title bar.