perl-module/lib/PSPP.pm

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