10 our @ISA = qw(Exporter Tie::Hash);
11 # Items to export into callers namespace by default. Note: do not export
12 # names by default without a very good reason. Use EXPORT_OK instead.
13 # Do not simply export all your public functions/methods/constants.
15 AnyIni UserIni SystemIni
17 our $VERSION = '0.03';
19 XSLoader::load 'OS2::PrfDB', $VERSION;
21 # Preloaded methods go here.
24 new_from_int OS2::PrfDB::Hini OS2::Prf::System(0),
25 'Anyone of two "systemish" databases', 1;
29 new_from_int OS2::PrfDB::Hini OS2::Prf::System(1), 'User settings database', 1;
33 new_from_int OS2::PrfDB::Hini OS2::Prf::System(2),'System settings database',1;
36 # Internal structure 0 => HINI, 1 => array of entries, 2 => iterator.
39 die "Usage: tie %arr, OS2::PrfDB, filename\n" unless @_ == 2;
40 my ($obj, $file) = @_;
41 my $hini = ref $file eq 'OS2::PrfDB::Hini' ? $file
42 : new OS2::PrfDB::Hini $file;
43 die "Error opening profile database `$file': $!" unless $hini;
44 # print "tiehash `@_', hini $hini\n" if $debug;
45 bless [$hini, undef, undef];
49 my ($self, $key, $val) = @_;
51 die unless ref $val eq 'HASH';
53 tie %sub, 'OS2::PrfDB::Sub', $self->[0], $key;
58 my ($self, $key) = @_;
61 tie %sub, 'OS2::PrfDB::Sub', $self->[0], $key;
66 my ($self, $key) = @_;
69 tie %sub, 'OS2::PrfDB::Sub', $self->[0], $key;
73 # CLEAR ???? - deletion of the whole
76 my ($self, $key) = @_;
78 return OS2::Prf::GetLength($self->[0]->[0], $key, undef) >= 0;
83 my $keys = OS2::Prf::Get($self->[0]->[0], undef, undef);
84 return undef unless defined $keys;
86 $self->[1] = [split /\0/, $keys];
87 # print "firstkey1 $self, `$self->[3]->[0], $self->[3]->[1]'\n" if $debug;
89 return $self->[1]->[0];
90 # OS2::Prf::Get($self->[0]->[0], $self->[2], $self->[3]->[0]));
94 # print "nextkey `@_'\n" if $debug;
96 return undef unless $self->[2]++ < $#{$self->[1]};
97 my $key = $self->[1]->[$self->[2]];
98 return $key; #, OS2::Prf::Get($self->[0]->[0], $self->[2], $key));
101 package OS2::PrfDB::Hini;
104 die "Usage: new OS2::PrfDB::Hini filename\n" unless @_ == 2;
107 my $hini = OS2::Prf::Open($file);
108 die "Error opening profile database `$file': $!" unless $hini;
109 bless [$hini, $file];
112 # Takes HINI and file name:
114 sub new_from_int { shift; bless [@_] }
116 # Internal structure 0 => HINI, 1 => filename, 2 => do-not-close.
120 my $hini = $self->[0];
121 unless ($self->[2]) {
122 OS2::Prf::Close($hini) or die "Error closing profile `$self->[1]': $!";
126 package OS2::PrfDB::Sub;
130 our @ISA = qw{Tie::Hash};
132 # Internal structure 0 => HINI, 1 => array of entries, 2 => iterator,
136 die "Usage: tie %arr, OS2::PrfDB::Sub, filename, appname\n" unless @_ == 3;
137 my ($obj, $file, $app) = @_;
138 my $hini = ref $file eq 'OS2::PrfDB::Hini' ? $file
139 : new OS2::PrfDB::Hini $file;
140 die "Error opening profile database `$file': $!" unless $hini;
141 # print "tiehash `@_', hini $hini\n" if $debug;
142 bless [$hini, undef, undef, $app];
146 my ($self, $key, $val) = @_;
148 OS2::Prf::Set($self->[0]->[0], $self->[3], $key, $val);
152 my ($self, $key) = @_;
154 OS2::Prf::Get($self->[0]->[0], $self->[3], $key);
158 my ($self, $key) = @_;
160 OS2::Prf::Set($self->[0]->[0], $self->[3], $key, undef);
163 # CLEAR ???? - deletion of the whole
166 my ($self, $key) = @_;
168 return OS2::Prf::GetLength($self->[0]->[0], $self->[3], $key) >= 0;
173 my $keys = OS2::Prf::Get($self->[0]->[0], $self->[3], undef);
174 return undef unless defined $keys;
176 $self->[1] = [split /\0/, $keys];
177 # print "firstkey1 $self, `$self->[3]->[0], $self->[3]->[1]'\n" if $debug;
179 return $self->[1]->[0];
180 # OS2::Prf::Get($self->[0]->[0], $self->[2], $self->[3]->[0]));
184 # print "nextkey `@_'\n" if $debug;
186 return undef unless $self->[2]++ < $#{$self->[1]};
187 my $key = $self->[1]->[$self->[2]];
188 return $key; #, OS2::Prf::Get($self->[0]->[0], $self->[2], $key));
191 # Autoload methods go after =cut, and are processed by the autosplit program.
195 # Below is the stub of documentation for your module. You better edit it!
199 OS2::PrfDB - Perl extension for access to OS/2 setting database.
204 tie %settings, OS2::PrfDB, 'my.ini';
205 tie %subsettings, OS2::PrfDB::Sub, 'my.ini', 'mykey';
207 print "$settings{firstkey}{subkey}\n";
208 print "$subsettings{subkey}\n";
210 tie %system, OS2::PrfDB, SystemIni;
211 $system{myapp}{mykey} = "myvalue";
216 The extention provides both high-level and low-level access to .ini
219 =head2 High level access
221 High-level access is the tie-hash access via two packages:
222 C<OS2::PrfDB> and C<OS2::PrfDB::Sub>. First one supports one argument,
223 the name of the file to open, the second one the name of the file to
224 open and so called I<Application name>, or the primary key of the
227 tie %settings, OS2::PrfDB, 'my.ini';
228 tie %subsettings, OS2::PrfDB::Sub, 'my.ini', 'mykey';
230 One may substitute a handle for already opened ini-file instead of the
231 file name (obtained via low-level access functions). In particular, 3
232 functions SystemIni(), UserIni(), and AnyIni() provide handles to the
233 "systemish" databases. AniIni will read from both, and write into User
236 =head2 Low-level access
238 Low-level access functions reside in the package C<OS2::Prf>. They are
244 Opens the database, returns an I<integer handle>.
248 Closes the database given an I<integer handle>.
250 =item C<Get(hndl, appname, key)>
252 Retrieves data from the database given 2-part-key C<appname> C<key>.
253 If C<key> is C<undef>, return the "\0" delimited list of C<key>s,
254 terminated by \0. If C<appname> is C<undef>, returns the list of
255 possible C<appname>s in the same form.
257 =item C<GetLength(hndl, appname, key)>
259 Same as above, but returns the length of the value.
261 =item C<Set(hndl, appname, key, value [ , length ])>
263 Sets the value. If the C<value> is not defined, removes the C<key>. If
264 the C<key> is not defined, removes the C<appname>.
268 Return an I<integer handle> associated with the system database. If
269 C<val> is 1, it is I<User> database, if 2, I<System> database, if
270 0, handle for "both" of them: the handle works for read from any one,
271 and for write into I<User> one.
275 returns a reference to a list of two strings, giving names of the
276 I<User> and I<System> databases.
278 =item C<SetUser(file)>
280 B<(Not tested.)> Sets the profile name of the I<User> database. The
281 application should have a message queue to use this function!
285 =head2 Integer handles
287 To convert a name or an integer handle into an object acceptable as
288 argument to tie() interface, one may use the following functions from
289 the package C<OS2::Prf::Hini>:
293 =item C<new(package, file)>
295 =item C<new_from_int(package, int_hndl [ , filename ])>
301 SystemIni(), UserIni(), and AnyIni().
305 Ilya Zakharevich, ilya@math.ohio-state.edu