Skip to content
Newer
Older
100644 276 lines (273 sloc) 9.45 KB
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
1 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
2 # cgi.rb - cgi support library
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
3 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
4 # Copyright (C) 2000 Network Applied Communication Laboratory, Inc.
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
5 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
6 # Copyright (C) 2000 Information-technology Promotion Agency, Japan
7 #
8 # Author: Wakou Aoyama <wakou@ruby-lang.org>
9 #
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
10 # Documentation: Wakou Aoyama (RDoc'd and embellished by William Webber)
11 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
12 # == Overview
13 #
14 # The Common Gateway Interface (CGI) is a simple protocol
15 # for passing an HTTP request from a web server to a
16 # standalone program, and returning the output to the web
17 # browser. Basically, a CGI program is called with the
18 # parameters of the request passed in either in the
19 # environment (GET) or via $stdin (POST), and everything
20 # it prints to $stdout is returned to the client.
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
21 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
22 # This file holds the +CGI+ class. This class provides
23 # functionality for retrieving HTTP request parameters,
24 # managing cookies, and generating HTML output. See the
25 # class documentation for more details and examples of use.
26 #
27 # The file cgi/session.rb provides session management
28 # functionality; see that file for more details.
29 #
30 # See http://www.w3.org/CGI/ for more information on the CGI
31 # protocol.
32
8f21162 @richkilmer bring lib up to r22701 (ruby 1.9.1_0 tag). there are build issues usi…
richkilmer authored Mar 2, 2009
33 raise "Please, use ruby 1.9.0 or later." if RUBY_VERSION < "1.9.0"
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
34
35 # CGI class. See documentation for the file cgi.rb for an overview
36 # of the CGI protocol.
37 #
38 # == Introduction
39 #
40 # CGI is a large class, providing several categories of methods, many of which
41 # are mixed in from other modules. Some of the documentation is in this class,
42 # some in the modules CGI::QueryExtension and CGI::HtmlExtension. See
43 # CGI::Cookie for specific information on handling cookies, and cgi/session.rb
44 # (CGI::Session) for information on sessions.
45 #
46 # For queries, CGI provides methods to get at environmental variables,
47 # parameters, cookies, and multipart request data. For responses, CGI provides
48 # methods for writing output and generating HTML.
49 #
50 # Read on for more details. Examples are provided at the bottom.
51 #
52 # == Queries
53 #
54 # The CGI class dynamically mixes in parameter and cookie-parsing
55 # functionality, environmental variable access, and support for
56 # parsing multipart requests (including uploaded files) from the
57 # CGI::QueryExtension module.
58 #
59 # === Environmental Variables
60 #
61 # The standard CGI environmental variables are available as read-only
62 # attributes of a CGI object. The following is a list of these variables:
63 #
64 #
65 # AUTH_TYPE HTTP_HOST REMOTE_IDENT
66 # CONTENT_LENGTH HTTP_NEGOTIATE REMOTE_USER
67 # CONTENT_TYPE HTTP_PRAGMA REQUEST_METHOD
68 # GATEWAY_INTERFACE HTTP_REFERER SCRIPT_NAME
69 # HTTP_ACCEPT HTTP_USER_AGENT SERVER_NAME
70 # HTTP_ACCEPT_CHARSET PATH_INFO SERVER_PORT
71 # HTTP_ACCEPT_ENCODING PATH_TRANSLATED SERVER_PROTOCOL
72 # HTTP_ACCEPT_LANGUAGE QUERY_STRING SERVER_SOFTWARE
73 # HTTP_CACHE_CONTROL REMOTE_ADDR
74 # HTTP_FROM REMOTE_HOST
75 #
76 #
77 # For each of these variables, there is a corresponding attribute with the
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
78 # same name, except all lower case and without a preceding HTTP_.
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
79 # +content_length+ and +server_port+ are integers; the rest are strings.
80 #
81 # === Parameters
82 #
83 # The method #params() returns a hash of all parameters in the request as
84 # name/value-list pairs, where the value-list is an Array of one or more
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
85 # values. The CGI object itself also behaves as a hash of parameter names
86 # to values, but only returns a single value (as a String) for each
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
87 # parameter name.
88 #
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
89 # For instance, suppose the request contains the parameter
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
90 # "favourite_colours" with the multiple values "blue" and "green". The
91 # following behaviour would occur:
92 #
93 # cgi.params["favourite_colours"] # => ["blue", "green"]
94 # cgi["favourite_colours"] # => "blue"
95 #
96 # If a parameter does not exist, the former method will return an empty
97 # array, the latter an empty string. The simplest way to test for existence
98 # of a parameter is by the #has_key? method.
99 #
100 # === Cookies
101 #
102 # HTTP Cookies are automatically parsed from the request. They are available
103 # from the #cookies() accessor, which returns a hash from cookie name to
104 # CGI::Cookie object.
105 #
106 # === Multipart requests
107 #
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
108 # If a request's method is POST and its content type is multipart/form-data,
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
109 # then it may contain uploaded files. These are stored by the QueryExtension
110 # module in the parameters of the request. The parameter name is the name
111 # attribute of the file input field, as usual. However, the value is not
112 # a string, but an IO object, either an IOString for small files, or a
113 # Tempfile for larger ones. This object also has the additional singleton
114 # methods:
115 #
116 # #local_path():: the path of the uploaded file on the local filesystem
117 # #original_filename():: the name of the file on the client computer
118 # #content_type():: the content type of the file
119 #
120 # == Responses
121 #
122 # The CGI class provides methods for sending header and content output to
123 # the HTTP client, and mixes in methods for programmatic HTML generation
124 # from CGI::HtmlExtension and CGI::TagMaker modules. The precise version of HTML
125 # to use for HTML generation is specified at object creation time.
126 #
127 # === Writing output
128 #
129 # The simplest way to send output to the HTTP client is using the #out() method.
130 # This takes the HTTP headers as a hash parameter, and the body content
131 # via a block. The headers can be generated as a string using the #header()
132 # method. The output stream can be written directly to using the #print()
133 # method.
134 #
135 # === Generating HTML
136 #
137 # Each HTML element has a corresponding method for generating that
138 # element as a String. The name of this method is the same as that
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
139 # of the element, all lowercase. The attributes of the element are
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
140 # passed in as a hash, and the body as a no-argument block that evaluates
141 # to a String. The HTML generation module knows which elements are
142 # always empty, and silently drops any passed-in body. It also knows
143 # which elements require matching closing tags and which don't. However,
144 # it does not know what attributes are legal for which elements.
145 #
146 # There are also some additional HTML generation methods mixed in from
147 # the CGI::HtmlExtension module. These include individual methods for the
148 # different types of form inputs, and methods for elements that commonly
149 # take particular attributes where the attributes can be directly specified
150 # as arguments, rather than via a hash.
151 #
152 # == Examples of use
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
153 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
154 # === Get form values
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
155 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
156 # require "cgi"
157 # cgi = CGI.new
158 # value = cgi['field_name'] # <== value string for 'field_name'
159 # # if not 'field_name' included, then return "".
160 # fields = cgi.keys # <== array of field names
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
161 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
162 # # returns true if form has 'field_name'
163 # cgi.has_key?('field_name')
164 # cgi.has_key?('field_name')
165 # cgi.include?('field_name')
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
166 #
167 # CAUTION! cgi['field_name'] returned an Array with the old
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
168 # cgi.rb(included in ruby 1.6)
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
169 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
170 # === Get form values as hash
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
171 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
172 # require "cgi"
173 # cgi = CGI.new
174 # params = cgi.params
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
175 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
176 # cgi.params is a hash.
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
177 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
178 # cgi.params['new_field_name'] = ["value"] # add new param
179 # cgi.params['field_name'] = ["new_value"] # change value
180 # cgi.params.delete('field_name') # delete param
181 # cgi.params.clear # delete all params
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
182 #
183 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
184 # === Save form values to file
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
185 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
186 # require "pstore"
187 # db = PStore.new("query.db")
188 # db.transaction do
189 # db["params"] = cgi.params
190 # end
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
191 #
192 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
193 # === Restore form values from file
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
194 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
195 # require "pstore"
196 # db = PStore.new("query.db")
197 # db.transaction do
198 # cgi.params = db["params"]
199 # end
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
200 #
201 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
202 # === Get multipart form values
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
203 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
204 # require "cgi"
205 # cgi = CGI.new
206 # value = cgi['field_name'] # <== value string for 'field_name'
207 # value.read # <== body of value
208 # value.local_path # <== path to local file of value
209 # value.original_filename # <== original filename of value
210 # value.content_type # <== content_type of value
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
211 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
212 # and value has StringIO or Tempfile class methods.
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
213 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
214 # === Get cookie values
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
215 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
216 # require "cgi"
217 # cgi = CGI.new
218 # values = cgi.cookies['name'] # <== array of 'name'
219 # # if not 'name' included, then return [].
220 # names = cgi.cookies.keys # <== array of cookie names
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
221 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
222 # and cgi.cookies is a hash.
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
223 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
224 # === Get cookie objects
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
225 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
226 # require "cgi"
227 # cgi = CGI.new
228 # for name, cookie in cgi.cookies
229 # cookie.expires = Time.now + 30
230 # end
231 # cgi.out("cookie" => cgi.cookies) {"string"}
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
232 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
233 # cgi.cookies # { "name1" => cookie1, "name2" => cookie2, ... }
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
234 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
235 # require "cgi"
236 # cgi = CGI.new
237 # cgi.cookies['name'].expires = Time.now + 30
238 # cgi.out("cookie" => cgi.cookies['name']) {"string"}
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
239 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
240 # === Print http header and html string to $DEFAULT_OUTPUT ($>)
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
241 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
242 # require "cgi"
243 # cgi = CGI.new("html3") # add HTML generation methods
244 # cgi.out() do
245 # cgi.html() do
246 # cgi.head{ cgi.title{"TITLE"} } +
247 # cgi.body() do
248 # cgi.form() do
249 # cgi.textarea("get_text") +
250 # cgi.br +
251 # cgi.submit
252 # end +
253 # cgi.pre() do
254 # CGI::escapeHTML(
255 # "params: " + cgi.params.inspect + "\n" +
256 # "cookies: " + cgi.cookies.inspect + "\n" +
257 # ENV.collect() do |key, value|
258 # key + " --> " + value + "\n"
259 # end.join("")
260 # )
261 # end
262 # end
263 # end
264 # end
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
265 #
511dc44 initial import
Laurent Sansonetti authored Feb 25, 2008
266 # # add HTML generation methods
267 # CGI.new("html3") # html3.2
268 # CGI.new("html4") # html4.01 (Strict)
269 # CGI.new("html4Tr") # html4.01 Transitional
270 # CGI.new("html4Fr") # html4.01 Frameset
271 #
8f21162 @richkilmer bring lib up to r22701 (ruby 1.9.1_0 tag). there are build issues usi…
richkilmer authored Mar 2, 2009
272 require 'cgi/core'
273 require 'cgi/cookie'
274 require 'cgi/util'
467bc1b Update library and removing working tags
Thibault Martin-Lagardette authored May 18, 2010
275 CGI.autoload(:HtmlExtension, 'cgi/html')
Something went wrong with that request. Please try again.