Corrected typos in the perl documentation

[pspp-builds.git] / perl-module / lib / PSPP.pm

diff --git a/perl-module/lib/PSPP.pm b/perl-module/lib/PSPP.pm
index 783ae25669982a695f1318d3e13b1eac533e8d1a..b84c311e21db8526e595208884925b62515149b9 100644 (file)
--- a/perl-module/lib/PSPP.pm
+++ b/perl-module/lib/PSPP.pm
@@ -2,11 +2,9 @@ use 5.008008;
 use strict;
 use warnings;
 
 use strict;
 use warnings;
 

-our $VERSION = '0.7.0';
-

 =head1 NAME
 
 =head1 NAME
 

-PSPP - Perl extension to PSPP
+PSPP-Perl - Perl extension to PSPP

 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 


@@ -14,17 +12,21 @@ PSPP - Perl extension to PSPP
 
 =head1 DESCRIPTION
 
 
 =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
 
 =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
 
 
 =pod
 


@@ -41,8 +43,9 @@ use POSIX ;
 
 use constant { SYSMIS => -(POSIX::DBL_MAX), 
               PERL_EPOCH => 12219379200 # Number of seconds between 
 
 use constant { SYSMIS => -(POSIX::DBL_MAX), 
               PERL_EPOCH => 12219379200 # Number of seconds between 

+                   # 14th October 1582
+                  # and 

                   # 1st January 1970 
                   # 1st January 1970 

-                  # and 14th October 1582

               };
 
 
               };
 
 


@@ -77,11 +80,61 @@ Sets the weighting variable to C<var>.
 sub new
 {
     my $class = shift;
 sub new
 {
     my $class = shift;

-    my $self = _dict_new ();
+    my $self = pxs_dict_new ();

     bless ($self, $class);
     return $self;
 }
 
     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
 package PSPP::Fmt;
 
 =pod


@@ -161,7 +214,7 @@ sub new
     my $dict = shift;
     my $name = shift;
     my %format = @_;
     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);
     if ( ref $self ) 
     {
        bless ($self, $class);


@@ -196,7 +249,7 @@ An integer denoting the number of decimal places for the format.
 
 =item width
 
 
 =item width
 

-An integer denoting the number of width of the format.
+An integer denoting the width of the format.

 
 =back
 
 
 =back
 


@@ -208,7 +261,7 @@ sub set_write_format
 {
     my $var = shift;
     my %format = @_;
 {
     my $var = shift;
     my %format = @_;

-    _set_write_format ($var, \%format);
+    pxs_set_write_format ($var, \%format);

 }
 
 =pod
 }
 
 =pod


@@ -224,7 +277,7 @@ sub set_print_format
 {
     my $var = shift;
     my %format = @_;
 {
     my $var = shift;
     my %format = @_;

-    _set_print_format ($var, \%format);
+    pxs_set_print_format ($var, \%format);

 }
 
 =pod
 }
 
 =pod


@@ -242,7 +295,7 @@ sub set_output_format
 {
     my $var = shift;
     my %format = @_;
 {
     my $var = shift;
     my %format = @_;

-    _set_output_format ($var, \%format);
+    pxs_set_output_format ($var, \%format);

 }
 
 =pod
 }
 
 =pod


@@ -308,8 +361,26 @@ sub set_value_labels
 Sets the missing values for the variable.  
 No more than three missing values may be specified.
 
 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;
 
 
 package PSPP::Sysfile;
 


@@ -347,7 +418,7 @@ sub new
     my $dict = shift;
     my $opts = shift;
 
     my $dict = shift;
     my $opts = shift;
 

-    my $self  = _create_sysfile ($filename, $dict, $opts);
+    my $self  = pxs_create_sysfile ($filename, $dict, $opts);

 
     if ( ref $self ) 
     {
 
     if ( ref $self ) 
     {


@@ -368,7 +439,88 @@ The system file will be automatically closed when it goes out of scope.
 
 =cut
 
 
 =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 ussage,  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__
 
 1;
 __END__


@@ -380,21 +532,19 @@ John Darrington, E<lt>john@darrington.wattle.id.auE<gt>
 
 =head1 COPYRIGHT AND LICENSE
 
 
 =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
 
 =cut