Prima::Utils - miscellanneous routines
The module contains several helper routines, implemented in both C and perl. Whereas the C-coded parts are accessible only if 'use Prima;' statement was issued prior to the 'use Prima::Utils' invocation, the perl-coded are always available. This makes the module valuable when used without the rest of toolkit code.
Calls SUB with PARAMS after TIMEOUT milliseconds.
Invokes the system-depended sound and/or visual bell, corresponding to one of following constants:
mb::Error mb::Warning mb::Information mb::Question
Returns one of gui::XXX constants, reflecting the graphic user interface used in the system:
gui::XXX
gui::Default gui::PM gui::Windows gui::XLib gui::GTK
Returns one of apc::XXX constants, reflecting the platfrom. Currently, the list of the supported platforms is:
apc::XXX
apc::Win32 apc::Unix
Obsolete function.
Returns stdlib's ceil() of DOUBLE
Converts PATH from perl module notation into a file path, and searches for the file in @INC paths set. If a file is found, its full filename is returned; otherwise undef is returned.
@INC
undef
Returns stdlib's floor() of DOUBLE
Returns last system error, if any
If called with no parameters, returns path to a directory, usually ~/.prima, that can be used to contain 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 anonymous array to drive letters, used by the system. FIRST_DRIVE can be set to other value to start enumeration from. Some OSes can probe eventual diskette drives inside the drive enumeration routines, so there is a chance to increase responsiveness of the function it might be reasonable to set FIRST_DRIVE to C: string.
C:
If the system supports no drive letters, empty array reference is returned ( unix ).
Returns one of dt::XXX constants, describing the type of 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
Issues a tone of FREQUENCY in Hz with DURATION in milliseconds.
Returns the login name of the user. Sometimes is preferred to the perl-provided getlogin ( see "getlogin" in perlfunc ) .
getlogin
Accepts COLOR string on one of the three formats:
#rgb #rrggbb #rrrgggbbb
and returns 24-bit RGB integer value.
Since perl 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.
The following fine points need to be understood prior to using these functions though:
Prima makes a distinction whether scalars have their utf8 bit set or not throughout the whole toolking. 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 for the file systems.
Perl implementation for native Win32 creates virtual environments for each thread, keeping 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 convertable to ANSI. Keep that in mind when mixing Prima and core functions. (To add more confusion, under the unix these two chdirs are identical when the path is fully convertable).
Prima::Utils::chdir
CORE::chdir
Under unix, reading entries from environment or file system is opportunistic: if is a valid utf8, then it is a utf8 string. Mostly because .UTF-8 locale are default and standard everywhere. Prima ignores $ENV{LANG} here. This is a bit problematic on Perls under 5.22 as these don't provide means to check for utf8 string validity, so everything will be slapped a utf8 bit on here -- beware.
$ENV{LANG}
Same as POSIX::access.
POSIX::access
Same as CORE::chdir but disregards thread local environment on Win32.
Same as CORE::chmod
CORE::chmod
Mimic homonymous perl functions
Same as Cwd::getcwd
Cwd::getcwd
Reads content of PATH directory 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 call of stat for every file.
stat
Also, getdir is consistently inclined to treat filenames in utf8, disregarding both perl unicode settings and the locale.
Same as reading from $ENV{$NAME} but disregards thread local environment on Win32.
$ENV{$NAME}
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
Same as setting $ENV{$NAME} = $VAL but disregards thread local environment on Win32.
$ENV{$NAME} = $VAL
Same as CORE::stat, except where there is sub-second time resolution provided, returns atime/mtime/ctime entries as floats, same as Time::HiRes::stat.
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 where there is sub-second time resolution provided, returns atime/mtime/ctime entries as floats, same as Time::HiRes::utime.
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.