X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=perl-module%2Flib%2FPSPP.pm;h=2dccd10a36973e560e8be7d267b92f9bdb918ac1;hb=71fa94505d7d559e3f6bb90092268225db826732;hp=783ae25669982a695f1318d3e13b1eac533e8d1a;hpb=66b1b93cf6ca53c86199e88e5972f3017c56314c;p=pspp-builds.git

diff --git a/perl-module/lib/PSPP.pm b/perl-module/lib/PSPP.pm
index 783ae256..2dccd10a 100644
--- a/perl-module/lib/PSPP.pm
+++ b/perl-module/lib/PSPP.pm
@@ -2,11 +2,9 @@ use 5.008008;
 use strict;
 use warnings;
 
-our $VERSION = '0.7.0';
-
 =head1 NAME
 
-PSPP - Perl extension to PSPP
+PSPP-Perl - Perl extension to PSPP
 
 =head1 SYNOPSIS
 
@@ -14,17 +12,21 @@ PSPP - Perl extension to PSPP
 
 =head1 DESCRIPTION
 
-PSPP:: provides an interface to the libraries used by pspp to create
-system files.  
+PSPP-Perl provides an interface to the libraries used by pspp to read and
+write system files.  
 
 =head1 EXPORT
 
 None by default.
 
 =cut
+BEGIN {
+	$PSPP::VERSION='0.7.2';
+	require XSLoader;
+	XSLoader::load('PSPP', $PSPP::VERSION);
+}
 
-require XSLoader;
-XSLoader::load('PSPP', $VERSION);
+PSPP::onBoot($PSPP::VERSION);
 
 =pod
 
@@ -41,8 +43,9 @@ use POSIX ;
 
 use constant { SYSMIS => -(POSIX::DBL_MAX), 
 	       PERL_EPOCH => 12219379200 # Number of seconds between 
+                   # 14th October 1582
+		   # and 
 		   # 1st January 1970 
-		   # and 14th October 1582
 	       };
 
 
@@ -77,11 +80,61 @@ Sets the weighting variable to C<var>.
 sub new
 {
     my $class = shift;
-    my $self = _dict_new ();
+    my $self = pxs_dict_new ();
     bless ($self, $class);
     return $self;
 }
 
+=pod
+
+=head3 get_var_cnt ()
+
+Returns the number of variables in the dictionary.
+
+=head3 get_var ($idx)
+
+Returns the C<idx>th variable from the dictionary.
+Returns undef if C<idx> is greater than or equal to the number
+of variables in the dictionary.
+
+=cut
+
+sub get_var
+{
+    my $dict = shift;
+    my $idx = shift;
+    my $var = pxs_get_variable ($dict, $idx);
+
+    if ( ref $var ) 
+    {
+	bless ($var, "PSPP::Var");
+    }
+    return $var;
+}
+
+=pod
+
+=head3 get_var_by_name ($name)
+
+Returns the variable from the dictionary whose name is C<name>.
+If there is no such variable, a null reference will be returned.
+
+=cut
+
+sub get_var_by_name
+{
+    my $dict = shift;
+    my $name = shift;
+    my $var = pxs_get_var_by_name ($dict, $name);
+
+    if ( ref $var ) 
+    {
+	bless ($var, "PSPP::Var");
+    }
+    return $var;
+}
+
+
 package PSPP::Fmt;
 
 =pod
@@ -144,7 +197,7 @@ package PSPP::Var;
 =head3 new ($dict, $name, %input_fmt)
 
 Creates and returns a new variable in the dictionary C<dict>.  The 
-new variable will have the name C<name>.
+new variable will have the name C<name>.  C<name> must be a valid UTF8 string.
 The input format is set by the C<input_fmt> parameter 
 (See L</PSPP::Fmt>).
 By default, the write and print formats are the same as the input format.
@@ -161,7 +214,7 @@ sub new
     my $dict = shift;
     my $name = shift;
     my %format = @_;
