GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  PLACK::UTIL (3)

.ds Aq ’

NAME

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

CONTENTS

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



<B>SecurityB>: 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.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 PLACK::UTIL (3) 2015-06-03

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.