str: Always null-terminate string in str_format_26adic().
[pspp-builds.git] / 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