Improve error messages for missing subcommands.
[pspp] / 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