2 @chapter The PSPP language
6 @note{PSPP is not even close to completion.
7 Only a few statistical procedures are implemented. PSPP
8 is a work in progress.}
10 This chapter discusses elements common to many PSPP commands.
11 Later chapters will describe individual commands in detail.
14 * Tokens:: Characters combine to form tokens.
15 * Commands:: Tokens combine to form commands.
16 * Syntax Variants:: Batch vs. Interactive mode
17 * Types of Commands:: Commands come in several flavors.
18 * Order of Commands:: Commands combine to form syntax files.
19 * Missing Observations:: Handling missing observations.
20 * Variables:: The unit of data storage.
21 * Files:: Files used by PSPP.
22 * File Handles:: How files are named.
23 * BNF:: How command syntax is described.
29 @cindex language, lexical analysis
30 @cindex language, tokens
32 @cindex lexical analysis
34 PSPP divides most syntax file lines into series of short chunks
36 Tokens are then grouped to form commands, each of which tells
37 PSPP to take some action---read in data, write out data, perform
38 a statistical procedure, etc. Each type of token is
44 Identifiers are names that typically specify variables, commands, or
45 subcommands. The first character in an identifier must be a letter,
46 @samp{#}, or @samp{@@}. The remaining characters in the identifier
47 must be letters, digits, or one of the following special characters:
53 @cindex case-sensitivity
54 Identifiers may be any length, but only the first 64 bytes are
55 significant. Identifiers are not case-sensitive: @code{foobar},
56 @code{Foobar}, @code{FooBar}, @code{FOOBAR}, and @code{FoObaR} are
57 different representations of the same identifier.
59 @cindex identifiers, reserved
60 @cindex reserved identifiers
61 Some identifiers are reserved. Reserved identifiers may not be used
62 in any context besides those explicitly described in this manual. The
63 reserved identifiers are:
66 @center ALL AND BY EQ GE GT LE LT NE NOT OR TO WITH
70 Keywords are a subclass of identifiers that form a fixed part of
71 command syntax. For example, command and subcommand names are
72 keywords. Keywords may be abbreviated to their first 3 characters if
73 this abbreviation is unambiguous. (Unique abbreviations of 3 or more
74 characters are also accepted: @samp{FRE}, @samp{FREQ}, and
75 @samp{FREQUENCIES} are equivalent when the last is a keyword.)
77 Reserved identifiers are always used as keywords. Other identifiers
78 may be used both as keywords and as user-defined identifiers, such as
85 Numbers are expressed in decimal. A decimal point is optional.
86 Numbers may be expressed in scientific notation by adding @samp{e} and
87 a base-10 exponent, so that @samp{1.234e3} has the value 1234. Here
88 are some more examples of valid numbers:
91 -5 3.14159265359 1e100 -.707 8945.
94 Negative numbers are expressed with a @samp{-} prefix. However, in
95 situations where a literal @samp{-} token is expected, what appears to
96 be a negative number is treated as @samp{-} followed by a positive
99 No white space is allowed within a number token, except for horizontal
100 white space between @samp{-} and the rest of the number.
102 The last example above, @samp{8945.} will be interpreted as two
103 tokens, @samp{8945} and @samp{.}, if it is the last token on a line.
104 @xref{Commands, , Forming commands of tokens}.
110 @cindex case-sensitivity
111 Strings are literal sequences of characters enclosed in pairs of
112 single quotes (@samp{'}) or double quotes (@samp{"}). To include the
113 character used for quoting in the string, double it, e.g.@:
114 @samp{'it''s an apostrophe'}. White space and case of letters are
115 significant inside strings.
117 Strings can be concatenated using @samp{+}, so that @samp{"a" + 'b' +
118 'c'} is equivalent to @samp{'abc'}. Concatenation is useful for
119 splitting a single string across multiple source lines. The maximum
120 length of a string, after concatenation, is 255 characters.
122 Strings may also be expressed as hexadecimal, octal, or binary
123 character values by prefixing the initial quote character by @samp{X},
124 @samp{O}, or @samp{B} or their lowercase equivalents. Each pair,
125 triplet, or octet of characters, according to the radix, is
126 transformed into a single character with the given value. If there is
127 an incomplete group of characters, the missing final digits are
128 assumed to be @samp{0}. These forms of strings are nonportable
129 because numeric values are associated with different characters by
130 different operating systems. Therefore, their use should be confined
131 to syntax files that will not be widely distributed.
133 @cindex characters, reserved
136 The character with value 00 is reserved for
137 internal use by PSPP. Its use in strings causes an error and
138 replacement by a space character.
140 @item Punctuators and Operators
143 These tokens are the punctuators and operators:
146 @center , / = ( ) + - * / ** < <= <> > >= ~= & | .
149 Most of these appear within the syntax of commands, but the period
150 (@samp{.}) punctuator is used only at the end of a command. It is a
151 punctuator only as the last character on a line (except white space).
152 When it is the last non-space character on a line, a period is not
153 treated as part of another token, even if it would otherwise be part
154 of, e.g.@:, an identifier or a floating-point number.
156 Actually, the character that ends a command can be changed with
157 @cmd{SET}'s ENDCMD subcommand (@pxref{SET}), but we do not recommend
158 doing so. Throughout the remainder of this manual we will assume that
159 the default setting is in effect.
163 @section Forming commands of tokens
165 @cindex PSPP, command structure
166 @cindex language, command structure
167 @cindex commands, structure
169 Most PSPP commands share a common structure. A command begins with a
170 command name, such as @cmd{FREQUENCIES}, @cmd{DATA LIST}, or @cmd{N OF
171 CASES}. The command name may be abbreviated to its first word, and
172 each word in the command name may be abbreviated to its first three
173 or more characters, where these abbreviations are unambiguous.
175 The command name may be followed by one or more @dfn{subcommands}.
176 Each subcommand begins with a subcommand name, which may be
177 abbreviated to its first three letters. Some subcommands accept a
178 series of one or more specifications, which follow the subcommand
179 name, optionally separated from it by an equals sign
180 (@samp{=}). Specifications may be separated from each other
181 by commas or spaces. Each subcommand must be separated from the next (if any)
182 by a forward slash (@samp{/}).
184 There are multiple ways to mark the end of a command. The most common
185 way is to end the last line of the command with a period (@samp{.}) as
186 described in the previous section (@pxref{Tokens}). A blank line, or
187 one that consists only of white space or comments, also ends a command
188 by default, although you can use the NULLINE subcommand of @cmd{SET}
189 to disable this feature (@pxref{SET}).
191 @node Syntax Variants
192 @section Variants of syntax.
195 @cindex Interactive syntax
197 There are two variants of command syntax, @i{viz}: @dfn{batch} mode and
198 @dfn{interactive} mode.
199 Batch mode is the default when reading commands from a file.
200 Interactive mode is the default when commands are typed at a prompt
202 Certain commands, such as @cmd{INSERT} (@pxref{INSERT}), may explicitly
203 change the syntax mode.
205 In batch mode, any line that contains a non-space character
206 in the leftmost column begins a new command.
207 Thus, each command consists of a flush-left line followed by any
208 number of lines indented from the left margin.
209 In this mode, a plus or minus sign (@samp{+}, @samp{@minus{}}) as the
210 first character in a line is ignored and causes that line to begin a
211 new command, which allows for visual indentation of a command without
212 that command being considered part of the previous command.
213 The period terminating the end of a command is optional but recommended.
215 In interactive mode, each command must either be terminated with a period,
216 or an empty line must follow the command.
217 The use of (@samp{+} and @samp{@minus{}} as continuation characters is not
220 @node Types of Commands
221 @section Types of Commands
223 Commands in PSPP are divided roughly into six categories:
226 @item Utility commands
227 @cindex utility commands
228 Set or display various global options that affect PSPP operations.
229 May appear anywhere in a syntax file. @xref{Utilities, , Utility
232 @item File definition commands
233 @cindex file definition commands
234 Give instructions for reading data from text files or from special
235 binary ``system files''. Most of these commands replace any previous
236 data or variables with new data or
237 variables. At least one file definition command must appear before the first command in any of
238 the categories below. @xref{Data Input and Output}.
240 @item Input program commands
241 @cindex input program commands
242 Though rarely used, these provide tools for reading data files
243 in arbitrary textual or binary formats. @xref{INPUT PROGRAM}.
245 @item Transformations
246 @cindex transformations
247 Perform operations on data and write data to output files. Transformations
248 are not carried out until a procedure is executed.
250 @item Restricted transformations
251 @cindex restricted transformations
252 Transformations that cannot appear in certain contexts. @xref{Order
253 of Commands}, for details.
257 Analyze data, writing results of analyses to the listing file. Cause
258 transformations specified earlier in the file to be performed. In a
259 more general sense, a @dfn{procedure} is any command that causes the
260 active file (the data) to be read.
263 @node Order of Commands
264 @section Order of Commands
265 @cindex commands, ordering
266 @cindex order of commands
268 PSPP does not place many restrictions on ordering of commands. The
269 main restriction is that variables must be defined before they are otherwise
270 referenced. This section describes the details of command ordering,
271 but most users will have no need to refer to them.
273 PSPP possesses five internal states, called initial, INPUT PROGRAM,
274 FILE TYPE, transformation, and procedure states. (Please note the
275 distinction between the @cmd{INPUT PROGRAM} and @cmd{FILE TYPE}
276 @emph{commands} and the INPUT PROGRAM and FILE TYPE @emph{states}.)
278 PSPP starts in the initial state. Each successful completion
279 of a command may cause a state transition. Each type of command has its
280 own rules for state transitions:
283 @item Utility commands
288 Do not cause state transitions. Exception: when @cmd{N OF CASES}
289 is executed in the procedure state, it causes a transition to the
290 transformation state.
293 @item @cmd{DATA LIST}
298 When executed in the initial or procedure state, causes a transition to
299 the transformation state.
301 Clears the active file if executed in the procedure or transformation
305 @item @cmd{INPUT PROGRAM}
308 Invalid in INPUT PROGRAM and FILE TYPE states.
310 Causes a transition to the INPUT PROGRAM state.
312 Clears the active file.
315 @item @cmd{FILE TYPE}
318 Invalid in INPUT PROGRAM and FILE TYPE states.
320 Causes a transition to the FILE TYPE state.
322 Clears the active file.
325 @item Other file definition commands
328 Invalid in INPUT PROGRAM and FILE TYPE states.
330 Cause a transition to the transformation state.
332 Clear the active file, except for @cmd{ADD FILES}, @cmd{MATCH FILES},
336 @item Transformations
339 Invalid in initial and FILE TYPE states.
341 Cause a transition to the transformation state.
344 @item Restricted transformations
347 Invalid in initial, INPUT PROGRAM, and FILE TYPE states.
349 Cause a transition to the transformation state.
355 Invalid in initial, INPUT PROGRAM, and FILE TYPE states.
357 Cause a transition to the procedure state.
361 @node Missing Observations
362 @section Handling missing observations
363 @cindex missing values
364 @cindex values, missing
366 PSPP includes special support for unknown numeric data values.
367 Missing observations are assigned a special value, called the
368 @dfn{system-missing value}. This ``value'' actually indicates the
369 absence of a value; it means that the actual value is unknown. Procedures
370 automatically exclude from analyses those observations or cases that
371 have missing values. Details of missing value exclusion depend on the
372 procedure and can often be controlled by the user; refer to
373 descriptions of individual procedures for details.
375 The system-missing value exists only for numeric variables. String
376 variables always have a defined value, even if it is only a string of
379 Variables, whether numeric or string, can have designated
380 @dfn{user-missing values}. Every user-missing value is an actual value
381 for that variable. However, most of the time user-missing values are
382 treated in the same way as the system-missing value. String variables
383 that are wider than a certain width, usually 8 characters (depending on
384 computer architecture), cannot have user-missing values.
386 For more information on missing values, see the following sections:
387 @ref{Variables}, @ref{MISSING VALUES}, @ref{Expressions}. See also the
388 documentation on individual procedures for information on how they
389 handle missing values.
396 Variables are the basic unit of data storage in PSPP. All the
397 variables in a file taken together, apart from any associated data, are
398 said to form a @dfn{dictionary}.
399 Some details of variables are described in the sections below.
402 * Attributes:: Attributes of variables.
403 * System Variables:: Variables automatically defined by PSPP.
404 * Sets of Variables:: Lists of variable names.
405 * Input and Output Formats:: Input and output formats.
406 * Scratch Variables:: Variables deleted by procedures.
410 @subsection Attributes of Variables
411 @cindex variables, attributes of
412 @cindex attributes of variables
413 Each variable has a number of attributes, including:
417 An identifier, up to 64 bytes long. Each variable must have a different name.
420 Some system variable names begin with @samp{$}, but user-defined
421 variables' names may not begin with @samp{$}.
425 @cindex variable names, ending with period
426 The final character in a variable name should not be @samp{.}, because
427 such an identifier will be misinterpreted when it is the final token
428 on a line: @code{FOO.} will be divided into two separate tokens,
429 @samp{FOO} and @samp{.}, indicating end-of-command. @xref{Tokens}.
432 The final character in a variable name should not be @samp{_}, because
433 some such identifiers are used for special purposes by PSPP
436 As with all PSPP identifiers, variable names are not case-sensitive.
437 PSPP capitalizes variable names on output the same way they were
438 capitalized at their point of definition in the input.
440 @cindex variables, type
441 @cindex type of variables
445 @cindex variables, width
446 @cindex width of variables
448 (string variables only) String variables with a width of 8 characters or
449 fewer are called @dfn{short string variables}. Short string variables
450 can be used in many procedures where @dfn{long string variables} (those
451 with widths greater than 8) are not allowed.
453 Certain systems may consider strings longer than 8
454 characters to be short strings. Eight characters represents a minimum
455 figure for the maximum length of a short string.
458 Variables in the dictionary are arranged in a specific order.
459 @cmd{DISPLAY} can be used to show this order: see @ref{DISPLAY}.
462 Either reinitialized to 0 or spaces for each case, or left at its
463 existing value. @xref{LEAVE}.
465 @cindex missing values
466 @cindex values, missing
468 Optionally, up to three values, or a range of values, or a specific
469 value plus a range, can be specified as @dfn{user-missing values}.
470 There is also a @dfn{system-missing value} that is assigned to an
471 observation when there is no other obvious value for that observation.
472 Observations with missing values are automatically excluded from
473 analyses. User-missing values are actual data values, while the
474 system-missing value is not a value at all. @xref{Missing Observations}.
476 @cindex variable labels
477 @cindex labels, variable
479 A string that describes the variable. @xref{VARIABLE LABELS}.
482 @cindex labels, value
484 Optionally, these associate each possible value of the variable with a
485 string. @xref{VALUE LABELS}.
489 Display width, format, and (for numeric variables) number of decimal
490 places. This attribute does not affect how data are stored, just how
491 they are displayed. Example: a width of 8, with 2 decimal places.
492 @xref{Input and Output Formats}.
496 Similar to print format, but used by the @cmd{WRITE} command
499 @cindex custom attributes
500 @item Custom attributes
501 User-defined associations between names and values. @xref{VARIABLE
505 @node System Variables
506 @subsection Variables Automatically Defined by PSPP
507 @cindex system variables
508 @cindex variables, system
510 There are seven system variables. These are not like ordinary
511 variables because system variables are not always stored. They can be used only
512 in expressions. These system variables, whose values and output formats
513 cannot be modified, are described below.
516 @cindex @code{$CASENUM}
518 Case number of the case at the moment. This changes as cases are
523 Date the PSPP process was started, in format A9, following the
524 pattern @code{DD MMM YY}.
526 @cindex @code{$JDATE}
528 Number of days between 15 Oct 1582 and the time the PSPP process
531 @cindex @code{$LENGTH}
533 Page length, in lines, in format F11.
535 @cindex @code{$SYSMIS}
537 System missing value, in format F1.
541 Number of seconds between midnight 14 Oct 1582 and the time the active file
542 was read, in format F20.
544 @cindex @code{$WIDTH}
546 Page width, in characters, in format F3.
549 @node Sets of Variables
550 @subsection Lists of variable names
551 @cindex @code{TO} convention
552 @cindex convention, @code{TO}
554 To refer to a set of variables, list their names one after another.
555 Optionally, their names may be separated by commas. To include a
556 range of variables from the dictionary in the list, write the name of
557 the first and last variable in the range, separated by @code{TO}. For
558 instance, if the dictionary contains six variables with the names
559 @code{ID}, @code{X1}, @code{X2}, @code{GOAL}, @code{MET}, and
560 @code{NEXTGOAL}, in that order, then @code{X2 TO MET} would include
561 variables @code{X2}, @code{GOAL}, and @code{MET}.
563 Commands that define variables, such as @cmd{DATA LIST}, give
564 @code{TO} an alternate meaning. With these commands, @code{TO} define
565 sequences of variables whose names end in consecutive integers. The
566 syntax is two identifiers that begin with the same root and end with
567 numbers, separated by @code{TO}. The syntax @code{X1 TO X5} defines 5
568 variables, named @code{X1}, @code{X2}, @code{X3}, @code{X4}, and
569 @code{X5}. The syntax @code{ITEM0008 TO ITEM0013} defines 6
570 variables, named @code{ITEM0008}, @code{ITEM0009}, @code{ITEM0010},
571 @code{ITEM0011}, @code{ITEM0012}, and @code{ITEM00013}. The syntaxes
572 @code{QUES001 TO QUES9} and @code{QUES6 TO QUES3} are invalid.
574 After a set of variables has been defined with @cmd{DATA LIST} or
575 another command with this method, the same set can be referenced on
576 later commands using the same syntax.
578 @node Input and Output Formats
579 @subsection Input and Output Formats
582 An @dfn{input format} describes how to interpret the contents of an
583 input field as a number or a string. It might specify that the field
584 contains an ordinary decimal number, a time or date, a number in binary
585 or hexadecimal notation, or one of several other notations. Input
586 formats are used by commands such as @cmd{DATA LIST} that read data or
587 syntax files into the PSPP active file.
589 Every input format corresponds to a default @dfn{output format} that
590 specifies the formatting used when the value is output later. It is
591 always possible to explicitly specify an output format that resembles
592 the input format. Usually, this is the default, but in cases where the
593 input format is unfriendly to human readability, such as binary or
594 hexadecimal formats, the default output format is an easier-to-read
597 Every variable has two output formats, called its @dfn{print format} and
598 @dfn{write format}. Print formats are used in most output contexts;
599 write formats are used only by @cmd{WRITE} (@pxref{WRITE}). Newly
600 created variables have identical print and write formats, and
601 @cmd{FORMATS}, the most commonly used command for changing formats
602 (@pxref{FORMATS}), sets both of them to the same value as well. Thus,
603 most of the time, the distinction between print and write formats is
606 Input and output formats are specified to PSPP with a @dfn{format
607 specification} of the form @code{TYPEw} or @code{TYPEw.d}, where
608 @code{TYPE} is one of the format types described later, @code{w} is a
609 field width measured in columns, and @code{d} is an optional number of
610 decimal places. If @code{d} is omitted, a value of 0 is assumed. Some
611 formats do not allow a nonzero @code{d} to be specified.
613 The following sections describe the input and output formats supported
617 * Basic Numeric Formats::
618 * Custom Currency Formats::
619 * Legacy Numeric Formats::
620 * Binary and Hexadecimal Numeric Formats::
621 * Time and Date Formats::
622 * Date Component Formats::
626 @node Basic Numeric Formats
627 @subsubsection Basic Numeric Formats
629 @cindex numeric formats
630 The basic numeric formats are used for input and output of real numbers
631 in standard or scientific notation. The following table shows an
632 example of how each format displays positive and negative numbers with
633 the default decimal point setting:
636 @multitable {DOLLAR10.2} {@code{@tie{}$3,141.59}} {@code{-$3,141.59}}
637 @headitem Format @tab @code{@tie{}3141.59} @tab @code{-3141.59}
638 @item F8.2 @tab @code{@tie{}3141.59} @tab @code{-3141.59}
639 @item COMMA9.2 @tab @code{@tie{}3,141.59} @tab @code{-3,141.59}
640 @item DOT9.2 @tab @code{@tie{}3.141,59} @tab @code{-3.141,59}
641 @item DOLLAR10.2 @tab @code{@tie{}$3,141.59} @tab @code{-$3,141.59}
642 @item PCT9.2 @tab @code{@tie{}3141.59%} @tab @code{-3141.59%}
643 @item E8.1 @tab @code{@tie{}3.1E+003} @tab @code{-3.1E+003}
647 On output, numbers in F format are expressed in standard decimal
648 notation with the requested number of decimal places. The other formats
649 output some variation on this style:
653 Numbers in COMMA format are additionally grouped every three digits by
654 inserting a grouping character. The grouping character is ordinarily a
655 comma, but it can be changed to a period (@pxref{SET DECIMAL}).
658 DOT format is like COMMA format, but it interchanges the role of the
659 decimal point and grouping characters. That is, the current grouping
660 character is used as a decimal point and vice versa.
663 DOLLAR format is like COMMA format, but it prefixes the number with
667 PCT format is like F format, but adds @samp{%} after the number.
670 The E format always produces output in scientific notation.
673 On input, the basic numeric formats accept positive and numbers in
674 standard decimal notation or scientific notation. Leading and trailing
675 spaces are allowed. An empty or all-spaces field, or one that contains
676 only a single period, is treated as the system missing value.
678 In scientific notation, the exponent may be introduced by a sign
679 (@samp{+} or @samp{-}), or by one of the letters @samp{e} or @samp{d}
680 (in uppercase or lowercase), or by a letter followed by a sign. A
681 single space may follow the letter or the sign or both.
683 On fixed-format @cmd{DATA LIST} (@pxref{DATA LIST FIXED}) and in a few
684 other contexts, decimals are implied when the field does not contain a
685 decimal point. In F6.5 format, for example, the field @code{314159} is
686 taken as the value 3.14159 with implied decimals. Decimals are never
687 implied if an explicit decimal point is present or if scientific
690 E and F formats accept the basic syntax already described. The other
691 formats allow some additional variations:
695 COMMA, DOLLAR, and DOT formats ignore grouping characters within the
696 integer part of the input field. The identity of the grouping
697 character depends on the format.
700 DOLLAR format allows a dollar sign to precede the number. In a negative
701 number, the dollar sign may precede or follow the minus sign.
704 PCT format allows a percent sign to follow the number.
707 All of the basic number formats have a maximum field width of 40 and
708 accept no more than 16 decimal places, on both input and output. Some
709 additional restrictions apply:
713 As input formats, the basic numeric formats allow no more decimal places
714 than the field width. As output formats, the field width must be
715 greater than the number of decimal places; that is, large enough to
716 allow for a decimal point and the number of requested decimal places.
717 DOLLAR and PCT formats must allow an additional column for @samp{$} or
721 The default output format for a given input format increases the field
722 width enough to make room for optional input characters. If an input
723 format calls for decimal places, the width is increased by 1 to make
724 room for an implied decimal point. COMMA, DOT, and DOLLAR formats also
725 increase the output width to make room for grouping characters. DOLLAR
726 and PCT further increase the output field width by 1 to make room for
727 @samp{$} or @samp{%}. The increased output width is capped at 40, the
731 The E format is exceptional. For output, E format has a minimum width
732 of 7 plus the number of decimal places. The default output format for
733 an E input format is an E format with at least 3 decimal places and
734 thus a minimum width of 10.
737 More details of basic numeric output formatting are given below:
741 Output rounds to nearest, with ties rounded away from zero. Thus, 2.5
742 is output as @code{3} in F1.0 format, and -1.125 as @code{-1.13} in F5.1
746 The system-missing value is output as a period in a field of spaces,
747 placed in the decimal point's position, or in the rightmost column if no
748 decimal places are requested. A period is used even if the decimal
749 point character is a comma.
752 A number that does not fill its field is right-justified within the
756 A number is too large for its field causes decimal places to be dropped
757 to make room. If dropping decimals does not make enough room,
758 scientific notation is used if the field is wide enough. If a number
759 does not fit in the field, even in scientific notation, the overflow is
760 indicated by filling the field with asterisks (@samp{*}).
763 COMMA, DOT, and DOLLAR formats insert grouping characters only if space
764 is available for all of them. Grouping characters are never inserted
765 when all decimal places must be dropped. Thus, 1234.56 in COMMA5.2
766 format is output as @samp{@tie{}1235} without a comma, even though there
767 is room for one, because all decimal places were dropped.
770 DOLLAR or PCT format drop the @samp{$} or @samp{%} only if the number
771 would not fit at all without it. Scientific notation with @samp{$} or
772 @samp{%} is preferred to ordinary decimal notation without it.
775 Except in scientific notation, a decimal point is included only when
776 it is followed by a digit. If the integer part of the number being
777 output is 0, and a decimal point is included, then the zero before the
778 decimal point is dropped.
780 In scientific notation, the number always includes a decimal point,
781 even if it is not followed by a digit.
784 A negative number includes a minus sign only in the presence of a
785 nonzero digit: -0.01 is output as @samp{-.01} in F4.2 format but as
786 @samp{@tie{}@tie{}.0} in F4.1 format. Thus, a ``negative zero'' never
787 includes a minus sign.
790 In negative numbers output in DOLLAR format, the dollar sign follows the
791 negative sign. Thus, -9.99 in DOLLAR6.2 format is output as
795 In scientific notation, the exponent is output as @samp{E} followed by
796 @samp{+} or @samp{-} and exactly three digits. Numbers with magnitude
797 less than 10**-999 or larger than 10**999 are not supported by most
798 computers, but if they are supported then their output is considered
799 to overflow the field and will be output as asterisks.
802 On most computers, no more than 15 decimal digits are significant in
803 output, even if more are printed. In any case, output precision cannot
804 be any higher than input precision; few data sets are accurate to 15
805 digits of precision. Unavoidable loss of precision in intermediate
806 calculations may also reduce precision of output.
809 Special values such as infinities and ``not a number'' values are
810 usually converted to the system-missing value before printing. In a few
811 circumstances, these values are output directly. In fields of width 3
812 or greater, special values are output as however many characters will
813 fit from @code{+Infinity} or @code{-Infinity} for infinities, from
814 @code{NaN} for ``not a number,'' or from @code{Unknown} for other values
815 (if any are supported by the system). In fields under 3 columns wide,
816 special values are output as asterisks.
819 @node Custom Currency Formats
820 @subsubsection Custom Currency Formats
822 @cindex currency formats
823 The custom currency formats are closely related to the basic numeric
824 formats, but they allow users to customize the output format. The
825 SET command configures custom currency formats, using the syntax
827 SET CC@var{x}=@t{"}@var{string}@t{"}.
830 where @var{x} is A, B, C, D, or E, and @var{string} is no more than 16
833 @var{string} must contain exactly three commas or exactly three periods
834 (but not both), except that a single quote character may be used to
835 ``escape'' a following comma, period, or single quote. If three commas
836 are used, commas will be used for grouping in output, and a period will
837 be used as the decimal point. Uses of periods reverses these roles.
839 The commas or periods divide @var{string} into four fields, called the
840 @dfn{negative prefix}, @dfn{prefix}, @dfn{suffix}, and @dfn{negative
841 suffix}, respectively. The prefix and suffix are added to output
842 whenever space is available. The negative prefix and negative suffix
843 are always added to a negative number when the output includes a nonzero
846 The following syntax shows how custom currency formats could be used to
847 reproduce basic numeric formats:
851 SET CCA="-,,,". /* Same as COMMA.
852 SET CCB="-...". /* Same as DOT.
853 SET CCC="-,$,,". /* Same as DOLLAR.
854 SET CCD="-,,%,". /* Like PCT, but groups with commas.
858 Here are some more examples of custom currency formats. The final
859 example shows how to use a single quote to escape a delimiter:
863 SET CCA=",EUR,,-". /* Euro.
864 SET CCB="(,USD ,,)". /* US dollar.
865 SET CCC="-.R$..". /* Brazilian real.
866 SET CCD="-,, NIS,". /* Israel shekel.
867 SET CCE="-.Rp'. ..". /* Indonesia Rupiah.
871 @noindent These formats would yield the following output:
874 @multitable {CCD13.2} {@code{@tie{}@tie{}USD 3,145.59}} {@code{(USD 3,145.59)}}
875 @headitem Format @tab @code{@tie{}3145.59} @tab @code{-3145.59}
876 @item CCA12.2 @tab @code{@tie{}EUR3,145.59} @tab @code{EUR3,145.59-}
877 @item CCB14.2 @tab @code{@tie{}@tie{}USD 3,145.59} @tab @code{(USD 3,145.59)}
878 @item CCC11.2 @tab @code{@tie{}R$3.145,59} @tab @code{-R$3.145,59}
879 @item CCD13.2 @tab @code{@tie{}3,145.59 NIS} @tab @code{-3,145.59 NIS}
880 @item CCE10.0 @tab @code{@tie{}Rp. 3.146} @tab @code{-Rp. 3.146}
884 The default for all the custom currency formats is @samp{-,,,},
885 equivalent to COMMA format.
887 @node Legacy Numeric Formats
888 @subsubsection Legacy Numeric Formats
890 The N and Z numeric formats provide compatibility with legacy file
891 formats. They have much in common:
895 Output is rounded to the nearest representable value, with ties rounded
899 Numbers too large to display are output as a field filled with asterisks
903 The decimal point is always implicitly the specified number of digits
904 from the right edge of the field, except that Z format input allows an
905 explicit decimal point.
908 Scientific notation may not be used.
911 The system-missing value is output as a period in a field of spaces.
912 The period is placed just to the right of the implied decimal point in
913 Z format, or at the right end in N format or in Z format if no decimal
914 places are requested. A period is used even if the decimal point
915 character is a comma.
918 Field width may range from 1 to 40. Decimal places may range from 0 up
919 to the field width, to a maximum of 16.
922 When a legacy numeric format used for input is converted to an output
923 format, it is changed into the equivalent F format. The field width is
924 increased by 1 if any decimal places are specified, to make room for a
925 decimal point. For Z format, the field width is increased by 1 more
926 column, to make room for a negative sign. The output field width is
927 capped at 40 columns.
930 @subsubheading N Format
932 The N format supports input and output of fields that contain only
933 digits. On input, leading or trailing spaces, a decimal point, or any
934 other non-digit character causes the field to be read as the
935 system-missing value. As a special exception, an N format used on
936 @cmd{DATA LIST FREE} or @cmd{DATA LIST LIST} is treated as the
939 On output, N pads the field on the left with zeros. Negative numbers
940 are output like the system-missing value.
942 @subsubheading Z Format
944 The Z format is a ``zoned decimal'' format used on IBM mainframes. Z
945 format encodes the sign as part of the final digit, which must be one of
953 where the characters in each row represent digits 0 through 9 in order.
954 Characters in the first two rows indicate a positive sign; those in the
955 third indicate a negative sign.
957 On output, Z fields are padded on the left with spaces. On input,
958 leading and trailing spaces are ignored. Any character in an input
959 field other than spaces, the digit characters above, and @samp{.} causes
960 the field to be read as system-missing.
962 The decimal point character for input and output is always @samp{.},
963 even if the decimal point character is a comma (@pxref{SET DECIMAL}).
965 Nonzero, negative values output in Z format are marked as negative even
966 when no nonzero digits are output. For example, -0.2 is output in Z1.0
967 format as @samp{J}. The ``negative zero'' value supported by most
968 machines is output as positive.
970 @node Binary and Hexadecimal Numeric Formats
971 @subsubsection Binary and Hexadecimal Numeric Formats
973 @cindex binary formats
974 @cindex hexadecimal formats
975 The binary and hexadecimal formats are primarily designed for
976 compatibility with existing machine formats, not for human readability.
977 All of them therefore have a F format as default output format. Some of
978 these formats are only portable between machines with compatible byte
979 ordering (endianness) or floating-point format.
981 Binary formats use byte values that in text files are interpreted as
982 special control functions, such as carriage return and line feed. Thus,
983 data in binary formats should not be included in syntax files or read
984 from data files with variable-length records, such as ordinary text
985 files. They may be read from or written to data files with fixed-length
986 records. @xref{FILE HANDLE}, for information on working with
987 fixed-length records.
989 @subsubheading P and PK Formats
991 These are binary-coded decimal formats, in which every byte (except the
992 last, in P format) represents two decimal digits. The most-significant
993 4 bits of the first byte is the most-significant decimal digit, the
994 least-significant 4 bits of the first byte is the next decimal digit,
997 In P format, the most-significant 4 bits of the last byte are the
998 least-significant decimal digit. The least-significant 4 bits represent
999 the sign: decimal 15 indicates a negative value, decimal 13 indicates a
1002 Numbers are rounded downward on output. The system-missing value and
1003 numbers outside representable range are output as zero.
1005 The maximum field width is 16. Decimal places may range from 0 up to
1006 the number of decimal digits represented by the field.
1008 The default output format is an F format with twice the input field
1009 width, plus one column for a decimal point (if decimal places were
1012 @subsubheading IB and PIB Formats
1014 These are integer binary formats. IB reads and writes 2's complement
1015 binary integers, and PIB reads and writes unsigned binary integers. The
1016 byte ordering is by default the host machine's, but SET RIB may be used
1017 to select a specific byte ordering for reading (@pxref{SET RIB}) and
1018 SET WIB, similarly, for writing (@pxref{SET WIB}).
1020 The maximum field width is 8. Decimal places may range from 0 up to the
1021 number of decimal digits in the largest value representable in the field
1024 The default output format is an F format whose width is the number of
1025 decimal digits in the largest value representable in the field width,
1026 plus 1 if the format has decimal places.
1028 @subsubheading RB Format
1030 This is a binary format for real numbers. By default it reads and
1031 writes the host machine's floating-point format, but SET RRB may be
1032 used to select an alternate floating-point format for reading
1033 (@pxref{SET RRB}) and SET WRB, similarly, for writing (@pxref{SET
1036 The recommended field width depends on the floating-point format.
1037 NATIVE (the default format), IDL, IDB, VD, VG, and ZL formats should use
1038 a field width of 8. ISL, ISB, VF, and ZS formats should use a field
1039 width of 4. Other field widths will not produce useful results. The
1040 maximum field width is 8. No decimal places may be specified.
1042 The default output format is F8.2.
1044 @subsubheading PIBHEX and RBHEX Formats
1046 These are hexadecimal formats, for reading and writing binary formats
1047 where each byte has been recoded as a pair of hexadecimal digits.
1049 A hexadecimal field consists solely of hexadecimal digits
1050 @samp{0}@dots{}@samp{9} and @samp{A}@dots{}@samp{F}. Uppercase and
1051 lowercase are accepted on input; output is in uppercase.
1053 Other than the hexadecimal representation, these formats are equivalent
1054 to PIB and RB formats, respectively. However, bytes in PIBHEX format
1055 are always ordered with the most-significant byte first (big-endian
1056 order), regardless of the host machine's native byte order or PSPP
1059 Field widths must be even and between 2 and 16. RBHEX format allows no
1060 decimal places; PIBHEX allows as many decimal places as a PIB format
1061 with half the given width.
1063 @node Time and Date Formats
1064 @subsubsection Time and Date Formats
1066 @cindex time formats
1067 @cindex date formats
1068 In PSPP, a @dfn{time} is an interval. The time formats translate
1069 between human-friendly descriptions of time intervals and PSPP's
1070 internal representation of time intervals, which is simply the number of
1071 seconds in the interval. PSPP has two time formats:
1074 @multitable {Time Format} {@code{dd-mmm-yyyy HH:MM:SS.ss}} {@code{01-OCT-1978 04:31:17.01}}
1075 @headitem Time Format @tab Template @tab Example
1076 @item TIME @tab @code{hh:MM:SS.ss} @tab @code{04:31:17.01}
1077 @item DTIME @tab @code{DD HH:MM:SS.ss} @tab @code{00 04:31:17.01}
1081 A @dfn{date} is a moment in the past or the future. Internally, PSPP
1082 represents a date as the number of seconds since the @dfn{epoch},
1083 midnight, Oct. 14, 1582. The date formats translate between
1084 human-readable dates and PSPP's numeric representation of dates and
1085 times. PSPP has several date formats:
1088 @multitable {Date Format} {@code{dd-mmm-yyyy HH:MM:SS.ss}} {@code{01-OCT-1978 04:31:17.01}}
1089 @headitem Date Format @tab Template @tab Example
1090 @item DATE @tab @code{dd-mmm-yyyy} @tab @code{01-OCT-1978}
1091 @item ADATE @tab @code{mm/dd/yyyy} @tab @code{10/01/1978}
1092 @item EDATE @tab @code{dd.mm.yyyy} @tab @code{01.10.1978}
1093 @item JDATE @tab @code{yyyyjjj} @tab @code{1978274}
1094 @item SDATE @tab @code{yyyy/mm/dd} @tab @code{1978/10/01}
1095 @item QYR @tab @code{q Q yyyy} @tab @code{3 Q 1978}
1096 @item MOYR @tab @code{mmm yyyy} @tab @code{OCT 1978}
1097 @item WKYR @tab @code{ww WK yyyy} @tab @code{40 WK 1978}
1098 @item DATETIME @tab @code{dd-mmm-yyyy HH:MM:SS.ss} @tab @code{01-OCT-1978 04:31:17.01}
1102 The templates in the preceding tables describe how the time and date
1103 formats are input and output:
1107 Day of month, from 1 to 31. Always output as two digits.
1111 Month. In output, @code{mm} is output as two digits, @code{mmm} as the
1112 first three letters of an English month name (January, February,
1113 @dots{}). In input, both of these formats, plus Roman numerals, are
1117 Year. In output, DATETIME always produces a 4-digit year; other
1118 formats can produce a 2- or 4-digit year. The century assumed for
1119 2-digit years depends on the EPOCH setting (@pxref{SET EPOCH}). In
1120 output, a year outside the epoch causes the whole field to be filled
1121 with asterisks (@samp{*}).
1124 Day of year (Julian day), from 1 to 366. This is exactly three digits
1125 giving the count of days from the start of the year. January 1 is
1129 Quarter of year, from 1 to 4. Quarters start on January 1, April 1,
1130 July 1, and October 1.
1133 Week of year, from 1 to 53. Output as exactly two digits. January 1 is
1134 the first day of week 1.
1137 Count of days, which may be positive or negative. Output as at least
1141 Count of hours, which may be positive or negative. Output as at least
1145 Hour of day, from 0 to 23. Output as exactly two digits.
1148 Minute of hour, from 0 to 59. Output as exactly two digits.
1151 Seconds within minute, from 0 to 59. The integer part is output as
1152 exactly two digits. On output, seconds and fractional seconds may or
1153 may not be included, depending on field width and decimal places. On
1154 input, seconds and fractional seconds are optional. The DECIMAL setting
1155 controls the character accepted and displayed as the decimal point
1156 (@pxref{SET DECIMAL}).
1159 For output, the date and time formats use the delimiters indicated in
1160 the table. For input, date components may be separated by spaces or by
1161 one of the characters @samp{-}, @samp{/}, @samp{.}, or @samp{,}, and
1162 time components may be separated by spaces, @samp{:}, or @samp{.}. On
1163 input, the @samp{Q} separating quarter from year and the @samp{WK}
1164 separating week from year may be uppercase or lowercase, and the spaces
1165 around them are optional.
1167 On input, all time and date formats accept any amount of leading and
1168 trailing white space.
1170 The maximum width for time and date formats is 40 columns. Minimum
1171 input and output width for each of the time and date formats is shown
1175 @multitable {DATETIME} {Min. Input Width} {Min. Output Width} {4-digit year}
1176 @headitem Format @tab Min. Input Width @tab Min. Output Width @tab Option
1177 @item DATE @tab 8 @tab 9 @tab 4-digit year
1178 @item ADATE @tab 8 @tab 8 @tab 4-digit year
1179 @item EDATE @tab 8 @tab 8 @tab 4-digit year
1180 @item JDATE @tab 5 @tab 5 @tab 4-digit year
1181 @item SDATE @tab 8 @tab 8 @tab 4-digit year
1182 @item QYR @tab 4 @tab 6 @tab 4-digit year
1183 @item MOYR @tab 6 @tab 6 @tab 4-digit year
1184 @item WKYR @tab 6 @tab 8 @tab 4-digit year
1185 @item DATETIME @tab 17 @tab 17 @tab seconds
1186 @item TIME @tab 5 @tab 5 @tab seconds
1187 @item DTIME @tab 8 @tab 8 @tab seconds
1191 In the table, ``Option'' describes what increased output width enables:
1195 A field 2 columns wider than minimum will include a 4-digit year.
1196 (DATETIME format always includes a 4-digit year.)
1199 A field 3 columns wider than minimum will include seconds as well as
1200 minutes. A field 5 columns wider than minimum, or more, can also
1201 include a decimal point and fractional seconds (but no more than allowed
1202 by the format's decimal places).
1205 For the time and date formats, the default output format is the same as
1206 the input format, except that PSPP increases the field width, if
1207 necessary, to the minimum allowed for output.
1209 Time or dates narrower than the field width are right-justified within
1212 When a time or date exceeds the field width, characters are trimmed from
1213 the end until it fits. This can occur in an unusual situation, e.g.@:
1214 with a year greater than 9999 (which adds an extra digit), or for a
1215 negative value on TIME or DTIME (which adds a leading minus sign).
1217 @c What about out-of-range values?
1219 The system-missing value is output as a period at the right end of the
1222 @node Date Component Formats
1223 @subsubsection Date Component Formats
1225 The WKDAY and MONTH formats provide input and output for the names of
1226 weekdays and months, respectively.
1228 On output, these formats convert a number between 1 and 7, for WKDAY, or
1229 between 1 and 12, for MONTH, into the English name of a day or month,
1230 respectively. If the name is longer than the field, it is trimmed to
1231 fit. If the name is shorter than the field, it is padded on the right
1232 with spaces. Values outside the valid range, and the system-missing
1233 value, are output as all spaces.
1235 On input, English weekday or month names (in uppercase or lowercase) are
1236 converted back to their corresponding numbers. Weekday and month names
1237 may be abbreviated to their first 2 or 3 letters, respectively.
1239 The field width may range from 2 to 40, for WKDAY, or from 3 to 40, for
1240 MONTH. No decimal places are allowed.
1242 The default output format is the same as the input format.
1244 @node String Formats
1245 @subsubsection String Formats
1247 @cindex string formats
1248 The A and AHEX formats are the only ones that may be assigned to string
1249 variables. Neither format allows any decimal places.
1251 In A format, the entire field is treated as a string value. The field
1252 width may range from 1 to 32,767, the maximum string width. The default
1253 output format is the same as the input format.
1255 In AHEX format, the field is composed of characters in a string encoded
1256 as hex digit pairs. On output, hex digits are output in uppercase; on
1257 input, uppercase and lowercase are both accepted. The default output
1258 format is A format with half the input width.
1260 @node Scratch Variables
1261 @subsection Scratch Variables
1263 @cindex scratch variables
1264 Most of the time, variables don't retain their values between cases.
1265 Instead, either they're being read from a data file or the active file,
1266 in which case they assume the value read, or, if created with
1268 another transformation, they're initialized to the system-missing value
1269 or to blanks, depending on type.
1271 However, sometimes it's useful to have a variable that keeps its value
1272 between cases. You can do this with @cmd{LEAVE} (@pxref{LEAVE}), or you can
1273 use a @dfn{scratch variable}. Scratch variables are variables whose
1274 names begin with an octothorpe (@samp{#}).
1276 Scratch variables have the same properties as variables left with
1277 @cmd{LEAVE}: they retain their values between cases, and for the first
1278 case they are initialized to 0 or blanks. They have the additional
1279 property that they are deleted before the execution of any procedure.
1280 For this reason, scratch variables can't be used for analysis. To use
1281 a scratch variable in an analysis, use @cmd{COMPUTE} (@pxref{COMPUTE})
1282 to copy its value into an ordinary variable, then use that ordinary
1283 variable in the analysis.
1286 @section Files Used by PSPP
1288 PSPP makes use of many files each time it runs. Some of these it
1289 reads, some it writes, some it creates. Here is a table listing the
1290 most important of these files:
1293 @cindex file, command
1294 @cindex file, syntax file
1295 @cindex command file
1299 These names (synonyms) refer to the file that contains instructions
1300 that tell PSPP what to do. The syntax file's name is specified on
1301 the PSPP command line. Syntax files can also be read with
1302 @cmd{INCLUDE} (@pxref{INCLUDE}).
1307 Data files contain raw data in text or binary format. Data can also
1308 be embedded in a syntax file with @cmd{BEGIN DATA} and @cmd{END DATA}.
1310 @cindex file, output
1313 One or more output files are created by PSPP each time it is
1314 run. The output files receive the tables and charts produced by
1315 statistical procedures. The output files may be in any number of formats,
1316 depending on how PSPP is configured.
1319 @cindex file, active
1321 The active file is the ``file'' on which all PSPP procedures are
1322 performed. The active file consists of a dictionary and a set of cases.
1323 The active file is not necessarily a disk file: it is stored in memory
1327 @cindex file, system
1329 System files are binary files that store a dictionary and a set of
1330 cases. @cmd{GET} and @cmd{SAVE} read and write system files.
1332 @cindex portable file
1333 @cindex file, portable
1335 Portable files are files in a text-based format that store a dictionary
1336 and a set of cases. @cmd{IMPORT} and @cmd{EXPORT} read and write
1339 @cindex scratch file
1340 @cindex file, scratch
1342 Scratch files consist of a dictionary and cases and may be stored in
1343 memory or on disk. Most procedures that act on a system file or
1344 portable file can use a scratch file instead. The contents of scratch
1345 files persist within a single PSPP session only. @cmd{GET} and
1346 @cmd{SAVE} can be used to read and write scratch files. Scratch files
1347 are a PSPP extension.
1351 @section File Handles
1352 @cindex file handles
1354 A @dfn{file handle} is a reference to a data file, system file, portable
1355 file, or scratch file. Most often, a file handle is specified as the
1356 name of a file as a string, that is, enclosed within @samp{'} or
1359 A file name string that begins or ends with @samp{|} is treated as the
1360 name of a command to pipe data to or from. You can use this feature
1361 to read data over the network using a program such as @samp{curl}
1362 (e.g.@: @code{GET '|curl -s -S http://example.com/mydata.sav'}), to
1363 read compressed data from a file using a program such as @samp{zcat}
1364 (e.g.@: @code{GET '|zcat mydata.sav.gz'}), and for many other
1367 PSPP also supports declaring named file handles with the @cmd{FILE
1368 HANDLE} command. This command associates an identifier of your choice
1369 (the file handle's name) with a file. Later, the file handle name can
1370 be substituted for the name of the file. When PSPP syntax accesses a
1371 file multiple times, declaring a named file handle simplifies updating
1372 the syntax later to use a different file. Use of @cmd{FILE HANDLE} is
1373 also required to read data files in binary formats. @xref{FILE HANDLE},
1374 for more information.
1376 PSPP assumes that a file handle name that begins with @samp{#} refers to
1377 a scratch file, unless the name has already been declared on @cmd{FILE
1378 HANDLE} to refer to another kind of file. A scratch file is similar to
1379 a system file, except that it persists only for the duration of a given
1380 PSPP session. Most commands that read or write a system or portable
1381 file, such as @cmd{GET} and @cmd{SAVE}, also accept scratch file
1382 handles. Scratch file handles may also be declared explicitly with
1383 @cmd{FILE HANDLE}. Scratch files are a PSPP extension.
1385 In some circumstances, PSPP must distinguish whether a file handle
1386 refers to a system file or a portable file. When this is necessary to
1387 read a file, e.g.@: as an input file for @cmd{GET} or @cmd{MATCH FILES},
1388 PSPP uses the file's contents to decide. In the context of writing a
1389 file, e.g.@: as an output file for @cmd{SAVE} or @cmd{AGGREGATE}, PSPP
1390 decides based on the file's name: if it ends in @samp{.por} (with any
1391 capitalization), then PSPP writes a portable file; otherwise, PSPP
1392 writes a system file.
1394 INLINE is reserved as a file handle name. It refers to the ``data
1395 file'' embedded into the syntax file between @cmd{BEGIN DATA} and
1396 @cmd{END DATA}. @xref{BEGIN DATA}, for more information.
1398 The file to which a file handle refers may be reassigned on a later
1399 @cmd{FILE HANDLE} command if it is first closed using @cmd{CLOSE FILE
1400 HANDLE}. The @cmd{CLOSE FILE HANDLE} command is also useful to free the
1401 storage associated with a scratch file. @xref{CLOSE FILE HANDLE}, for
1405 @section Backus-Naur Form
1407 @cindex Backus-Naur Form
1408 @cindex command syntax, description of
1409 @cindex description of command syntax
1411 The syntax of some parts of the PSPP language is presented in this
1412 manual using the formalism known as @dfn{Backus-Naur Form}, or BNF. The
1413 following table describes BNF:
1419 Words in all-uppercase are PSPP keyword tokens. In BNF, these are
1420 often called @dfn{terminals}. There are some special terminals, which
1421 are written in lowercase for clarity:
1424 @cindex @code{number}
1428 @cindex @code{integer}
1429 @item @code{integer}
1432 @cindex @code{string}
1436 @cindex @code{var-name}
1437 @item @code{var-name}
1438 A single variable name.
1442 @item @code{=}, @code{/}, @code{+}, @code{-}, etc.
1443 Operators and punctuators.
1447 The end of the command. This is not necessarily an actual dot in the
1448 syntax file: @xref{Commands}, for more details.
1453 @cindex nonterminals
1454 Other words in all lowercase refer to BNF definitions, called
1455 @dfn{productions}. These productions are also known as
1456 @dfn{nonterminals}. Some nonterminals are very common, so they are
1457 defined here in English for clarity:
1460 @cindex @code{var-list}
1462 A list of one or more variable names or the keyword @code{ALL}.
1464 @cindex @code{expression}
1466 An expression. @xref{Expressions}, for details.
1470 @cindex ``is defined as''
1472 @samp{::=} means ``is defined as''. The left side of @samp{::=} gives
1473 the name of the nonterminal being defined. The right side of @samp{::=}
1474 gives the definition of that nonterminal. If the right side is empty,
1475 then one possible expansion of that nonterminal is nothing. A BNF
1476 definition is called a @dfn{production}.
1479 @cindex terminals and nonterminals, differences
1480 So, the key difference between a terminal and a nonterminal is that a
1481 terminal cannot be broken into smaller parts---in fact, every terminal
1482 is a single token (@pxref{Tokens}). On the other hand, nonterminals are
1483 composed of a (possibly empty) sequence of terminals and nonterminals.
1484 Thus, terminals indicate the deepest level of syntax description. (In
1485 parsing theory, terminals are the leaves of the parse tree; nonterminals
1489 @cindex start symbol
1490 @cindex symbol, start
1491 The first nonterminal defined in a set of productions is called the
1492 @dfn{start symbol}. The start symbol defines the entire syntax for