 |
|
| |
Prima::Utils(3) |
User Contributed Perl Documentation |
Prima::Utils(3) |
Prima::Utils - miscellanneous routines
The module contains miscellaneous helper routines.
- alarm $TIMEOUT, $SUB, @PARAMS
- Calls SUB with PARAMS after TIMEOUT milliseconds.
- beep [ FLAGS = mb::Error ]
- Invokes the system-depended sound and/or visual bell, corresponding to one
of following constants:
mb::Error
mb::Warning
mb::Information
mb::Question
- get_gui
- Returns one of "gui::XXX" constants,
reflecting the graphic user interface used in the system:
gui::Default
gui::PM
gui::Windows
gui::XLib
gui::GTK
- get_os
- Returns one of "apc::XXX" constants,
reflecting the platfrom. Currently, the list of the supported platforms
is:
apc::Win32
apc::Unix
- ceil DOUBLE
- Obsolete function.
Returns stdlib's ceil() of DOUBLE
- find_image PATH
- 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.
- floor DOUBLE
- Obsolete function.
Returns stdlib's floor() of DOUBLE
- last_error
- Returns last system error, if any
- path [ FILE ]
- 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.
- post $SUB, @PARAMS
- Postpones a call to SUB with PARAMS until the next event loop tick.
- query_drives_map [ FIRST_DRIVE = "A:" ]
- Returns anonymous array to drive letters, used by the system. FIRST_DRIVE
can be set to other value to start enumeration from. Win32 can probe
removable drives there, so to increase responsiveness of the function it
might be reasonable to call it with FIRST_DRIVE set to
"C:" .
If the system supports no drive letters, empty array reference
is returned ( unix ).
- query_drive_type DRIVE
- 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::None
dt::Unknown
dt::Floppy
dt::HDD
dt::Network
dt::CDROM
dt::Memory
- sound [ FREQUENCY = 2000, DURATION = 100 ]
- Issues a tone of FREQUENCY in Hz with DURATION in milliseconds.
- username
- Returns the login name of the user. Sometimes is preferred to the
perl-provided "getlogin" ( see
"getlogin" in perlfunc ) .
- xcolor COLOR
- 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).
- 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.
- 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.
- access PATH, MODE
- Same as "POSIX::access".
- chdir DIR
- Same as "CORE::chdir" but disregards
thread local environment on Win32.
- chmod PATH, MODE
- Same as "CORE::chmod"
- closedir, readdir, rewinddir, seekdir, telldir DIRHANDLE
- Mimic homonymous perl functions
- getcwd
- Same as "Cwd::getcwd"
- getdir PATH
- 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.
Also, getdir is consistently inclined to treat filenames in
utf8, disregarding both perl unicode settings and the locale.
- getenv NAME
- Reads directly from environment, possibly bypassing %ENV
, and disregarding thread local environment on Win32.
- link OLDNAME, NEWNAME
- Same as "CORE::link".
- local2sv TEXT
- Converts 8-bit text into either 8-bit non-utf8-bit or unicode utf8-bit
string. May return undef on memory allocation failure.
- mkdir DIR, [ MODE = 0666 ]
- Same as "CORE::mkdir".
- open_file PATH, FLAGS
- Same as "POSIX::open"
- open_dir PATH
- Returns directory handle to be used on
"readdir",
"closedir",
"rewinddir",
"telldir",
"seekdir".
- rename OLDNAME, NEWNAME
- Same as "CORE::rename"
- rmdir PATH
- Same as "CORE::rmdir"
- setenv NAME, VAL
- Directly sets environment variable, possibly bypassing
%ENV , depending on how perl is built. Also disregards 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.
- stat PATH
- 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".
- sv2local TEXT, FAIL_IF_CANNOT = 1
- 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
- unlink PATH
- Same as "CORE::unlink".
- utime ATIME, MTIME, PATH
- Same as "CORE::utime", except where
there is sub-second time resolution provided, accepts atime/mtime/ctime
entries as floats, same as
"Time::HiRes::utime".
Dmitry Karasik, <dmitry@karasik.eu.org>.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc.
|