Current File : //opt/cpanel/ea-ruby24/root/usr/share/ri/system/CGI/cdesc-CGI.ri
U:RDoc::NormalClass[iI"CGI:ET@I" Object;To:RDoc::Markup::Document: @parts[ o;;[oS:RDoc::Markup::Heading:
leveli: textI"
Overview;To: RDoc::Markup::BlankLine o: 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":There are some utility tool defined in cgi/util.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"?CAUTION! cgi['field_name'] 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/util'
;TI".CGI.escapeHTML('Usage: foo "bar" <baz>')
;T;0S; ;
i; I")Some utility methods like a function;T@o;;[ I"require 'cgi/util'
;TI"include CGI::Util
;TI"*escapeHTML('Usage: foo "bar" <baz>')
;TI"(h('Usage: foo "bar" <baz>') # alias;T;0:
@fileI"lib/cgi.rb;T:0@omit_headings_from_table_of_contents_below0o;;[ ;I"lib/cgi/cookie.rb;T;0o;;[ ;I"lib/cgi/core.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[i I"CR;FI" CGI::CR;T00o;;[o;
;[I" String for carriage return;T;@S;0@S@cRDoc::NormalClass0U;[i I"LF;FI" CGI::LF;T00o;;[o;
;[I"String for linefeed;T;@S;0@S@@o0U;[i I"EOL;FI"
CGI::EOL;T00o;;[o;
;[I"'Standard internet newline sequence;T;@S;0@S@@o0U;[i I"NEEDS_BINMODE;FI"CGI::NEEDS_BINMODE;T00o;;[o;
;[I":Whether processing will be required in binary vs text;T;@S;0@S@@o0U;[i I"PATH_SEPARATOR;FI"CGI::PATH_SEPARATOR;T00o;;[o;
;[I"/Path separators in different environments.;T;@S;0@S@@o0U;[i I"HTTP_STATUS;FI"CGI::HTTP_STATUS;T00o;;[o;
;[I"HTTP status codes.;T;@S;0@S@@o0U;[i I"MAX_MULTIPART_COUNT;FI" CGI::MAX_MULTIPART_COUNT;T00o;;[o;
;[I"8Maximum number of request parameters when multipart;T;@S;0@S@@o0[[I" Util;To;;[ ;@S;0@d[[I"
class;T[[;[ [I"accept_charset;F@d[I"accept_charset=;F@d[I"new;T@d[I"
parse;F@d[:protected[ [: private[ [I"
instance;T[[;[ [I" header;T@d[I"http_header;F@d[I"out;F@d[I"
print;F@d[;[ [;[[I"env_table;F@d[I"
stdinput;F@d[I"stdoutput;F@d[[I" Util;To;;[ ;@S;0@d[I"QueryExtension;To;;[ ;@S;0@d[I"
Html3;To;;[ ;@S;0@d[I"HtmlExtension;To;;[ ;@S;0@d[I"
Html4;To;;[ ;@S;0@d[I"HtmlExtension;To;;[ ;@S;0@d[I" Html4Tr;To;;[ ;@S;0@d[I"HtmlExtension;To;;[ ;@S;0@d[I" Html4Tr;To;;[ ;@S;0@d[I" Html4Fr;To;;[ ;@S;0@d[I"HtmlExtension;To;;[ ;@S;0@d[I"
Html5;To;;[ ;@S;0@d[I"HtmlExtension;To;;[ ;@S;0@d[I" Util;To;;[ ;@_;0I"lib/cgi/util.rb;T[U:RDoc::Context::Section[i 0o;;[ ;0;0[ @M@P@S@V@Y@\@_@_cRDoc::TopLevel
Mini Shell