Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CGI::Lite(3)	      User Contributed Perl Documentation	  CGI::Lite(3)

NAME
       CGI::Lite - Process and decode WWW forms	and cookies

SYNOPSIS
	   use CGI::Lite ();

	   my $cgi = CGI::Lite->new ();

	   $cgi->set_directory ('/some/dir') or	die "Directory cannot be set.\n";
	   $cgi->add_mime_type ('text/csv');

	   my $cookies = $cgi->parse_cookies;
	   my $form    = $cgi->parse_new_form_data;

	   my $status  = $cgi->is_error;
	   if ($status)	{
	       my $message = $cgi->get_error_message;
	       die $message;
	   }

DESCRIPTION
       This module can be used to decode form data, query strings, file
       uploads and cookies in a	very simple manner.

       It has only one dependency and is therefore relatively fast to
       instantiate. This makes it well suited to a non-persistent CGI
       scenario.

METHODS
       Here are	the methods used to process the	forms and cookies:

   new
       The constructor takes no	arguments and returns a	new CGI::Lite object.

   parse_form_data
       This handles the	following types	of requests: GET, HEAD and POST.  By
       default,	CGI::Lite uses the environment variable	REQUEST_METHOD to
       determine the manner in which the query/form information	should be
       decoded.	However, it may	also be	passed a valid request method as a
       scalar string to	force CGI::Lite	to decode the information in a
       specific	manner.

	       my $params = $cgi->parse_form_data ('GET');

       For multipart/form-data,	uploaded files are stored in the user selected
       directory (see set_directory). If timestamp mode	is on (see
       add_timestamp), the files are named in the following format:

	   timestamp__filename

       where the filename is specified in the "Content-disposition" header.
       NOTE:, the browser URL encodes the name of the file. This module	makes
       no effort to decode the information for security	reasons.  However,
       this can	be achieved by creating	a subroutine and then using the
       filter_filename method.

       Returns either a	hash or	a reference to the hash, which contains	all of
       the key/value pairs. For	fields that contain file information, the
       value contains either the path to the file, or the filehandle (see the
       set_file_type method).

   parse_new_form_data
       As for parse_form_data, but clears the CGI object state before
       processing the request. This is useful in persistent applications (e.g.
       FCGI), where the	CGI object is reused for multiple requests. e.g.

	   my $CGI = CGI::Lite->new ();
	   while (FCGI::accept > 0)
	   {
	       my $query = $CGI->parse_new_form_data ();
	       # process query
	   }

   parse_cookies
       Decodes and parses cookies passed by the	browser. This method works in
       much the	same manner as parse_form_data.	As these two data sources are
       treated the same	internally, users who wish to extract form and cookie
       data separately might find it easiest to	call parse_cookies first and
       then parse_new_form_data	in order to retrieve two distinct hashes (or
       hashrefs).

   is_error
       This method is used to check for	any potential errors after calling
       either parse_form_data or parse_cookies.

	   my $form = $cgi->parse_form_data ();
	   my $went_wrong = $cgi->is_error ();

       Returns 0 if there is no	error, 1 otherwise.

   get_error_message
       If an error occurs when parsing form/query information or cookies, this
       method may be used to retrieve the error	message. Remember, the
       presence	of any errors can be checked by	calling	the is_error method.

	   my $msg = $cgi->get_error_message ();

       Returns the error message as a plain text string.

   set_platform
       This method is used to set the platform on which	the web	server is
       running.	CGI::Lite uses this information	to translate end-of-line (EOL)
       characters for uploaded files (see the add_mime_type and
       remove_mime_type	methods) so that they are accounted for	properly on
       that platform.

	   $cgi->set_platform ($platform);

       $platform can be	any of (case insensitive):

	   Unix					 EOL: \012	= \n
	   Windows, Windows95, DOS, NT,	PC	 EOL: \015\012	= \r\n
	   Mac or Macintosh			 EOL: \015	= \r

       "Unix" is the default.

       Returns undef.

   set_size_limit
       To set a	specific limit on the total size of the	request	(in bytes)
       call this method	with that size as the sole argument. A size of zero
       effectively disables POST requests. To specify an unlimited size	(the
       default)	use an argument	of -1.

	   my $size_limit = $cgi->set_size_limit (10_000_000);

       Returns the new value if	provided, otherwise the	existing value.

   deny_uploads
       To prevent any file uploads simply call this method with	an argument of
       1. To enable them again,	use an argument	of zero.

	   my $deny_uploads = $cgi->deny_uploads (1);

       Returns the new value if	provided, otherwise the	existing value.

   force_unique_cookies
       It is generally considered a mistake to send an HTTP request with
       multiple	cookies	of the same name. However, the RFC is somewhat vague
       regarding how servers are expected to handle such an eventuality.
       CGI::Lite has always allowed such multiple values and returned them as
       an arrayref to be entirely consistent with the same treatment of
       form/query data.

       To override the default behaviour this method may be called with	a
       single integer argument before the call to parse_cookies. An argument
       of 1 means that the first cookie	value will be used and the others
       discarded. An argument of 2 means that the last cookie value will be
       used and	the others discarded. An argument of 3 means that an arrayref
       will be returned	as usual but an	error raised to	indicate the
       situation.  An argument of 0 (or	any other value) sets it back to the
       default.

	   $cgi->force_unique_cookies (1);
	   $cgi->parse_cookies;

       Note that if there is already an	item of	data in	the CGI::Lite object
       which matches the name of a cookie then the subsequent parse_cookies
       call will treat the new cookie value as another data item and the
       resulting behaviour will	be affected by this method. This is another
       reason to call parse_cookies before parse_form_data.

       Returns the new value if	provided, otherwise the	existing value.

   set_directory
       Used to set the directory where the uploaded files will be stored (only
       applies to the multipart/form-data encoding scheme).

	   my $tmpdir =	'/some/dir';
	   $cgi->set_directory ($tmpdir) or
	       die "Directory $tmpdir cannot be	used.\n";

       This function should be called before parse_form_data, or else the
       directory defaults to "/tmp". If	the application	cannot write to	the
       directory for whatever reason, an error status is returned.

       Returns 0 on error, 1 otherwise.

   close_all_files
	   $cgi->close_all_files;

       All uploaded files that are opened as a result of calling set_file_type
       with the	"handle" argument can be closed	in one shot by calling this
       method which takes no arguments and returns undef.

   add_mime_type
       By default, EOL characters are translated for all uploaded files	with
       specific	MIME types (i.e. text/plain, text/html,	etc.).	This method
       can be used to add to the list of MIME types. For example, if you want
       CGI::Lite to translate EOL characters for uploaded files	of
       application/mac-binhex40, then you would	do this:

	   $cgi->add_mime_type ('application/mac-binhex40');

       Returns 1 if this MIME type is newly added, 0 otherwise.

   remove_mime_type
       This method is the converse of add_mime_type. It	allows for the removal
       of a particular MIME type. For example, if you do not want CGI::Lite to
       translate EOL characters	for uploaded files of type text/html, then you
       would do	this:

	   $cgi->remove_mime_type ('text/html');

       Returns 1 if this MIME type is newly deleted, 0 otherwise.

   get_mime_types
       Returns the list	of the MIME types for which EOL	translation is
       performed.

	   my @mimelist	= $cgi->get_mime_types ();

   get_upload_type
       Returns the MIME	type of	uploaded data. Takes the field name as a
       scalar argument.	This previously	undocumented function was named
       print_mime_type prior to	version	3.0.

	   my $this_type = $cgi->get_upload_type ($field);

       Returns the MIME	type as	a scalar string	if single valued, an arrayref
       if multi-valued or undef	if the argument	does not exist or has no type.

   set_file_type
       The names of uploaded files are returned	by default when	the
       parse_form_data method is called	. But if this method is	passed the
       string "handle" as its argument beforehand then the handles to the
       files are returned instead. However, the	name of	each handle still
       corresponds to the filename.

	   # $fh has been set to one of	'handle' or 'file'
	   $cgi->set_file_type ($fh);

       This function should be called before any call to parse_form_data, or
       else it will have no effect.

   add_timestamp
       By default, a timestamp is added	to the front of	uploaded files.
       However,	there is the option of completely turning off timestamp	mode
       (value 0), or adding a timestamp	only for existing files	(value 2).

	   $cgi->add_timestamp ($tsflag);
	   # where $tsflag takes one of	these values
	   #	   0 = no timestamp
	   #	   1 = timestamp all files (default)
	   #	   2 = timestamp only if file exists

   filter_filename
       This method is used to change the manner	in which uploaded files	are
       named. For example, if you want uploaded	filenames to be	all upper
       case, you can use the following code:

	   $cgi->filter_filename (\&make_uppercase);
	   $cgi->parse_form_data;

	   # ...

	   sub make_uppercase
	   {
	       my $file	= shift;

	       $file =~	tr/a-z/A-Z/;
	       return $file;
	   }

       This method is perhaps best used	to sanitise filenames for a specific
       O/S or filesystem e.g. by removing spaces or leading hyphens, etc.

   set_buffer_size
       This method allows fine-grained control of the buffer size used
       internally when dealing with multipart form data. However, the actual
       buffer size that	the algorithm uses can be up to	3x the value specified
       as the argument.	This ensures that boundary strings are not "split"
       between multiple	reads. So, take	this into consideration	when setting
       the buffer size.

	   my $size = $cgi->set_buffer_size (4096);

       The buffer size may not be set below 256	bytes nor above	the total
       amount of multipart form	data. The default value	is 1024	bytes.

       Returns the buffer size.

   get_ordered_keys
       Returns either a	reference to an	array or an array itself consisting of
       the form	fields/cookies in the order they were parsed.

	   my $keys = $cgi->get_ordered_keys;
	   my @keys = $cgi->get_ordered_keys;

   print_data
       Displays	all the	key/value pairs	(either	form data or cookie
       information) in an ordered fashion to standard output. It is mainly
       useful for debugging. There are no arguments and	no return values.

   wrap_textarea
       This is a method	to wrap	a long string into one that is separated by
       EOL characters (see set_platform) at fixed lengths.  The	two arguments
       to be passed to this method are the string and the length at which the
       line separator is to be added.

	   my $new_string = $cgi->wrap_textarea	($string, $length);

       Returns the modified string.

   get_multiple_values
       The values returned by the parsing methods in this module for multiple
       fields with the same name are given as array references.	This utility
       method exists to	convert	either a scalar	value or an array reference
       into a list thus	removing the need for the user to determine whether
       the returned value for any field	is a reference or a scalar.

	   @all_values = $cgi->get_multiple_values ($reference);

       It is only provided as a	convenience to the user	and is not used
       internally by the module	itself.

       Returns a list consisting of the	multiple values.

   browser_escape
       Certain characters have special significance within HTML. These
       characters are: <, >, &,	", # and %. To display these "special"
       characters, they	can be escaped using the following notation "&#NNN;"
       where NNN is their ASCII	code.  This utility method does	just that.

	   $escaped_string = $cgi->browser_escape ($string);

       Returns the escaped string.

   url_encode
       This method will	URL-encode a string passed as its argument. It may be
       used to encode any data to be passed as a query string to a CGI
       application, for	example.

	   $encoded_string = $cgi->url_encode ($string);

       Returns the URL-encoded string.

   url_decode
       This method is used to URL-decode a string.

	   $decoded_string = $cgi->url_decode ($string);

       Returns the URL-decoded string.

   is_dangerous
       This method checks for the existence of dangerous meta-characters.

	   $status = $cgi->is_dangerous	($string);

       Returns 1 if such characters are	found, 0 otherwise.

