NAME
PSPP-Perl - Perl extension to PSPP
SYNOPSIS
use PSPP;DESCRIPTION
PSPP-Perl provides an interface to the libraries used by pspp to read and write system files.
EXPORT
None by default.
PROGRAMMER'S INTERFACE
The subroutines in this package return zero or unref on error. When errors occur, a string describing the error is written to $PSPP::errstr.
PSPP::Dict::new
Creates a new dictionary. This returned dictionary will be empty. Returns undef on failure.
set_documents ($string)
Sets the documents (comments) to string.
add_document ($string)
Appends string to the documents.
clear_documents ()
Removes all documents.
set_weight ($var)
Sets the weighting variable to var.
get_var_cnt ()
Returns the number of variables in the dictionary.
get_var ($idx)
Returns the idxth variable from the dictionary. Returns undef if idx is greater than or equal to the number of variables in the dictionary.
get_var_by_name ($name)
Returns the variable from the dictionary whose name is name. If there is no such variable, a null reference will be returned.
PSPP::Fmt
Contains constants used to denote variable format types. The identifiers are the same as those used in pspp to denote formats. For example PSPP::Fmt::F defines floating point format, and PSPP::Fmt::A denotes string format.
PSPP::Var
new ($dict, $name, %input_fmt)
Creates and returns a new variable in the dictionary dict. The new variable will have the name name. The input format is set by the input_fmt parameter (See "PSPP::Fmt"). By default, the write and print formats are the same as the input format. The write and print formats may be changed (See "set_write_format"), "set_print_format"). The input format may not be changed after the variable has been created. If the variable cannot be created, undef is returned.
set_label ($label)
Sets the variable label to label.
set_write_format (%fmt)
Sets the write format to fmt. <fmt> is a hash containing the keys:
- FMT
-
A constant denoting the format type. See "PSPP::Fmt".
- decimals
-
An integer denoting the number of decimal places for the format.
- width
-
An integer denoting the width of the format.
On error the subroutine returns zero.
set_print_format (%fmt)
Sets the print format to fmt. On error the subroutine returns zero.
get_write_format ()
Returns a reference to a hash containing the write format for the variable.
get_print_format ()
Returns a reference to a hash containing the print format for the variable.
set_output_format (%fmt)
Sets the write and print formats to fmt. This is the same as calling set_write_format followed by set_print_format. On error the subroutine returns zero.
clear_value_labels ()
Removes all value labels from the variable.
add_value_label ($key, $label)
Adds the value label label to the variable for the value key. On error the subroutine returns zero.
add_value_labels (@array)
set_value_labels ($key, $value)
Set_value_labels is identical to calling "clear_value_labels" followed by "add_value_labels". On error the subroutine returns zero.
set_missing_values ($val1 [, $val2[, $val3] ])
Sets the missing values for the variable. No more than three missing values may be specified.
get_attributes()
Returns a reference to a hash of the custom variable attributes. Each value of the hash is a reference to an array containing the attribute values.
get_name ()
Returns the name of the variable.
get_label ()
Returns the label of the variable or undef if there is no label.
get_value_labels ()
Returns a reference to a hash containing the value labels for the variable. The hash is keyed by data values which correpond to the labels.
PSPP::Sysfile
new ($filename, $dict [,%opts])
Creates a new system file from the dictionary dict. The file will be written to the file called filename. opt, if specified, is a hash containing optional parameters for the system file. Currently, the only supported parameter is compress. If compress is non zero, then the system file written will be in the compressed format. On error, undef is returned.
append_case (@case)
Appends a case to the system file. Case is an array of scalars, each of which are the values of the variables in the dictionary corresponding to the system file. The special value PSPP::SYSMIS may be used to indicate that a value is system missing. If the array contains less elements than variables in the dictionary, remaining values will be set to system missing.
close ()
Closes the system file.
This subroutine closes the system file and flushes it to disk. No further cases may be written once the file has been closed. The system file will be automatically closed when it goes out of scope.
PSPP::Reader
open ($filename)
Opens a system file for reading.
Open is used to read data from an existing system file. It creates and returns a PSPP::Reader object which can be used to read data and dictionary information from filename.
get_dict ()
Returns the dictionary associated with the reader.
get_next_case ()
Retrieves the next case from the reader. This method returns an array of scalars, each of which are the values of the data in the system file. The first call to get_next_case after open has been called retrieves the first case in the system file. Each subsequent call retrieves the next case. If there are no more cases to be read, the function returns an empty list.
If the case contains system missing values, these values are set to the empty string.
Miscellaneous subroutines
The following subroutines provide (hopefully) useful information about the values retrieved from a reader.
PSPP::format_value ($value, $variable)
Returns a scalar containing a string representing value formatted according to the print format of variable. In the most common ussage, value should be a value of variable.
PSPP::value_is_missing ($value, $variable)
Returns non-zero if value is either system missing, or if it matches the user missing criteria for variable.
AUTHOR
John Darrington, <john@darrington.wattle.id.au>
COPYRIGHT AND LICENSE
Copyright (C) 2007, 2008, 2009 by Free Software Foundation
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.