|
4.20 os |
4.21 directory_operations |
This part of the guide contains detailed descriptions of the
BUSH built-in packages.
4.11 cgi Package
The BUSH CGI package is based on and uses David A. Wheeler's AdaCGI package.
It provides form processing, string encoding, and cookie operations.
Using the CGI package, programmers can write scripts that run when invoked
by web servers using the Common Gateway Interface (CGI). Bush's large feature
set and strong error checking make it ideal for writing web server applications.
The examples directory contains a script called minimal_cgi, a CGI script
that displays form variables.
procedure minimal_cgi is
-- Demonstrate Bush's CGI interface
-- based on AdaCGI's minimal.adb example
-- To run this script directly (without a HTTP server), set the
-- environment variable REQUEST_METHOD to "GET" and the variable
-- QUERY_STRING to either "" or "x=a&y=b".
begin
cgi.put_cgi_header;
cgi.put_html_head( "Minimal Form Demonstration" );
if cgi.input_received then
cgi.put_variables;
else
put_line( "<form method=" & ASCII.Quotation & "POST" & ASCII.Quotation &
">What's your name?<input name=" & ASCII.Quotation & "username" &
ASCII.Quotation & "><input type=" & ASCII.Quotation & "submit" &
ASCII.Quotation & "></form>" );
end if;
cgi.put_html_tail;
end minimal_cgi;
To run it without a web server, define exported strings QUERY_STRING and
REQUEST_METHOD. If there is no information to process (QUERY_STRING is
an empty string) it will return a form, otherwise it will display the value
of the CGI variables.
=> QUERY_STRING : string := ""
=> pragma export( shell, QUERY_STRING )
=> REQUEST_METHOD : string := "GET"
=> pragma export( shell, REQUEST_METHOD )
=> bush examples/minimal_cgi.bush
content_type: text/html
<html><head><title>Minimal Form Demonstration</title>
</head><body>
<form method="POST">What's your name?<input name="username"><input type="submit"></form>
</body7gt;</html>
=> QUERY_STRING : string := "x=a&y=b"
=> bush examples/minimal_cgi.bush
content_type: text/html
<html><head><title>Minimal Form Demonstration</title>
</head><body>
<pre>
<b>x</b>: <i>a</i>
<b>y</b>: <i>b</i>
</pre>
</body></html>
The CGI package uses the standard Ada types except for one additional enumerated
type:
-
type cgi.cgi_method_type is (cgi.get, cgi.post, cgi.unknown);
-- the form posting method
To use cgi_method_type or its elements, prefix the items with "cgi." as
you would with any other package declaration.
b := cgi.parsing_errors
True if there were errors parsing.
Example: if cgi.parsing_errors then ...
Ada Equivalent: CGI.Parsing_Errors
Parameters:
b |
return value |
boolean |
required |
true if there were parsing errors |
|
b := cgi.input_received
True if there were CGI variables passed to the script.
Example: if cgi.input_received then ...
Ada Equivalent: CGI.Input_Received
Parameters:
b |
return value |
boolean |
required |
true if there was input received |
|
b := cgi.is_index
True if an "IsIndex" request was made.
Example: if cgi.is_index ...
Ada Equivalent: CGI.Is_Index
Parameters:
b |
return value |
boolean |
required |
true if a "IsIndex" request was made |
|
m := cgi.cgi_method
Identify the CGI standard that was used to communicate with the web
server.
Example: if cgi.cgi_method = cgi.get then ...
Ada Equivalent: CGI.CGI_Method
Parameters:
m |
return value |
cgi.cgi_method_type |
required |
the method (cgi.get, cgi.post or cgi.unknown) |
|
s := cgi.value( v, i, b )
Return the value of a CGI variable (a form field).
Example: username := cgi.value( "username" );
Ada Equivalent: CGI.Value
Parameters:
s |
return value |
string |
required |
the value of the variable |
v |
in |
string |
required |
the name of the variable |
i |
in |
positive |
1 |
which variable (1 = first match, 2 = second match, etc.) |
r |
in |
boolean |
false |
if true, an exception will be raised if the variable is missing, otherwise
an empty string is returned |
|
b := cgi.key_exists( v )
Return true if a CGI variable (a form field) exists.
Example: if cgi.key_exists( "credit_card_expiry_date" ) then ...
Ada Equivalent: CGI.Key_Exists
Parameters:
b |
return value |
boolean |
required |
true if the variable exists |
v |
in |
string |
required |
the variable to check |
|
n := cgi.key_count( v )
Return the number of times the variable name (or name of a form field)
occurs.
Example: for k in 1..cgi.key_count( "phone_number" ) loop ...
Ada Equivalent: CGI.Key_Count
Parameters:
n |
return value |
natural |
required |
the number of occurrences |
v |
in |
string |
required |
the variable to check |
|
n := cgi.argument_count
Return the total number of variables, including duplicates with the
same name. occurs.
Example: for k in 1..cgi.argument_count loop ...
Ada Equivalent: CGI.Argument_Count
Parameters:
n |
return value |
natural |
required |
the number of variables |
|
s := cgi.key( p )
Return the name of pth CGI variable.
Example: first_variable := cgi.key( 1 );
Ada Equivalent: CGI.Key
Parameters:
s |
return value |
string |
required |
the CGI variable name |
p |
in |
positive |
required |
the variable position (1..cgi.argument_count). A bad value will raise
an exception. |
|
n := cgi.key_value( p )
Return the value of the pth CGI variable.
Example: first_value := cgi.key_value( 1 );
Ada Equivalent: CGI.Value (NOTE: a different name)
Parameters:
s |
return value |
string |
required |
the variable value |
p |
in |
positive |
required |
the position of the variable (1..cgi.argument_count) |
|
b := cgi.key_value_exists( v, s )
True if a CGI variable v has value s.
Example: if cgi.key_value_exists( "country", "US" ) then ...
Ada Equivalent: CGI.Key_Value_Exists
Parameters:
b |
return value |
boolean |
required |
true if the variable has the value |
v |
in |
string |
required |
the CGI variable |
s |
in |
string |
required |
the value to test for |
|
cgi.put_cgi_header( h )
Write the CGI header to current_output, including two carriage returns.
This header determines the form of the program's reply (by default, an
HTML document).
Example: first_value := cgi.key_value( 1 );
Ada Equivalent: CGI.Value (NOTE: a different name)
Parameters:
h |
in |
string |
Content-type: text/html |
the CGI header to use |
|
cgi.put_html_head( t, m )
Write a simple HTML header to current_output, including a title and
optional mailto link to the page author.
Example: cgi.put_html_head( "Search results", "itdept@yourorg.com"
)
Ada Equivalent: CGI.Put_HTML_Head
Parameters:
t |
in |
string |
required |
the page title |
m |
in |
string |
no mailto |
the email address of the author |
|
cgi.put_html_heading( s, l )
Write a simple HTML <h1> to <h6> heading.
Example: cgi.put_html_heading( "OmniCorp Sales Statistics", 1 )
Ada Equivalent: CGI.Value (NOTE: a different name)
Parameters:
s |
in |
string |
required |
the heading text |
l |
in |
positive |
required |
the heading level (1..6) |
|
cgi.put_html_tail
Complete an HTML document by writing " to current_output.
Example: cgi.put_html_tail;
Ada Equivalent: CGI.Put_HTML_Tail;
Parameters:
none |
cgi.put_error_message( s )
Write a short HTML document containing an error message. Use cgi.put_cgi_header
first.
Example: cgi.put_error_message( "the disk is full" )
Ada Equivalent: CGI.Put_Error_Message
Parameters:
s |
in |
string |
required |
the error message |
|
cgi.put_variables
Display the CGI variables in HTML format. Use for debugging.
Example: cgi.put_variables;
Ada Equivalent: CGI.Put_Variables;
Parameters:
none |
s := cgi.my_url
Return the URL of the script.
Example: script_url := cgi.my_url;
Ada Equivalent: CGI.My_URL
Parameters:
s |
return value |
string |
required |
the URL of the script |
|
n := cgi.line_count( s )
Count the number of lines is value s, 0 if an empty string.
Example: if cgi.line_count( address ) > 4 then ...
Ada Equivalent: CGI.Line_Count
Parameters:
n |
return value |
natural |
required |
the number of lines (0 if null string) |
s |
in |
string |
required |
the string to test |
|
n := cgi.line_count_of_value( v )
Count the number of lines in the value of variable v, 0 if an empty
string.
Example: if cgi.line_count_of_value( address ) > 4 then ...
Ada Equivalent: CGI.Line_Count_Of_Value
Parameters:
n |
return value |
natural |
required |
the number of lines (0 if null string) |
v |
in |
string |
required |
the CGI variable to test |
|
l := cgi.line( s, p )
Return the pth line of string s.
Example: second_line := cgi.line( address, 2 );
Ada Equivalent: CGI.Line
Parameters:
l |
return value |
string |
required |
the line |
s |
in |
string |
required |
the CGI variable value to get the line from |
p |
in |
positive |
required |
the line number (1..cgi.line_count). A bad value raises an exception. |
|
l := cgi.value_of_line( v, p )
Return the pth line of the value of CGI variable v.
Example: second_line := cgi.line( "address", 2 );
Ada Equivalent: CGI.Value_Of_Line
Parameters:
l |
return value |
string |
required |
the line |
v |
in |
string |
required |
the CGI variable to get the line from |
p |
in |
positive |
required |
the line number (1..cgi.line_count). A bad value raises an exception. |
|
s := cgi.url_decode( u, b )
Decode HTML-encoded %HH hexadecimal characters into their corresponding
ASCII characters. If b is true, translate plus signs to spaces.
Example: s := cgi.url_decode( encoded_url );
Ada Equivalent: CGI.URL_Decode
Parameters:
s |
return value |
string |
required |
the decoded string |
u |
in |
string |
required |
the URL-encoded string |
b |
in |
boolean |
true |
translate plus signs to spaces if true |
|
u := cgi.url_encode( s, b )
Encode the string using %HH hexadecimal characters. If b is true, translate
plus signs to spaces.
Example: encoded_url := cgi.url_encode( s );
Ada Equivalent: CGI.URL_Decode
Parameters:
u |
return value |
string |
required |
the URL-encoded string |
s |
in |
string |
required |
the string to encode |
b |
in |
boolean |
true |
translate plus signs to spaces if true |
|
h := cgi.html_encode( s )
Encode the string escaping illegal HTML characters. For example, '>'
becomes >).
Example: safe_html := cgi.html_encode( "This is <illegal> HTML!"
);
Ada Equivalent: CGI.HTML_Encode
Parameters:
h |
return value |
string |
required |
the HTML-encoded string |
s |
in |
string |
required |
the string to encode |
|
cgi.set_cookie( v, s, x, p, d, b )
Set a cookie's properties. Call this before Put_CGI_Header.
Example: cgi.set_cookie( "last_visit", "none" );
Ada Equivalent: CGI.Set_Cookie
Parameters:
v |
in |
string |
required |
the cookie name |
s |
in |
string |
required |
the cookie value |
x |
in |
string |
none |
the expiry date |
p |
in |
string |
PATH_INFO value |
the cookie path |
d |
in |
string |
SERVER_NAME value |
the domain value |
b |
in |
boolean |
false |
true if secure |
|
s := cgi.cookie_value( c [, p] )
Get the value of pth instance of cookie c.
Example: cookie := cgi.cookie_value( "date_visited" );
Ada Equivalent: CGI.Cookie_Value
Parameters:
s |
return value |
string |
required |
the cookie value |
c |
in |
string |
required |
the cookie name |
p |
in |
positive |
1 |
the instance of the cookie name |
|
n := cgi.cookie_count( c [, p] )
Return the number of cookies.
Example: for i in 1..cgi.cookie_count loop ...
Ada Equivalent: CGI.Cookie_Count
Parameters:
s |
return value |
natural |
required |
the number of cookies |
|
cgi.get_environment is not implemented: it is already available through
the command_line package.
Back to Top
|