DEPRECATED METHODS
       The following methods and subroutines are deprecated. Please do not use
       them in new code	and consider excising them from	old code. They will be
       removed in a future release.

       return_error
	       $cgi->return_error ('error 1', 'error 2', 'error	3');

	   You can use this method to print errors to standard output (ie. as
	   part	of the HTTP response) and exit.	This method is deprecated as
	   of version 3.0.  The	same functionality can be achieved with:

	       print ('error 1', 'error	2', 'error 3');
	       exit 1;

       create_variables
	   This	method is deprecated as	of version 3.0.	It runs	contrary to
	   the principles of structured	programming and	has really nothing to
	   do with CGI form or cookie handling.	It is retained here for
	   backwards compatibility but will be removed entirely	in later
	   versions.

	       %form = ('name'	 => 'alan wells',
			'sport'	 => 'track and field',
			'events' => '100m');

	       $cgi->create_variables (\%hash);

	   This	converts a hash	ref into scalars named for its keys and	this
	   example will	create three scalar variables: $name, $sport and
	   $events.

OBSOLETE METHODS/SUBROUTINES
       The following methods and subroutines were deprecated in	the 2.x	branch
       and have	now been removed entirely from the module.

       escape_dangerous_chars
	   The use of this subroutine had been strongly	discouraged for	more
	   than	a decade (See
	   <https://web.archive.org/web/20100627014535/http://use.perl.org/~cbrooks/journal/10542>
	   and <http://www.securityfocus.com/archive/1/311414> for an advisory
	   by Ronald F.	Guilmette.) It has been	removed	as of version 3.0.

       print_form_data
	   Use print_data instead.

       print_cookie_data
	   Use print_data instead.

       Compatibility note: in 2.x and older versions the following were	to be
       used as subroutines rather than methods:

       browser_escape
       url_encode
       url_decode
       is_dangerous

       They will still work as such and	are still exported by default. Users
       are encouraged to migrate to the	new method calls instead as both the
       export and subroutine interface will be retired in future. Non-method
       use currently triggers a	warning.

