1Prima::Utils(3) User Contributed Perl Documentation Prima::Utils(3)
2
6 Prima::Utils - miscellanneous routines
7
9 The module contains miscellaneous helper routines.
10
12 alarm $TIMEOUT, $SUB, @PARAMS
13 Calls SUB with PARAMS after TIMEOUT milliseconds. Return 0 on
14 failure, and the active timer on success. The timer can be stopped
15 to disarm the alarm.
16 beep [ FLAGS = mb::Error ]
18 Invokes the system-depended sound and/or visual bell, corresponding
19 to one of following constants:
20 mb::Error
22 mb::Warning
23 mb::Information
24 mb::Question
25 get_gui
27 Returns one of "gui::XXX" constants, reflecting the graphic user
28 interface used in the system:
29 gui::Default
31 gui::PM
32 gui::Windows
33 gui::XLib
34 gui::GTK
35 get_os
37 Returns one of "apc::XXX" constants, reflecting the platfrom.
38 Currently, the list of the supported platforms is:
39 apc::Win32
41 apc::Unix
42 find_image PATH
44 Converts PATH from perl module notation into a file path, and
45 searches for the file in @INC paths set. If a file is found, its
46 full filename is returned; otherwise "undef" is returned.
47 last_error
49 Returns last system error, if any
50 nearest_i NUMBERS
52 Performs " floor($_ + .5) " operation over NUMBERS which can be an
53 array or an arrayref. Returns converted integers that in either an
54 array or an arrayref, depending on the calling syntax.
55 nearest_d NUMBERS
57 Performs " floor($_ * 1e15 + .5) / 1e15 " operation over NUMBERS
58 which can be an array or an arrayref. Returns converted NVs that
59 in either an array or an arrayref, depending on the calling syntax.
60 Used to protect against perl configurations that calculate "sin",
61 "cos" etc with only 15 significant digits in the mantissa.
62 path [ FILE ]
64 If called with no parameters, returns path to a directory, usually
65 ~/.prima, that can be used to contain the user settings of a
66 toolkit module or a program. If FILE is specified, appends it to
67 the path and returns the full file name. In the latter case the
68 path is automatically created by "File::Path::mkpath" unless it
69 already exists.
70 post $SUB, @PARAMS
72 Postpones a call to SUB with PARAMS until the next event loop tick.
73 query_drives_map [ FIRST_DRIVE = "A:" ]
75 Returns anonymous array to drive letters, used by the system.
76 FIRST_DRIVE can be set to other value to start enumeration from.
77 Win32 can probe removable drives there, so to increase
78 responsiveness of the function it might be reasonable to call it
79 with FIRST_DRIVE set to "C:" .
80 If the system supports no drive letters, empty array reference is
82 returned ( unix ).
83 query_drive_type DRIVE
85 Returns one of "dt::XXX" constants, describing the type of drive,
86 where DRIVE is a 1-character string. If there is no such drive, or
87 the system supports no drive letters ( unix ), "dt::None" is
88 returned.
89 dt::None
91 dt::Unknown
92 dt::Floppy
93 dt::HDD
94 dt::Network
95 dt::CDROM
96 dt::Memory
97 sleep SECONDS
99 Same as perl's native "sleep" (i.e. "CORE::sleep") but with the
100 event loop running. Note that the argument it takes is seconds,
101 for the sake of compatibility, while the rest of the toolkit
102 operates in milliseconds.
103 sound [ FREQUENCY = 2000, DURATION = 100 ]
105 Issues a tone of FREQUENCY in Hz with DURATION in milliseconds.
106 username
108 Returns the login name of the user. Sometimes is preferred to the
109 perl-provided "getlogin" ( see "getlogin" in perlfunc ) .
110 xcolor COLOR
112 Accepts COLOR string on one of the three formats:
113 #rgb
115 #rrggbb
116 #rrrgggbbb
117 and returns 24-bit RGB integer value.
119 wait CONDITION [, TIMEOUT ]
121 Waits for a condition for max TIMEOUT milliseconds, or forever if
122 TIMEOUT is undefined.
123 Returns undef on failure, 0 on TIMEOUT, 1 on successful CONDITION.
125 CONDITION is either a scalar reference, or a sub to be polled,
127 where their values are treated as 0 as a signal to continue the
128 wait, and 1 as a stop signal.
129
131 Since perl win32 unicode support for files is unexistent, Prima has its
132 own parallel set of functions mimicking native functions, ie "open",
133 "chdir" etc. This means that files with names that cannot be converted
134 to ANSI (ie user-preferred) codepage are not visible in perl, but the
135 functions below mitigate that problem.
136 The following fine points need to be understood prior to using these
138 functions though:
139 • Prima makes a distinction whether scalars have their utf8 bit set
141 or not throughout the whole toolking. For example, text output in
142 both unix and windows is different depending on the bit, treating
143 non-utf8-bit text as locale-specific, and utf8-bit text as unicode.
144 The same model is applied for the file systems.
145 • Perl implementation for native Win32 creates virtual environments
147 for each thread, keeping current directory, environment variables,
148 etc. This means that under Win32 calling "Prima::Utils::chdir" will
149 NOT automatically make "CORE::chdir" assume that value, even if the
150 path is convertable to ANSI. Keep that in mind when mixing Prima
151 and core functions. (To add more confusion, under the unix these
152 two chdirs are identical when the path is fully convertable).
153 • Under unix, reading entries from environment or file system is
155 opportunistic: if is a valid utf8, then it is a utf8 string. Mostly
156 because .UTF-8 locale are default and standard everywhere. Prima
157 ignores $ENV{LANG} here. This is a bit problematic on Perls under
158 5.22 as these don't provide means to check for utf8 string
159 validity, so everything will be slapped a utf8 bit on here --
160 Beware.
161 • Setting environment variables may or may not sync with %ENV ,
163 depending on how perl is built. Also, %ENV will warn when trying
164 to set scalars with utf-8 bit there.
165 access PATH, MODE
167 Same as "POSIX::access".
168 chdir DIR
170 Same as "CORE::chdir" but disregards thread local environment on
171 Win32.
172 chmod PATH, MODE
174 Same as "CORE::chmod"
175 closedir, readdir, rewinddir, seekdir, telldir DIRHANDLE
177 Mimic homonymous perl functions
178 getcwd
180 Same as "Cwd::getcwd"
181 getdir PATH
183 Reads content of PATH directory and returns array of string pairs,
184 where the first item is a file name, and the second is a file type.
185 The file type is a string, one of the following:
187 "fifo" - named pipe
189 "chr" - character special file
190 "dir" - directory
191 "blk" - block special file
192 "reg" - regular file
193 "lnk" - symbolic link
194 "sock" - socket
195 "wht" - whiteout
196 This function was implemented for faster directory reading, to
198 avoid successive call of "stat" for every file.
199 Also, getdir is consistently inclined to treat filenames in utf8,
201 disregarding both perl unicode settings and the locale.
202 getenv NAME
204 Reads directly from environment, possibly bypassing %ENV , and
205 disregarding thread local environment on Win32.
206 link OLDNAME, NEWNAME
208 Same as "CORE::link".
209 local2sv TEXT
211 Converts 8-bit text into either 8-bit non-utf8-bit or unicode
212 utf8-bit string. May return undef on memory allocation failure.
213 mkdir DIR, [ MODE = 0666 ]
215 Same as "CORE::mkdir".
216 open_file PATH, FLAGS
218 Same as "POSIX::open"
219 open_dir PATH
221 Returns directory handle to be used on "readdir", "closedir",
222 "rewinddir", "telldir", "seekdir".
223 rename OLDNAME, NEWNAME
225 Same as "CORE::rename"
226 rmdir PATH
228 Same as "CORE::rmdir"
229 setenv NAME, VAL
231 Directly sets environment variable, possibly bypassing %ENV ,
232 depending on how perl is built. Also disregards thread local
233 environment on Win32.
234 Note that effective synchronization between this call and %ENV is
236 not always possible, since Win32 perl implementation simply does
237 not allow that. One is advised to assign to %ENV manually, but
238 only if both NAME and VAL don't have their utf8 bit set, otherwise
239 perl will warn about wide characters.
240 stat PATH
242 Same as "CORE::stat", except where there is sub-second time
243 resolution provided, returns atime/mtime/ctime entries as floats,
244 same as "Time::HiRes::stat".
245 sv2local TEXT, FAIL_IF_CANNOT = 1
247 Converts either 8-bit non-utf8-bit or unicode utf8-bit string into
248 a local encoding. May return undef on memory allocation failure,
249 or if TEXT contains unconvertible characters when FAIL_IF_CANNOT =
250 1
251 unlink PATH
253 Same as "CORE::unlink".
254 utime ATIME, MTIME, PATH
256 Same as "CORE::utime", except where there is sub-second time
257 resolution provided, accepts atime/mtime/ctime entries as floats,
258 same as "Time::HiRes::utime".
259
261 Dmitry Karasik, <dmitry@karasik.eu.org>.
262
264 Prima, Prima::sys::FS.
265perl v5.38.0 2023-07-21 Prima::Utils(3)