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