1Plack::Util(3)        User Contributed Perl Documentation       Plack::Util(3)
2
3
4

NAME

6       Plack::Util - Utility subroutines for Plack server and framework
7       developers
8

FUNCTIONS

10       TRUE, FALSE
11             my $true  = Plack::Util::TRUE;
12             my $false = Plack::Util::FALSE;
13
14           Utility constants to include when you specify boolean variables in
15           $env hash (e.g. "psgi.multithread").
16
17       load_class
18             my $class = Plack::Util::load_class($class [, $prefix ]);
19
20           Constructs a class name and "require" the class. Throws an
21           exception if the .pm file for the class is not found, just with the
22           built-in "require".
23
24           If $prefix is set, the class name is prepended to the $class unless
25           $class begins with "+" sign, which means the class name is already
26           fully qualified.
27
28             my $class = Plack::Util::load_class("Foo");                   # Foo
29             my $class = Plack::Util::load_class("Baz", "Foo::Bar");       # Foo::Bar::Baz
30             my $class = Plack::Util::load_class("+XYZ::ZZZ", "Foo::Bar"); # XYZ::ZZZ
31
32           Note that this function doesn't validate (or "sanitize") the passed
33           string, hence if you pass a user input to this function (which is
34           an insecure thing to do in the first place) it might lead to
35           unexpected behavior of loading files outside your @INC path. If you
36           want a generic module loading function, you should check out CPAN
37           modules such as Module::Runtime.
38
39       is_real_fh
40             if ( Plack::Util::is_real_fh($fh) ) { }
41
42           returns true if a given $fh is a real file handle that has a file
43           descriptor. It returns false if $fh is PerlIO handle that is not
44           really related to the underlying file etc.
45
46       content_length
47             my $cl = Plack::Util::content_length($body);
48
49           Returns the length of content from body if it can be calculated. If
50           $body is an array ref it's a sum of length of each chunk, if $body
51           is a real filehandle it's a remaining size of the filehandle,
52           otherwise returns undef.
53
54       set_io_path
55             Plack::Util::set_io_path($fh, "/path/to/foobar.txt");
56
57           Sets the (absolute) file path to $fh filehandle object, so you can
58           call "$fh->path" on it. As a side effect $fh is blessed to an
59           internal package but it can still be treated as a normal file
60           handle.
61
62           This module doesn't normalize or absolutize the given path, and is
63           intended to be used from Server or Middleware implementations. See
64           also IO::File::WithPath.
65
66       foreach
67             Plack::Util::foreach($body, $cb);
68
69           Iterate through $body which is an array reference or
70           IO::Handle-like object and pass each line (which is NOT really
71           guaranteed to be a line) to the callback function.
72
73           It internally sets the buffer length $/ to 65536 in case it reads
74           the binary file, unless otherwise set in the caller's code.
75
76       load_psgi
77             my $app = Plack::Util::load_psgi $psgi_file_or_class;
78
79           Load "app.psgi" file or a class name (like "MyApp::PSGI") and
80           require the file to get PSGI application handler. If the file can't
81           be loaded (e.g. file doesn't exist or has a perl syntax error), it
82           will throw an exception.
83
84           Since version 1.0006, this function would not load PSGI files from
85           include paths (@INC) unless it looks like a class name that only
86           consists of "[A-Za-z0-9_:]". For example:
87
88             Plack::Util::load_psgi("app.psgi");          # ./app.psgi
89             Plack::Util::load_psgi("/path/to/app.psgi"); # /path/to/app.psgi
90             Plack::Util::load_psgi("MyApp::PSGI");       # MyApp/PSGI.pm from @INC
91
92           Security: If you give this function a class name or module name
93           that is loadable from your system, it will load the module. This
94           could lead to a security hole:
95
96             my $psgi = ...; # user-input: consider "Moose"
97             $app = Plack::Util::load_psgi($psgi); # this would lead to 'require "Moose.pm"'!
98
99           Generally speaking, passing an external input to this function is
100           considered very insecure. If you really want to do that, validate
101           that a given file name contains dots (like "foo.psgi") and also
102           turn it into a full path in your caller's code.
103
104       run_app
105             my $res = Plack::Util::run_app $app, $env;
106
107           Runs the $app by wrapping errors with eval and if an error is
108           found, logs it to "$env->{'psgi.errors'}" and returns the template
109           500 Error response.
110
111       header_get, header_exists, header_set, header_push, header_remove
112             my $hdrs = [ 'Content-Type' => 'text/plain' ];
113
114             my $v = Plack::Util::header_get($hdrs, $key); # First found only
115             my @v = Plack::Util::header_get($hdrs, $key);
116             my $bool = Plack::Util::header_exists($hdrs, $key);
117             Plack::Util::header_set($hdrs, $key, $val);   # overwrites existent header
118             Plack::Util::header_push($hdrs, $key, $val);
119             Plack::Util::header_remove($hdrs, $key);
120
121           Utility functions to manipulate PSGI response headers array
122           reference. The methods that read existent header value handles
123           header name as case insensitive.
124
125             my $hdrs = [ 'Content-Type' => 'text/plain' ];
126             my $v = Plack::Util::header_get($hdrs, 'content-type'); # 'text/plain'
127
128       headers
129             my $headers = [ 'Content-Type' => 'text/plain' ];
130
131             my $h = Plack::Util::headers($headers);
132             $h->get($key);
133             if ($h->exists($key)) { ... }
134             $h->set($key => $val);
135             $h->push($key => $val);
136             $h->remove($key);
137             $h->headers; # same reference as $headers
138
139           Given a header array reference, returns a convenient object that
140           has an instance methods to access "header_*" functions with an OO
141           interface. The object holds a reference to the original given
142           $headers argument and updates the reference accordingly when called
143           write methods like "set", "push" or "remove". It also has "headers"
144           method that would return the same reference.
145
146       status_with_no_entity_body
147             if (status_with_no_entity_body($res->[0])) { }
148
149           Returns true if the given status code doesn't have any Entity body
150           in HTTP response, i.e. it's 100, 101, 204 or 304.
151
152       inline_object
153             my $o = Plack::Util::inline_object(
154                 write => sub { $h->push_write(@_) },
155                 close => sub { $h->push_shutdown },
156             );
157             $o->write(@stuff);
158             $o->close;
159
160           Creates an instant object that can react to methods passed in the
161           constructor. Handy to create when you need to create an IO stream
162           object for input or errors.
163
164       encode_html
165             my $encoded_string = Plack::Util::encode_html( $string );
166
167           Entity encodes "<", ">", "&", """ and "'" in the input string and
168           returns it.
169
170       response_cb
171           See "RESPONSE CALLBACK" in Plack::Middleware for details.
172
173
174
175perl v5.38.0                      2023-07-21                    Plack::Util(3)