1Prima::Utils(3) User Contributed Perl Documentation Prima::Utils(3)
2
6 Prima::Utils - miscellanneous routines
7
9 The module contains several helper routines, implemented in both C and
10 perl. Whereas the C-coded parts are accessible only if 'use Prima;'
11 statement was issued prior to the 'use Prima::Utils' invocation, the
12 perl-coded are always available. This makes the module valuable when
13 used without the rest of toolkit code.
14
16 alarm $TIMEOUT, $SUB, @PARAMS
17 Calls SUB with PARAMS after TIMEOUT milliseconds.
18 beep [ FLAGS = mb::Error ]
20 Invokes the system-depended sound and/or visual bell, corresponding
21 to one of following constants:
22 mb::Error
24 mb::Warning
25 mb::Information
26 mb::Question
27 get_gui
29 Returns one of "gui::XXX" constants, reflecting the graphic user
30 interface used in the system:
31 gui::Default
33 gui::PM
34 gui::Windows
35 gui::XLib
36 gui::GTK
37 get_os
39 Returns one of "apc::XXX" constants, reflecting the platfrom.
40 Currently, the list of the supported platforms is:
41 apc::Win32
43 apc::Unix
44 ceil DOUBLE
46 Obsolete function.
47 Returns stdlib's ceil() of DOUBLE
49 find_image PATH
51 Converts PATH from perl module notation into a file path, and
52 searches for the file in @INC paths set. If a file is found, its
53 full filename is returned; otherwise "undef" is returned.
54 floor DOUBLE
56 Obsolete function.
57 Returns stdlib's floor() of DOUBLE
59 last_error
61 Returns last system error, if any
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 Some OSes can probe eventual diskette drives inside the drive
78 enumeration routines, so there is a chance to increase
79 responsiveness of the function it might be reasonable to set
80 FIRST_DRIVE to "C:" string.
81 If the system supports no drive letters, empty array reference is
83 returned ( unix ).
84 query_drive_type DRIVE
86 Returns one of "dt::XXX" constants, describing the type of drive,
87 where DRIVE is a 1-character string. If there is no such drive, or
88 the system supports no drive letters ( unix ), "dt::None" is
89 returned.
90 dt::None
92 dt::Unknown
93 dt::Floppy
94 dt::HDD
95 dt::Network
96 dt::CDROM
97 dt::Memory
98 sound [ FREQUENCY = 2000, DURATION = 100 ]
100 Issues a tone of FREQUENCY in Hz with DURATION in milliseconds.
101 username
103 Returns the login name of the user. Sometimes is preferred to the
104 perl-provided "getlogin" ( see "getlogin" in perlfunc ) .
105 xcolor COLOR
107 Accepts COLOR string on one of the three formats:
108 #rgb
110 #rrggbb
111 #rrrgggbbb
112 and returns 24-bit RGB integer value.
114
116 Since perl win32 unicode support for files is unexistent, Prima has its
117 own parallel set of functions mimicking native functions, ie open,
118 chdir etc. This means that files with names that cannot be converted to
119 ANSI (ie user-preferred ) codepage are not visible in perl, but the
120 functions below mitigate that problem.
121 The following fine points need to be understood prior to using these
123 functions though:
124 • Prima makes a distinction whether scalars have their utf8 bit set
126 or not throughout the whole toolking. For example, text output in
127 both unix and windows is different depending on the bit, treating
128 non-utf8-bit text as locale-specific, and utf8-bit text as unicode.
129 The same model is applied for the file systems.
130 • Perl implementation for native Win32 creates virtual environments
132 for each thread, keeping current directory, environment variables,
133 etc. This means that under Win32 calling "Prima::Utils::chdir" will
134 NOT automatically make "CORE::chdir" assume that value, even if the
135 path is convertable to ANSI. Keep that in mind when mixing Prima
136 and core functions. (To add more confusion, under the unix these
137 two chdirs are identical when the path is fully convertable).
138 • Under unix, reading entries from environment or file system is
140 opportunistic: if is a valid utf8, then it is a utf8 string. Mostly
141 because .UTF-8 locale are default and standard everywhere. Prima
142 ignores $ENV{LANG} here. This is a bit problematic on Perls under
143 5.22 as these don't provide means to check for utf8 string
144 validity, so everything will be slapped a utf8 bit on here --
145 beware.
146 access PATH, MODE
148 Same as "POSIX::access".
149 chdir DIR
151 Same as "CORE::chdir" but disregards thread local environment on
152 Win32.
153 chmod PATH, MODE
155 Same as "CORE::chmod"
156 closedir, readdir, rewinddir, seekdir, telldir DIRHANDLE
158 Mimic homonymous perl functions
159 getcwd
161 Same as "Cwd::getcwd"
162 getdir PATH
164 Reads content of PATH directory and returns array of string pairs,
165 where the first item is a file name, and the second is a file type.
166 The file type is a string, one of the following:
168 "fifo" - named pipe
170 "chr" - character special file
171 "dir" - directory
172 "blk" - block special file
173 "reg" - regular file
174 "lnk" - symbolic link
175 "sock" - socket
176 "wht" - whiteout
177 This function was implemented for faster directory reading, to
179 avoid successive call of "stat" for every file.
180 Also, getdir is consistently inclined to treat filenames in utf8,
182 disregarding both perl unicode settings and the locale.
183 getenv NAME
185 Same as reading from $ENV{$NAME} but disregards thread local
186 environment on Win32.
187 link OLDNAME, NEWNAME
189 Same as "CORE::link".
190 local2sv TEXT
192 Converts 8-bit text into either 8-bit non-utf8-bit or unicode
193 utf8-bit string. May return undef on memory allocation failure.
194 mkdir DIR, [ MODE = 0666 ]
196 Same as "CORE::mkdir".
197 open_file PATH, FLAGS
199 Same as "POSIX::open"
200 open_dir PATH
202 Returns directory handle to be used on "readdir", "closedir",
203 "rewinddir", "telldir", "seekdir".
204 rename OLDNAME, NEWNAME
206 Same as "CORE::rename"
207 rmdir PATH
209 Same as "CORE::rmdir"
210 setenv NAME, VAL
212 Same as setting " $ENV{$NAME} = $VAL " but disregards thread local
213 environment on Win32.
214 stat PATH
216 Same as "CORE::stat", except where there is sub-second time
217 resolution provided, returns atime/mtime/ctime entries as floats,
218 same as "Time::HiRes::stat".
219 sv2local TEXT, FAIL_IF_CANNOT = 1
221 Converts either 8-bit non-utf8-bit or unicode utf8-bit string into
222 a local encoding. May return undef on memory allocation failure,
223 or if TEXT contains unconvertible characters when FAIL_IF_CANNOT =
224 1
225 unlink PATH
227 Same as "CORE::unlink".
228 utime ATIME, MTIME, PATH
230 Same as "CORE::utime", except where there is sub-second time
231 resolution provided, returns atime/mtime/ctime entries as floats,
232 same as "Time::HiRes::utime".
233
235 Dmitry Karasik, <dmitry@karasik.eu.org>.
236
238 Prima, Prima::sys::FS.
239perl v5.34.0 2021-07-22 Prima::Utils(3)