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.0';
  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_attributes()
 359
 360 Returns a reference to a hash of the custom variable attributes.
 361 Each value of the hash is a reference to an array containing the
 362 attribute values.
 363
 364 =head3 get_name ()
 365
 366 Returns the name of the variable.
 367
 368 =head3 get_label ()
 369
 370 Returns the label of the variable or undef if there is no label.
 371
 372 =head3 get_value_labels ()
 373
 374 Returns a reference to a hash containing the value labels for the variable.
 375 The hash is keyed by data values which correpond to the labels.
 376
 377 =cut
 378
 379 package PSPP::Sysfile;
 380
 381 =pod
 382
 383 =head2 PSPP::Sysfile
 384
 385 =head3 new ($filename, $dict [,%opts])
 386
 387 Creates a new system file from the dictionary C<dict>.  The file will
 388 be written to the file called C<filename>.
 389 C<opt>, if specified, is a hash containing optional parameters for the
 390 system file.  Currently, the only supported parameter is
 391 C<compress>. If C<compress> is non zero, then the system file written
 392 will be in the compressed format.
 393 On error, undef is returned.
 394
 395
 396 =head3 append_case (@case)
 397
 398 Appends a case to the system file.
 399 C<Case> is an array of scalars, each of which are the values of
 400 the variables in the dictionary corresponding to the system file.
 401 The special value C<PSPP::SYSMIS> may be used to indicate that a value
 402 is system missing.
 403 If the array contains less elements than variables in the dictionary,
 404 remaining values will be set to system missing.
 405
 406 =cut
 407
 408 sub new
 409 {
 410     my $class = shift;
 411     my $filename = shift;
 412     my $dict = shift;
 413     my $opts = shift;
 414
 415     my $self  = pxs_create_sysfile ($filename, $dict, $opts);
 416
 417     if ( ref $self )
 418     {
 419         bless ($self, $class);
 420     }
 421     return $self;
 422 }
 423
 424 =pod
 425
 426 =head3 close ()
 427
 428 Closes the system file.
 429
 430 This subroutine closes the system file and flushes it to disk.  No
 431 further cases may be written once the file has been closed.
 432 The system file will be automatically closed when it goes out of scope.
 433
 434 =cut
 435
 436 package PSPP::Reader;
 437
 438 =pod
 439
 440 =head2 PSPP::Reader
 441
 442 =cut
 443
 444 sub open
 445 {
 446     my $class = shift;
 447     my $filename = shift;
 448
 449     my $self  = pxs_open_sysfile ($filename);
 450
 451     if ( ref $self )
 452     {
 453         bless ($self, $class);
 454     }
 455     return $self;
 456 }
 457
 458 =pod
 459
 460 =head3 open ($filename)
 461
 462 Opens a system file for reading.
 463
 464 Open is used to read data from an existing system file.
 465 It creates and returns a PSPP::Reader object which can be used to read
 466 data and dictionary information from C<filename>.
 467
 468 =cut
 469
 470 sub get_dict
 471 {
 472     my $reader = shift;
 473
 474     my $dict = pxs_get_dict ($reader);
 475
 476     bless ($dict, "PSPP::Dict");
 477
 478     return $dict;
 479 }
 480
 481 =pod
 482
 483 =head3 get_dict ()
 484
 485 Returns the dictionary associated with the reader.
 486
 487 =head3 get_next_case ()
 488
 489 Retrieves the next case from the reader.
 490 This method returns an array of scalars, each of which are the values of
 491 the data in the system file.
 492 The first call to C<get_next_case> after C<open> has been called retrieves
 493 the first case in the system file.  Each subsequent call retrieves the next
 494 case.  If there are no more cases to be read, the function returns undef.
 495
 496 If the case contains system missing values, these values are set to the
 497 empty string.
 498
 499 =head2 Miscellaneous subroutines
 500
 501 The following subroutines provide (hopefully) useful information about the
 502 values retrieved from a reader.
 503
 504 =head3 PSPP::format_value ($value, $variable)
 505
 506 Returns a scalar containing a string representing C<value> formatted accoring
 507 to the print format of C<variable>.
 508 In the most common ussage,  C<value> should be a value of C<variable>.
 509
 510
 511 =head3 PSPP::value_is_missing ($value, $variable)
 512
 513 Returns non-zero if C<value> is either system missing, or if it matches the
 514 user missing criteria for C<variable>.
 515
 516 =cut
 517
 518 1;
 519 __END__
 520
 521
 522 =head1 AUTHOR
 523
 524 John Darrington, E<lt>john@darrington.wattle.id.auE<gt>
 525
 526 =head1 COPYRIGHT AND LICENSE
 527
 528 Copyright (C) 2007, 2008, 2009 by Free Software Foundation
 529
 530 This program is free software: you can redistribute it and/or modify
 531 it under the terms of the GNU General Public License as published by
 532 the Free Software Foundation, either version 3 of the License, or
 533 (at your option) any later version.
 534
 535 This program is distributed in the hope that it will be useful,
 536 but WITHOUT ANY WARRANTY; without even the implied warranty of
 537 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 538 GNU General Public License for more details.
 539
 540 You should have received a copy of the GNU General Public License
 541 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 542
 543 =cut