A C Exceptions Package Written Using the FunnelWeb Literate Programming Tool ============================================================================ Date : 29 September 1993. Author : Ross N. Williams (ross@guest.adelaide.edu.au). Snail : 16 Lerwick Avenue, Hazelwood Park 5066, Australia. Phone : +61 8 379-9217 (24 hours). Fax : +61 8 373-4911 (24 hours). Status : This covering document is Copyright (C) Ross Williams, 1993. However, permission is granted to make and distribute verbatim copies of this document provided that this information block and copyright notice is included. ABSTRACT: This document describes the release of a C package that provides Ada-like exceptions for the C programming language. The package is written in a literate style using the FunnelWeb literate programming tool, and so acts not only as a useful C package, but also as an example of a literate program written in a commercial environment. This distribution provides enough dependent files to allow the package to be printed and used without having to install FunnelWeb. Introduction ------------ Since releasing my literate programming tool FunnelWeb over one year ago, I have been aware of the pressing need for an example program written using FunnelWeb. Despite the fact that I have written ALL my code since that time using FunnelWeb, I haven't felt motivated to release any of the code, partly because most of it is proprietary, and partly because I didn't want to have to go through the detail of extracting and shipping the header files upon which the published code would depend. Recently, however, I identified a package that I felt motivated to publish for three reasons. First, it is a package that many C programmers could find extremely useful. Second, it is a tricky package and so it demonstrates very well the benefits of literate programming without in any way being a contrived example. Third, being a low-level package, it does not depend on many other packages or header files (only my style file and a tiny assertions package). For these reasons I have decided to make the package public. I am hoping that the package will not only act as a useful piece of software for C programmers, but will also act as a flagship example for FunnelWeb and literate programming in general. Brief Package Description ------------------------- The package is written in C and provides a very clean and safe implementation of Ada-like exceptions for the C programming language. The package is implemented using the ANSI standard setjmp and longjmp functions. Here is an example of the sort of facility the package provides. The example is contrived, but gives a taste of what the package can do. The first line is the declaration of the exception and appears in the variable declaration section. EX_LOCAL(read_err,"read_err: Error reading an input file."); ... EX_BEGIN while (more_input(input)) { read_file(input,buffer); write_output(output,buffer); } EX_FORGET EX_WHEN(read_err) error_flag = TRUE; fprintf(logfile,"Read error. Aborting read."); file_close(input); EX_END A "Normal" Package ------------------ An important aspect of this publication is that this exceptions package was not in any way "polished" for publication. The exceptions package was chosen because it is a tricky package and demonstrates the use of literate programming well (other, more boring, packages are quite-rightly less-intensely documented). But apart from this aspect, the literate programming style embodied in "except.fw" is representative of the way I normally do programming, and if you looked, you would find a dozen or so similarly-prepared modules in my personal C library. In fact the exceptions package was prepared in a text editor (using FunnelWeb to generate except.h and except.c and ex_test.c) without ever generating except.tex, or printing or previewing the typeset documentation at all. The only concession made to publication was that just before publication, I typeset and printed except.tex once (just to make sure that the whole document wasn't set in italics or something :-) and subsequently corrected 23 minor grammatical and spelling errors in the documentation parts of the document before shipping. This exception package and other packages like it were constructed as part of the development of a commercial product which my company Rocksoft^tm Pty Ltd intends to release "real soon now". Thus, this exceptions package represents the practical use of FunnelWeb in a real commercial environment. How To Print The Package ------------------------ To print the package, FTP the file "except.tex" OR "except.ps" from ftp.adelaide.edu.au/pub/funnelweb/examples/except.tex (or .ps) and print out a copy of the FunnelWeb-prepared documentation. The document is 43 pages long (the actual code is much shorter). If you like what you read, you can then FTP the other files from the same directory and start using the package. You don't need FunnelWeb to print or use the package, as I have done all the FunnelWeb processing for you. The C package itself is embodied in except.h and except.c which in turn require style.h and as.h and as.c. All of these files are supplied. FunnelWeb itself is available in "ftp.adelaide.edu.au/pub/funnelweb/". Portability ----------- So far I have only compiled and tested this package on a Macintosh using THINK C. However, I expect it to be fairly portable, as I have become very aware of portability issues in the last few years, and this sensitivity should manifest itself in the code. If you do decide to FTP and compile the source code for the exceptions package, even if you do encounter one or two portability problems, the test suite provided in ex_test.c will provide assurance that the package is working. Summary of Files ---------------- The following table describes the files in the distribution. Each file is either "Source" (i.e. hand written) or was generated from another file. "except.h", "except.c", "ex_text.c", and "except.tex" were all generated by applying FunnelWeb to the file "except.fw" using the command "fw except -t". "except.ps" was generated from "except.tex" using TeX and a .dvi-to-PostScript conversion program (OzTeX/OzTeX in this case). Although the exceptions package is basically self-contained in except.fw, the code it generates is written using my normal C style and so is dependent on two external packages: my assertions package (as) and my style header file. Instead of incorporating these packages into the exceptions package, I have chosen to provide stripped down versions of these support files with the exceptions package. These two packages provide a few minor stylistic definitions. I decided not to ship FunnelWebized forms of these files because 1) I didn't want to detract attention from the main exception package, 2) they were big and messy and only part of them was required, 3) they were remenants from the non-FunnelWebized FunnelWeb source code itself, and for this reason have so far eluded FunnelWebization in my C library (i.e. FunnelWebized forms don't yet exist :-). +------------+---------------------------------------------------------------+ | Gen From | File Description | +------------+---------------------------------------------------------------+ | Source | 0README - This summary file. | | Source | as.c - Assertion package implementation file. | | Source | as.h - Assertion package specification file. | | except.fw | except.c - Exceptions package implementation file. | | Source | except.fw - FunnelWeb source file for exceptions package. | | except.fw | except.h - Exceptions package specification file. | | except.tex | except.ps - PostScript file with typeset form of except.fw | | except.fw | except.tex - TeX file containing a typeset form of except.fw. | | except.fw | ex_test.c - Test program for the exceptions package. | | Source | style.h - Style header file. | +------------+---------------------------------------------------------------+ ----