-    my $self = _dict_create_var ($dict, $name, \%format);
+    my $self = pxs_dict_create_var ($dict, $name, \%format);
     if ( ref $self ) 
     {
 	bless ($self, $class);
@@ -173,7 +226,7 @@ sub new
 
 =head3 set_label ($label)
 
-Sets the variable label to C<label>.
+Sets the variable label to C<label>, which must be a valid UTF8 string.
 
 
 =cut
@@ -196,7 +249,7 @@ An integer denoting the number of decimal places for the format.
 
 =item width
 
-An integer denoting the number of width of the format.
+An integer denoting the width of the format.
 
 =back
 
@@ -208,7 +261,7 @@ sub set_write_format
 {
     my $var = shift;
     my %format = @_;
-    _set_write_format ($var, \%format);
+    pxs_set_write_format ($var, \%format);
 }
 
 =pod
@@ -224,11 +277,21 @@ sub set_print_format
 {
     my $var = shift;
     my %format = @_;
-    _set_print_format ($var, \%format);
+    pxs_set_print_format ($var, \%format);
 }
 
 =pod
 
+
+=head3 get_write_format ()
+
+Returns a reference to a hash containing the write format for the variable.
+
+
+=head3 get_print_format ()
+
+Returns a reference to a hash containing the print format for the variable.
+
 =head3 set_output_format (%fmt)
 
 Sets the write and print formats to C<fmt>.  This is the same as
@@ -242,7 +305,7 @@ sub set_output_format
 {
     my $var = shift;
     my %format = @_;
-    _set_output_format ($var, \%format);
+    pxs_set_output_format ($var, \%format);
 }
 
 =pod
@@ -259,6 +322,7 @@ Removes all value labels from the variable.
 =head3 add_value_label ($key, $label)
 
 Adds the value label C<label> to the variable for the value C<key>.
+C<label> must be a valid UTF8 string.
 On error the subroutine returns zero.
 
 =head3 add_value_labels (@array)
@@ -285,7 +349,7 @@ sub add_value_labels
 
 =pod
 
-=head3 set_value_labels ($key, $value)
+=head3 set_value_labels ($key, $label)
 
 C<Set_value_labels> is identical to calling L</clear_value_labels>
 followed by L</add_value_labels>.
@@ -308,8 +372,26 @@ sub set_value_labels
 Sets the missing values for the variable.  
 No more than three missing values may be specified.
 
-=cut
+=head3 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.
+
+=head3 get_name ()
+
+Returns the name of the variable.
+
+=head3 get_label ()
+
+Returns the label of the variable or undef if there is no label.
+
+=head3 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.
 
+=cut
 
 package PSPP::Sysfile;
 
@@ -333,6 +415,7 @@ On error, undef is returned.
 Appends a case to the system file.
 C<Case> is an array of scalars, each of which are the values of 
 the variables in the dictionary corresponding to the system file.
+If the case contains strings, then the strings must be UTF8 encoded.
 The special value C<PSPP::SYSMIS> may be used to indicate that a value
 is system missing.
 If the array contains less elements than variables in the dictionary,
@@ -347,7 +430,7 @@ sub new
     my $dict = shift;
     my $opts = shift;
 
-    my $self  = _create_sysfile ($filename, $dict, $opts);
+    my $self  = pxs_create_sysfile ($filename, $dict, $opts);
 
     if ( ref $self ) 
     {
@@ -368,7 +451,88 @@ The system file will be automatically closed when it goes out of scope.
 
 =cut
 
+package PSPP::Reader;
+
+=pod
+
+=head2 PSPP::Reader
+
+=cut
+
+sub open
+{
+    my $class = shift;
+    my $filename = shift;
+
+    my $self  = pxs_open_sysfile ($filename);
+
+    if ( ref $self ) 
+    {
+	bless ($self, $class);
+    }
+    return $self;
+}
+
+=pod
+
+=head3 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 C<filename>.
+
+=cut
+
+sub get_dict
+{
+    my $reader = shift;
+
+    my $dict = pxs_get_dict ($reader);
+
+    bless ($dict, "PSPP::Dict");
+
+    return $dict;
+}
+
+=pod
+
+=head3 get_dict ()
+
+Returns the dictionary associated with the reader.
 
+=head3 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 C<get_next_case> after C<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.
+
+=head2 Miscellaneous subroutines
+
+The following subroutines provide (hopefully) useful information about the 
+values retrieved from a reader.
+
+=head3 PSPP::format_value ($value, $variable)
+
+Returns a scalar containing a string representing C<value> formatted according 
+to the print format of C<variable>.
+In the most common usage,  C<value> should be a value of C<variable>.
+
+
+=head3 PSPP::value_is_missing ($value, $variable)
+
+Returns non-zero if C<value> is either system missing, or if it matches the 
+user missing criteria for C<variable>.
+
+=cut
 
 1;
 __END__
@@ -380,21 +544,19 @@ John Darrington, E<lt>john@darrington.wattle.id.auE<gt>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright (C) 2007 by Free Software Foundation
+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 2 of the
-   License, or (at your option) any later version.
+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.
+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, write to the Free Software
-   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
-   02110-1301, USA.
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 =cut