value-parser: Remove redundant call to lex_force_string() in parse_value().
[pspp-builds.git] / 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     TIME =>     29, 
183     DTIME =>    30, 
184     WKDAY =>    31, 
185     MONTH =>    32, 
186     A =>        33, 
187     AHEX =>     34
188 };
189
190
191 =head2 PSPP::Var
192
193 =cut
194
195 package PSPP::Var;
196
197 =head3 new ($dict, $name, %input_fmt)
198
199 Creates and returns a new variable in the dictionary C<dict>.  The 
200 new variable will have the name C<name>.  C<name> must be a valid UTF8 string.
201 The input format is set by the C<input_fmt> parameter 
202 (See L</PSPP::Fmt>).
203 By default, the write and print formats are the same as the input format.
204 The write and print formats may be changed (See L</set_write_format>), 
205 L</set_print_format>).  The input format may not be changed after
206 the variable has been created.
207 If the variable cannot be created, undef is returned.
208
209 =cut
210
211 sub new
212 {
213     my $class = shift;
214     my $dict = shift;
215     my $name = shift;
216     my %format = @_;
217     my $self = pxs_dict_create_var ($dict, $name, \%format);
218     if ( ref $self ) 
219     {
220         bless ($self, $class);
221     }
222     return $self;
223 }
224
225 =pod
226
227 =head3 set_label ($label)
228
229 Sets the variable label to C<label>, which must be a valid UTF8 string.
230
231
232 =cut
233
234 =pod
235
236 =head3 set_write_format (%fmt)
237
238 Sets the write format to C<fmt>. <fmt> is a hash containing the keys:
239
240 =over 2
241
242 =item FMT
243
244 A constant denoting the format type.  See L</PSPP::Fmt>.
245
246 =item decimals
247
248 An integer denoting the number of decimal places for the format.
249
250 =item width
251
252 An integer denoting the width of the format.
253
254 =back
255
256 On error the subroutine returns zero.
257
258 =cut
259
260 sub set_write_format
261 {
262     my $var = shift;
263     my %format = @_;
264     pxs_set_write_format ($var, \%format);
265 }
266
267 =pod
268
269 =head3 set_print_format (%fmt)
270
271 Sets the print format to C<fmt>.
272 On error the subroutine returns zero.
273
274 =cut
275
276 sub set_print_format
277 {
278     my $var = shift;
279     my %format = @_;
280     pxs_set_print_format ($var, \%format);
281 }
282
283 =pod
284
285
286 =head3 get_write_format ()
287
288 Returns a reference to a hash containing the write format for the variable.
289
290
291 =head3 get_print_format ()
292
293 Returns a reference to a hash containing the print format for the variable.
294
295 =head3 set_output_format (%fmt)
296
297 Sets the write and print formats to C<fmt>.  This is the same as
298 calling set_write_format followed by set_print_format.
299 On error the subroutine returns zero.
300
301 =cut
302
303
304 sub set_output_format
305 {
306     my $var = shift;
307     my %format = @_;
308     pxs_set_output_format ($var, \%format);
309 }
310
311 =pod
312
313 =head3 clear_value_labels ()
314
315 Removes all value labels from the variable.
316
317 =cut
318
319
320 =pod
321
322 =head3 add_value_label ($key, $label)
323
324 Adds the value label C<label> to the variable for the value C<key>.
325 C<label> must be a valid UTF8 string.
326 On error the subroutine returns zero.
327
328 =head3 add_value_labels (@array)
329
330 =cut
331
332 sub add_value_labels
333 {
334     my $var = shift;
335     my %values = @_;
336     my @li;
337
338     my $n = 0;
339     while ( @li = each %values ) 
340     {
341         if ( $var->add_value_label ($li[0], "$li[1]") ) 
342         {
343             $n++;
344         }
345     }
346
347     return $n;
348 }
349
350 =pod
351
352 =head3 set_value_labels ($key, $label)
353
354 C<Set_value_labels> is identical to calling L</clear_value_labels>
355 followed by L</add_value_labels>.
356 On error the subroutine returns zero.
357
358 =cut
359
360 sub set_value_labels
361 {
362     my $self = shift;
363     my %labels = @_;
364     $self->clear_value_labels () ;
365     $self->add_value_labels (%labels);
366 }
367
368 =pod
369
370 =head3 set_missing_values ($val1 [, $val2[, $val3] ])
371
372 Sets the missing values for the variable.  
373 No more than three missing values may be specified.
374
375 =head3 get_attributes()
376
377 Returns a reference to a hash of the custom variable attributes.
378 Each value of the hash is a reference to an array containing the 
379 attribute values.
380
381 =head3 get_name ()
382
383 Returns the name of the variable.
384
385 =head3 get_label ()
386
387 Returns the label of the variable or undef if there is no label.
388
389 =head3 get_value_labels ()
390
391 Returns a reference to a hash containing the value labels for the variable.
392 The hash is keyed by data values which correpond to the labels.
393
394 =cut
395
396 package PSPP::Sysfile;
397
398 =pod
399
400 =head2 PSPP::Sysfile
401
402 =head3 new ($filename, $dict [,%opts])
403
404 Creates a new system file from the dictionary C<dict>.  The file will
405 be written to the file called C<filename>.
406 C<opt>, if specified, is a hash containing optional parameters for the
407 system file.  Currently, the only supported parameter is
408 C<compress>. If C<compress> is non zero, then the system file written
409 will be in the compressed format.
410 On error, undef is returned.
411
412
413 =head3 append_case (@case)
414
415 Appends a case to the system file.
416 C<Case> is an array of scalars, each of which are the values of 
417 the variables in the dictionary corresponding to the system file.
418 If the case contains strings, then the strings must be UTF8 encoded.
419 The special value C<PSPP::SYSMIS> may be used to indicate that a value
420 is system missing.
421 If the array contains less elements than variables in the dictionary,
422 remaining values will be set to system missing.
423
424 =cut
425
426 sub new
427 {
428     my $class = shift;
429     my $filename = shift;
430     my $dict = shift;
431     my $opts = shift;
432
433     my $self  = pxs_create_sysfile ($filename, $dict, $opts);
434
435     if ( ref $self ) 
436     {
437         bless ($self, $class);
438     }
439     return $self;
440 }
441
442 =pod
443
444 =head3 close ()
445
446 Closes the system file.
447
448 This subroutine closes the system file and flushes it to disk.  No
449 further cases may be written once the file has been closed.
450 The system file will be automatically closed when it goes out of scope.
451
452 =cut
453
454 package PSPP::Reader;
455
456 =pod
457
458 =head2 PSPP::Reader
459
460 =cut
461
462 sub open
463 {
464     my $class = shift;
465     my $filename = shift;
466
467     my $self  = pxs_open_sysfile ($filename);
468
469     if ( ref $self ) 
470     {
471         bless ($self, $class);
472     }
473     return $self;
474 }
475
476 =pod
477
478 =head3 open ($filename)
479
480 Opens a system file for reading.
481
482 Open is used to read data from an existing system file. 
483 It creates and returns a PSPP::Reader object which can be used to read 
484 data and dictionary information from C<filename>.
485
486 =cut
487
488 sub get_dict
489 {
490     my $reader = shift;
491
492     my $dict = pxs_get_dict ($reader);
493
494     bless ($dict, "PSPP::Dict");
495
496     return $dict;
497 }
498
499 =pod
500
501 =head3 get_dict ()
502
503 Returns the dictionary associated with the reader.
504
505 =head3 get_next_case ()
506
507 Retrieves the next case from the reader.
508 This method returns an array of scalars, each of which are the values of 
509 the data in the system file.
510 The first call to C<get_next_case> after C<open> has been called retrieves
511 the first case in the system file.  Each subsequent call retrieves the next
512 case.  If there are no more cases to be read, the function returns an empty
513 list.
514
515 If the case contains system missing values, these values are set to the 
516 empty string.
517
518 =head2 Miscellaneous subroutines
519
520 The following subroutines provide (hopefully) useful information about the 
521 values retrieved from a reader.
522
523 =head3 PSPP::format_value ($value, $variable)
524
525 Returns a scalar containing a string representing C<value> formatted according 
526 to the print format of C<variable>.
527 In the most common usage,  C<value> should be a value of C<variable>.
528
529
530 =head3 PSPP::value_is_missing ($value, $variable)
531
532 Returns non-zero if C<value> is either system missing, or if it matches the 
533 user missing criteria for C<variable>.
534
535 =cut
536
537 1;
538 __END__
539
540
541 =head1 AUTHOR
542
543 John Darrington, E<lt>john@darrington.wattle.id.auE<gt>
544
545 =head1 COPYRIGHT AND LICENSE
546
547 Copyright (C) 2007, 2008, 2009 by Free Software Foundation
548
549 This program is free software: you can redistribute it and/or modify
550 it under the terms of the GNU General Public License as published by
551 the Free Software Foundation, either version 3 of the License, or
552 (at your option) any later version.
553
554 This program is distributed in the hope that it will be useful,
555 but WITHOUT ANY WARRANTY; without even the implied warranty of
556 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
557 GNU General Public License for more details.
558
559 You should have received a copy of the GNU General Public License
560 along with this program.  If not, see <http://www.gnu.org/licenses/>.
561
562 =cut