U:RDoc::NormalClass[iI"CGI:ET@I"Object;To:RDoc::Markup::Document:@parts[o;;[:
@fileI"ext/cgi/escape/escape.c;T:0@omit_headings_from_table_of_contents_below0o;;[oS:RDoc::Markup::Heading:
leveli:	textI"
Overview;To:RDoc::Markup::BlankLineo:RDoc::Markup::Paragraph;[
I"QThe Common Gateway Interface (CGI) is a simple protocol for passing an HTTP ;TI"Qrequest from a web server to a standalone program, and returning the output ;TI"Qto the web browser.  Basically, a CGI program is called with the parameters ;TI"Lof the request passed in either in the environment (GET) or via $stdin ;TI"K(POST), and everything it prints to $stdout is returned to the client.;T@o;;[I"KThis file holds the CGI class.  This class provides functionality for ;TI"Oretrieving HTTP request parameters, managing cookies, and generating HTML ;TI"output.;T@o;;[I"OThe file CGI::Session provides session management functionality; see that ;TI"class for more details.;T@o;;[I"ISee http://www.w3.org/CGI/ for more information on the CGI protocol.;T@S;;i;
I"Introduction;T@o;;[
I"RCGI is a large class, providing several categories of methods, many of which ;TI"Sare mixed in from other modules.  Some of the documentation is in this class, ;TI"Jsome in the modules CGI::QueryExtension and CGI::HtmlExtension.  See ;TI"RCGI::Cookie for specific information on handling cookies, and cgi/session.rb ;TI"0(CGI::Session) for information on sessions.;T@o;;[I"JFor queries, CGI provides methods to get at environmental variables, ;TI"Sparameters, cookies, and multipart request data.  For responses, CGI provides ;TI"4methods for writing output and generating HTML.;T@o;;[I"DRead on for more details.  Examples are provided at the bottom.;T@S;;i;
I"Queries;T@o;;[	I"EThe CGI class dynamically mixes in parameter and cookie-parsing ;TI"Dfunctionality,  environmental variable access, and support for ;TI"Dparsing multipart requests (including uploaded files) from the ;TI" CGI::QueryExtension module.;T@S;;i;
I"Environmental Variables;T@o;;[I"IThe standard CGI environmental variables are available as read-only ;TI"Mattributes of a CGI object.  The following is a list of these variables:;T@o:RDoc::Markup::Verbatim;[I"=AUTH_TYPE               HTTP_HOST          REMOTE_IDENT
;TI"<CONTENT_LENGTH          HTTP_NEGOTIATE     REMOTE_USER
;TI"?CONTENT_TYPE            HTTP_PRAGMA        REQUEST_METHOD
;TI"<GATEWAY_INTERFACE       HTTP_REFERER       SCRIPT_NAME
;TI"<HTTP_ACCEPT             HTTP_USER_AGENT    SERVER_NAME
;TI"<HTTP_ACCEPT_CHARSET     PATH_INFO          SERVER_PORT
;TI"@HTTP_ACCEPT_ENCODING    PATH_TRANSLATED    SERVER_PROTOCOL
;TI"@HTTP_ACCEPT_LANGUAGE    QUERY_STRING       SERVER_SOFTWARE
;TI")HTTP_CACHE_CONTROL      REMOTE_ADDR
;TI")HTTP_FROM               REMOTE_HOST
;T:@format0o;;[I"NFor each of these variables, there is a corresponding attribute with the ;TI"Esame name, except all lower case and without a preceding HTTP_. ;TI"K+content_length+ and +server_port+ are integers; the rest are strings.;T@S;;i;
I"Parameters;T@o;;[
I"MThe method #params() returns a hash of all parameters in the request as ;TI"Lname/value-list pairs, where the value-list is an Array of one or more ;TI"Nvalues.  The CGI object itself also behaves as a hash of parameter names ;TI"Gto values, but only returns a single value (as a String) for each ;TI"parameter name.;T@o;;[I">For instance, suppose the request contains the parameter ;TI"K"favourite_colours" with the multiple values "blue" and "green".  The ;TI"$following behavior would occur:;T@o;;[I"=cgi.params["favourite_colours"]  # => ["blue", "green"]
;TI"2cgi["favourite_colours"]         # => "blue"
;T;0o;;[I"KIf a parameter does not exist, the former method will return an empty ;TI"Parray, the latter an empty string.  The simplest way to test for existence ;TI"/of a parameter is by the #has_key? method.;T@S;;i;
I"Cookies;T@o;;[I"QHTTP Cookies are automatically parsed from the request.  They are available ;TI"Lfrom the #cookies() accessor, which returns a hash from cookie name to ;TI"CGI::Cookie object.;T@S;;i;
I"Multipart requests;T@o;;[I"PIf a request's method is POST and its content type is multipart/form-data, ;TI"Qthen it may contain uploaded files.  These are stored by the QueryExtension ;TI"Nmodule in the parameters of the request.  The parameter name is the name ;TI"Mattribute of the file input field, as usual.  However, the value is not ;TI"Ja string, but an IO object, either an IOString for small files, or a ;TI"NTempfile for larger ones.  This object also has the additional singleton ;TI"
methods:;T@o:RDoc::Markup::List:
@type:	NOTE:@items[o:RDoc::Markup::ListItem:@label[I"#local_path();T;[o;;[I":the path of the uploaded file on the local filesystem;To;;[I"#original_filename();T;[o;;[I"0the name of the file on the client computer;To;;[I"#content_type();T;[o;;[I"!the content type of the file;T@S;;i;
I"Responses;T@o;;[	I"MThe CGI class provides methods for sending header and content output to ;TI"Lthe HTTP client, and mixes in methods for programmatic HTML generation ;TI"Ufrom CGI::HtmlExtension and CGI::TagMaker modules.  The precise version of HTML ;TI"Eto use for HTML generation is specified at object creation time.;T@S;;i;
I"Writing output;T@o;;[
I"TThe simplest way to send output to the HTTP client is using the #out() method. ;TI"KThis takes the HTTP headers as a hash parameter, and the body content ;TI"Uvia a block.  The headers can be generated as a string using the #http_header() ;TI"Nmethod.  The output stream can be written directly to using the #print() ;TI"method.;T@S;;i;
I"Generating HTML;T@o;;[
I"FEach HTML element has a corresponding method for generating that ;TI"Gelement as a String.  The name of this method is the same as that ;TI"Gof the element, all lowercase.  The attributes of the element are ;TI"Mpassed in as a hash, and the body as a no-argument block that evaluates ;TI"Gto a String.  The HTML generation module knows which elements are ;TI"Ialways empty, and silently drops any passed-in body.  It also knows ;TI"Mwhich elements require matching closing tags and which don't.  However, ;TI"Cit does not know what attributes are legal for which elements.;T@o;;[
I"JThere are also some additional HTML generation methods mixed in from ;TI"Nthe CGI::HtmlExtension module.  These include individual methods for the ;TI"Ldifferent types of form inputs, and methods for elements that commonly ;TI"Otake particular attributes where the attributes can be directly specified ;TI"*as arguments, rather than via a hash.;T@S;;i;
I";Utility HTML escape and other methods like a function.;T@o;;[I"LThere are some utility tools defined in cgi/util.rb and cgi/escape.rb. ;TI"?Escape and unescape methods are defined in cgi/escape.rb. ;TI"CAnd when include, you can use utility methods like a function.;T@S;;i;
I"Examples of use;T@S;;i;
I"Get form values;T@o;;[I"require "cgi"
;TI"cgi = CGI.new
;TI"Evalue = cgi['field_name']   # <== value string for 'field_name'
;TI"7  # if not 'field_name' included, then return "".
;TI"=fields = cgi.keys            # <== array of field names
;TI"
;TI"-# returns true if form has 'field_name'
;TI" cgi.has_key?('field_name')
;TI" cgi.has_key?('field_name')
;TI" cgi.include?('field_name')
;T;0o;;[I"LCAUTION! <code>cgi['field_name']</code> returned an Array with the old ;TI"!cgi.rb(included in Ruby 1.6);T@S;;i;
I"Get form values as hash;T@o;;[I"require "cgi"
;TI"cgi = CGI.new
;TI"params = cgi.params
;T;0o;;[I"cgi.params is a hash.;T@o;;[	I"?cgi.params['new_field_name'] = ["value"]  # add new param
;TI">cgi.params['field_name'] = ["new_value"]  # change value
;TI">cgi.params.delete('field_name')           # delete param
;TI"Ccgi.params.clear                          # delete all params
;T;0S;;i;
I"Save form values to file;T@o;;[
I"require "pstore"
;TI"!db = PStore.new("query.db")
;TI"db.transaction do
;TI"!  db["params"] = cgi.params
;TI"	end
;T;0S;;i;
I""Restore form values from file;T@o;;[
I"require "pstore"
;TI"!db = PStore.new("query.db")
;TI"db.transaction do
;TI"!  cgi.params = db["params"]
;TI"	end
;T;0S;;i;
I"Get multipart form values;T@o;;[I"require "cgi"
;TI"cgi = CGI.new
;TI"Evalue = cgi['field_name']   # <== value string for 'field_name'
;TI"5value.read                  # <== body of value
;TI"Cvalue.local_path            # <== path to local file of value
;TI"Bvalue.original_filename     # <== original filename of value
;TI"=value.content_type          # <== content_type of value
;T;0o;;[I"6and value has StringIO or Tempfile class methods.;T@S;;i;
I"Get cookie values;T@o;;[
I"require "cgi"
;TI"cgi = CGI.new
;TI"9values = cgi.cookies['name']  # <== array of 'name'
;TI"1  # if not 'name' included, then return [].
;TI"?names = cgi.cookies.keys      # <== array of cookie names
;T;0o;;[I"and cgi.cookies is a hash.;T@S;;i;
I"Get cookie objects;T@o;;[I"require "cgi"
;TI"cgi = CGI.new
;TI"%for name, cookie in cgi.cookies
;TI"&  cookie.expires = Time.now + 30
;TI"	end
;TI"1cgi.out("cookie" => cgi.cookies) {"string"}
;TI"
;TI"Ccgi.cookies # { "name1" => cookie1, "name2" => cookie2, ... }
;TI"
;TI"require "cgi"
;TI"cgi = CGI.new
;TI"1cgi.cookies['name'].expires = Time.now + 30
;TI"9cgi.out("cookie" => cgi.cookies['name']) {"string"}
;T;0S;;i;
I">Print http header and html string to $DEFAULT_OUTPUT ($>);T@o;;['I"require "cgi"
;TI";cgi = CGI.new("html4")  # add HTML generation methods
;TI"cgi.out do
;TI"  cgi.html do
;TI"    cgi.head do
;TI"!      cgi.title { "TITLE" }
;TI"    end +
;TI"    cgi.body do
;TI"*      cgi.form("ACTION" => "uri") do
;TI"        cgi.p do
;TI"*          cgi.textarea("get_text") +
;TI"          cgi.br +
;TI"          cgi.submit
;TI"        end
;TI"      end +
;TI"      cgi.pre do
;TI"        CGI.escapeHTML(
;TI"3          "params: #{cgi.params.inspect}\n" +
;TI"5          "cookies: #{cgi.cookies.inspect}\n" +
;TI"+          ENV.collect do |key, value|
;TI")            "#{key} --> #{value}\n"
;TI"          end.join("")
;TI"        )
;TI"      end
;TI"
    end
;TI"  end
;TI"	end
;TI"
;TI"## add HTML generation methods
;TI"#CGI.new("html3")    # html3.2
;TI"-CGI.new("html4")    # html4.01 (Strict)
;TI"1CGI.new("html4Tr")  # html4.01 Transitional
;TI"-CGI.new("html4Fr")  # html4.01 Frameset
;TI"!CGI.new("html5")    # html5
;T;0S;;i;
I"Some utility methods;T@o;;[I"require 'cgi/escape'
;TI".CGI.escapeHTML('Usage: foo "bar" <baz>')
;T;0S;;i;
I")Some utility methods like a function;T@o;;[	I"require 'cgi/escape'
;TI"include CGI::Escape
;TI"*escapeHTML('Usage: foo "bar" <baz>')
;TI"(h('Usage: foo "bar" <baz>') # alias;T;0;	I"lib/cgi.rb;T;
0o;;[;	I"lib/cgi/cookie.rb;T;
0o;;[;	I"lib/cgi/core.rb;T;
0o;;[;	I"lib/cgi/escape.rb;T;
0o;;[;	I"lib/cgi/html.rb;T;
0o;;[;	I"lib/cgi/session.rb;T;
0o;;[;	I"lib/cgi/session/pstore.rb;T;
0o;;[;	I"lib/cgi/util.rb;T;
0;	0;
0[[
I"accept_charset;TI"R;T:publicFI"lib/cgi/core.rb;T[
U:RDoc::Constant[iI"VERSION;TI"CGI::VERSION;T;0o;;[;	@Q
;
0@Q
@cRDoc::NormalClass0U;[iI"CR;TI"CGI::CR;T;0o;;[o;;[I"String for carriage return;T;	@W
;
0@W
@@s
0U;[iI"LF;TI"CGI::LF;T;0o;;[o;;[I"String for linefeed;T;	@W
;
0@W
@@s
0U;[iI"EOL;TI"
CGI::EOL;T;0o;;[o;;[I"'Standard internet newline sequence;T;	@W
;
0@W
@@s
0U;[iI"NEEDS_BINMODE;TI"CGI::NEEDS_BINMODE;T;0o;;[o;;[I":Whether processing will be required in binary vs text;T;	@W
;
0@W
@@s
0U;[iI"PATH_SEPARATOR;TI"CGI::PATH_SEPARATOR;T;0o;;[o;;[I"/Path separators in different environments.;T;	@W
;
0@W
@@s
0U;[iI"HTTP_STATUS;TI"CGI::HTTP_STATUS;T;0o;;[o;;[I"HTTP status codes.;T;	@W
;
0@W
@@s
0U;[iI"MAX_MULTIPART_COUNT;TI"CGI::MAX_MULTIPART_COUNT;T;0o;;[o;;[I"8Maximum number of request parameters when multipart;T;	@W
;
0@W
@@s
0[[I"Escape;To;;[;	@W
;
0@k
[I"Escape;To;;[;	@Z
;
0I"lib/cgi/escape.rb;T[I"	Util;To;;[;	@f
;
0I"lib/cgi/util.rb;T[[I"
class;T[[;[	[I"accept_charset;T@k
[I"accept_charset=;T@k
[I"new;T@k
[I"
parse;T@k
[:protected[[:private[[I"
instance;T[[;[	[I"header;T@k
[I"http_header;T@k
[I"out;T@k
[I"
print;T@k
[;[[;[	[I"_no_crlf_check;T@k
[I"env_table;T@k
[I"
stdinput;T@k
[I"stdoutput;T@k
[[I"Escape;To;;[;	@W
;
0@k
[I"QueryExtension;To;;[;	@W
;
0@k
[I"
Html3;To;;[;	@W
;
0@k
[I"HtmlExtension;To;;[;	@W
;
0@k
[I"
Html4;To;;[;	@W
;
0@k
[I"HtmlExtension;To;;[;	@W
;
0@k
[I"Html4Tr;To;;[;	@W
;
0@k
[I"HtmlExtension;To;;[;	@W
;
0@k
[I"Html4Tr;To;;[;	@W
;
0@k
[I"Html4Fr;To;;[;	@W
;
0@k
[I"HtmlExtension;To;;[;	@W
;
0@k
[I"
Html5;To;;[;	@W
;
0@k
[I"HtmlExtension;To;;[;	@W
;
0@k
[I"Escape;To;;[;	@Z
;
0@�
[I"	Util;To;;[;	@f
;
0@�
[U:RDoc::Context::Section[i0o;;[;	0;
0[@
@Q
@T
@W
@Z
@]
@`
@c
@f
@f
cRDoc::TopLevel