Gold Fish 3/goldfish_volume_3.bin/files/dev/e/stderr/stderr.doc

Text File | 1994-09-11 | 8KB | 215 lines

StdErr.m
A Standard Error Port for Amiga E by Trey Van Riper (Cheese
Olfactory Workshop).

0. DESCRIPTION

StdErr.m provides Amiga E users with an easy-to-use standard
error port for their Amiga E programs.  The module is fairly
intelligent, handling things with a kind of grace and ease
anyone could hope for.  You almost cannot foul the use of
this program module up (almost).

1. HOW TO USE

Firstly, you need Amiga E v3.0 or greater (since this IS a
module).  Then, of course, you need an Amiga, and an idea
for a program you want to write.

NOTE: For those users using previous version of Amiga E,
there's an archive floating around called StdErrUpd2.lha.
This archive isn't quite as nice as this, but it's as nice
an item as could be created with previous versions of Amiga
E.  You'll need EPP to best use that version of StdErr.

At the end of your PROC main(), make sure you call
'err_Dispose()' so you'll free up anything that StdErr might
have opened up (files, for example).  It's at this time that
Workbench progs will also get their little prompt saying to
press RETURN to close the error window (if appropriate).

Then, whenever your program seems to have found an error,
call 'err_WriteF()' (more details coming up).  There is one
minor caveat, though... there are three kinds of errors
StdErr might come up with on its own... "OPEN", "FILE", and
"MEM".  These errors come up as exceptions, so I would
advise against using StdErr in EXCEPT handling, unless you
know what you're doing.  Frankly, I've been using StdErr in
my exceptions without any trouble.. I'm just thinking of
potential problems.

Of course, I wasn't satisfied to have StdErr work TOO
simply.. so I gave it so many bells and whistles that you
won't WANT to use anything else.  This module should be
included in every program you write, it's so simple to use.

Here's some details:

1.1. PROC err_New(filename=NIL)

This PROC allows you to direct errors to a particular file.
If 'filename' is 0, the stderr port is used (CONSOLE:, for
the curious).  If 'filename' := stdout, further error
reports are put to stdout.  If 'filename' is a pointer to
text, the file of that name will be created (if there's an
error), and text will be appended to it.

If no arguments are passed to err_New(), 'filename' will be
assumed to be 0.

1.2. PROC err_Name(program_name)

This PROC lets you change which name StdErr calls your
program by.  This is used for stderr output to a file, and
for Fault routines (if IoErr() is non-zero, StdErr
automagically prints the associated text for the error).

If 'program_name' is omitted, 'StdErr' is assumed.

1.3. PROC err_Dispose()

You must use this PROC at the end of your program.. if you
don't, funky ugly things will happen.  I wish I could have
automated this, but I cannot.. you'll have to remember to do
this yourself.  This procedure only needs to be called at
the end of the program, unless you're doing something really
peculiar.  It'll tell WB users how to close the window, and
it will close down open filehandles.

1.4. PROC err_WriteF(format,items)

The main PROC... this is the biggie.  You may use this PROC
anytime before err_Dispose().  The 'format' is the same as
any WriteF statement, but 'items' needs to be enclosed in
'[]'s or the statement won't work correctly (eg.
err_WriteF('Big Time Screwup in \s\n',[procname]).  If
IoErr() is set prior to invoking this function, a nice
Fault() will be printed to StdErr automatically.

Note that 'items' can be left out (eg,
"err_WriteF(format)"), as can 'format' (eg. err_WriteF()).
Calling err_WriteF() without arguments will essentially make
StdErr test IoErr() for a value, and Fault() the results to
the user... kinda slick, really.

2. REGISTRATION/DISTRIBUTION INFORMATION

This code is given freely to the E programming community
(even if, somehow, you manage to find a way to make use of
it on other platforms.. I don't care).  All I ask is that
I'm credited with the routines.. nothing more, nothing less.
I didn't spend a TREMENDOUS amount of time on it, but I DID
spend some time, and concerning some of the meticulous care
I placed in this project, I feel I have at least earned
credit for its creation.

So.. I don't care if you're selling your product
commercially, shareware, or just making a freeware project,
feel free to use this as long as I'm credited.

I WILL limit distribution of this in one way: it may not be
altered.  Feel free to spread this module literally all over
the world, but do NOT alter the documentation or the
routines themselves as you pass them on.  If you want to
create your own stderr module, feel free to take credit for
it, but I only want to take credit for my own work.  If your
work is based strongly on my own, feel free to credit me,
but clearly indicate where you've made alterations, and
spread a separate version (claiming responsibility for your
alterations).

3. WORD TO THE UNWISE

If you decide to use these routines, have a care to the user
you're about to assault.  Some folks want to be able to
redirect information to a file or something.. they don't
take very well to someone writing a program that writes to a
stderr port for such frivolous reasons as 'Well, I had this
really k00l ANSI file I wanted to dump on the screen, and I
didn't want anyone to redirect it.'

Standard error ports are intended to be just that.. 'error'
ports.  You're trying to give information regarding an
error.. something most people want to be able to see in
something like a separate filehandle on the console.
Fortunately, most Amiga E programmers I've seen seem to
really respect that, so I don't mind providing something
like this for them.  But when Amiga E finally starts to hit
it big, I really don't want folks to use StdErr to do stupid
pranks.  Be kind.  Be gentle.  Be a pal.  Be a PROGRAMMER!

4. ACKNOWLEDGMENTS

I'd like to thank Barry Wills for providing EE (a very nice
editor, especially the folding.. I look forward to being
able to use it more reliably on my poor ol' 68000), and for
complementing me on this small project.

I'd also like to thank Wouter van [Insert Long Name Here]
for writing Amiga E.  Now that E is Object Oriented, I feel
much happier about using this new Object Oriented Standard
Error port (basically, it frees up yet another variable name
I can use to my own demented ends).  This man has done a
FINE job on an excellent programming language I can only
begin to tap.

5. COMMENTS/HOSTILITY/LETTERS OF ADORATION/TERMS OF ENDEARMENT

Currently, I'm available at the following E-mail address, in
order of preference/reliability:

[e-mail]
[e-mail]
[e-mail]

I can also be written to via snail-mail:

Trey Van Riper
19-A Dortch Ave.
Asheville, NC 28801
USA

You may correspond in English (my best language), French,
American Sign Language, Esperanto, and Latin (note, any
language other than English may get unpredictable
results/responses from me, as my vocabulary is rather weak
in everything except English.. also, if you somehow manage
to communicate to me in ASL, I'll be rather surprised..
especially if it's via mail).  Sorry other languages aren't
supported, but I can only learn so many at a time.

The above information should be good until around the summer
of 1995, at which time things may become rather
unpredictable for me (I'll have earned my degree in music,
and may have moved on to find work somewhere.. I may also
have learned some other language).

6. HISTORY

(Note: ignoring versions of StdErr for Amiga E v2.(whatever))

StdErr 3.0:

* Initial release.

-- Known Bugs:

Ugly looking internal errors.

StdErr 3.1:

* Started using $VER: string (duh).
* Cleaned up the internal error scheme quite a bit.  StdErr
  now will attempt to give as much information as possible
  as to why it didn't work.. which may not help the user
  figure out what s/he did wrong, but it's a start.  So far,
  the only way I've been able to test this is to try to
  make StdErr open a file that has been locked.

-- Known Bugs:

StdErr will not print anything anywhere if it has been told
to direct output to a file that has been locked (devices
that have been write-protected/locked are okay, but files
that are locked will not do).  I have yet to figure out why.