perl-module/lib/PSPP.pm.in

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