CGI-Exception: README.txt

Release: 0.3.0


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 for details.

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


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.


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.


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'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|
    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
    ## 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'"


public domain


makoto kuwata <kwa(at)>

copyright© 2007-2008 all rights reserved.