Sloop::Lib
DESCRIPTION
Sloop::Lib is a hodge podge of simple utility functions used by other modules, some of which are documented for external use here. You can import them by name.
SUBROUTINES
callerTag ($packageName)
Wrapper on caller() which goes up the call stack until the package is not $packageName (which can just be __PACKAGE__,
to apply to the current one) -- in the spirit of Carp but seemingly more accurate,
and also more detailed.
The output is a single string:
In: lib/foo/bar.pm (line 123?) Package: foo::bar Sub: whatever() Call: hello()
There is no final newline.
The difference between "Call" and "Sub" is one stack frame, with the former being up from everything else (i.e., presumably where the original error is).
If the walk up leads to a top level line in the base script outside any subroutine (which is unlikely in an event driven Sloop context), then an empty string is returned; likewise for "Call: ".
checkURL ($client, $min, $max)
Uses Sloop::Client::Request::pathFromLevel() to determine if the remainder of a request path (after the handler cascade) is appropriate.
The number of levels should be between $min and $max, inclusive. However, both can be left undefined, in which case only a 0 remainder is acceptable. If only $min is defined, then the remainder levels can be anything greater than that.
If this test fails, $client is sent a generic 404 message, a debug message including the original request path is logged, and the function returns undef. Otherwise, $client is returned unmodified.
fastSlurp ($path)
Reads a file into a scalar. This is about ten lines of XS code combining low level POSIX C I/O with the perl API. It is faster than any method I've found for slurping files in perl on linux.
$! is set on failure.
$path File to fetch.
Returns A scalar containing the file or undef if the file can't be read.
httpTimestamp($time, $zone)
This function returns a timestamp string valid for use in HTTP headers as per RFC 822 section 5.
$time is an array reference to the return value of perl's localtime() or gmtime() functions.
$zone is the three letter time zone in capitals, e.g., "GMT".
lcSuffix($filename)
Returns a lower cased version of a file's suffix.
$filename A file name or path.
Returns A lower cased version of the file suffix, or undef if there wasn't one.
makeCookie($name, $value, $duration, @attr)
This is a convenience function for constructing an HTTP header value, to be used with "Set-Cookie:" in a response. See the the 'cookie' parameter to Sloop::Client::reply()). This line can also be used with javascript methods for setting cookies.
$name and $value is the name/value pair identifying the cookie. You can fetch a cookie $value set on a Sloop::Client::Request object by calling $req->findCookieValue($name).
The $name should not contain any whitespace or the following characters: ( ) < > @ , ; : \ / " { } [ ] ? =
Those will be pruned out if present. The $value should not contain whitespace or any of the following characters: \ " , ;
Niether name nor value should contain non-ASCII characters, but makeCookie() does not check for this!
$duration is how long a cookie remains valid for, in minutes, from the time it is issued to a client.
@attr is an optional list of string cookie attributes. If this is an https connection, make sure to include 'Secure'. If you want an alternate path or domain associated with the cookie, use 'Path=/path' or 'Domain=wherever'. If you want an HTTP only cookie, use 'HttpOnly'. For more information, see RFC 6265.
randomToken($length)
Creates a random string composed of the characters A-Z, a-z, and 0-9 (i.e., base 62 digits).
$length is the length of the string.
Returns: The random token.
terminateDirPath($path)
Appends '/' to a directory path if it is not present.
$path is a scalar containing the path. This should NOT be a reference -- it will be appended to via XS code.
untaintPath($pathref)
Checks a path for '..' and escapes (by prefixing '\') \ * | < and >.
$pathref is a reference to scalar containing the path.
Returns 0 if the path contains '..', 1 otherwise.