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 ceil DOUBLE
42 Obsolete function.
43 Returns stdlib's ceil() of DOUBLE
45 find_image PATH
47 Converts PATH from perl module notation into a file path, and
48 searches for the file in @INC paths set. If a file is found, its
49 full filename is returned; otherwise "undef" is returned.
50 floor DOUBLE
52 Obsolete function.
53 Returns stdlib's floor() of DOUBLE
55 last_error
57 Returns last system error, if any
58 path [ FILE ]
60 If called with no parameters, returns path to a directory, usually
61 ~/.prima, that can be used to contain the user settings of a
62 toolkit module or a program. If FILE is specified, appends it to
63 the path and returns the full file name. In the latter case the
64 path is automatically created by "File::Path::mkpath" unless it
65 already exists.
66 post $SUB, @PARAMS
68 Postpones a call to SUB with PARAMS until the next event loop tick.
69 query_drives_map [ FIRST_DRIVE = "A:" ]
71 Returns anonymous array to drive letters, used by the system.
72 FIRST_DRIVE can be set to other value to start enumeration from.
73 Win32 can probe removable drives there, so to increase
74 responsiveness of the function it might be reasonable to call it
75 with FIRST_DRIVE set to "C:" .
76 If the system supports no drive letters, empty array reference is
78 returned ( unix ).
79 query_drive_type DRIVE
81 Returns one of "dt::XXX" constants, describing the type of drive,
82 where DRIVE is a 1-character string. If there is no such drive, or
83 the system supports no drive letters ( unix ), "dt::None" is
84 returned.
85 dt::None
87 dt::Unknown
88 dt::Floppy
89 dt::HDD
90 dt::Network
91 dt::CDROM
92 dt::Memory
93 sound [ FREQUENCY = 2000, DURATION = 100 ]
95 Issues a tone of FREQUENCY in Hz with DURATION in milliseconds.
96 username
98 Returns the login name of the user. Sometimes is preferred to the
99 perl-provided "getlogin" ( see "getlogin" in perlfunc ) .
100 xcolor COLOR
102 Accepts COLOR string on one of the three formats:
103 #rgb
105 #rrggbb
106 #rrrgggbbb
107 and returns 24-bit RGB integer value.
109
111 Since perl win32 unicode support for files is unexistent, Prima has its
112 own parallel set of functions mimicking native functions, ie "open",
113 "chdir" etc. This means that files with names that cannot be converted
114 to ANSI (ie user-preferred) codepage are not visible in perl, but the
115 functions below mitigate that problem.
116 The following fine points need to be understood prior to using these
118 functions though:
119 • Prima makes a distinction whether scalars have their utf8 bit set
121 or not throughout the whole toolking. For example, text output in
122 both unix and windows is different depending on the bit, treating
123 non-utf8-bit text as locale-specific, and utf8-bit text as unicode.
124 The same model is applied for the file systems.
125 • Perl implementation for native Win32 creates virtual environments
127 for each thread, keeping current directory, environment variables,
128 etc. This means that under Win32 calling "Prima::Utils::chdir" will
129 NOT automatically make "CORE::chdir" assume that value, even if the
130 path is convertable to ANSI. Keep that in mind when mixing Prima
131 and core functions. (To add more confusion, under the unix these
132 two chdirs are identical when the path is fully convertable).
133 • Under unix, reading entries from environment or file system is
135 opportunistic: if is a valid utf8, then it is a utf8 string. Mostly
136 because .UTF-8 locale are default and standard everywhere. Prima
137 ignores $ENV{LANG} here. This is a bit problematic on Perls under
138 5.22 as these don't provide means to check for utf8 string
139 validity, so everything will be slapped a utf8 bit on here --
140 Beware.
141 • Setting environment variables may or may not sync with %ENV ,
143 depending on how perl is built. Also, %ENV will warn when trying
144 to set scalars with utf-8 bit there.
145 access PATH, MODE
147 Same as "POSIX::access".
148 chdir DIR
150 Same as "CORE::chdir" but disregards thread local environment on
151 Win32.
152 chmod PATH, MODE
154 Same as "CORE::chmod"
155 closedir, readdir, rewinddir, seekdir, telldir DIRHANDLE
157 Mimic homonymous perl functions
158 getcwd
160 Same as "Cwd::getcwd"
161 getdir PATH
163 Reads content of PATH directory and returns array of string pairs,
164 where the first item is a file name, and the second is a file type.
165 The file type is a string, one of the following:
167 "fifo" - named pipe
169 "chr" - character special file
170 "dir" - directory
171 "blk" - block special file
172 "reg" - regular file
173 "lnk" - symbolic link
174 "sock" - socket
175 "wht" - whiteout
176 This function was implemented for faster directory reading, to
178 avoid successive call of "stat" for every file.
179 Also, getdir is consistently inclined to treat filenames in utf8,
181 disregarding both perl unicode settings and the locale.
182 getenv NAME
184 Reads directly from environment, possibly bypassing %ENV , and
185 disregarding thread local environment on Win32.
186 link OLDNAME, NEWNAME
188 Same as "CORE::link".
189 local2sv TEXT
191 Converts 8-bit text into either 8-bit non-utf8-bit or unicode
192 utf8-bit string. May return undef on memory allocation failure.
193 mkdir DIR, [ MODE = 0666 ]
195 Same as "CORE::mkdir".
196 open_file PATH, FLAGS
198 Same as "POSIX::open"
199 open_dir PATH
201 Returns directory handle to be used on "readdir", "closedir",
202 "rewinddir", "telldir", "seekdir".
203 rename OLDNAME, NEWNAME
205 Same as "CORE::rename"
206 rmdir PATH
208 Same as "CORE::rmdir"
209 setenv NAME, VAL
211 Directly sets environment variable, possibly bypassing %ENV ,
212 depending on how perl is built. Also disregards thread local
213 environment on Win32.
214 Note that effective synchronization between this call and %ENV is
216 not always possible, since Win32 perl implementation simply does
217 not allow that. One is advised to assign to %ENV manually, but
218 only if both NAME and VAL don't have their utf8 bit set, otherwise
219 perl will warn about wide characters.
220 stat PATH
222 Same as "CORE::stat", except where there is sub-second time
223 resolution provided, returns atime/mtime/ctime entries as floats,
224 same as "Time::HiRes::stat".
225 sv2local TEXT, FAIL_IF_CANNOT = 1
227 Converts either 8-bit non-utf8-bit or unicode utf8-bit string into
228 a local encoding. May return undef on memory allocation failure,
229 or if TEXT contains unconvertible characters when FAIL_IF_CANNOT =
230 1
231 unlink PATH
233 Same as "CORE::unlink".
234 utime ATIME, MTIME, PATH
236 Same as "CORE::utime", except where there is sub-second time
237 resolution provided, accepts atime/mtime/ctime entries as floats,
238 same as "Time::HiRes::utime".
239
241 Dmitry Karasik, <dmitry@karasik.eu.org>.
242
244 Prima, Prima::sys::FS.
245perl v5.34.1 2022-04-20 Prima::Utils(3)