format: Always output 2-digit hours for TIME format.
[pspp] / perl-module / lib / PSPP.pm.in
1 use 5.008008;
2 use strict;
3 use warnings;
4
5 =head1 NAME
6
7 PSPP-Perl - Perl extension to PSPP
8
9 =head1 SYNOPSIS
10
11   use PSPP;
12
13 =head1 DESCRIPTION
14
15 PSPP-Perl provides an interface to the libraries used by pspp to read and
16 write system files.  
17
18 =head1 EXPORT
19
20 None by default.
21
22 =cut
23 BEGIN {
24         $PSPP::VERSION='@VERSION_FOR_PERL@';
25         require XSLoader;
26         XSLoader::load('PSPP', $PSPP::VERSION);
27 }
28
29 PSPP::onBoot($PSPP::VERSION);
30
31 =pod
32
33 =head1 PROGRAMMER'S INTERFACE
34
35 The subroutines in this package return zero or unref on error.
36 When errors occur, a string describing the error is written 
37 to C<$PSPP::errstr>. 
38
39 =cut
40
41 package PSPP;
42 use POSIX ;
43
44 use constant { SYSMIS => -(POSIX::DBL_MAX), 
45                PERL_EPOCH => 12219379200 # Number of seconds between 
46                    # 14th October 1582
47                    # and 
48                    # 1st January 1970 
49                };
50
51
52
53 package PSPP::Dict;
54
55 =pod
56
57 =head2 PSPP::Dict::new
58
59 Creates a new dictionary.  This returned dictionary will be empty.
60 Returns undef on failure.
61
62 =head3 set_documents ($string)
63
64 Sets the documents (comments) to C<string>.
65
66 =head3 add_document ($string)
67
68 Appends C<string> to the documents.
69
70 =head3 clear_documents ()
71
72 Removes all documents.
73
74 =head3 set_weight ($var)
75
76 Sets the weighting variable to C<var>.
77
78 =cut
79
80 sub new
81 {
82     my $class = shift;
83     my $self = pxs_dict_new ();
84     bless ($self, $class);
85     return $self;
86 }
87
88 =pod
89
90 =head3 get_var_cnt ()
91
92 Returns the number of variables in the dictionary.
93
94 =head3 get_var ($idx)
95
96 Returns the C<idx>th variable from the dictionary.
97 Returns undef if C<idx> is greater than or equal to the number
98 of variables in the dictionary.
99
100 =cut
101
102 sub get_var
103 {
104     my $dict = shift;
105     my $idx = shift;
106     my $var = pxs_get_variable ($dict, $idx);
107
108     if ( ref $var ) 
109     {
110         bless ($var, "PSPP::Var");
111     }
112     return $var;
113 }
114
115 =pod
116
117 =head3 get_var_by_name ($name)
118
119 Returns the variable from the dictionary whose name is C<name>.
120 If there is no such variable, a null reference will be returned.
121
122 =cut
123
124 sub get_var_by_name
125 {
126     my $dict = shift;
127     my $name = shift;
128     my $var = pxs_get_var_by_name ($dict, $name);
129
130     if ( ref $var ) 
131     {
132         bless ($var, "PSPP::Var");
133     }
134     return $var;
135 }
136
137
138 package PSPP::Fmt;
139
140 =pod
141
142 =head2 PSPP::Fmt
143
144 Contains constants used to denote variable format types.  
145 The identifiers are the same as  those used in pspp to denote formats.
146 For  example C<PSPP::Fmt::F> defines floating point format, and
147 C<PSPP::Fmt::A> denotes string format.
148
149 =cut
150
151 # These must correspond to the values in src/data/format.h
152 use constant {
153     F =>        0,
154     COMMA =>    1,
155     DOT =>      2, 
156     DOLLAR =>   3, 
157     PCT =>      4, 
158     E =>        5, 
159     CCA =>      6, 
160     CCB =>      7, 
161     CCC =>      8, 
162     CCD =>      9, 
163     CCE =>      10, 
164     N =>        11, 
165     Z =>        12, 
166     P =>        13, 
167     PK =>       14, 
168     IB =>       15, 
169     PIB =>      16, 
170     PIBHEX =>   17, 
171     RB =>       18, 
172     RBHEX =>    19, 
173     DATE =>     20, 
174     ADATE =>    21, 
175     EDATE =>    22, 
176     JDATE =>    23, 
177     SDATE =>    24, 
178     QYR =>      25, 
179     MOYR =>     26, 
180     WKYR =>     27, 
181     DATETIME => 28, 
182     YMDHMS =>   29, 
183     MTIME =>    30, 
184     TIME =>     31, 
185     DTIME =>    32, 
186     WKDAY =>    33, 
187     MONTH =>    34, 
188     A =>        35, 
189     AHEX =>     36
190 };
191
192
193 =head2 PSPP::Var
194
195 =cut
196
197 package PSPP::Var;
198
199 =head3 new ($dict, $name, %input_fmt)
200
201 Creates and returns a new variable in the dictionary C<dict>.  The 
202 new variable will have the name C<name>.  C<name> must be a valid UTF8 string.
203 The input format is set by the C<input_fmt> parameter 
204 (See L</PSPP::Fmt>).
205 By default, the write and print formats are the same as the input format.
206 The write and print formats may be changed (See L</set_write_format>), 
207 L</set_print_format>).  The input format may not be changed after
208 the variable has been created.
209 If the variable cannot be created, undef is returned.
210
211 =cut
212
213 sub new
214 {
215     my $class = shift;
216     my $dict = shift;
217     my $name = shift;
218     my %format = @_;
219     my $self = pxs_dict_create_var ($dict, $name, \%format);
220     if ( ref $self ) 
221     {
222         bless ($self, $class);
223     }
224     return $self;
225 }
226
227 =pod
228
229 =head3 set_label ($label)
230
231 Sets the variable label to C<label>, which must be a valid UTF8 string.
232
233
234 =cut
235
236 =pod
237
238 =head3 set_write_format (%fmt)
239
240 Sets the write format to C<fmt>. <fmt> is a hash containing the keys:
241
242 =over 2
243
244 =item FMT
245
246 A constant denoting the format type.  See L</PSPP::Fmt>.
247
248 =item decimals
249
250 An integer denoting the number of decimal places for the format.
251
252 =item width
253
254 An integer denoting the width of the format.
255
256 =back
257
258 On error the subroutine returns zero.
259
260 =cut
261
262 sub set_write_format
263 {
264     my $var = shift;
265     my %format = @_;
266     pxs_set_write_format ($var, \%format);
267 }
268
269 =pod
270
271 =head3 set_print_format (%fmt)
272
273 Sets the print format to C<fmt>.
274 On error the subroutine returns zero.
275
276 =cut
277
278 sub set_print_format
279 {
280     my $var = shift;
281     my %format = @_;
282     pxs_set_print_format ($var, \%format);
283 }
284
285 =pod
286
287
288 =head3 get_write_format ()
289
290 Returns a reference to a hash containing the write format for the variable.
291
292
293 =head3 get_print_format ()
294
295 Returns a reference to a hash containing the print format for the variable.
296
297 =head3 set_output_format (%fmt)
298
299 Sets the write and print formats to C<fmt>.  This is the same as
300 calling set_write_format followed by set_print_format.
301 On error the subroutine returns zero.
302
303 =cut
304
305
306 sub set_output_format
307 {
308     my $var = shift;
309     my %format = @_;
310     pxs_set_output_format ($var, \%format);
311 }
312
313 =pod
314
315 =head3 clear_value_labels ()
316
317 Removes all value labels from the variable.
318
319 =cut
320
321
322 =pod
323
324 =head3 add_value_label ($key, $label)
325
326 Adds the value label C<label> to the variable for the value C<key>.
327 C<label> must be a valid UTF8 string.
328 On error the subroutine returns zero.
329
330 =head3 add_value_labels (@array)
331
332 =cut
333
334 sub add_value_labels
335 {
336     my $var = shift;
337     my %values = @_;
338     my @li;
339
340     my $n = 0;
341     while ( @li = each %values ) 
342     {
343         if ( $var->add_value_label ($li[0], "$li[1]") ) 
344         {
345             $n++;
346         }
347     }
348
349     return $n;
350 }
351
352 =pod
353
354 =head3 set_value_labels ($key, $label)
355
356 C<Set_value_labels> is identical to calling L</clear_value_labels>
357 followed by L</add_value_labels>.
358 On error the subroutine returns zero.
359
360 =cut
361
362 sub set_value_labels
363 {
364     my $self = shift;
365     my %labels = @_;
366     $self->clear_value_labels () ;
367     $self->add_value_labels (%labels);
368 }
369
370 =pod
371
372 =head3 set_missing_values ($val1 [, $val2[, $val3] ])
373
374 Sets the missing values for the variable.  
375 No more than three missing values may be specified.
376
377 =head3 get_attributes()
378
379 Returns a reference to a hash of the custom variable attributes.
380 Each value of the hash is a reference to an array containing the 
381 attribute values.
382
383 =head3 get_name ()
384
385 Returns the name of the variable.
386
387 =head3 get_label ()
388
389 Returns the label of the variable or undef if there is no label.
390
391 =head3 get_value_labels ()
392
393 Returns a reference to a hash containing the value labels for the variable.
394 The hash is keyed by data values which correpond to the labels.
395
396 =cut
397
398 package PSPP::Sysfile;
399
400 =pod
401
402 =head2 PSPP::Sysfile
403
404 =head3 new ($filename, $dict [,%opts])
405
406 Creates a new system file from the dictionary C<dict>.  The file will
407 be written to the file called C<filename>. The string C<filename> must 
408 be encoded in UTF-8.
409 C<opt>, if specified, is a hash containing optional parameters for the
410 system file.  Currently, the only supported parameter is
411 C<compress>. If C<compress> is non zero, then the system file written
412 will be in the compressed format.
413 On error, undef is returned.
414
415
416 =head3 append_case (@case)
417
418 Appends a case to the system file.
419 C<Case> is an array of scalars, each of which are the values of 
420 the variables in the dictionary corresponding to the system file.
421 If the case contains strings, then the strings must be UTF8 encoded.
422 The special value C<PSPP::SYSMIS> may be used to indicate that a value
423 is system missing.
424 If the array contains less elements than variables in the dictionary,
425 remaining values will be set to system missing.
426
427 =cut
428
429 sub new
430 {
431     my $class = shift;
432     my $filename = shift;
433     my $dict = shift;
434     my $opts = shift;
435
436     my $self  = pxs_create_sysfile ($filename, $dict, $opts);
437
438     if ( ref $self ) 
439     {
440         bless ($self, $class);
441     }
442     return $self;
443 }
444
445 =pod
446
447 =head3 close ()
448
449 Closes the system file.
450
451 This subroutine closes the system file and flushes it to disk.  No
452 further cases may be written once the file has been closed.
453 The system file will be automatically closed when it goes out of scope.
454
455 =cut
456
457 package PSPP::Reader;
458
459 =pod
460
461 =head2 PSPP::Reader
462
463 =cut
464
465 sub open
466 {
467     my $class = shift;
468     my $filename = shift;
469
470     my $self  = pxs_open_sysfile ($filename);
471
472     if ( ref $self ) 
473     {
474         bless ($self, $class);
475     }
476     return $self;
477 }
478
479 =pod
480
481 =head3 open ($filename)
482
483 Opens a system file for reading.
484
485 Open is used to read data from an existing system file. 
486 It creates and returns a PSPP::Reader object which can be used to read 
487 data and dictionary information from C<filename>.  The string C<filename> 
488 must be in UTF-8 encoding.
489
490 =head3 get_case_cnt ()
491
492 Returns the number of cases in a open system file.  Some files
493 do not store the number of cases.  In these instances undef
494 will be returned.  Therefore, then programmer must check that the
495 returned value is not undef before using it.
496
497 =cut
498
499 sub get_dict
500 {
501     my $reader = shift;
502
503     my $dict = pxs_get_dict ($reader);
504
505     bless ($dict, "PSPP::Dict");
506
507     return $dict;
508 }
509
510 =pod
511
512 =head3 get_dict ()
513
514 Returns the dictionary associated with the reader.
515
516 =head3 get_next_case ()
517
518 Retrieves the next case from the reader.
519 This method returns an array of scalars, each of which are the values of 
520 the data in the system file.
521 The first call to C<get_next_case> after C<open> has been called retrieves
522 the first case in the system file.  Each subsequent call retrieves the next
523 case.  If there are no more cases to be read, the function returns an empty
524 list.
525
526 If the case contains system missing values, these values are set to the 
527 empty string.
528
529 =head2 Miscellaneous subroutines
530
531 The following subroutines provide (hopefully) useful information about the 
532 values retrieved from a reader.
533
534 =head3 PSPP::format_value ($value, $variable)
535
536 Returns a scalar containing a string representing C<value> formatted according 
537 to the print format of C<variable>.
538 In the most common usage,  C<value> should be a value of C<variable>.
539
540
541 =head3 PSPP::value_is_missing ($value, $variable)
542
543 Returns non-zero if C<value> is either system missing, or if it matches the 
544 user missing criteria for C<variable>.
545
546 =cut
547
548 1;
549 __END__
550
551
552 =head1 AUTHOR
553
554 John Darrington, E<lt>john@darrington.wattle.id.auE<gt>
555
556 =head1 COPYRIGHT AND LICENSE
557
558 Copyright (C) 2007, 2008, 2009 by Free Software Foundation
559
560 This program is free software: you can redistribute it and/or modify
561 it under the terms of the GNU General Public License as published by
562 the Free Software Foundation, either version 3 of the License, or
563 (at your option) any later version.
564
565 This program is distributed in the hope that it will be useful,
566 but WITHOUT ANY WARRANTY; without even the implied warranty of
567 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
568 GNU General Public License for more details.
569
570 You should have received a copy of the GNU General Public License
571 along with this program.  If not, see <http://www.gnu.org/licenses/>.
572
573 =cut