7 PSPP-Perl - Perl extension to PSPP
15 PSPP-Perl provides an interface to the libraries used by pspp to read and
24 $PSPP::VERSION='0.7.2';
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 number of variables in the dictionary.
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.
106 my $var = pxs_get_variable ($dict, $idx);
110 bless ($var, "PSPP::Var");
117 =head3 get_var_by_name ($name)
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.
128 my $var = pxs_get_var_by_name ($dict, $name);
132 bless ($var, "PSPP::Var");
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.
151 # These must correspond to the values in src/data/format.h
197 =head3 new ($dict, $name, %input_fmt)
199 Creates and returns a new variable in the dictionary C<dict>. The
200 new variable will have the name C<name>.
201 The input format is set by the C<input_fmt> parameter
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.
217 my $self = pxs_dict_create_var ($dict, $name, \%format);
220 bless ($self, $class);
227 =head3 set_label ($label)
229 Sets the variable label to C<label>.
236 =head3 set_write_format (%fmt)
238 Sets the write format to C<fmt>. <fmt> is a hash containing the keys:
244 A constant denoting the format type. See L</PSPP::Fmt>.
248 An integer denoting the number of decimal places for the format.
252 An integer denoting the width of the format.
256 On error the subroutine returns zero.
264 pxs_set_write_format ($var, \%format);
269 =head3 set_print_format (%fmt)
271 Sets the print format to C<fmt>.
272 On error the subroutine returns zero.
280 pxs_set_print_format ($var, \%format);
286 =head3 get_write_format ()
288 Returns a reference to a hash containing the write format for the variable.
291 =head3 get_print_format ()
293 Returns a reference to a hash containing the print format for the variable.
295 =head3 set_output_format (%fmt)
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.
304 sub set_output_format
308 pxs_set_output_format ($var, \%format);
313 =head3 clear_value_labels ()
315 Removes all value labels from the variable.
322 =head3 add_value_label ($key, $label)
324 Adds the value label C<label> to the variable for the value C<key>.
325 On error the subroutine returns zero.
327 =head3 add_value_labels (@array)
338 while ( @li = each %values )
340 if ( $var->add_value_label ($li[0], "$li[1]") )
351 =head3 set_value_labels ($key, $value)
353 C<Set_value_labels> is identical to calling L</clear_value_labels>
354 followed by L</add_value_labels>.
355 On error the subroutine returns zero.
363 $self->clear_value_labels () ;
364 $self->add_value_labels (%labels);
369 =head3 set_missing_values ($val1 [, $val2[, $val3] ])
371 Sets the missing values for the variable.
372 No more than three missing values may be specified.
374 =head3 get_attributes()
376 Returns a reference to a hash of the custom variable attributes.
377 Each value of the hash is a reference to an array containing the
382 Returns the name of the variable.
386 Returns the label of the variable or undef if there is no label.
388 =head3 get_value_labels ()
390 Returns a reference to a hash containing the value labels for the variable.
391 The hash is keyed by data values which correpond to the labels.
395 package PSPP::Sysfile;
401 =head3 new ($filename, $dict [,%opts])
403 Creates a new system file from the dictionary C<dict>. The file will
404 be written to the file called C<filename>.
405 C<opt>, if specified, is a hash containing optional parameters for the
406 system file. Currently, the only supported parameter is
407 C<compress>. If C<compress> is non zero, then the system file written
408 will be in the compressed format.
409 On error, undef is returned.
412 =head3 append_case (@case)
414 Appends a case to the system file.
415 C<Case> is an array of scalars, each of which are the values of
416 the variables in the dictionary corresponding to the system file.
417 The special value C<PSPP::SYSMIS> may be used to indicate that a value
419 If the array contains less elements than variables in the dictionary,
420 remaining values will be set to system missing.
427 my $filename = shift;
431 my $self = pxs_create_sysfile ($filename, $dict, $opts);
435 bless ($self, $class);
444 Closes the system file.
446 This subroutine closes the system file and flushes it to disk. No
447 further cases may be written once the file has been closed.
448 The system file will be automatically closed when it goes out of scope.
452 package PSPP::Reader;
463 my $filename = shift;
465 my $self = pxs_open_sysfile ($filename);
469 bless ($self, $class);
476 =head3 open ($filename)
478 Opens a system file for reading.
480 Open is used to read data from an existing system file.
481 It creates and returns a PSPP::Reader object which can be used to read
482 data and dictionary information from C<filename>.
490 my $dict = pxs_get_dict ($reader);
492 bless ($dict, "PSPP::Dict");
501 Returns the dictionary associated with the reader.
503 =head3 get_next_case ()
505 Retrieves the next case from the reader.
506 This method returns an array of scalars, each of which are the values of
507 the data in the system file.
508 The first call to C<get_next_case> after C<open> has been called retrieves
509 the first case in the system file. Each subsequent call retrieves the next
510 case. If there are no more cases to be read, the function returns an empty
513 If the case contains system missing values, these values are set to the
516 =head2 Miscellaneous subroutines
518 The following subroutines provide (hopefully) useful information about the
519 values retrieved from a reader.
521 =head3 PSPP::format_value ($value, $variable)
523 Returns a scalar containing a string representing C<value> formatted according
524 to the print format of C<variable>.
525 In the most common ussage, C<value> should be a value of C<variable>.
528 =head3 PSPP::value_is_missing ($value, $variable)
530 Returns non-zero if C<value> is either system missing, or if it matches the
531 user missing criteria for C<variable>.
541 John Darrington, E<lt>john@darrington.wattle.id.auE<gt>
543 =head1 COPYRIGHT AND LICENSE
545 Copyright (C) 2007, 2008, 2009 by Free Software Foundation
547 This program is free software: you can redistribute it and/or modify
548 it under the terms of the GNU General Public License as published by
549 the Free Software Foundation, either version 3 of the License, or
550 (at your option) any later version.
552 This program is distributed in the hope that it will be useful,
553 but WITHOUT ANY WARRANTY; without even the implied warranty of
554 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
555 GNU General Public License for more details.
557 You should have received a copy of the GNU General Public License
558 along with this program. If not, see <http://www.gnu.org/licenses/>.