X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=perl-module%2Flib%2FPSPP.pm;h=2dccd10a36973e560e8be7d267b92f9bdb918ac1;hb=73ee9eab1bd4159ad1982f3012abf3631131052e;hp=f99afde36ea7d68b85591708ec1595f83c6ca7c0;hpb=591e1f9d131470cdd92a2ea3f15d9ae53be36918;p=pspp-builds.git

diff --git a/perl-module/lib/PSPP.pm b/perl-module/lib/PSPP.pm
index f99afde3..2dccd10a 100644
--- a/perl-module/lib/PSPP.pm
+++ b/perl-module/lib/PSPP.pm
@@ -4,7 +4,7 @@ use warnings;
 
 =head1 NAME
 
-PSPP - Perl extension to PSPP
+PSPP-Perl - Perl extension to PSPP
 
 =head1 SYNOPSIS
 
@@ -12,8 +12,8 @@ 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
 
@@ -21,7 +21,7 @@ None by default.
 
 =cut
 BEGIN {
-	do 'pspp-vers.pl' || die "No version set";
+	$PSPP::VERSION='0.7.2';
 	require XSLoader;
 	XSLoader::load('PSPP', $PSPP::VERSION);
 }
@@ -87,9 +87,15 @@ sub new
 
 =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
 
@@ -106,6 +112,28 @@ sub get_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;
 
@@ -169,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.
@@ -198,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
@@ -221,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
 
@@ -254,6 +282,16 @@ sub set_print_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
@@ -284,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)
@@ -310,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>.
@@ -333,6 +372,12 @@ sub set_value_labels
 Sets the missing values for the variable.  
 No more than three missing values may be specified.
 
+=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.
@@ -370,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,
@@ -435,7 +481,7 @@ 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.
+data and dictionary information from C<filename>.
 
 =cut
 
@@ -461,9 +507,10 @@ Returns the dictionary associated with the reader.
 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 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 undef.
+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.
@@ -475,9 +522,9 @@ values retrieved from a reader.
 
 =head3 PSPP::format_value ($value, $variable)
 
-Returns a scalar containing a string representing C<value> formatted accoring 
+Returns a scalar containing a string representing C<value> formatted according 
 to the print format of C<variable>.
-In the most common ussage,  C<value> should be a value of C<variable>.
+In the most common usage,  C<value> should be a value of C<variable>.
 
 
 =head3 PSPP::value_is_missing ($value, $variable)
@@ -497,7 +544,7 @@ John Darrington, E<lt>john@darrington.wattle.id.auE<gt>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright (C) 2007, 2008 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