1 ## PSPP - a program for statistical analysis.
2 ## Copyright (C) 2019 Free Software Foundation, Inc.
4 ## This program is free software: you can redistribute it and/or modify
5 ## it under the terms of the GNU General Public License as published by
6 ## the Free Software Foundation, either version 3 of the License, or
7 ## (at your option) any later version.
9 ## This program is distributed in the hope that it will be useful,
10 ## but WITHOUT ANY WARRANTY; without even the implied warranty of
11 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 ## GNU General Public License for more details.
14 ## You should have received a copy of the GNU General Public License
15 ## along with this program. If not, see <http://www.gnu.org/licenses/>.
23 PSPP-Perl - Perl extension to PSPP
31 PSPP-Perl provides an interface to the libraries used by pspp to read and
40 $PSPP::VERSION='@VERSION_FOR_PERL@';
42 XSLoader::load('PSPP', $PSPP::VERSION);
45 PSPP::onBoot($PSPP::VERSION);
49 =head1 PROGRAMMER'S INTERFACE
51 The subroutines in this package return zero or unref on error.
52 When errors occur, a string describing the error is written
60 use constant { SYSMIS => -(POSIX::DBL_MAX),
61 PERL_EPOCH => 12219379200 # Number of seconds between
73 =head2 PSPP::Dict::new
75 Creates a new dictionary. This returned dictionary will be empty.
76 Returns undef on failure.
78 =head3 set_documents ($string)
80 Sets the documents (comments) to C<string>.
82 =head3 add_document ($string)
84 Appends C<string> to the documents.
86 =head3 clear_documents ()
88 Removes all documents.
90 =head3 set_weight ($var)
92 Sets the weighting variable to C<var>.
99 my $self = pxs_dict_new ();
100 bless ($self, $class);
106 =head3 get_var_cnt ()
108 Returns the number of variables in the dictionary.
110 =head3 get_var ($idx)
112 Returns the C<idx>th variable from the dictionary.
113 Returns undef if C<idx> is greater than or equal to the number
114 of variables in the dictionary.
122 my $var = pxs_get_variable ($dict, $idx);
126 bless ($var, "PSPP::Var");
133 =head3 get_var_by_name ($name)
135 Returns the variable from the dictionary whose name is C<name>.
136 If there is no such variable, a null reference will be returned.
144 my $var = pxs_get_var_by_name ($dict, $name);
148 bless ($var, "PSPP::Var");
160 Contains constants used to denote variable format types.
161 The identifiers are the same as those used in pspp to denote formats.
162 For example C<PSPP::Fmt::F> defines floating point format, and
163 C<PSPP::Fmt::A> denotes string format.
167 # These must correspond to the values in src/data/format.h
215 =head3 new ($dict, $name, %input_fmt)
217 Creates and returns a new variable in the dictionary C<dict>. The
218 new variable will have the name C<name>. C<name> must be a valid UTF8 string.
219 The input format is set by the C<input_fmt> parameter
221 By default, the write and print formats are the same as the input format.
222 The write and print formats may be changed (See L</set_write_format>),
223 L</set_print_format>). The input format may not be changed after
224 the variable has been created.
225 If the variable cannot be created, undef is returned.
235 my $self = pxs_dict_create_var ($dict, $name, \%format);
238 bless ($self, $class);
245 =head3 set_label ($label)
247 Sets the variable label to C<label>, which must be a valid UTF8 string.
254 =head3 set_write_format (%fmt)
256 Sets the write format to C<fmt>. <fmt> is a hash containing the keys:
262 A constant denoting the format type. See L</PSPP::Fmt>.
266 An integer denoting the number of decimal places for the format.
270 An integer denoting the width of the format.
274 On error the subroutine returns zero.
282 pxs_set_write_format ($var, \%format);
287 =head3 set_print_format (%fmt)
289 Sets the print format to C<fmt>.
290 On error the subroutine returns zero.
298 pxs_set_print_format ($var, \%format);
304 =head3 get_write_format ()
306 Returns a reference to a hash containing the write format for the variable.
309 =head3 get_print_format ()
311 Returns a reference to a hash containing the print format for the variable.
313 =head3 set_output_format (%fmt)
315 Sets the write and print formats to C<fmt>. This is the same as
316 calling set_write_format followed by set_print_format.
317 On error the subroutine returns zero.
322 sub set_output_format
326 pxs_set_output_format ($var, \%format);
331 =head3 clear_value_labels ()
333 Removes all value labels from the variable.
340 =head3 add_value_label ($key, $label)
342 Adds the value label C<label> to the variable for the value C<key>.
343 C<label> must be a valid UTF8 string.
344 On error the subroutine returns zero.
346 =head3 add_value_labels (@array)
357 while ( @li = each %values )
359 if ( $var->add_value_label ($li[0], "$li[1]") )
370 =head3 set_value_labels ($key, $label)
372 C<Set_value_labels> is identical to calling L</clear_value_labels>
373 followed by L</add_value_labels>.
374 On error the subroutine returns zero.
382 $self->clear_value_labels () ;
383 $self->add_value_labels (%labels);
388 =head3 set_missing_values ($val1 [, $val2[, $val3] ])
390 Sets the missing values for the variable.
391 No more than three missing values may be specified.
393 =head3 get_attributes()
395 Returns a reference to a hash of the custom variable attributes.
396 Each value of the hash is a reference to an array containing the
401 Returns the name of the variable.
405 Returns the label of the variable or undef if there is no label.
407 =head3 get_value_labels ()
409 Returns a reference to a hash containing the value labels for the variable.
410 The hash is keyed by data values which correpond to the labels.
414 package PSPP::Sysfile;
420 =head3 new ($filename, $dict [,%opts])
422 Creates a new system file from the dictionary C<dict>. The file will
423 be written to the file called C<filename>. The string C<filename> must
425 C<opt>, if specified, is a hash containing optional parameters for the
426 system file. Currently, the only supported parameter is
427 C<compress>. If C<compress> is non zero, then the system file written
428 will be in the compressed format.
429 On error, undef is returned.
432 =head3 append_case (@case)
434 Appends a case to the system file.
435 C<Case> is an array of scalars, each of which are the values of
436 the variables in the dictionary corresponding to the system file.
437 If the case contains strings, then the strings must be UTF8 encoded.
438 The special value C<PSPP::SYSMIS> may be used to indicate that a value
440 If the array contains less elements than variables in the dictionary,
441 remaining values will be set to system missing.
448 my $filename = shift;
452 my $self = pxs_create_sysfile ($filename, $dict, $opts);
456 bless ($self, $class);
465 Closes the system file.
467 This subroutine closes the system file and flushes it to disk. No
468 further cases may be written once the file has been closed.
469 The system file will be automatically closed when it goes out of scope.
473 package PSPP::Reader;
484 my $filename = shift;
486 my $self = pxs_open_sysfile ($filename);
490 bless ($self, $class);
497 =head3 open ($filename)
499 Opens a system file for reading.
501 Open is used to read data from an existing system file.
502 It creates and returns a PSPP::Reader object which can be used to read
503 data and dictionary information from C<filename>. The string C<filename>
504 must be in UTF-8 encoding.
506 =head3 get_case_cnt ()
508 Returns the number of cases in a open system file. Some files
509 do not store the number of cases. In these instances undef
510 will be returned. Therefore, then programmer must check that the
511 returned value is not undef before using it.
519 my $dict = pxs_get_dict ($reader);
521 bless ($dict, "PSPP::Dict");
530 Returns the dictionary associated with the reader.
532 =head3 get_next_case ()
534 Retrieves the next case from the reader.
535 This method returns an array of scalars, each of which are the values of
536 the data in the system file.
537 The first call to C<get_next_case> after C<open> has been called retrieves
538 the first case in the system file. Each subsequent call retrieves the next
539 case. If there are no more cases to be read, the function returns an empty
542 If the case contains system missing values, these values are set to the
545 =head2 Miscellaneous subroutines
547 The following subroutines provide (hopefully) useful information about the
548 values retrieved from a reader.
550 =head3 PSPP::format_value ($value, $variable)
552 Returns a scalar containing a string representing C<value> formatted according
553 to the print format of C<variable>.
554 In the most common usage, C<value> should be a value of C<variable>.
557 =head3 PSPP::value_is_missing ($value, $variable)
559 Returns non-zero if C<value> is either system missing, or if it matches the
560 user missing criteria for C<variable>.
570 John Darrington, E<lt>john@darrington.wattle.id.auE<gt>
572 =head1 COPYRIGHT AND LICENSE
574 Copyright (C) 2007, 2008, 2009 by Free Software Foundation
576 This program is free software: you can redistribute it and/or modify
577 it under the terms of the GNU General Public License as published by
578 the Free Software Foundation, either version 3 of the License, or
579 (at your option) any later version.
581 This program is distributed in the hope that it will be useful,
582 but WITHOUT ANY WARRANTY; without even the implied warranty of
583 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
584 GNU General Public License for more details.
586 You should have received a copy of the GNU General Public License
587 along with this program. If not, see <http://www.gnu.org/licenses/>.