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.
14 beep [ FLAGS = mb::Error ]
16 Invokes the system-depended sound and/or visual bell, corresponding
17 to one of following constants:
18 mb::Error
20 mb::Warning
21 mb::Information
22 mb::Question
23 get_gui
25 Returns one of "gui::XXX" constants, reflecting the graphic user
26 interface used in the system:
27 gui::Default
29 gui::PM
30 gui::Windows
31 gui::XLib
32 gui::GTK
33 get_os
35 Returns one of "apc::XXX" constants, reflecting the platfrom.
36 Currently, the list of the supported platforms is:
37 apc::Win32
39 apc::Unix
40 find_image PATH
42 Converts PATH from perl module notation into a file path, and
43 searches for the file in @INC paths set. If a file is found, its
44 full filename is returned; otherwise "undef" is returned.
45 last_error
47 Returns last system error, if any
48 nearest_i NUMBERS
50 Performs " floor($_ + .5) " operation over NUMBERS which can be an
51 array or an arrayref. Returns converted integers that in either an
52 array or an arrayref, depending on the calling syntax.
53 nearest_d NUMBERS
55 Performs " floor($_ * 1e15 + .5) / 1e15 " operation over NUMBERS
56 which can be an array or an arrayref. Returns converted NVs that
57 in either an array or an arrayref, depending on the calling syntax.
58 Used to protect against perl configurations that calculate "sin",
59 "cos" etc with only 15 significant digits in the mantissa.
60 path [ FILE ]
62 If called with no parameters, returns path to a directory, usually
63 ~/.prima, that can be used to contain the user settings of a
64 toolkit module or a program. If FILE is specified, appends it to
65 the path and returns the full file name. In the latter case the
66 path is automatically created by "File::Path::mkpath" unless it
67 already exists.
68 post $SUB, @PARAMS
70 Postpones a call to SUB with PARAMS until the next event loop tick.
71 query_drives_map [ FIRST_DRIVE = "A:" ]
73 Returns anonymous array to drive letters, used by the system.
74 FIRST_DRIVE can be set to other value to start enumeration from.
75 Win32 can probe removable drives there, so to increase
76 responsiveness of the function it might be reasonable to call it
77 with FIRST_DRIVE set to "C:" .
78 If the system supports no drive letters, empty array reference is
80 returned ( unix ).
81 query_drive_type DRIVE
83 Returns one of "dt::XXX" constants, describing the type of drive,
84 where DRIVE is a 1-character string. If there is no such drive, or
85 the system supports no drive letters ( unix ), "dt::None" is
86 returned.
87 dt::None
89 dt::Unknown
90 dt::Floppy
91 dt::HDD
92 dt::Network
93 dt::CDROM
94 dt::Memory
95 sound [ FREQUENCY = 2000, DURATION = 100 ]
97 Issues a tone of FREQUENCY in Hz with DURATION in milliseconds.
98 username
100 Returns the login name of the user. Sometimes is preferred to the
101 perl-provided "getlogin" ( see "getlogin" in perlfunc ) .
102 xcolor COLOR
104 Accepts COLOR string on one of the three formats:
105 #rgb
107 #rrggbb
108 #rrrgggbbb
109 and returns 24-bit RGB integer value.
111
113 Since perl win32 unicode support for files is unexistent, Prima has its
114 own parallel set of functions mimicking native functions, ie "open",
115 "chdir" etc. This means that files with names that cannot be converted
116 to ANSI (ie user-preferred) codepage are not visible in perl, but the
117 functions below mitigate that problem.
118 The following fine points need to be understood prior to using these
120 functions though:
121 • Prima makes a distinction whether scalars have their utf8 bit set
123 or not throughout the whole toolking. For example, text output in
124 both unix and windows is different depending on the bit, treating
125 non-utf8-bit text as locale-specific, and utf8-bit text as unicode.
126 The same model is applied for the file systems.
127 • Perl implementation for native Win32 creates virtual environments
129 for each thread, keeping current directory, environment variables,
130 etc. This means that under Win32 calling "Prima::Utils::chdir" will
131 NOT automatically make "CORE::chdir" assume that value, even if the
132 path is convertable to ANSI. Keep that in mind when mixing Prima
133 and core functions. (To add more confusion, under the unix these
134 two chdirs are identical when the path is fully convertable).
135 • Under unix, reading entries from environment or file system is
137 opportunistic: if is a valid utf8, then it is a utf8 string. Mostly
138 because .UTF-8 locale are default and standard everywhere. Prima
139 ignores $ENV{LANG} here. This is a bit problematic on Perls under
140 5.22 as these don't provide means to check for utf8 string
141 validity, so everything will be slapped a utf8 bit on here --
142 Beware.
143 • Setting environment variables may or may not sync with %ENV ,
145 depending on how perl is built. Also, %ENV will warn when trying
146 to set scalars with utf-8 bit there.
147 access PATH, MODE
149 Same as "POSIX::access".
150 chdir DIR
152 Same as "CORE::chdir" but disregards thread local environment on
153 Win32.
154 chmod PATH, MODE
156 Same as "CORE::chmod"
157 closedir, readdir, rewinddir, seekdir, telldir DIRHANDLE
159 Mimic homonymous perl functions
160 getcwd
162 Same as "Cwd::getcwd"
163 getdir PATH
165 Reads content of PATH directory and returns array of string pairs,
166 where the first item is a file name, and the second is a file type.
167 The file type is a string, one of the following:
169 "fifo" - named pipe
171 "chr" - character special file
172 "dir" - directory
173 "blk" - block special file
174 "reg" - regular file
175 "lnk" - symbolic link
176 "sock" - socket
177 "wht" - whiteout
178 This function was implemented for faster directory reading, to
180 avoid successive call of "stat" for every file.
181 Also, getdir is consistently inclined to treat filenames in utf8,
183 disregarding both perl unicode settings and the locale.
184 getenv NAME
186 Reads directly from environment, possibly bypassing %ENV , and
187 disregarding thread local environment on Win32.
188 link OLDNAME, NEWNAME
190 Same as "CORE::link".
191 local2sv TEXT
193 Converts 8-bit text into either 8-bit non-utf8-bit or unicode
194 utf8-bit string. May return undef on memory allocation failure.
195 mkdir DIR, [ MODE = 0666 ]
197 Same as "CORE::mkdir".
198 open_file PATH, FLAGS
200 Same as "POSIX::open"
201 open_dir PATH
203 Returns directory handle to be used on "readdir", "closedir",
204 "rewinddir", "telldir", "seekdir".
205 rename OLDNAME, NEWNAME
207 Same as "CORE::rename"
208 rmdir PATH
210 Same as "CORE::rmdir"
211 setenv NAME, VAL
213 Directly sets environment variable, possibly bypassing %ENV ,
214 depending on how perl is built. Also disregards thread local
215 environment on Win32.
216 Note that effective synchronization between this call and %ENV is
218 not always possible, since Win32 perl implementation simply does
219 not allow that. One is advised to assign to %ENV manually, but
220 only if both NAME and VAL don't have their utf8 bit set, otherwise
221 perl will warn about wide characters.
222 stat PATH
224 Same as "CORE::stat", except where there is sub-second time
225 resolution provided, returns atime/mtime/ctime entries as floats,
226 same as "Time::HiRes::stat".
227 sv2local TEXT, FAIL_IF_CANNOT = 1
229 Converts either 8-bit non-utf8-bit or unicode utf8-bit string into
230 a local encoding. May return undef on memory allocation failure,
231 or if TEXT contains unconvertible characters when FAIL_IF_CANNOT =
232 1
233 unlink PATH
235 Same as "CORE::unlink".
236 utime ATIME, MTIME, PATH
238 Same as "CORE::utime", except where there is sub-second time
239 resolution provided, accepts atime/mtime/ctime entries as floats,
240 same as "Time::HiRes::utime".
241
243 Dmitry Karasik, <dmitry@karasik.eu.org>.
244
246 Prima, Prima::sys::FS.
247perl v5.36.0 2023-03-20 Prima::Utils(3)