= README.txt

Release: 0.3.0

http://cgi-exception.rubyforge.org/
http://rubyforge.org/projects/cgi-exception/


== About

CGI-Exception is a small script to show exception raised in your
CGI script into browser, like PHP. You don't need to look for error
messages in Web server's log file.

In addition, CGI-Exception supports EditorKicker which is a pretty
tool to invoke your favorite editor and open errored file when an
exception raised on your script.
See http://editorkicker.rubyforge.org/ for details.

NOTICE: CGI-Exception supports CGI and mod_ruby, and it is easy
to use it in FastCGI (see blow for detail).


== Install

If you have installed RubyGems, just type 'gem install cgi-exception'
with administrator priviledge.

Or, just type 'ruby setup.rb' with administrator priviledge.

Or, copy 'lib/cgi_exception.rb' to proper directory such as
'/usr/local/lib/ruby/site_ruby/1.8'.

It is recommended to install EditorKicker as well as CGI-Exception.

NOTICE: It is NOT recommended to install by RubyGems, because
'require "rubygems"' is too heavy operation for CGI program.


== Usage

All you have to do is to require 'cgi_exception'.
If you do so and exception raised, what and where exception raised will
be shown in browser.

In addition, if you installed and required EditorKicker, TextMate or
Emacs will be invoked automatically when you got exceptions.
See README of EditorKicker for details.


== Example

For example, the following code will raise exception at line 5, because
local variable 'user' is not initialized.

1: #!/usr/bin/env ruby
2: require 'cgi'
3: require 'cgi_exception'
4: require 'editor_kicker' if ENV['SERVER_NAME'] == 'localhost'
5: print CGI.new.header('text/html')
6: print " <h1>Example</h1>\n"
7: print " <p>Hello #user</p>\n" # ERROR!
8: print " <p>unreachable</p>\n"

You'll see the following message in your browser if you access the above
CGI script.

/var/www/cgi-bin/foo.cgi:7: undefined local variable or method `user'
for main:Object (NameError)

If you are using FastCGI, try the following code:

#!/usr/bin/env ruby
require 'cgi'
require 'fcgi'
require 'cgi_exception'

FCGI.each do |cgi|
begin
print cgi.header('text/html')
print " <h1>Example</h1>\n"
print " <p>Hello #user</p>\n" # ERROR!
print " <p>unreachable</p>\n"
rescue Exception => ex
CGIExceptionPrinter.new(false).handle(ex)
## invoke Emacs automatically only when on localhost
if cgi.env_table['SERVER_NAME'] == 'localhost'
require 'editor_kicker'
ENV['EDITOR_KICKER'] = \
"emacsclient -n -s /tmp/emacs501/server +%s '%s'"
EditorKicker.handle(ex)
end
end
end


== License

public domain


== Author

makoto kuwata <kwa(at)kuwata-lab.com>

copyright(c) 2007-2008 kuwata-lab.com all rights reserved.