7 PSPP - Perl extension to PSPP
15 PSPP:: provides an interface to the libraries used by pspp to create
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 a variable from a dictionary
100 my $var = pxs_get_variable ($dict, $idx);
104 bless ($var, "PSPP::Var");
116 Contains constants used to denote variable format types.
117 The identifiers are the same as those used in pspp to denote formats.
118 For example C<PSPP::Fmt::F> defines floating point format, and
119 C<PSPP::Fmt::A> denotes string format.
123 # These must correspond to the values in src/data/format.h
169 =head3 new ($dict, $name, %input_fmt)
171 Creates and returns a new variable in the dictionary C<dict>. The
172 new variable will have the name C<name>.
173 The input format is set by the C<input_fmt> parameter
175 By default, the write and print formats are the same as the input format.
176 The write and print formats may be changed (See L</set_write_format>),
177 L</set_print_format>). The input format may not be changed after
178 the variable has been created.
179 If the variable cannot be created, undef is returned.
189 my $self = pxs_dict_create_var ($dict, $name, \%format);
192 bless ($self, $class);
199 =head3 set_label ($label)
201 Sets the variable label to C<label>.
208 =head3 set_write_format (%fmt)
210 Sets the write format to C<fmt>. <fmt> is a hash containing the keys:
216 A constant denoting the format type. See L</PSPP::Fmt>.
220 An integer denoting the number of decimal places for the format.
224 An integer denoting the number of width of the format.
228 On error the subroutine returns zero.
236 pxs_set_write_format ($var, \%format);
241 =head3 set_print_format (%fmt)
243 Sets the print format to C<fmt>.
244 On error the subroutine returns zero.
252 pxs_set_print_format ($var, \%format);
257 =head3 set_output_format (%fmt)
259 Sets the write and print formats to C<fmt>. This is the same as
260 calling set_write_format followed by set_print_format.
261 On error the subroutine returns zero.
266 sub set_output_format
270 pxs_set_output_format ($var, \%format);
275 =head3 clear_value_labels ()
277 Removes all value labels from the variable.
284 =head3 add_value_label ($key, $label)
286 Adds the value label C<label> to the variable for the value C<key>.
287 On error the subroutine returns zero.
289 =head3 add_value_labels (@array)
300 while ( @li = each %values )
302 if ( $var->add_value_label ($li[0], "$li[1]") )
313 =head3 set_value_labels ($key, $value)
315 C<Set_value_labels> is identical to calling L</clear_value_labels>
316 followed by L</add_value_labels>.
317 On error the subroutine returns zero.
325 $self->clear_value_labels () ;
326 $self->add_value_labels (%labels);
331 =head3 set_missing_values ($val1 [, $val2[, $val3] ])
333 Sets the missing values for the variable.
334 No more than three missing values may be specified.
339 package PSPP::Sysfile;
345 =head3 new ($filename, $dict [,%opts])
347 Creates a new system file from the dictionary C<dict>. The file will
348 be written to the file called C<filename>.
349 C<opt>, if specified, is a hash containing optional parameters for the
350 system file. Currently, the only supported parameter is
351 C<compress>. If C<compress> is non zero, then the system file written
352 will be in the compressed format.
353 On error, undef is returned.
356 =head3 append_case (@case)
358 Appends a case to the system file.
359 C<Case> is an array of scalars, each of which are the values of
360 the variables in the dictionary corresponding to the system file.
361 The special value C<PSPP::SYSMIS> may be used to indicate that a value
363 If the array contains less elements than variables in the dictionary,
364 remaining values will be set to system missing.
371 my $filename = shift;
375 my $self = pxs_create_sysfile ($filename, $dict, $opts);
379 bless ($self, $class);
388 Closes the system file.
390 This subroutine closes the system file and flushes it to disk. No
391 further cases may be written once the file has been closed.
392 The system file will be automatically closed when it goes out of scope.
396 package PSPP::Reader;
401 my $filename = shift;
403 my $self = pxs_open_sysfile ($filename);
407 bless ($self, $class);
417 my $dict = pxs_get_dict ($reader);
419 bless ($dict, "PSPP::Dict");
432 John Darrington, E<lt>john@darrington.wattle.id.auE<gt>
434 =head1 COPYRIGHT AND LICENSE
436 Copyright (C) 2007 by Free Software Foundation
438 This program is free software; you can redistribute it and/or
439 modify it under the terms of the GNU General Public License as
440 published by the Free Software Foundation; either version 2 of the
441 License, or (at your option) any later version.
443 This program is distributed in the hope that it will be useful, but
444 WITHOUT ANY WARRANTY; without even the implied warranty of
445 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
446 General Public License for more details.
448 You should have received a copy of the GNU General Public License
449 along with this program; if not, write to the Free Software
450 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA