Changeset 35

Show
Ignore:
Timestamp:
06/18/08 17:49:51 (5 years ago)
Author:
clinton
Message:

Updated docs to include Cookie docs

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/lib/Mungo.pm

    r33 r35  
    8282     # Use a scalar reference! 
    8383     $Response->Include(\$asp, @args); 
     84   %> 
     85 
     86   <!-- Cookie facilities --> 
     87   <% 
     88     # Read cookie 
     89     $single_value = $Request->Cookies($cookie_name); 
     90     $hashref = $Request->Cookies($cookie_name); 
     91 
     92     # Set cookie 
     93     $Response->Cookies($cookie_name, $single_value); 
     94     $Response->Cookies($cookie_name, $hash_ref); 
    8495   %> 
    8596 
    …… 
    296307sub Response { return Mungo::Response->new($_[0]); } 
    297308 
     309=head2 $encoded = $mungo->URLEncode($string); 
     310 
     311=head2 $encoded = Mungo->URLEncode($string); 
     312 
     313Encodes a string to escape characters that are not permitted in a URL. 
     314 
     315=cut 
     316 
    298317sub URLEncode { 
    299318  my $self = shift; 
    …… 
    302321  return $s; 
    303322} 
     323 
     324=head2 $string = $mungo->URLDecode($encoded); 
     325 
     326=head2 $string = Mungo->URLDecode($encoded); 
     327 
     328Decodes a string to unescape characters that are not permitted in a URL. 
     329 
     330=cut 
     331 
    304332sub URLDecode { 
    305333  my $self = shift; 
    …… 
    318346  return HTML::Entities::decode_entities( $s ); 
    319347} 
     348 
     349 
     350# Private? 
    320351sub demangle_name { 
    321352  my $self = shift; 
    …… 
    336367} 
    337368 
     369# Private? 
    338370sub filename2packagename { 
    339371  my ($self, $filename) = @_; 
    …… 
    368400  $page->content(@_); 
    369401} 
     402# Private? 
    370403sub include_file { 
    371404  my $self = shift; 
    …… 
    402435  $page->content(@_); 
    403436} 
     437# Private? 
    404438sub packagize { 
    405439  my $self = shift; 

  • trunk/lib/Mungo/Cookie.pm

    r17 r35  
    44# For information on licensing see: 
    55#   https://labs.omniti.com/zetaback/trunk/LICENSE 
     6 
     7=head1 NAME 
     8 
     9Mungo::Cookie - Cookie support class 
     10 
     11=head1 SYNOPSIS 
     12 
     13  # Use via Mungo::Request->Cookies 
     14  my $value = $Request->cookies($cookie_name, $key_name); 
     15 
     16=head1 DESCRIPTION 
     17 
     18Represents one or more  
     19 
     20=cut 
    621 
    722use strict; 
    …… 
    2641); 
    2742 
     43# Private constructor. 
     44# $cookiejar = Mungo::Cookie->new($apache_req); 
     45# $cookiejar = Mungo::Cookie->new($raw_cookie_string); 
     46#   Splits the incoming cookie string on ; to find sub-cookies 
     47#  If subcookie has a single value (with no key): 
     48#   $self->{$subcookie_name}->{Value} = $value 
     49#  If subcookie has a key-value pairs: 
     50#   $self->{$subcookie_name}->{Value}->{$key} = $value; 
    2851sub new { 
    2952  my $class = shift; 
    …… 
    3659  my $self = bless {}, $class; 
    3760  foreach my $cookie (split /;\s*/, $cstr) {        # ; seperated cookies 
     61      # $cname = subcookie name 
     62      # @lk = list of key, value pairs in subcookie 
     63      # @kv = a key, value pair in a subcookie 
    3864    my ($cname, $rest) = split /=/, $cookie, 2;     # cookie=OPAQUE_STRING 
    3965    my @lk = ($rest !~ /[=&]/) ?                    # single value ? 
    …… 
    94120  return $cstring; 
    95121} 
     122 
     123 
    96124sub inject_headers { 
    97125  my $self = shift; 
    …… 
    115143} 
    116144 
     145# Sigh.  "friend" method. 
     146 
     147# Why??? 
     148# $cookie_object = $cookie_object->__get(); 
     149 
     150# If $cookie_name is single-valued.... 
     151#  $value = $cookie_object->__get($cookie_name); 
     152 
     153# If $cookie_name is multi-valued.... 
     154#  $hashref = $cookie_object->__get($cookie_name); 
     155 
     156# If $cookie_name is multi-valued.... 
     157#  $value = $cookie_object->__get($cookie_name, $key); 
     158 
    117159sub __get { 
    118160  my $self = shift; 
    …… 
    120162  return $self unless(@_); 
    121163 
    122   my $key = shift; 
     164  my $cookie_name = shift; 
    123165  if(@_) { 
    124     my $part = shift; 
    125     return (exists $self->{$key} && ref $self->{$key}->{Value} eq 'HASH' && 
    126             exists $self->{$key}->{Value}->{$part}) ? 
    127              $self->{$key}->{Value}->{$part} : 
     166    my $key = shift; 
     167    return (exists $self->{$cookie_name} && ref $self->{$cookie_name}->{Value} eq 'HASH' && 
     168            exists $self->{$cookie_name}->{Value}->{$key}) ? 
     169             $self->{$cookie_name}->{Value}->{$key} : 
    128170             undef; 
    129171  } 
    130   return (exists $self->{$key}->{Value}) ? $self->{$key}->{Value} : undef; 
    131 } 
     172  return (exists $self->{$cookie_name}->{Value}) ? $self->{$cookie_name}->{Value} : undef; 
     173} 
     174 
     175 
     176# $cookie->__set($cookie_name, $value); 
     177# $cookie->__set($cookie_name, $key, $value); 
     178# $cookie->__set($cookie_name, 'Expires', $value); 
     179# $cookie->__set($cookie_name, 'Path', $value); 
     180# $cookie->__set($cookie_name, 'Domain', $value); 
     181# $cookie->__set($cookie_name, 'Secure', $value); 
    132182 
    133183sub __set { 
    134184  my $self = shift; 
    135185  my $cname = shift; 
     186  my $value = shift; 
    136187  my $key = undef; 
    137   my $value = shift; 
    138188  if(@_) { 
    139189    $key = $value; 

  • trunk/lib/Mungo/Request.pm

    r34 r35  
    1010eval "use APR::Table;"; 
    1111our $AUTOLOAD; 
     12 
     13=head1 NAME 
     14 
     15Mungo::Request - represent an HTTP request context 
     16 
     17=head1 SYNOPSIS 
     18 
     19  <!-- Within your HTML, you get a Request object for free --> 
     20  <% if (defined $Request) { ... } %> 
     21 
     22  <!-- Get params --> 
     23  <% 
     24     my $value = $Request->Params('param_name'); 
     25     my %params = $Request->Params(); 
     26  %> 
     27 
     28  <!-- Get cookies --> 
     29  <% 
     30     # for single-valued cookies 
     31     my $value = $Request->Cookies($cookie_name); 
     32 
     33     # for multi-valued cookies 
     34     my $hashref = $Request->Cookies($cookie_name); 
     35 
     36     # for multi-valued cookies 
     37     my $value = $Request->Cookies($cookie_name, $key); 
     38 
     39  %> 
     40 
     41=head1 DESCRIPTION 
     42 
     43Represents the request side of a Mungo request cycle. 
     44 
     45See Mungo, and Mungo::Request. 
     46 
     47=cut 
     48 
    1249 
    1350sub new { 
    …… 
    5895} 
    5996 
     97=head2 $value = $Request->Cookies($cookie_name); 
     98 
     99=head2 $hashref = $Request->Cookies($cookie_name); 
     100 
     101=head2 $value = $Request->Cookies($cookie_name, $key); 
     102 
     103Reads and parses incoming cookie data.  Behavior depends on whether  
     104the cookie contained name-value pairs. 
     105 
     106If not, the first form simply returns the value set in the given cookie name, or undef. 
     107 
     108If name-value pairs are present, the second form returns a hashref of all the name-value pairs. 
     109 
     110If name-value pairs are present, the third form returns the value for the given key. 
     111 
     112If no such cookie with the given name exists, returns undef. 
     113 
     114=cut 
     115 
    60116sub Cookies { 
    61117  my $self = shift; 
    62   my $ccls = 'Mungo::Cookie'; 
    63   my $cookie = $self->{$ccls} ||= $ccls->new($self->{'Apache::Request'}); 
     118  my $cookie_class = 'Mungo::Cookie'; 
     119  my $cookie = $self->{$cookie_class} ||= $cookie_class->new($self->{'Apache::Request'}); 
    64120  return $cookie->__get(@_); 
    65121} 
     122 
     123=head2 $value = $Request->QueryString($name); 
     124 
     125=head2 %params = $Request->QueryString(); 
     126 
     127=head2 $params_hashref = $Request->QueryString(); 
     128 
     129Returns one value (first form) or all values (second and third forms) 
     130from the submitted query string. 
     131 
     132Params() is preferred. 
     133 
     134=cut 
     135 
    66136sub QueryString { 
    67137  my $self = shift; 
    …… 
    81151  return \%qs; 
    82152} 
     153 
    83154sub decode_form { 
    84155  my $class = ref $_[0] ? ref $_[0] : $_[0]; 
    …… 
    100171  return $form; 
    101172} 
     173 
     174=head2 $value = $Request->Form($name); 
     175 
     176=head2 %params = $Request->Form(); 
     177 
     178=head2 $params_hashref = $Request->Form(); 
     179 
     180Returns one value (first form) or all values (second and third forms) 
     181from the submitted POST data. 
     182 
     183Params() is preferred. 
     184 
     185=cut 
     186 
    102187sub Form { 
    103188  my $self = shift; 
    …… 
    119204} 
    120205 
     206=head2 $value = $Request->Params($name); 
     207 
     208=head2 %params = $Request->Params(); 
     209 
     210=head2 $params_hashref = $Request->Params(); 
     211 
     212Returns one value (first form) or all values (second and third forms) 
     213from the submitted CGI parameters, whether that was via the query string or via POST data. 
     214 
     215This method is recommended over Form and QueryString, because it is independent  
     216of how the data was submitted. 
     217 
     218If both methods provide data, Form overrides QueryString. 
     219 
     220=cut 
     221 
    121222sub Params { 
    122223  my $self = shift; 
    …… 
    131232} 
    132233 
     234=head2 $value = $Request->ServerVariables($variable_name); 
     235 
     236Returns information about the request or the server.  Only certain  
     237variables are supported: 
     238 
     239  REFERER, REFERRER, DOCUMENT_ROOT, HTTP_HOST 
     240 
     241=cut 
     242 
    133243sub ServerVariables { 
    134244  my $self = shift; 
    …… 
    156266} 
    157267 
     268=head1 AUTHOR 
     269 
     270Theo Schlossnagle (code) 
     271 
     272Clinton Wolfe (docs) 
     273 
     274 
     275=cut 
     276 
    1582771; 

  • trunk/lib/Mungo/Response.pm

    r33 r35  
    44# For information on licensing see: 
    55#   https://labs.omniti.com/zetaback/trunk/LICENSE 
     6 
     7=head1 NAME 
     8 
     9Mungo::Response - Represent response side of HTTP request cycle 
     10 
     11=head1 SYNOPSIS 
     12 
     13  <!-- You get a Response object for free when you use Mungo --> 
     14  <% if ($Response) { ... } %> 
     15 
     16  <!-- Read and Mungo-process other files --> 
     17  <% 
     18     # Prints to browser 
     19     $Response->Include('/some/file.html', $arg1); 
     20 
     21     # Caputured 
     22     my $output = $Response->TrapInclude('/some/file.html'); 
     23 
     24     # Can also print to browser via Response 
     25     print $Response "Hello world!"; 
     26  %> 
     27 
     28  <!-- May also set headers --> 
     29  <% 
     30     $Response->AddHeader('header_name' => $value); 
     31  %> 
     32 
     33  <!-- Halt processing and jump out of the handler --> 
     34  <% 
     35     # With a 302 
     36     $Response->Redirect('/new/url/'); 
     37 
     38     # Just end 
     39     $Response->End(); 
     40  %> 
     41 
     42  <!-- Cookie facility --> 
     43  <% 
     44     # Single valued cookies 
     45     $Response->Cookies($cookie_name, $cookie_value); 
     46 
     47     # Multivalued cookies 
     48     $Response->Cookies($cookie_name, $key, $value); 
     49 
     50     # Cookie options 
     51     $Response->Cookies($cookie_name, 'Domain', $value); 
     52     $Response->Cookies($cookie_name, 'Expires', $value); 
     53     $Response->Cookies($cookie_name, 'Path', $value); 
     54     $Response->Cookies($cookie_name, 'Secure', $value); 
     55  %> 
     56 
     57=head1 DESCRIPTION 
     58 
     59Represents the response side of the Mungo request cycle. 
     60 
     61=cut 
     62 
    663 
    764use strict; 
    …… 
    103160} 
    104161 
     162=head2 $Response->AddHeader('header_name' => 'header_value'); 
     163 
     164Adds an HTTP header to the response. 
     165 
     166Dies if headers (or any other output) has already been sent. 
     167 
     168=cut 
     169 
    105170sub AddHeader { 
    106171  my $self = shift; 
    …… 
    115180  $cookie->__set(@_); 
    116181} 
     182 
     183=head2 $Response->Redirect($url); 
     184 
     185Issues a 302 redirect with the new location as $url. 
     186 
     187Dies if headers (or any other output) has already been sent. 
     188 
     189=cut 
     190 
    117191sub Redirect { 
    118192  my $self = shift; 
    …… 
    208282} 
    209283 
     284=head2 $output = $Response->TrapInclude($filename, @args); 
     285 
     286Like Include(), but results are returned as a string, instead of being printed. 
     287 
     288=cut 
     289 
    210290sub TrapInclude { 
    211291  my $self = shift; 
    …… 
    226306} 
    227307 
     308=head2 $Response->End() 
     309 
     310Stops processing the current response, shuts down the  
     311output handle, and jumps out of the response handler.   
     312No further processing will occur. 
     313 
     314=cut 
     315 
    228316sub End { 
    229317  my $self = shift; 
    …… 
    302390sub UNTIE { } 
    303391 
     392=head1 AUTHOR 
     393 
     394Theo Schlossnagle 
     395 
     396Clinton Wolfe (docs) 
     397 
     398=cut 
     399 
    3044001;