7 PSPP-Perl - Perl extension to PSPP
15 PSPP-Perl provides an interface to the libraries used by pspp to read and
24 do 'pspp-vers.pl' || die "No version set";
26 XSLoader::load('PSPP', $PSPP::VERSION);
29 PSPP::onBoot($PSPP::VERSION);
33 =head1 PROGRAMMER'S INTERFACE
35 The subroutines in this package return zero or unref on error.
36 When errors occur, a string describing the error is written
44 use constant { SYSMIS => -(POSIX::DBL_MAX),
45 PERL_EPOCH => 12219379200 # Number of seconds between
57 =head2 PSPP::Dict::new
59 Creates a new dictionary. This returned dictionary will be empty.
60 Returns undef on failure.
62 =head3 set_documents ($string)
64 Sets the documents (comments) to C<string>.
66 =head3 add_document ($string)
68 Appends C<string> to the documents.
70 =head3 clear_documents ()
72 Removes all documents.
74 =head3 set_weight ($var)
76 Sets the weighting variable to C<var>.
83 my $self = pxs_dict_new ();
84 bless ($self, $class);
92 Returns the C<idx>th variable from the dictionary.
100 my $var = pxs_get_variable ($dict, $idx);
104 bless ($var, "PSPP::Var");
111 =head3 get_var_by_name ($name)
113 Returns the variable from the dictionary whose name is C<name>.
114 If there is no such variable, a null reference will be returned.
122 my $var = pxs_get_var_by_name ($dict, $name);
126 bless ($var, "PSPP::Var");
138 Contains constants used to denote variable format types.
139 The identifiers are the same as those used in pspp to denote formats.
140 For example C<PSPP::Fmt::F> defines floating point format, and
141 C<PSPP::Fmt::A> denotes string format.
145 # These must correspond to the values in src/data/format.h
191 =head3 new ($dict, $name, %input_fmt)
193 Creates and returns a new variable in the dictionary C<dict>. The
194 new variable will have the name C<name>.
195 The input format is set by the C<input_fmt> parameter
197 By default, the write and print formats are the same as the input format.
198 The write and print formats may be changed (See L</set_write_format>),
199 L</set_print_format>). The input format may not be changed after
200 the variable has been created.
201 If the variable cannot be created, undef is returned.
211 my $self = pxs_dict_create_var ($dict, $name, \%format);
214 bless ($self, $class);
221 =head3 set_label ($label)
223 Sets the variable label to C<label>.
230 =head3 set_write_format (%fmt)
232 Sets the write format to C<fmt>. <fmt> is a hash containing the keys:
238 A constant denoting the format type. See L</PSPP::Fmt>.
242 An integer denoting the number of decimal places for the format.
246 An integer denoting the number of width of the format.
250 On error the subroutine returns zero.
258 pxs_set_write_format ($var, \%format);
263 =head3 set_print_format (%fmt)
265 Sets the print format to C<fmt>.
266 On error the subroutine returns zero.
274 pxs_set_print_format ($var, \%format);
279 =head3 set_output_format (%fmt)
281 Sets the write and print formats to C<fmt>. This is the same as
282 calling set_write_format followed by set_print_format.
283 On error the subroutine returns zero.
288 sub set_output_format
292 pxs_set_output_format ($var, \%format);
297 =head3 clear_value_labels ()
299 Removes all value labels from the variable.
306 =head3 add_value_label ($key, $label)
308 Adds the value label C<label> to the variable for the value C<key>.
309 On error the subroutine returns zero.
311 =head3 add_value_labels (@array)
322 while ( @li = each %values )
324 if ( $var->add_value_label ($li[0], "$li[1]") )
335 =head3 set_value_labels ($key, $value)
337 C<Set_value_labels> is identical to calling L</clear_value_labels>
338 followed by L</add_value_labels>.
339 On error the subroutine returns zero.
347 $self->clear_value_labels () ;
348 $self->add_value_labels (%labels);
353 =head3 set_missing_values ($val1 [, $val2[, $val3] ])
355 Sets the missing values for the variable.
356 No more than three missing values may be specified.
360 Returns the name of the variable.
364 Returns the label of the variable or undef if there is no label.
366 =head3 get_value_labels ()
368 Returns a reference to a hash containing the value labels for the variable.
369 The hash is keyed by data values which correpond to the labels.
373 package PSPP::Sysfile;
379 =head3 new ($filename, $dict [,%opts])
381 Creates a new system file from the dictionary C<dict>. The file will
382 be written to the file called C<filename>.
383 C<opt>, if specified, is a hash containing optional parameters for the
384 system file. Currently, the only supported parameter is
385 C<compress>. If C<compress> is non zero, then the system file written
386 will be in the compressed format.
387 On error, undef is returned.
390 =head3 append_case (@case)
392 Appends a case to the system file.
393 C<Case> is an array of scalars, each of which are the values of
394 the variables in the dictionary corresponding to the system file.
395 The special value C<PSPP::SYSMIS> may be used to indicate that a value
397 If the array contains less elements than variables in the dictionary,
398 remaining values will be set to system missing.
405 my $filename = shift;
409 my $self = pxs_create_sysfile ($filename, $dict, $opts);
413 bless ($self, $class);
422 Closes the system file.
424 This subroutine closes the system file and flushes it to disk. No
425 further cases may be written once the file has been closed.
426 The system file will be automatically closed when it goes out of scope.
430 package PSPP::Reader;
441 my $filename = shift;
443 my $self = pxs_open_sysfile ($filename);
447 bless ($self, $class);
454 =head3 open ($filename)
456 Opens a system file for reading.
458 Open is used to read data from an existing system file.
459 It creates and returns a PSPP::Reader object which can be used to read
460 data and dictionary information from <C>filename.
468 my $dict = pxs_get_dict ($reader);
470 bless ($dict, "PSPP::Dict");
479 Returns the dictionary associated with the reader.
481 =head3 get_next_case ()
483 Retrieves the next case from the reader.
484 This method returns an array of scalars, each of which are the values of
485 the data in the system file.
486 The first call to <C>get_next_case after <C>open has been called retrieves
487 the first case in the system file. Each subsequent call retrieves the next
488 case. If there are no more cases to be read, the function returns undef.
490 If the case contains system missing values, these values are set to the
493 =head2 Miscellaneous subroutines
495 The following subroutines provide (hopefully) useful information about the
496 values retrieved from a reader.
498 =head3 PSPP::format_value ($value, $variable)
500 Returns a scalar containing a string representing C<value> formatted accoring
501 to the print format of C<variable>.
502 In the most common ussage, C<value> should be a value of C<variable>.
505 =head3 PSPP::value_is_missing ($value, $variable)
507 Returns non-zero if C<value> is either system missing, or if it matches the
508 user missing criteria for C<variable>.
518 John Darrington, E<lt>john@darrington.wattle.id.auE<gt>
520 =head1 COPYRIGHT AND LICENSE
522 Copyright (C) 2007, 2008 by Free Software Foundation
524 This program is free software: you can redistribute it and/or modify
525 it under the terms of the GNU General Public License as published by
526 the Free Software Foundation, either version 3 of the License, or
527 (at your option) any later version.
529 This program is distributed in the hope that it will be useful,
530 but WITHOUT ANY WARRANTY; without even the implied warranty of
531 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
532 GNU General Public License for more details.
534 You should have received a copy of the GNU General Public License
535 along with this program. If not, see <http://www.gnu.org/licenses/>.