perl-module/lib/PSPP.pm

   1 use 5.008008;
   2 use strict;
   3 use warnings;
   4
   5 do 'pspp-vers.pl' || die "No version set";
   6
   7 =head1 NAME
   8
   9 PSPP - Perl extension to PSPP
  10
  11 =head1 SYNOPSIS
  12
  13   use PSPP;
  14
  15 =head1 DESCRIPTION
  16
  17 PSPP:: provides an interface to the libraries used by pspp to create
  18 system files.
  19
  20 =head1 EXPORT
  21
  22 None by default.
  23
  24 =cut
  25
  26 require XSLoader;
  27 XSLoader::load('PSPP', $PSPP::VERSION);
  28
  29 =pod
  30
  31 =head1 PROGRAMMER'S INTERFACE
  32
  33 The subroutines in this package return zero or unref on error.
  34 When errors occur, a string describing the error is written
  35 to C<$PSPP::errstr>.
  36
  37 =cut
  38
  39 package PSPP;
  40 use POSIX ;
  41
  42 use constant { SYSMIS => -(POSIX::DBL_MAX),
  43                PERL_EPOCH => 12219379200 # Number of seconds between
  44                    # 1st January 1970
  45                    # and 14th October 1582
  46                };
  47
  48
  49
  50 package PSPP::Dict;
  51
  52 =pod
  53
  54 =head2 PSPP::Dict::new
  55
  56 Creates a new dictionary.  This returned dictionary will be empty.
  57 Returns undef on failure.
  58
  59 =head3 set_documents ($string)
  60
  61 Sets the documents (comments) to C<string>.
  62
  63 =head3 add_document ($string)
  64
  65 Appends C<string> to the documents.
  66
  67 =head3 clear_documents ()
  68
  69 Removes all documents.
  70
  71 =head3 set_weight ($var)
  72
  73 Sets the weighting variable to C<var>.
  74
  75 =cut
  76
  77 sub new
  78 {
  79     my $class = shift;
  80     my $self = _dict_new ();
  81     bless ($self, $class);
  82     return $self;
  83 }
  84
  85 package PSPP::Fmt;
  86
  87 =pod
  88
  89 =head2 PSPP::Fmt
  90
  91 Contains constants used to denote variable format types.
  92 The identifiers are the same as  those used in pspp to denote formats.
  93 For  example C<PSPP::Fmt::F> defines floating point format, and
  94 C<PSPP::Fmt::A> denotes string format.
  95
  96 =cut
  97
  98 # These must correspond to the values in src/data/format.h
  99 use constant {
 100     F =>        0,
 101     COMMA =>    1,
 102     DOT =>      2,
 103     DOLLAR =>   3,
 104     PCT =>      4,
 105     E =>        5,
 106     CCA =>      6,
 107     CCB =>      7,
 108     CCC =>      8,
 109     CCD =>      9,
 110     CCE =>      10,
 111     N =>        11,
 112     Z =>        12,
 113     P =>        13,
 114     PK =>       14,
 115     IB =>       15,
 116     PIB =>      16,
 117     PIBHEX =>   17,
 118     RB =>       18,
 119     RBHEX =>    19,
 120     DATE =>     20,
 121     ADATE =>    21,
 122     EDATE =>    22,
 123     JDATE =>    23,
 124     SDATE =>    24,
 125     QYR =>      25,
 126     MOYR =>     26,
 127     WKYR =>     27,
 128     DATETIME => 28,
 129     TIME =>     29,
 130     DTIME =>    30,
 131     WKDAY =>    31,
 132     MONTH =>    32,
 133     A =>        33,
 134     AHEX =>     34
 135 };
 136
 137
 138 =head2 PSPP::Var
 139
 140 =cut
 141
 142 package PSPP::Var;
 143
 144 =head3 new ($dict, $name, %input_fmt)
 145
 146 Creates and returns a new variable in the dictionary C<dict>.  The
 147 new variable will have the name C<name>.
 148 The input format is set by the C<input_fmt> parameter
 149 (See L</PSPP::Fmt>).
 150 By default, the write and print formats are the same as the input format.
 151 The write and print formats may be changed (See L</set_write_format>),
 152 L</set_print_format>).  The input format may not be changed after
 153 the variable has been created.
 154 If the variable cannot be created, undef is returned.
 155
 156 =cut
 157
 158 sub new
 159 {
 160     my $class = shift;
 161     my $dict = shift;
 162     my $name = shift;
 163     my %format = @_;
 164     my $self = _dict_create_var ($dict, $name, \%format);
 165     if ( ref $self )
 166     {
 167         bless ($self, $class);
 168     }
 169     return $self;
 170 }
 171
 172 =pod
 173
 174 =head3 set_label ($label)
 175
 176 Sets the variable label to C<label>.
 177
 178
 179 =cut
 180
 181 =pod
 182
 183 =head3 set_write_format (%fmt)
 184
 185 Sets the write format to C<fmt>. <fmt> is a hash containing the keys:
 186
 187 =over 2
 188
 189 =item FMT
 190
 191 A constant denoting the format type.  See L</PSPP::Fmt>.
 192
 193 =item decimals
 194
 195 An integer denoting the number of decimal places for the format.
 196
 197 =item width
 198
 199 An integer denoting the number of width of the format.
 200
 201 =back
 202
 203 On error the subroutine returns zero.
 204
 205 =cut
 206
 207 sub set_write_format
 208 {
 209     my $var = shift;
 210     my %format = @_;
 211     _set_write_format ($var, \%format);
 212 }
 213
 214 =pod
 215
 216 =head3 set_print_format (%fmt)
 217
 218 Sets the print format to C<fmt>.
 219 On error the subroutine returns zero.
 220
 221 =cut
 222
 223 sub set_print_format
 224 {
 225     my $var = shift;
 226     my %format = @_;
 227     _set_print_format ($var, \%format);
 228 }
 229
 230 =pod
 231
 232 =head3 set_output_format (%fmt)
 233
 234 Sets the write and print formats to C<fmt>.  This is the same as
 235 calling set_write_format followed by set_print_format.
 236 On error the subroutine returns zero.
 237
 238 =cut
 239
 240
 241 sub set_output_format
 242 {
 243     my $var = shift;
 244     my %format = @_;
 245     _set_output_format ($var, \%format);
 246 }
 247
 248 =pod
 249
 250 =head3 clear_value_labels ()
 251
 252 Removes all value labels from the variable.
 253
 254 =cut
 255
 256
 257 =pod
 258
 259 =head3 add_value_label ($key, $label)
 260
 261 Adds the value label C<label> to the variable for the value C<key>.
 262 On error the subroutine returns zero.
 263
 264 =head3 add_value_labels (@array)
 265
 266 =cut
 267
 268 sub add_value_labels
 269 {
 270     my $var = shift;
 271     my %values = @_;
 272     my @li;
 273
 274     my $n = 0;
 275     while ( @li = each %values )
 276     {
 277         if ( $var->add_value_label ($li[0], "$li[1]") )
 278         {
 279             $n++;
 280         }
 281     }
 282
 283     return $n;
 284 }
 285
 286 =pod
 287
 288 =head3 set_value_labels ($key, $value)
 289
 290 C<Set_value_labels> is identical to calling L</clear_value_labels>
 291 followed by L</add_value_labels>.
 292 On error the subroutine returns zero.
 293
 294 =cut
 295
 296 sub set_value_labels
 297 {
 298     my $self = shift;
 299     my %labels = @_;
 300     $self->clear_value_labels () ;
 301     $self->add_value_labels (%labels);
 302 }
 303
 304 =pod
 305
 306 =head3 set_missing_values ($val1 [, $val2[, $val3] ])
 307
 308 Sets the missing values for the variable.
 309 No more than three missing values may be specified.
 310
 311 =cut
 312
 313
 314 package PSPP::Sysfile;
 315
 316 =pod
 317
 318 =head2 PSPP::Sysfile
 319
 320 =head3 new ($filename, $dict [,%opts])
 321
 322 Creates a new system file from the dictionary C<dict>.  The file will
 323 be written to the file called C<filename>.
 324 C<opt>, if specified, is a hash containing optional parameters for the
 325 system file.  Currently, the only supported parameter is
 326 C<compress>. If C<compress> is non zero, then the system file written
 327 will be in the compressed format.
 328 On error, undef is returned.
 329
 330
 331 =head3 append_case (@case)
 332
 333 Appends a case to the system file.
 334 C<Case> is an array of scalars, each of which are the values of
 335 the variables in the dictionary corresponding to the system file.
 336 The special value C<PSPP::SYSMIS> may be used to indicate that a value
 337 is system missing.
 338 If the array contains less elements than variables in the dictionary,
 339 remaining values will be set to system missing.
 340
 341 =cut
 342
 343 sub new
 344 {
 345     my $class = shift;
 346     my $filename = shift;
 347     my $dict = shift;
 348     my $opts = shift;
 349
 350     my $self  = _create_sysfile ($filename, $dict, $opts);
 351
 352     if ( ref $self )
 353     {
 354         bless ($self, $class);
 355     }
 356     return $self;
 357 }
 358
 359 =pod
 360
 361 =head3 close ()
 362
 363 Closes the system file.
 364
 365 This subroutine closes the system file and flushes it to disk.  No
 366 further cases may be written once the file has been closed.
 367 The system file will be automatically closed when it goes out of scope.
 368
 369 =cut
 370
 371
 372
 373 1;
 374 __END__
 375
 376
 377 =head1 AUTHOR
 378
 379 John Darrington, E<lt>john@darrington.wattle.id.auE<gt>
 380
 381 =head1 COPYRIGHT AND LICENSE
 382
 383 Copyright (C) 2007 by Free Software Foundation
 384
 385    This program is free software; you can redistribute it and/or
 386    modify it under the terms of the GNU General Public License as
 387    published by the Free Software Foundation; either version 2 of the
 388    License, or (at your option) any later version.
 389
 390    This program is distributed in the hope that it will be useful, but
 391    WITHOUT ANY WARRANTY; without even the implied warranty of
 392    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 393    General Public License for more details.
 394
 395    You should have received a copy of the GNU General Public License
 396    along with this program; if not, write to the Free Software
 397    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 398    02110-1301, USA.
 399
 400 =cut