1@c PSPP - a program for statistical analysis. 2@c Copyright (C) 2019 Free Software Foundation, Inc. 3@c Permission is granted to copy, distribute and/or modify this document 4@c under the terms of the GNU Free Documentation License, Version 1.3 5@c or any later version published by the Free Software Foundation; 6@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. 7@c A copy of the license is included in the section entitled "GNU 8@c Free Documentation License". 9@c 10@node Invoking pspp-output 11@chapter Invoking @command{pspp-output} 12@cindex Invocation 13@cindex @command{pspp-output} 14 15@command{pspp-output} is a command-line utility accompanying @pspp{}. 16It supports multiple operations on SPSS viewer or @file{.spv} files, 17here called SPV files. SPSS 16 and later writes SPV files to 18represent the contents of its output editor. 19 20SPSS 15 and earlier versions instead use @file{.spo} files. 21@command{pspp-output} does not support this format. 22 23@command{pspp-options} may be invoked in the following ways: 24 25@display 26@t{pspp-output} @t{detect} @var{file} 27 28@t{pspp-output} [@var{options}] @t{dir} @var{file} 29 30@t{pspp-output} [@var{options}] @t{convert} @var{source} @var{destination} 31 32@t{pspp-output -@w{-}help} 33 34@t{pspp-output -@w{-}version} 35@end display 36 37Each of these forms is documented separately below. 38@command{pspp-output} also has several undocumented command forms that 39developers may find useful for debugging. 40 41@menu 42* The pspp-output detect Command:: 43* The pspp-output dir Command:: 44* The pspp-output convert Command:: 45* Input Selection Options:: 46@end menu 47 48@node The pspp-output detect Command 49@section The @code{detect} Command 50 51@display 52@t{pspp-output} @t{detect} @var{file} 53@end display 54 55When @var{file} is an SPV file, @command{pspp-output} exits 56successfully without outputting anything. When @var{file} is not an 57SPV file or some other error occurs, @command{pspp-output} prints an 58error message and exits with a failure indication. 59 60@node The pspp-output dir Command 61@section The @code{dir} Command 62 63@display 64@t{pspp-output} [@var{options}] @t{dir} @var{file} 65@end display 66 67Prints on stdout a table of contents for SPV file @var{file}. By 68default, this table lists every object in the file, except for hidden 69objects. @xref{Input Selection Options}, for information on the 70options available to select a subset of objects. 71 72The following additional option for @command{dir} is intended mainly 73for use by PSPP developers: 74 75@table @option 76@item --member-names 77Also show the names of the Zip members associated with each object. 78@end table 79 80@node The pspp-output convert Command 81@section The @code{convert} Command 82 83@display 84@t{pspp-output} [@var{options}] @t{convert} @var{source} @var{destination} 85@end display 86 87Reads SPV file @var{source} and converts it to another format, writing 88the output to @var{destination}. 89 90By default, the intended format for @var{destination} is inferred 91based on its extension, in the same way that the @command{pspp} 92program does for its output files. @xref{Invoking PSPP}, for details. 93 94@xref{Input Selection Options}, for information on the options 95available to select a subset of objects to include in the output. The 96following additional options are accepted: 97 98@table @option 99@item -O format=@var{format} 100Overrides the format inferred from the output file's extension. Use 101@option{--help} to list the available formats. @xref{Invoking PSPP}, 102for details of the available output formats. 103 104@item -O @var{option}=@var{value} 105Sets an option for the output file format. @xref{Invoking PSPP}, for 106details of the available output options. 107 108@item -F 109@itemx --force 110By default, if the source is corrupt or otherwise cannot be processed, 111the destination is not written. With @option{-F} or @option{--force}, 112the destination is written as best it can, even with errors. 113@end table 114 115@node Input Selection Options 116@section Input Selection Options 117 118The @command{dir} and @command{convert} commands, by default, operate 119on all of the objects in the source SPV file, except for objects that 120are not visible in the output viewer window. The user may specify 121these options to select a subset of the input objects. When multiple 122options are used, only objects that satisfy all of them are selected: 123 124@table @option 125@item --select=@r{[}^@r{]}@var{class}@dots{} 126Include only objects of the given @var{class}; with leading @samp{^}, 127include only objects not in the class. Use commas to separate 128multiple classes. The supported classes are: 129 130@quotation 131@code{charts headings logs models tables texts trees warnings 132outlineheaders pagetitle notes unknown other} 133@end quotation 134 135Use @option{--select=help} to print this list of classes. 136 137@item --commands=@r{[}^@r{]}@var{command}@dots{} 138@itemx --subtypes=@r{[}^@r{]}@var{subtype}@dots{} 139@itemx --labels=@r{[}^@r{]}@var{label}@dots{} 140Include only objects with the specified @var{command}, @var{subtype}, 141or @var{label}. With a leading @samp{^}, include only the objects 142that do not match. Multiple values may be specified separated by 143commas. An asterisk at the end of a value acts as a wildcard. 144 145The @option{--command} option matches command identifiers, case 146insensitively. All of the objects produced by a single command use 147the same, unique command identifier. Command identifiers are always 148in English regardless of the language used for output. They often 149differ from the command name in PSPP syntax. Use the 150@command{pspp-output} program's @command{dir} command to print command 151identifiers in particular output. 152 153The @option{--subtypes} option matches particular tables within a 154command, case insensitively. Subtypes are not necessarily unique: two 155commands that produce similar output tables may use the same subtype. 156Subtypes are always in English and @command{dir} will print them. 157 158The @option{--labels} option matches the labels in table output (that 159is, the table titles). Labels are affected by the output language, 160variable names and labels, split file settings, and other factors. 161 162@item --instances=@var{instance}@dots{} 163Include the specified @var{instance} of an object that matches the 164other criteria within a single command. The @var{instance} may be a 165number (1 for the first instance, 2 for the second, and so on) or 166@code{last} for the last instance. 167 168@item --show-hidden 169Include hidden output objects in the output. By default, they are 170excluded. 171 172@item --or 173Separates two sets of selection options. Objects selected by either 174set of options are included in the output. 175@end table 176 177The following additional input selection options are intended mainly 178for use by PSPP developers: 179 180@table @option 181@item --errors 182Include only objects that cause an error when read. With the 183@command{convert} command, this is most useful in conjunction with the 184@option{--force} option. 185 186@item --members=@var{member}@dots{} 187Include only the objects that include a listed Zip file @var{member}. 188More than one name may be included, comma-separated. The members in 189an SPV file may be listed with the @command{dir} command by adding the 190@option{--show-members} option or with the @command{zipinfo} program 191included with many operating systems. Error messages that 192@command{pspp-output} prints when it reads SPV files also often 193include member names. 194 195@item --member-names 196Displays the name of the Zip member or members associated with each 197object just above the object itself. 198@end table 199