This article contains information culled from the README.txt file included with the code archive.
Lots of things you don't usually need to see are deleted, e.g.:
- The qualifiers "std::", "class", "struct", "__thiscall" and "__cdecl" disappear
- Iterators are radically shortened to either just "IT", "iter", or, for a container "cont", "cont::iter" (you pick which form to use). You can then typically deduce the type details from the remaining context of error messages
- Any functors of the form less<whatever> are deleted; others are left intact. Thus the default "less<...>" functors don't clutter the messages when dealing with associative containers
- strings, istreams and ostreams of <char>, their traits, etc. reduce to just "string", "istream", "ostream", etc. Ahhh!
- iostream iterators are recognized and abbreviated
- Allocators in type names totally disappear, and allocators in function parameter lists reduce to just "alloc" (good riddance...)
Currently, all standard containers have been addressed, for the distribution version of the VC++6 library, version 3.08 of the Dinkumware library and 4.x of STLPort. Note: non-standard containers (such as Dinkumware's hash and slist) are not currently supported.
The reason I wrote this was to make it possible to teach C++ using the Koenig/Moo approach without scaring away students due to outlandishly complicated STL error messages. Thus, the filter leaves enough information to isolate the *most common* errors (wrong number of arguments, wrong argument type, etc.) in standard container operations involving most everyday data types. STL power users are always free to disable filtering to track down errors where the deleted detail is needed, then re-enable filtering when such details may no longer be needed. Two methods are provided to enable/disable filtering:
- The STLFilt.BAT file is low-bandwidth
- The STLTask tray icon program is convenient to use and allows instantaneous installation/uninstallation/reinstallation of the Proxy CL at any time, plus other nifty features such as instant filtering of a message copied into the Windows clipboard. The image provided with this article shows the STLTask context menu upon activation.
How it Works
1. Nuts and Bolts
When installed/active, the Proxy CL is found by the MSVC IDE and invoked as if it were the native CL.EXE program. The Proxy CL checks for the existence of the controlling toggle file (FILTERING.ON). If the toggle file is not detected, the Proxy CL simply invokes the native CL.EXE (usually renamed to CL2.EXE) with the same command arguments it was itself invoked with. This yields ordinary error message output.
If the toggle file is detected AND the file type being compiled qualifies for filtering, then the Proxy CL sets up an interprocess pipe between the native CL.EXE and an invocation of Perl. The native CL's output stream is then piped into the standard input of the Perl process (executing the STLFilt.pl script) to simplify STL-related messages. The output of the Perl script is then captured by the MSVC IDE and displayed in its output area, while the process status code of the native CL process controls the subsequent behavior of the IDE's build sequence.
While the command-line processing that the Proxy CL has to perform is a bit on the tricky side, it seems to now handle most MSVC-generated build scripts satisfactorily (the exception being third-party-based builds, such as when using tools such as TrueTime). The main benefit of the toggle file scheme I'm using for enabling/disabling filtering is that it does not require constant file renaming--my theory is that if major EXE files are constantly having to be renamed, that is asking for trouble.
In the early days of the filter there were several persistent bugs in the processing of MSVC-generated build scripts, so I did give STLTask (the taskbar utility) the power to install/uninstall the filter (see the description of Active/Inactive in GLOSSARY.txt) to make it easier to run native builds unencumbered by Proxy CL bugs. This installation/uninstallation copies either the Proxy CL (CL.STL) or the native CL (CL2.EXE) over CL.EXE. Because of the possibility of crashes etc. in the middle of such operations, STLTask tries real hard to make sure the files remain in a consistent state. If there is any doubt as to the current status of the filter (installed or not installed?) upon startup, STLTask resets everything to the native MSVC configuration (Proxy CL uninstalled) by default.
The CUJ Article
For background information on the origins and philosophy of this package, see my article in July, 2001 issue of The C/C++ Users Journal. The article was the Web Feature for July, 2001--that means it is now and forever available for viewing in its entirety on the CUJ web site, at http://www.cuj.com/articles/2001/0107/0107b/0107b.htm?topic=articles
Several substantive changes made to the software since the CUJ article was frozen for publication render portions of the article out-of-date. They are summarized in the README.txt file included with the archive (much of the text from that file comprises this article.)