CGI-Exception: 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>