VERSIONS
       This module maintained backwards	compatibility with versions of Perl
       back to 5.002 for a very	long time. Such	stability is a welcome
       attribute but it	restricts the code by disallowing access to features
       introduced into the language since 1996.

       With this in mind, there	are two	maintained branches of this module
       going forwards. The 2.x branch will retain the backwards	compatibility
       but will	not have any new features introduced. Changes to this legacy
       branch will be bug fixes	only. The new 3.x branch will be the main
       release and will	require	a more modern perl (5.6.0 is now the bare
       minimum). The 3.x branch	has new	features and has removed some of the
       legacy code including some methods which	had been deprecated for	more
       than a decade.  The attention of	users wishing to upgrade from 2.x to
       3.x is drawn to the "DEPRECATED METHODS"	and "OBSOLETE
       METHODS/SUBROUTINES" sections of	this document.

       Requests	for new	features in the	3.x branch should be made via the
       request tracker at
       <https://rt.cpan.org/Public/Dist/Display.html?Name=CGI-Lite>

SEE ALSO
       If you're looking for more comprehensive	CGI modules, you can either
       use the CGI::* modules or CGI.pm.

       CGI::Lite::Request uses some similar method names to CGI.pm thus
       allowing	easy transition	between	the two. It uses CGI::Lite as a
       dependency.

       CGI::Simple, CGI::Minimal and CGI::Thin are alternative lightweight CGI
       implementations.

