D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
proc
/
self
/
root
/
opt
/
alt
/
ruby34
/
share
/
ri
/
system
/
CGI
/
Filename :
cdesc-CGI.ri
back
Copy
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::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"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/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; I"lib/cgi.rb;T; 0o;;[ ; 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" VERSION;TI"CGI::VERSION;T;0o;;[ ; @P; 0@P@cRDoc::NormalClass0U;[i I"CR;TI" CGI::CR;T;0o;;[o;;[I" String for carriage return;T; @V; 0@V@@o0U;[i I"LF;TI" CGI::LF;T;0o;;[o;;[I"String for linefeed;T; @V; 0@V@@o0U;[i I"EOL;TI" CGI::EOL;T;0o;;[o;;[I"'Standard internet newline sequence;T; @V; 0@V@@o0U;[i I"NEEDS_BINMODE;TI"CGI::NEEDS_BINMODE;T;0o;;[o;;[I":Whether processing will be required in binary vs text;T; @V; 0@V@@o0U;[i I"PATH_SEPARATOR;TI"CGI::PATH_SEPARATOR;T;0o;;[o;;[I"/Path separators in different environments.;T; @V; 0@V@@o0U;[i I"HTTP_STATUS;TI"CGI::HTTP_STATUS;T;0o;;[o;;[I"HTTP status codes.;T; @V; 0@V@@o0U;[i I"MAX_MULTIPART_COUNT;TI" CGI::MAX_MULTIPART_COUNT;T;0o;;[o;;[I"8Maximum number of request parameters when multipart;T; @V; 0@V@@o0[[I" Util;To;;[ ; @V; 0@g[[I" class;T[[;[ [I"accept_charset;T@g[I"accept_charset=;T@g[I"new;T@g[I" parse;T@g[:protected[ [: private[ [I" instance;T[[;[ [I" header;T@g[I"http_header;T@g[I"out;T@g[I" print;T@g[;[ [;[ [I"_no_crlf_check;T@g[I"env_table;T@g[I" stdinput;T@g[I"stdoutput;T@g[ [I" Util;To;;[ ; @V; 0@g[I"QueryExtension;To;;[ ; @V; 0@g[I" Html3;To;;[ ; @V; 0@g[I"HtmlExtension;To;;[ ; @V; 0@g[I" Html4;To;;[ ; @V; 0@g[I" Html4Tr;To;;[ ; @V; 0@g[I" Html4Fr;To;;[ ; @V; 0@g[I" Html5;To;;[ ; @V; 0@g[U:RDoc::Context::Section[i 0o;;[ ; 0; 0[ @ @P@S@V@Y@\@_@b@bcRDoc::TopLevel