perl-module/lib/PSPP.pm

   1 use 5.008008;
   2 use strict;
   3 use warnings;
   4
   5 =head1 NAME
   6
   7 PSPP - Perl extension to PSPP
   8
   9 =head1 SYNOPSIS
  10
  11   use PSPP;
  12
  13 =head1 DESCRIPTION
  14
  15 PSPP:: provides an interface to the libraries used by pspp to create
  16 system files.
  17
  18 =head1 EXPORT
  19
  20 None by default.
  21
  22 =cut
  23 BEGIN {
  24         do 'pspp-vers.pl' || die "No version set";
  25         require XSLoader;
  26         XSLoader::load('PSPP', $PSPP::VERSION);
  27 }
  28
  29 PSPP::onBoot($PSPP::VERSION);
  30
  31 =pod
  32
  33 =head1 PROGRAMMER'S INTERFACE
  34
  35 The subroutines in this package return zero or unref on error.
  36 When errors occur, a string describing the error is written
  37 to C<$PSPP::errstr>.
  38
  39 =cut
  40
  41 package PSPP;
  42 use POSIX ;
  43
  44 use constant { SYSMIS => -(POSIX::DBL_MAX),
  45                PERL_EPOCH => 12219379200 # Number of seconds between
  46                    # 14th October 1582
  47                    # and
  48                    # 1st January 1970
  49                };
  50
  51
  52
  53 package PSPP::Dict;
  54
  55 =pod
  56
  57 =head2 PSPP::Dict::new
  58
  59 Creates a new dictionary.  This returned dictionary will be empty.
  60 Returns undef on failure.
  61
  62 =head3 set_documents ($string)
  63
  64 Sets the documents (comments) to C<string>.
  65
  66 =head3 add_document ($string)
  67
  68 Appends C<string> to the documents.
  69
  70 =head3 clear_documents ()
  71
  72 Removes all documents.
  73
  74 =head3 set_weight ($var)
  75
  76 Sets the weighting variable to C<var>.
  77
  78 =cut
  79
  80 sub new
  81 {
  82     my $class = shift;
  83     my $self = pxs_dict_new ();
  84     bless ($self, $class);
  85     return $self;
  86 }
  87
  88 =pod
  89
  90 =head3 get_var ($idx)
  91
  92 Returns the C<idx>th variable from the dictionary.
  93
  94 =cut
  95
  96 sub get_var
  97 {
  98     my $dict = shift;
  99     my $idx = shift;
 100     my $var = pxs_get_variable ($dict, $idx);
 101
 102     if ( ref $var )
 103     {
 104         bless ($var, "PSPP::Var");
 105     }
 106     return $var;
 107 }
 108
 109
 110 package PSPP::Fmt;
 111
 112 =pod
 113
 114 =head2 PSPP::Fmt
 115
 116 Contains constants used to denote variable format types.
 117 The identifiers are the same as  those used in pspp to denote formats.
 118 For  example C<PSPP::Fmt::F> defines floating point format, and
 119 C<PSPP::Fmt::A> denotes string format.
 120
 121 =cut
 122
 123 # These must correspond to the values in src/data/format.h
 124 use constant {
 125     F =>        0,
 126     COMMA =>    1,
 127     DOT =>      2,
 128     DOLLAR =>   3,
 129     PCT =>      4,
 130     E =>        5,
 131     CCA =>      6,
 132     CCB =>      7,
 133     CCC =>      8,
 134     CCD =>      9,
 135     CCE =>      10,
 136     N =>        11,
 137     Z =>        12,
 138     P =>        13,
 139     PK =>       14,
 140     IB =>       15,
 141     PIB =>      16,
 142     PIBHEX =>   17,
 143     RB =>       18,
 144     RBHEX =>    19,
 145     DATE =>     20,
 146     ADATE =>    21,
 147     EDATE =>    22,
 148     JDATE =>    23,
 149     SDATE =>    24,
 150     QYR =>      25,
 151     MOYR =>     26,
 152     WKYR =>     27,
 153     DATETIME => 28,
 154     TIME =>     29,
 155     DTIME =>    30,
 156     WKDAY =>    31,
 157     MONTH =>    32,
 158     A =>        33,
 159     AHEX =>     34
 160 };
 161
 162
 163 =head2 PSPP::Var
 164
 165 =cut
 166
 167 package PSPP::Var;
 168
 169 =head3 new ($dict, $name, %input_fmt)
 170
 171 Creates and returns a new variable in the dictionary C<dict>.  The
 172 new variable will have the name C<name>.
 173 The input format is set by the C<input_fmt> parameter
 174 (See L</PSPP::Fmt>).
 175 By default, the write and print formats are the same as the input format.
 176 The write and print formats may be changed (See L</set_write_format>),
 177 L</set_print_format>).  The input format may not be changed after
 178 the variable has been created.
 179 If the variable cannot be created, undef is returned.
 180
 181 =cut
 182
 183 sub new
 184 {
 185     my $class = shift;
 186     my $dict = shift;
 187     my $name = shift;
 188     my %format = @_;
 189     my $self = pxs_dict_create_var ($dict, $name, \%format);
 190     if ( ref $self )
 191     {
 192         bless ($self, $class);
 193     }
 194     return $self;
 195 }
 196
 197 =pod
 198
 199 =head3 set_label ($label)
 200
 201 Sets the variable label to C<label>.
 202
 203
 204 =cut
 205
 206 =pod
 207
 208 =head3 set_write_format (%fmt)
 209
 210 Sets the write format to C<fmt>. <fmt> is a hash containing the keys:
 211
 212 =over 2
 213
 214 =item FMT
 215
 216 A constant denoting the format type.  See L</PSPP::Fmt>.
 217
 218 =item decimals
 219
 220 An integer denoting the number of decimal places for the format.
 221
 222 =item width
 223
 224 An integer denoting the number of width of the format.
 225
 226 =back
 227
 228 On error the subroutine returns zero.
 229
 230 =cut
 231
 232 sub set_write_format
 233 {
 234     my $var = shift;
 235     my %format = @_;
 236     pxs_set_write_format ($var, \%format);
 237 }
 238
 239 =pod
 240
 241 =head3 set_print_format (%fmt)
 242
 243 Sets the print format to C<fmt>.
 244 On error the subroutine returns zero.
 245
 246 =cut
 247
 248 sub set_print_format
 249 {
 250     my $var = shift;
 251     my %format = @_;
 252     pxs_set_print_format ($var, \%format);
 253 }
 254
 255 =pod
 256
 257 =head3 set_output_format (%fmt)
 258
 259 Sets the write and print formats to C<fmt>.  This is the same as
 260 calling set_write_format followed by set_print_format.
 261 On error the subroutine returns zero.
 262
 263 =cut
 264
 265
 266 sub set_output_format
 267 {
 268     my $var = shift;
 269     my %format = @_;
 270     pxs_set_output_format ($var, \%format);
 271 }
 272
 273 =pod
 274
 275 =head3 clear_value_labels ()
 276
 277 Removes all value labels from the variable.
 278
 279 =cut
 280
 281
 282 =pod
 283
 284 =head3 add_value_label ($key, $label)
 285
 286 Adds the value label C<label> to the variable for the value C<key>.
 287 On error the subroutine returns zero.
 288
 289 =head3 add_value_labels (@array)
 290
 291 =cut
 292
 293 sub add_value_labels
 294 {
 295     my $var = shift;
 296     my %values = @_;
 297     my @li;
 298
 299     my $n = 0;
 300     while ( @li = each %values )
 301     {
 302         if ( $var->add_value_label ($li[0], "$li[1]") )
 303         {
 304             $n++;
 305         }
 306     }
 307
 308     return $n;
 309 }
 310
 311 =pod
 312
 313 =head3 set_value_labels ($key, $value)
 314
 315 C<Set_value_labels> is identical to calling L</clear_value_labels>
 316 followed by L</add_value_labels>.
 317 On error the subroutine returns zero.
 318
 319 =cut
 320
 321 sub set_value_labels
 322 {
 323     my $self = shift;
 324     my %labels = @_;
 325     $self->clear_value_labels () ;
 326     $self->add_value_labels (%labels);
 327 }
 328
 329 =pod
 330
 331 =head3 set_missing_values ($val1 [, $val2[, $val3] ])
 332
 333 Sets the missing values for the variable.
 334 No more than three missing values may be specified.
 335
 336 =head3 get_name ()
 337
 338 Returns the name of the variable.
 339
 340 =head3 get_label ()
 341
 342 Returns the label of the variable or undef if there is no label.
 343
 344 =head3 get_value_labels ()
 345
 346 Returns a reference to a hash containing the value labels for the variable.
 347 The hash is keyed by data values which correpond to the labels.
 348
 349 =cut
 350
 351 package PSPP::Sysfile;
 352
 353 =pod
 354
 355 =head2 PSPP::Sysfile
 356
 357 =head3 new ($filename, $dict [,%opts])
 358
 359 Creates a new system file from the dictionary C<dict>.  The file will
 360 be written to the file called C<filename>.
 361 C<opt>, if specified, is a hash containing optional parameters for the
 362 system file.  Currently, the only supported parameter is
 363 C<compress>. If C<compress> is non zero, then the system file written
 364 will be in the compressed format.
 365 On error, undef is returned.
 366
 367
 368 =head3 append_case (@case)
 369
 370 Appends a case to the system file.
 371 C<Case> is an array of scalars, each of which are the values of
 372 the variables in the dictionary corresponding to the system file.
 373 The special value C<PSPP::SYSMIS> may be used to indicate that a value
 374 is system missing.
 375 If the array contains less elements than variables in the dictionary,
 376 remaining values will be set to system missing.
 377
 378 =cut
 379
 380 sub new
 381 {
 382     my $class = shift;
 383     my $filename = shift;
 384     my $dict = shift;
 385     my $opts = shift;
 386
 387     my $self  = pxs_create_sysfile ($filename, $dict, $opts);
 388
 389     if ( ref $self )
 390     {
 391         bless ($self, $class);
 392     }
 393     return $self;
 394 }
 395
 396 =pod
 397
 398 =head3 close ()
 399
 400 Closes the system file.
 401
 402 This subroutine closes the system file and flushes it to disk.  No
 403 further cases may be written once the file has been closed.
 404 The system file will be automatically closed when it goes out of scope.
 405
 406 =cut
 407
 408 package PSPP::Reader;
 409
 410 =pod
 411
 412 =head2 PSPP::Reader
 413
 414 =cut
 415
 416 sub open
 417 {
 418     my $class = shift;
 419     my $filename = shift;
 420
 421     my $self  = pxs_open_sysfile ($filename);
 422
 423     if ( ref $self )
 424     {
 425         bless ($self, $class);
 426     }
 427     return $self;
 428 }
 429
 430 =pod
 431
 432 =head3 open ($filename)
 433
 434 Opens a system file for reading.
 435
 436 Open is used to read data from an existing system file.
 437 It creates and returns a PSPP::Reader object which can be used to read
 438 data and dictionary information from <C>filename.
 439
 440 =cut
 441
 442 sub get_dict
 443 {
 444     my $reader = shift;
 445
 446     my $dict = pxs_get_dict ($reader);
 447
 448     bless ($dict, "PSPP::Dict");
 449
 450     return $dict;
 451 }
 452
 453 =pod
 454
 455 =head3 get_dict ()
 456
 457 Returns the dictionary associated with the reader.
 458
 459 =head3 get_next_case ()
 460
 461 Retrieves the next case from the reader.
 462 This method returns an array of scalars, each of which are the values of
 463 the data in the system file.
 464 The first call to <C>get_next_case after <C>open has been called retrieves
 465 the first case in the system file.  Each subsequent call retrieves the next
 466 case.  If there are no more cases to be read, the function returns undef.
 467
 468 If the case contains system missing values, these values are set to the
 469 empty string.
 470
 471 =head2 Miscellaneous subroutines
 472
 473 The following subroutines provide (hopefully) useful information about the
 474 values retrieved from a reader.
 475
 476 =head3 PSPP::format_value ($value, $variable)
 477
 478 Returns a scalar containing a string representing C<value> formatted accoring
 479 to the print format of C<variable>.
 480 In the most common ussage,  C<value> should be a value of C<variable>.
 481
 482
 483 =head3 PSPP::value_is_missing ($value, $variable)
 484
 485 Returns non-zero if C<value> is either system missing, or if it matches the
 486 user missing criteria for C<variable>.
 487
 488 =cut
 489
 490 1;
 491 __END__
 492
 493
 494 =head1 AUTHOR
 495
 496 John Darrington, E<lt>john@darrington.wattle.id.auE<gt>
 497
 498 =head1 COPYRIGHT AND LICENSE
 499
 500 Copyright (C) 2007, 2008 by Free Software Foundation
 501
 502 This program is free software: you can redistribute it and/or modify
 503 it under the terms of the GNU General Public License as published by
 504 the Free Software Foundation, either version 3 of the License, or
 505 (at your option) any later version.
 506
 507 This program is distributed in the hope that it will be useful,
 508 but WITHOUT ANY WARRANTY; without even the implied warranty of
 509 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 510 GNU General Public License for more details.
 511
 512 You should have received a copy of the GNU General Public License
 513 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 514
 515 =cut