REPOSITORY
       <https://github.com/openstrike/perl-CGI-Lite>

MAINTAINER
       Maintenance of this module as of	May 2014 has been taken	over by	Pete
       Houston <cpan@openstrike.co.uk>.

ACKNOWLEDGMENTS
       The author (Shishir) thanks the following for finding bugs and offering
       suggestions:

       Eric D. Friedman	(friedman@uci.edu)
       Thomas Winzig (tsw@pvo.com)
       Len Charest (len@cogent.net)
       Achim Bohnet (ach@rosat.mpe-garching.mpg.de)
       John E. Townsend	(John.E.Townsend@BST.BLS.com)
       Andrew McRae (mcrae@internet.com)
       Dennis Grant (dg50@chrysler.com)
       Scott Neufeld (scott.neufeld@mis.ussurg.com)
       Raul Almquist (imrs@ShadowMAC.org)
       and many	others!

       The present maintainer wishes to	thank the previous maintainers:
       Smylers,	Andreas, Ben and Shishir.

COPYRIGHT INFORMATION
       Copyright (c) 1995, 1996, 1997 by Shishir Gundavaram.  All Rights
       Reserved.

       Changes in versions 2.03	onwards	are copyright 2014, 2015 by Pete
       Houston.

       Permission to use, copy,	and  distribute	 is  hereby granted, providing
       that the	above copyright	notice and this	permission appear in all
       copies and in supporting	documentation.

LICENCE
       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.0			  2018-05-19			  CGI::Lite(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | DEPRECATED METHODS | OBSOLETE METHODS/SUBROUTINES | VERSIONS | SEE ALSO | REPOSITORY | MAINTAINER | ACKNOWLEDGMENTS | COPYRIGHT INFORMATION | LICENCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CGI::Lite&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help