summaryrefslogtreecommitdiff
path: root/web/funnelweb/examples/0readme
blob: b75984d752999ed3af7423af9a24cd27568fb489 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171

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.                               |
+------------+---------------------------------------------------------------+

--<End of Announcement>--