perl-module/Examples.pod

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