-@node Language, Expressions, Invocation, Top
+@node Language
@chapter The PSPP language
@cindex language, PSPP
@cindex PSPP, language
-@quotation
-@strong{Please note:} PSPP is not even close to completion.
+@note{PSPP is not even close to completion.
Only a few statistical procedures are implemented. PSPP
-is a work in progress.
-@end quotation
+is a work in progress.}
This chapter discusses elements common to many PSPP commands.
Later chapters will describe individual commands in detail.
@menu
* Tokens:: Characters combine to form tokens.
* Commands:: Tokens combine to form commands.
+* Syntax Variants:: Batch vs. Interactive mode
* Types of Commands:: Commands come in several flavors.
* Order of Commands:: Commands combine to form syntax files.
* Missing Observations:: Handling missing observations.
* BNF:: How command syntax is described.
@end menu
-@node Tokens, Commands, Language, Language
+
+@node Tokens
@section Tokens
@cindex language, lexical analysis
@cindex language, tokens
the default setting is in effect.
@end table
-@node Commands, Types of Commands, Tokens, Language
+@node Commands
@section Forming commands of tokens
@cindex PSPP, command structure
by default, although you can use the NULLINE subcommand of @cmd{SET}
to disable this feature (@pxref{SET}).
-In batch mode only, that is, when reading commands from a file instead
-of an interactive user, any line that contains a non-space character
-in the leftmost column begins a new command. Thus, each command
-consists of a flush-left line followed by any number of lines indented
-from the left margin. In this mode, a plus or minus sign
-(@samp{+}, @samp{@minus{}}) as the first character
-in a line is ignored and causes that line to begin a new command,
-which allows for visual indentation of a command without that command
-being considered part of the previous command.
-
-@node Types of Commands, Order of Commands, Commands, Language
+@node Syntax Variants
+@section Variants of syntax.
+
+@cindex Batch syntax
+@cindex Interactive syntax
+
+There are two variants of command syntax, @i{viz}: @dfn{batch} mode and
+@dfn{interactive} mode.
+Batch mode is the default when reading commands from a file.
+Interactive mode is the default when commands are typed at a prompt
+by a user.
+Certain commands, such as @cmd{INSERT} (@pxref{INSERT}), may explicitly
+change the syntax mode.
+
+In batch mode, any line that contains a non-space character
+in the leftmost column begins a new command.
+Thus, each command consists of a flush-left line followed by any
+number of lines indented from the left margin.
+In this mode, a plus or minus sign (@samp{+}, @samp{@minus{}}) as the
+first character in a line is ignored and causes that line to begin a
+new command, which allows for visual indentation of a command without
+that command being considered part of the previous command.
+The period terminating the end of a command is optional but recommended.
+
+In interactive mode, each command must either be terminated with a period,
+or an empty line must follow the command.
+The use of (@samp{+} and @samp{@minus{}} as continuation characters is not
+permitted.
+
+@node Types of Commands
@section Types of Commands
Commands in PSPP are divided roughly into six categories:
active file (the data) to be read.
@end table
-@node Order of Commands, Missing Observations, Types of Commands, Language
+@node Order of Commands
@section Order of Commands
@cindex commands, ordering
@cindex order of commands
@end itemize
@end table
-@node Missing Observations, Variables, Order of Commands, Language
+@node Missing Observations
@section Handling missing observations
@cindex missing values
@cindex values, missing
Variables, whether numeric or string, can have designated
@dfn{user-missing values}. Every user-missing value is an actual value
for that variable. However, most of the time user-missing values are
-treated in the same way as the system-missing value. String variables
-that are wider than a certain width, usually 8 characters (depending on
-computer architecture), cannot have user-missing values.
+treated in the same way as the system-missing value.
For more information on missing values, see the following sections:
@ref{Variables}, @ref{MISSING VALUES}, @ref{Expressions}. See also the
documentation on individual procedures for information on how they
handle missing values.
-@node Variables, Files, Missing Observations, Language
+@node Variables
@section Variables
@cindex variables
@cindex dictionary
* Scratch Variables:: Variables deleted by procedures.
@end menu
-@node Attributes, System Variables, Variables, Variables
+@node Attributes
@subsection Attributes of Variables
@cindex variables, attributes of
@cindex attributes of variables
@item Width
(string variables only) String variables with a width of 8 characters or
fewer are called @dfn{short string variables}. Short string variables
-can be used in many procedures where @dfn{long string variables} (those
+may be used in a few contexts where @dfn{long string variables} (those
with widths greater than 8) are not allowed.
-Certain systems may consider strings longer than 8
-characters to be short strings. Eight characters represents a minimum
-figure for the maximum length of a short string.
-
@item Position
Variables in the dictionary are arranged in a specific order.
@cmd{DISPLAY} can be used to show this order: see @ref{DISPLAY}.
@item Write format
Similar to print format, but used by the @cmd{WRITE} command
(@pxref{WRITE}).
+
+@cindex custom attributes
+@item Custom attributes
+User-defined associations between names and values. @xref{VARIABLE
+ATTRIBUTE}.
@end table
-@node System Variables, Sets of Variables, Attributes, Variables
+@node System Variables
@subsection Variables Automatically Defined by PSPP
@cindex system variables
@cindex variables, system
Page width, in characters, in format F3.
@end table
-@node Sets of Variables, Input and Output Formats, System Variables, Variables
+@node Sets of Variables
@subsection Lists of variable names
@cindex @code{TO} convention
@cindex convention, @code{TO}
another command with this method, the same set can be referenced on
later commands using the same syntax.
-@node Input and Output Formats, Scratch Variables, Sets of Variables, Variables
+@node Input and Output Formats
@subsection Input and Output Formats
@cindex formats
The maximum width for time and date formats is 40 columns. Minimum
input and output width for each of the time and date formats is shown
below:
+
@float
@multitable {DATETIME} {Min. Input Width} {Min. Output Width} {4-digit year}
@headitem Format @tab Min. Input Width @tab Min. Output Width @tab Option
input, uppercase and lowercase are both accepted. The default output
format is A format with half the input width.
-@node Scratch Variables, , Input and Output Formats, Variables
+@node Scratch Variables
@subsection Scratch Variables
@cindex scratch variables
name of a file as a string, that is, enclosed within @samp{'} or
@samp{"}.
+A file name string that begins or ends with @samp{|} is treated as the
+name of a command to pipe data to or from. You can use this feature
+to read data over the network using a program such as @samp{curl}
+(e.g.@: @code{GET '|curl -s -S http://example.com/mydata.sav'}), to
+read compressed data from a file using a program such as @samp{zcat}
+(e.g.@: @code{GET '|zcat mydata.sav.gz'}), and for many other
+purposes.
+
PSPP also supports declaring named file handles with the @cmd{FILE
HANDLE} command. This command associates an identifier of your choice
(the file handle's name) with a file. Later, the file handle name can
@dfn{start symbol}. The start symbol defines the entire syntax for
that command.
@end itemize
-@setfilename ignored