pintos-os.org Git - pspp/blob - doc/pspp-output.texi

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