Prima::Utils - miscellaneous routines
The module contains miscellaneous helper routines
Calls SUB with PARAMS after TIMEOUT milliseconds. Returns 0 on failure, and the active timer on success. The timer can be stopped to disarm the alarm.
Invokes the system-depended sound and/or visual bell, corresponding to one of the following constants:
mb::Error mb::Warning mb::Information mb::Question
Returns one of the gui::XXX constants that report the graphic user interface used in the system:
gui::XXX
gui::Default gui::Windows gui::XLib gui::GTK
Returns one of the apc::XXX constants that report the system platform. Currently, the list of the supported platforms is:
apc::XXX
apc::Win32 apc::Unix
Converts PATH from a perl module notation into a file path and searches for the file in the @INC paths set. If the file is found, its full filename is returned; otherwise undef is returned.
@INC
undef
Returns last system error, if any
Performs floor($_ + .5) operation over NUMBERS which can be an array or an arrayref. Returns converted integers in either an array or an arrayref form, depending on the calling syntax.
floor($_ + .5)
Performs floor($_ * 1e15 + .5) / 1e15 operation over NUMBERS which can be an array or an arrayref. Returns converted NVs in either an array or an arrayref form, depending on the calling syntax. Used to protect against perl configurations that calculate sin, cos etc with only 15 significant digits in the mantissa. This function prevents the accumulation of error in these configurations.
floor($_ * 1e15 + .5) / 1e15
sin
cos
If called with no parameters, returns the path to a directory, usually ~/.prima, that can be used to store the user settings of a toolkit module or a program. If FILE is specified, appends it to the path and returns the full file name. In the latter case, the path is automatically created by File::Path::mkpath unless it already exists.
File::Path::mkpath
Postpones a call to SUB with PARAMS until the next event loop tick.
Returns an anonymous array to drive letters used by the system. FIRST_DRIVE can be set to another value to start enumeration from. Win32 can probe removable drives there, so to increase the responsiveness of the function it might be reasonable to call it with FIRST_DRIVE set to C: .
C:
If the system supports no drive letters, an empty array reference is returned ( unix ).
Returns one of the dt::XXX constants that describe the type of a drive, where DRIVE is a 1-character string. If there is no such drive, or the system supports no drive letters ( unix ), dt::None is returned.
dt::XXX
dt::None
dt::None dt::Unknown dt::Floppy dt::HDD dt::Network dt::CDROM dt::Memory
Same as perl's native sleep (i.e. CORE::sleep) but with the event loop running. Note that the argument it takes is seconds, for the sake of compatibility, while the rest of the toolkit operates in milliseconds.
sleep
CORE::sleep
Returns the login name of the user. Sometimes is preferred to the perl-provided getlogin ( see "getlogin" in perlfunc ) .
getlogin
Accepts COLOR string in one of the three formats:
#rgb #rrggbb #rrrgggbbb
and returns a 24-bit RGB integer value
Waits for a condition for max TIMEOUT milliseconds, or forever if TIMEOUT is undefined.
Returns undef on failure, 0 on TIMEOUT, 1 on a successful CONDITION.
CONDITION is either a scalar reference, or a sub to be polled, where their values are treated as 0 as a signal to continue the waiting, and 1 as a stop signal.
Since perl's win32 unicode support for files is unexistent, Prima has its own parallel set of functions mimicking native functions, ie open, chdir etc. This means that files with names that cannot be converted to ANSI (ie user-preferred) codepage are not visible in perl, but the functions below mitigate that problem.
open
chdir
The following fine points need to be understood before using these functions:
Prima makes a distinction between whether scalars have their utf8 bit set or not throughout the whole toolkit. For example, text output in both unix and windows is different depending on the bit, treating non-utf8-bit text as locale-specific, and utf8-bit text as unicode. The same model is applied to file names.
Perl implementation for native Win32 creates virtual environments for each thread and may keep more than one instance of the current directory, environment variables, etc. This means that under Win32, calling Prima::Utils::chdir will NOT automatically make CORE::chdir assume that value, even if the path is convertible to ANSI. Keep that in mind when mixing Prima and core functions. To add more confusion, under the unix, these two chdir calls are identical when the path is fully convertible.
Prima::Utils::chdir
CORE::chdir
Under unix, reading entries from the environment or the file system is opportunistic: if a text string (file name, environment entry) is a valid utf8 string, then it is treated and reported as one. Mostly because the .UTF-8 locales are default and found everywhere. Note that Prima ignores $ENV{LANG} here. This is a bit problematic on Perls under 5.22 as these don't provide > means to check for the utf8 string validity, so every string will be slapped > a utf8 bit on here -- beware.
$ENV{LANG}
Setting environment variables may or may not sync with %ENV , depending on how perl is built. Also, %ENV will warn when trying to set scalars with utf-8 bit there.
%ENV
Same as POSIX::access.
POSIX::access
Same as CORE::chdir but disregards the thread-local environment on Win32.
Same as CORE::chmod
CORE::chmod
Mimic homonymous perl functions
Same as Cwd::getcwd
Cwd::getcwd
Reads the content of the PATH directory and and returns array of string pairs where the first item is a file name and the second is a file type.
The file type is a string, one of the following:
"fifo" - named pipe "chr" - character special file "dir" - directory "blk" - block special file "reg" - regular file "lnk" - symbolic link "sock" - socket "wht" - whiteout
This function was implemented for faster directory reading, to avoid successive calls of stat for every file.
stat
Also, getdir is consistently inclined to treat filenames in utf8, disregarding both perl unicode settings and the locale.
Reads directly from environment, possibly bypassing %ENV , and disregarding thread-local environment on Win32.
Same as CORE::link.
CORE::link
Converts 8-bit text into either 8-bit non-utf8-bit or unicode utf8-bit string. May return undef on memory allocation failure.
Same as CORE::mkdir.
CORE::mkdir
Same as POSIX::open
POSIX::open
Returns directory handle to be used on readdir, closedir, rewinddir, telldir, seekdir.
readdir
closedir
rewinddir
telldir
seekdir
Same as CORE::rename
CORE::rename
Same as CORE::rmdir
CORE::rmdir
Directly sets environment variable, possibly bypassing %ENV , depending on how perl is built. Also disregards the thread-local environment on Win32.
Note that effective synchronization between this call and %ENV is not always possible, since Win32 perl implementation simply does not allow that. One is advised to assign to %ENV manually, but only if both NAME and VAL don't have their utf8 bit set, otherwise perl will warn about wide characters.
Same as CORE::stat, except on systems that provide sub-second time resolution, in which case returns the atime/mtime/ctime entries as floats, the same as Time::HiRes::stat does.
CORE::stat
Time::HiRes::stat
Converts either 8-bit non-utf8-bit or unicode utf8-bit string into a local encoding. May return undef on memory allocation failure, or if TEXT contains unconvertible characters when FAIL_IF_CANNOT = 1
Same as CORE::unlink.
CORE::unlink
Same as CORE::utime, except on systems that provide sub-second time resolution, in which case returns the atime/mtime/ctime entries as floats, the same as Time::HiRes::utime does.
CORE::utime
Time::HiRes::utime
Dmitry Karasik, <dmitry@karasik.eu.org>.
Prima, Prima::sys::FS.
To install Prima, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Prima
CPAN shell
perl -MCPAN -e shell install Prima
For more information on module installation, please visit the detailed CPAN module installation guide.