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

FreeBSD Manual Pages

  
 
  

home | help
Plack::Util(3)	      User Contributed Perl Documentation	Plack::Util(3)

NAME
       Plack::Util - Utility subroutines for Plack server and framework
       developers

FUNCTIONS
       TRUE, FALSE
	     my	$true  = Plack::Util::TRUE;
	     my	$false = Plack::Util::FALSE;

	   Utility constants to	include	when you specify boolean variables in
	   $env	hash (e.g. "psgi.multithread").

       load_class
	     my	$class = Plack::Util::load_class($class	[, $prefix ]);

	   Constructs a	class name and "require" the class. Throws an
	   exception if	the .pm	file for the class is not found, just with the
	   built-in "require".

	   If $prefix is set, the class	name is	prepended to the $class	unless
	   $class begins with "+" sign,	which means the	class name is already
	   fully qualified.

	     my	$class = Plack::Util::load_class("Foo");		   # Foo
	     my	$class = Plack::Util::load_class("Baz",	"Foo::Bar");	   # Foo::Bar::Baz
	     my	$class = Plack::Util::load_class("+XYZ::ZZZ", "Foo::Bar"); # XYZ::ZZZ

	   Note	that this function doesn't validate (or	"sanitize") the	passed
	   string, hence if you	pass a user input to this function (which is
	   an insecure thing to	do in the first	place) it might	lead to
	   unexpected behavior of loading files	outside	your @INC path.	If you
	   want	a generic module loading function, you should check out	CPAN
	   modules such	as Module::Runtime.

       is_real_fh
	     if	( Plack::Util::is_real_fh($fh) ) { }

	   returns true	if a given $fh is a real file handle that has a	file
	   descriptor. It returns false	if $fh is PerlIO handle	that is	not
	   really related to the underlying file etc.

       content_length
	     my	$cl = Plack::Util::content_length($body);

	   Returns the length of content from body if it can be	calculated. If
	   $body is an array ref it's a	sum of length of each chunk, if	$body
	   is a	real filehandle	it's a remaining size of the filehandle,
	   otherwise returns undef.

       set_io_path
	     Plack::Util::set_io_path($fh, "/path/to/foobar.txt");

	   Sets	the (absolute) file path to $fh	filehandle object, so you can
	   call	"$fh->path" on it. As a	side effect $fh	is blessed to an
	   internal package but	it can still be	treated	as a normal file
	   handle.

	   This	module doesn't normalize or absolutize the given path, and is
	   intended to be used from Server or Middleware implementations. See
	   also	IO::File::WithPath.

       foreach
	     Plack::Util::foreach($body, $cb);

	   Iterate through $body which is an array reference or
	   IO::Handle-like object and pass each	line (which is NOT really
	   guaranteed to be a line) to the callback function.

	   It internally sets the buffer length	$/ to 65536 in case it reads
	   the binary file, unless otherwise set in the	caller's code.

       load_psgi
	     my	$app = Plack::Util::load_psgi $psgi_file_or_class;

	   Load	"app.psgi" file	or a class name	(like "MyApp::PSGI") and
	   require the file to get PSGI	application handler. If	the file can't
	   be loaded (e.g. file	doesn't	exist or has a perl syntax error), it
	   will	throw an exception.

	   Since version 1.0006, this function would not load PSGI files from
	   include paths (@INC)	unless it looks	like a class name that only
	   consists of "[A-Za-z0-9_:]".	For example:

	     Plack::Util::load_psgi("app.psgi");	  # ./app.psgi
	     Plack::Util::load_psgi("/path/to/app.psgi"); # /path/to/app.psgi
	     Plack::Util::load_psgi("MyApp::PSGI");	  # MyApp/PSGI.pm from @INC

	   Security: If	you give this function a class name or module name
	   that	is loadable from your system, it will load the module. This
	   could lead to a security hole:

	     my	$psgi =	...; # user-input: consider "Moose"
	     $app = Plack::Util::load_psgi($psgi); # this would	lead to	'require "Moose.pm"'!

	   Generally speaking, passing an external input to this function is
	   considered very insecure. If	you really want	to do that, validate
	   that	a given	file name contains dots	(like "foo.psgi") and also
	   turn	it into	a full path in your caller's code.

       run_app
	     my	$res = Plack::Util::run_app $app, $env;

	   Runs	the $app by wrapping errors with eval and if an	error is
	   found, logs it to "$env->{'psgi.errors'}" and returns the template
	   500 Error response.

       header_get, header_exists, header_set, header_push, header_remove
	     my	$hdrs =	[ 'Content-Type' => 'text/plain' ];

	     my	$v = Plack::Util::header_get($hdrs, $key); # First found only
	     my	@v = Plack::Util::header_get($hdrs, $key);
	     my	$bool =	Plack::Util::header_exists($hdrs, $key);
	     Plack::Util::header_set($hdrs, $key, $val);   # overwrites	existent header
	     Plack::Util::header_push($hdrs, $key, $val);
	     Plack::Util::header_remove($hdrs, $key);

	   Utility functions to	manipulate PSGI	response headers array
	   reference. The methods that read existent header value handles
	   header name as case insensitive.

	     my	$hdrs =	[ 'Content-Type' => 'text/plain' ];
	     my	$v = Plack::Util::header_get($hdrs, 'content-type'); # 'text/plain'

       headers
	     my	$headers = [ 'Content-Type' => 'text/plain' ];

	     my	$h = Plack::Util::headers($headers);
	     $h->get($key);
	     if	($h->exists($key)) { ... }
	     $h->set($key => $val);
	     $h->push($key => $val);
	     $h->remove($key);
	     $h->headers; # same reference as $headers

	   Given a header array	reference, returns a convenient	object that
	   has an instance methods to access "header_*"	functions with an OO
	   interface. The object holds a reference to the original given
	   $headers argument and updates the reference accordingly when	called
	   write methods like "set", "push" or "remove". It also has "headers"
	   method that would return the	same reference.

       status_with_no_entity_body
	     if	(status_with_no_entity_body($res->[0]))	{ }

	   Returns true	if the given status code doesn't have any Entity body
	   in HTTP response, i.e. it's 100, 101, 204 or	304.

       inline_object
	     my	$o = Plack::Util::inline_object(
		 write => sub {	$h->push_write(@_) },
		 close => sub {	$h->push_shutdown },
	     );
	     $o->write(@stuff);
	     $o->close;

	   Creates an instant object that can react to methods passed in the
	   constructor.	Handy to create	when you need to create	an IO stream
	   object for input or errors.

       encode_html
	     my	$encoded_string	= Plack::Util::encode( $string );

	   Entity encodes "<", ">", "&", """ and "'" in	the input string and
	   returns it.

       response_cb
	   See "RESPONSE CALLBACK" in Plack::Middleware	for details.

perl v5.32.0			  2018-02-10			Plack::Util(3)

NAME | FUNCTIONS

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

home | help