perl-module/Examples.pod

   1 =pod
   2
   3 =head1 PSPP::Examples
   4
   5 This page shows some simple examples of using the PSPP module.
   6 See L<PSPP> for details on each of the subroutines.
   7
   8 =head2 A Simple example
   9
  10 This example creates a system file called F<foo.sav>, containing one
  11 variable called "id".  It contains no data.
  12
  13         use PSPP;
  14
  15         my $dict = PSPP::Dict->new ();
  16         my $var = PSPP::Var->new ($dict, "id");
  17
  18         my $sysfile = PSPP::Sysfile->new ("foo.sav", $dict);
  19         $sysfile->close();
  20
  21
  22 =head2 A slightly more complex example
  23
  24 In this example there are three variables, called "id", "name" and "dob".
  25 Their formats are F2.0, A80 and DATETIME17 respectively.
  26
  27         use PSPP;
  28
  29         my $dict = PSPP::Dict->new ();
  30         PSPP::Var->new ($dict, "id",
  31                    (fmt=>PSPP::Fmt::F, width=>2, decimals=>0) );
  32
  33         PSPP::Var->new ($dict, "name", (fmt=>PSPP::Fmt::A, width=>80) );
  34         PSPP::Var->new ($dict, "dob",  (fmt=>PSPP::Fmt::DATETIME) );
  35
  36         my $sysfile = PSPP::Sysfile->new ("foo.sav", $dict);
  37         $sysfile->close();
  38
  39 =head2 Changing the properties of variables
  40
  41 After a variable has been created, parameters may be set for it.
  42
  43         use PSPP;
  44
  45         my $dict = PSPP::Dict->new ();
  46         my $var1 = PSPP::Var->new ($dict, "id");
  47
  48         $var1->set_label ("A unique identifier");
  49         $var1->add_value_label (0, "Zero");
  50         $var1->add_value_label (1, "One");
  51
  52
  53 =head2 Appending data to the file
  54
  55 When a file is created, it contains no data.  Data is added by
  56 appending cases to the file.
  57
  58 This example creates a file with 3 cases.
  59
  60         use PSPP;
  61
  62         my $dict = PSPP::Dict->new ();
  63         PSPP::Var->new ($dict, "id",
  64            (fmt=>PSPP::Fmt::F, width=>2, decimals=>0) );
  65
  66         PSPP::Var->new ($dict, "name", (fmt=>PSPP::Fmt::A, width=>8) );
  67
  68         my $sysfile = PSPP::Sysfile->new ("foo.sav", $dict);
  69
  70         $sysfile->append_case ( [1, "Alf"] );
  71         $sysfile->append_case ( [2, "Bert"] );
  72         $sysfile->append_case ( [3, "Charlie"] );
  73
  74         $sysfile->close();
  75
  76 =head2  Variables with differing input and output formats
  77
  78 By default,  a variable's output format corresponds to the input format.
  79 However, the output format may be changed after the variable has
  80 been created.
  81
  82 This example shows how  to create a DATETIME variable using the current time
  83 as its value.  Since pspp uses a different epoch to perl, the constant
  84 PSPP::PERL_EPOCH needs to be added to the value returned from time(), in order
  85 that it be correctly represented by pspp.
  86
  87         use PSPP;
  88
  89         my $dict = PSPP::Dict->new ();
  90
  91         my $var1 = PSPP::Var->new ($dict, "entrytime",
  92                 (fmt=>PSPP::Fmt::F) );
  93
  94         $var1->set_output_format ( (fmt=>PSPP::Fmt::DATETIME, width=>20) );
  95
  96         my $sysfile = PSPP::Sysfile->new ("foo.sav", $dict);
  97
  98         my $now = time ();
  99
 100         $sysfile->append_case ( [ $now  + PSPP::PERL_EPOCH]  )
 101                 || die "Cant write case";
 102
 103         $sysfile->close();
 104
 105 =head2  Reading data
 106
 107 Data can be read from a system file or other source:
 108
 109         use PSPP;
 110
 111         my $sf = PSPP::Reader->open ("foo.sav");
 112
 113         my $dict = $sf->get_dict ();
 114
 115
 116 Once opened, the dictionary can be used like any other.
 117
 118         for ($v = 0 ; $v < $dict->get_var_cnt() ; $v++)
 119         {
 120             my $var = $dict->get_var ($v);
 121
 122             # Print the variables
 123             my $name = $var->get_name ();
 124             my $label = $var->get_label ();
 125             print "Var: $name, Label: $label\n";
 126
 127             # Retrieve and print the value labels
 128             my $vl = $var->get_value_labels ();
 129             print "$_: $vl->{$_}\n" for keys %$vl;
 130         }
 131
 132
 133 Reading of data must be done sequentially using the C<get_next_case> method.
 134
 135         while (my $c = $sf->get_next_case () )
 136         {
 137             my $v;
 138             for ($v = 0; $v < $dict->get_var_cnt(); $v++)
 139             {
 140                 print "val$v: @$c[$v] ";
 141             }
 142             print "\n";
 143         }
 144
 145
 146 =cut