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.
384 For more information on missing values, see the following sections:
385 @ref{Variables}, @ref{MISSING VALUES}, @ref{Expressions}. See also the
386 documentation on individual procedures for information on how they
387 handle missing values.
394 Variables are the basic unit of data storage in PSPP. All the
395 variables in a file taken together, apart from any associated data, are
396 said to form a @dfn{dictionary}.
397 Some details of variables are described in the sections below.
400 * Attributes:: Attributes of variables.
401 * System Variables:: Variables automatically defined by PSPP.
402 * Sets of Variables:: Lists of variable names.
403 * Input and Output Formats:: Input and output formats.
404 * Scratch Variables:: Variables deleted by procedures.
408 @subsection Attributes of Variables
409 @cindex variables, attributes of
410 @cindex attributes of variables
411 Each variable has a number of attributes, including:
415 An identifier, up to 64 bytes long. Each variable must have a different name.
418 Some system variable names begin with @samp{$}, but user-defined
419 variables' names may not begin with @samp{$}.
423 @cindex variable names, ending with period
424 The final character in a variable name should not be @samp{.}, because
425 such an identifier will be misinterpreted when it is the final token
426 on a line: @code{FOO.} will be divided into two separate tokens,
427 @samp{FOO} and @samp{.}, indicating end-of-command. @xref{Tokens}.
430 The final character in a variable name should not be @samp{_}, because
431 some such identifiers are used for special purposes by PSPP
434 As with all PSPP identifiers, variable names are not case-sensitive.
435 PSPP capitalizes variable names on output the same way they were
436 capitalized at their point of definition in the input.
438 @cindex variables, type
439 @cindex type of variables
443 @cindex variables, width
444 @cindex width of variables
446 (string variables only) String variables with a width of 8 characters or
447 fewer are called @dfn{short string variables}. Short string variables
448 may be used in a few contexts where @dfn{long string variables} (those
449 with widths greater than 8) are not allowed.
452 Variables in the dictionary are arranged in a specific order.
453 @cmd{DISPLAY} can be used to show this order: see @ref{DISPLAY}.
456 Either reinitialized to 0 or spaces for each case, or left at its
457 existing value. @xref{LEAVE}.
459 @cindex missing values
460 @cindex values, missing
462 Optionally, up to three values, or a range of values, or a specific
463 value plus a range, can be specified as @dfn{user-missing values}.
464 There is also a @dfn{system-missing value} that is assigned to an
465 observation when there is no other obvious value for that observation.
466 Observations with missing values are automatically excluded from
467 analyses. User-missing values are actual data values, while the
468 system-missing value is not a value at all. @xref{Missing Observations}.
470 @cindex variable labels
471 @cindex labels, variable
473 A string that describes the variable. @xref{VARIABLE LABELS}.
476 @cindex labels, value
478 Optionally, these associate each possible value of the variable with a
479 string. @xref{VALUE LABELS}.
483 Display width, format, and (for numeric variables) number of decimal
484 places. This attribute does not affect how data are stored, just how
485 they are displayed. Example: a width of 8, with 2 decimal places.
486 @xref{Input and Output Formats}.
490 Similar to print format, but used by the @cmd{WRITE} command
493 @cindex custom attributes
494 @item Custom attributes
495 User-defined associations between names and values. @xref{VARIABLE
499 @node System Variables
500 @subsection Variables Automatically Defined by PSPP
501 @cindex system variables
502 @cindex variables, system
504 There are seven system variables. These are not like ordinary
505 variables because system variables are not always stored. They can be used only
506 in expressions. These system variables, whose values and output formats
507 cannot be modified, are described below.
510 @cindex @code{$CASENUM}
512 Case number of the case at the moment. This changes as cases are
517 Date the PSPP process was started, in format A9, following the
518 pattern @code{DD MMM YY}.
520 @cindex @code{$JDATE}
522 Number of days between 15 Oct 1582 and the time the PSPP process
525 @cindex @code{$LENGTH}
527 Page length, in lines, in format F11.
529 @cindex @code{$SYSMIS}
531 System missing value, in format F1.
535 Number of seconds between midnight 14 Oct 1582 and the time the active file
536 was read, in format F20.
538 @cindex @code{$WIDTH}
540 Page width, in characters, in format F3.
543 @node Sets of Variables
544 @subsection Lists of variable names
545 @cindex @code{TO} convention
546 @cindex convention, @code{TO}
548 To refer to a set of variables, list their names one after another.
549 Optionally, their names may be separated by commas. To include a
550 range of variables from the dictionary in the list, write the name of
551 the first and last variable in the range, separated by @code{TO}. For
552 instance, if the dictionary contains six variables with the names
553 @code{ID}, @code{X1}, @code{X2}, @code{GOAL}, @code{MET}, and
554 @code{NEXTGOAL}, in that order, then @code{X2 TO MET} would include
555 variables @code{X2}, @code{GOAL}, and @code{MET}.
557 Commands that define variables, such as @cmd{DATA LIST}, give
558 @code{TO} an alternate meaning. With these commands, @code{TO} define
559 sequences of variables whose names end in consecutive integers. The
560 syntax is two identifiers that begin with the same root and end with
561 numbers, separated by @code{TO}. The syntax @code{X1 TO X5} defines 5
562 variables, named @code{X1}, @code{X2}, @code{X3}, @code{X4}, and
563 @code{X5}. The syntax @code{ITEM0008 TO ITEM0013} defines 6
564 variables, named @code{ITEM0008}, @code{ITEM0009}, @code{ITEM0010},
565 @code{ITEM0011}, @code{ITEM0012}, and @code{ITEM00013}. The syntaxes
566 @code{QUES001 TO QUES9} and @code{QUES6 TO QUES3} are invalid.
568 After a set of variables has been defined with @cmd{DATA LIST} or
569 another command with this method, the same set can be referenced on
570 later commands using the same syntax.
572 @node Input and Output Formats
573 @subsection Input and Output Formats
576 An @dfn{input format} describes how to interpret the contents of an
577 input field as a number or a string. It might specify that the field
578 contains an ordinary decimal number, a time or date, a number in binary
579 or hexadecimal notation, or one of several other notations. Input
580 formats are used by commands such as @cmd{DATA LIST} that read data or
581 syntax files into the PSPP active file.
583 Every input format corresponds to a default @dfn{output format} that
584 specifies the formatting used when the value is output later. It is
585 always possible to explicitly specify an output format that resembles
586 the input format. Usually, this is the default, but in cases where the
587 input format is unfriendly to human readability, such as binary or
588 hexadecimal formats, the default output format is an easier-to-read
591 Every variable has two output formats, called its @dfn{print format} and
592 @dfn{write format}. Print formats are used in most output contexts;
593 write formats are used only by @cmd{WRITE} (@pxref{WRITE}). Newly
594 created variables have identical print and write formats, and
595 @cmd{FORMATS}, the most commonly used command for changing formats
596 (@pxref{FORMATS}), sets both of them to the same value as well. Thus,
597 most of the time, the distinction between print and write formats is
600 Input and output formats are specified to PSPP with a @dfn{format
601 specification} of the form @code{TYPEw} or @code{TYPEw.d}, where
602 @code{TYPE} is one of the format types described later, @code{w} is a
603 field width measured in columns, and @code{d} is an optional number of
604 decimal places. If @code{d} is omitted, a value of 0 is assumed. Some
605 formats do not allow a nonzero @code{d} to be specified.
607 The following sections describe the input and output formats supported
611 * Basic Numeric Formats::
612 * Custom Currency Formats::
613 * Legacy Numeric Formats::
614 * Binary and Hexadecimal Numeric Formats::
615 * Time and Date Formats::
616 * Date Component Formats::
620 @node Basic Numeric Formats
621 @subsubsection Basic Numeric Formats
623 @cindex numeric formats
624 The basic numeric formats are used for input and output of real numbers
625 in standard or scientific notation. The following table shows an
626 example of how each format displays positive and negative numbers with
627 the default decimal point setting:
630 @multitable {DOLLAR10.2} {@code{@tie{}$3,141.59}} {@code{-$3,141.59}}
631 @headitem Format @tab @code{@tie{}3141.59} @tab @code{-3141.59}
632 @item F8.2 @tab @code{@tie{}3141.59} @tab @code{-3141.59}
633 @item COMMA9.2 @tab @code{@tie{}3,141.59} @tab @code{-3,141.59}
634 @item DOT9.2 @tab @code{@tie{}3.141,59} @tab @code{-3.141,59}
635 @item DOLLAR10.2 @tab @code{@tie{}$3,141.59} @tab @code{-$3,141.59}
636 @item PCT9.2 @tab @code{@tie{}3141.59%} @tab @code{-3141.59%}
637 @item E8.1 @tab @code{@tie{}3.1E+003} @tab @code{-3.1E+003}
641 On output, numbers in F format are expressed in standard decimal
642 notation with the requested number of decimal places. The other formats
643 output some variation on this style:
647 Numbers in COMMA format are additionally grouped every three digits by
648 inserting a grouping character. The grouping character is ordinarily a
649 comma, but it can be changed to a period (@pxref{SET DECIMAL}).
652 DOT format is like COMMA format, but it interchanges the role of the
653 decimal point and grouping characters. That is, the current grouping
654 character is used as a decimal point and vice versa.
657 DOLLAR format is like COMMA format, but it prefixes the number with
661 PCT format is like F format, but adds @samp{%} after the number.
664 The E format always produces output in scientific notation.
667 On input, the basic numeric formats accept positive and numbers in
668 standard decimal notation or scientific notation. Leading and trailing
669 spaces are allowed. An empty or all-spaces field, or one that contains
670 only a single period, is treated as the system missing value.
672 In scientific notation, the exponent may be introduced by a sign
673 (@samp{+} or @samp{-}), or by one of the letters @samp{e} or @samp{d}
674 (in uppercase or lowercase), or by a letter followed by a sign. A
675 single space may follow the letter or the sign or both.
677 On fixed-format @cmd{DATA LIST} (@pxref{DATA LIST FIXED}) and in a few
678 other contexts, decimals are implied when the field does not contain a
679 decimal point. In F6.5 format, for example, the field @code{314159} is
680 taken as the value 3.14159 with implied decimals. Decimals are never
681 implied if an explicit decimal point is present or if scientific
684 E and F formats accept the basic syntax already described. The other
685 formats allow some additional variations:
689 COMMA, DOLLAR, and DOT formats ignore grouping characters within the
690 integer part of the input field. The identity of the grouping
691 character depends on the format.
694 DOLLAR format allows a dollar sign to precede the number. In a negative
695 number, the dollar sign may precede or follow the minus sign.
698 PCT format allows a percent sign to follow the number.
701 All of the basic number formats have a maximum field width of 40 and
702 accept no more than 16 decimal places, on both input and output. Some
703 additional restrictions apply:
707 As input formats, the basic numeric formats allow no more decimal places
708 than the field width. As output formats, the field width must be
709 greater than the number of decimal places; that is, large enough to
710 allow for a decimal point and the number of requested decimal places.
711 DOLLAR and PCT formats must allow an additional column for @samp{$} or
715 The default output format for a given input format increases the field
716 width enough to make room for optional input characters. If an input
717 format calls for decimal places, the width is increased by 1 to make
718 room for an implied decimal point. COMMA, DOT, and DOLLAR formats also
719 increase the output width to make room for grouping characters. DOLLAR
720 and PCT further increase the output field width by 1 to make room for
721 @samp{$} or @samp{%}. The increased output width is capped at 40, the
725 The E format is exceptional. For output, E format has a minimum width
726 of 7 plus the number of decimal places. The default output format for
727 an E input format is an E format with at least 3 decimal places and
728 thus a minimum width of 10.
731 More details of basic numeric output formatting are given below:
735 Output rounds to nearest, with ties rounded away from zero. Thus, 2.5
736 is output as @code{3} in F1.0 format, and -1.125 as @code{-1.13} in F5.1
740 The system-missing value is output as a period in a field of spaces,
741 placed in the decimal point's position, or in the rightmost column if no
742 decimal places are requested. A period is used even if the decimal
743 point character is a comma.
746 A number that does not fill its field is right-justified within the
750 A number is too large for its field causes decimal places to be dropped
751 to make room. If dropping decimals does not make enough room,
752 scientific notation is used if the field is wide enough. If a number
753 does not fit in the field, even in scientific notation, the overflow is
754 indicated by filling the field with asterisks (@samp{*}).
757 COMMA, DOT, and DOLLAR formats insert grouping characters only if space
758 is available for all of them. Grouping characters are never inserted
759 when all decimal places must be dropped. Thus, 1234.56 in COMMA5.2
760 format is output as @samp{@tie{}1235} without a comma, even though there
761 is room for one, because all decimal places were dropped.
764 DOLLAR or PCT format drop the @samp{$} or @samp{%} only if the number
765 would not fit at all without it. Scientific notation with @samp{$} or
766 @samp{%} is preferred to ordinary decimal notation without it.
769 Except in scientific notation, a decimal point is included only when
770 it is followed by a digit. If the integer part of the number being
771 output is 0, and a decimal point is included, then the zero before the
772 decimal point is dropped.
774 In scientific notation, the number always includes a decimal point,
775 even if it is not followed by a digit.
778 A negative number includes a minus sign only in the presence of a
779 nonzero digit: -0.01 is output as @samp{-.01} in F4.2 format but as
780 @samp{@tie{}@tie{}.0} in F4.1 format. Thus, a ``negative zero'' never
781 includes a minus sign.
784 In negative numbers output in DOLLAR format, the dollar sign follows the
785 negative sign. Thus, -9.99 in DOLLAR6.2 format is output as
789 In scientific notation, the exponent is output as @samp{E} followed by
790 @samp{+} or @samp{-} and exactly three digits. Numbers with magnitude
791 less than 10**-999 or larger than 10**999 are not supported by most
792 computers, but if they are supported then their output is considered
793 to overflow the field and will be output as asterisks.
796 On most computers, no more than 15 decimal digits are significant in
797 output, even if more are printed. In any case, output precision cannot
798 be any higher than input precision; few data sets are accurate to 15
799 digits of precision. Unavoidable loss of precision in intermediate
800 calculations may also reduce precision of output.
803 Special values such as infinities and ``not a number'' values are
804 usually converted to the system-missing value before printing. In a few
805 circumstances, these values are output directly. In fields of width 3
806 or greater, special values are output as however many characters will
807 fit from @code{+Infinity} or @code{-Infinity} for infinities, from
808 @code{NaN} for ``not a number,'' or from @code{Unknown} for other values
809 (if any are supported by the system). In fields under 3 columns wide,
810 special values are output as asterisks.
813 @node Custom Currency Formats
814 @subsubsection Custom Currency Formats
816 @cindex currency formats
817 The custom currency formats are closely related to the basic numeric
818 formats, but they allow users to customize the output format. The
819 SET command configures custom currency formats, using the syntax
821 SET CC@var{x}=@t{"}@var{string}@t{"}.
824 where @var{x} is A, B, C, D, or E, and @var{string} is no more than 16
827 @var{string} must contain exactly three commas or exactly three periods
828 (but not both), except that a single quote character may be used to
829 ``escape'' a following comma, period, or single quote. If three commas
830 are used, commas will be used for grouping in output, and a period will
831 be used as the decimal point. Uses of periods reverses these roles.
833 The commas or periods divide @var{string} into four fields, called the
834 @dfn{negative prefix}, @dfn{prefix}, @dfn{suffix}, and @dfn{negative
835 suffix}, respectively. The prefix and suffix are added to output
836 whenever space is available. The negative prefix and negative suffix
837 are always added to a negative number when the output includes a nonzero
840 The following syntax shows how custom currency formats could be used to
841 reproduce basic numeric formats:
845 SET CCA="-,,,". /* Same as COMMA.
846 SET CCB="-...". /* Same as DOT.
847 SET CCC="-,$,,". /* Same as DOLLAR.
848 SET CCD="-,,%,". /* Like PCT, but groups with commas.
852 Here are some more examples of custom currency formats. The final
853 example shows how to use a single quote to escape a delimiter:
857 SET CCA=",EUR,,-". /* Euro.
858 SET CCB="(,USD ,,)". /* US dollar.
859 SET CCC="-.R$..". /* Brazilian real.
860 SET CCD="-,, NIS,". /* Israel shekel.
861 SET CCE="-.Rp'. ..". /* Indonesia Rupiah.
865 @noindent These formats would yield the following output:
868 @multitable {CCD13.2} {@code{@tie{}@tie{}USD 3,145.59}} {@code{(USD 3,145.59)}}
869 @headitem Format @tab @code{@tie{}3145.59} @tab @code{-3145.59}
870 @item CCA12.2 @tab @code{@tie{}EUR3,145.59} @tab @code{EUR3,145.59-}
871 @item CCB14.2 @tab @code{@tie{}@tie{}USD 3,145.59} @tab @code{(USD 3,145.59)}
872 @item CCC11.2 @tab @code{@tie{}R$3.145,59} @tab @code{-R$3.145,59}
873 @item CCD13.2 @tab @code{@tie{}3,145.59 NIS} @tab @code{-3,145.59 NIS}
874 @item CCE10.0 @tab @code{@tie{}Rp. 3.146} @tab @code{-Rp. 3.146}
878 The default for all the custom currency formats is @samp{-,,,},
879 equivalent to COMMA format.
881 @node Legacy Numeric Formats
882 @subsubsection Legacy Numeric Formats
884 The N and Z numeric formats provide compatibility with legacy file
885 formats. They have much in common:
889 Output is rounded to the nearest representable value, with ties rounded
893 Numbers too large to display are output as a field filled with asterisks
897 The decimal point is always implicitly the specified number of digits
898 from the right edge of the field, except that Z format input allows an
899 explicit decimal point.
902 Scientific notation may not be used.
905 The system-missing value is output as a period in a field of spaces.
906 The period is placed just to the right of the implied decimal point in
907 Z format, or at the right end in N format or in Z format if no decimal
908 places are requested. A period is used even if the decimal point
909 character is a comma.
912 Field width may range from 1 to 40. Decimal places may range from 0 up
913 to the field width, to a maximum of 16.
916 When a legacy numeric format used for input is converted to an output
917 format, it is changed into the equivalent F format. The field width is
918 increased by 1 if any decimal places are specified, to make room for a
919 decimal point. For Z format, the field width is increased by 1 more
920 column, to make room for a negative sign. The output field width is
921 capped at 40 columns.
924 @subsubheading N Format
926 The N format supports input and output of fields that contain only
927 digits. On input, leading or trailing spaces, a decimal point, or any
928 other non-digit character causes the field to be read as the
929 system-missing value. As a special exception, an N format used on
930 @cmd{DATA LIST FREE} or @cmd{DATA LIST LIST} is treated as the
933 On output, N pads the field on the left with zeros. Negative numbers
934 are output like the system-missing value.
936 @subsubheading Z Format
938 The Z format is a ``zoned decimal'' format used on IBM mainframes. Z
939 format encodes the sign as part of the final digit, which must be one of
947 where the characters in each row represent digits 0 through 9 in order.
948 Characters in the first two rows indicate a positive sign; those in the
949 third indicate a negative sign.
951 On output, Z fields are padded on the left with spaces. On input,
952 leading and trailing spaces are ignored. Any character in an input
953 field other than spaces, the digit characters above, and @samp{.} causes
954 the field to be read as system-missing.
956 The decimal point character for input and output is always @samp{.},
957 even if the decimal point character is a comma (@pxref{SET DECIMAL}).
959 Nonzero, negative values output in Z format are marked as negative even
960 when no nonzero digits are output. For example, -0.2 is output in Z1.0
961 format as @samp{J}. The ``negative zero'' value supported by most
962 machines is output as positive.
964 @node Binary and Hexadecimal Numeric Formats
965 @subsubsection Binary and Hexadecimal Numeric Formats
967 @cindex binary formats
968 @cindex hexadecimal formats
969 The binary and hexadecimal formats are primarily designed for
970 compatibility with existing machine formats, not for human readability.
971 All of them therefore have a F format as default output format. Some of
972 these formats are only portable between machines with compatible byte
973 ordering (endianness) or floating-point format.
975 Binary formats use byte values that in text files are interpreted as
976 special control functions, such as carriage return and line feed. Thus,
977 data in binary formats should not be included in syntax files or read
978 from data files with variable-length records, such as ordinary text
979 files. They may be read from or written to data files with fixed-length
980 records. @xref{FILE HANDLE}, for information on working with
981 fixed-length records.
983 @subsubheading P and PK Formats
985 These are binary-coded decimal formats, in which every byte (except the
986 last, in P format) represents two decimal digits. The most-significant
987 4 bits of the first byte is the most-significant decimal digit, the
988 least-significant 4 bits of the first byte is the next decimal digit,
991 In P format, the most-significant 4 bits of the last byte are the
992 least-significant decimal digit. The least-significant 4 bits represent
993 the sign: decimal 15 indicates a negative value, decimal 13 indicates a
996 Numbers are rounded downward on output. The system-missing value and
997 numbers outside representable range are output as zero.
999 The maximum field width is 16. Decimal places may range from 0 up to
1000 the number of decimal digits represented by the field.
1002 The default output format is an F format with twice the input field
1003 width, plus one column for a decimal point (if decimal places were
1006 @subsubheading IB and PIB Formats
1008 These are integer binary formats. IB reads and writes 2's complement
1009 binary integers, and PIB reads and writes unsigned binary integers. The
1010 byte ordering is by default the host machine's, but SET RIB may be used
1011 to select a specific byte ordering for reading (@pxref{SET RIB}) and
1012 SET WIB, similarly, for writing (@pxref{SET WIB}).
1014 The maximum field width is 8. Decimal places may range from 0 up to the
1015 number of decimal digits in the largest value representable in the field
1018 The default output format is an F format whose width is the number of
1019 decimal digits in the largest value representable in the field width,
1020 plus 1 if the format has decimal places.
1022 @subsubheading RB Format
1024 This is a binary format for real numbers. By default it reads and
1025 writes the host machine's floating-point format, but SET RRB may be
1026 used to select an alternate floating-point format for reading
1027 (@pxref{SET RRB}) and SET WRB, similarly, for writing (@pxref{SET
1030 The recommended field width depends on the floating-point format.
1031 NATIVE (the default format), IDL, IDB, VD, VG, and ZL formats should use
1032 a field width of 8. ISL, ISB, VF, and ZS formats should use a field
1033 width of 4. Other field widths will not produce useful results. The
1034 maximum field width is 8. No decimal places may be specified.
1036 The default output format is F8.2.
1038 @subsubheading PIBHEX and RBHEX Formats
1040 These are hexadecimal formats, for reading and writing binary formats
1041 where each byte has been recoded as a pair of hexadecimal digits.
1043 A hexadecimal field consists solely of hexadecimal digits
1044 @samp{0}@dots{}@samp{9} and @samp{A}@dots{}@samp{F}. Uppercase and
1045 lowercase are accepted on input; output is in uppercase.
1047 Other than the hexadecimal representation, these formats are equivalent
1048 to PIB and RB formats, respectively. However, bytes in PIBHEX format
1049 are always ordered with the most-significant byte first (big-endian
1050 order), regardless of the host machine's native byte order or PSPP
1053 Field widths must be even and between 2 and 16. RBHEX format allows no
1054 decimal places; PIBHEX allows as many decimal places as a PIB format
1055 with half the given width.
1057 @node Time and Date Formats
1058 @subsubsection Time and Date Formats
1060 @cindex time formats
1061 @cindex date formats
1062 In PSPP, a @dfn{time} is an interval. The time formats translate
1063 between human-friendly descriptions of time intervals and PSPP's
1064 internal representation of time intervals, which is simply the number of
1065 seconds in the interval. PSPP has two time formats:
1068 @multitable {Time Format} {@code{dd-mmm-yyyy HH:MM:SS.ss}} {@code{01-OCT-1978 04:31:17.01}}
1069 @headitem Time Format @tab Template @tab Example
1070 @item TIME @tab @code{hh:MM:SS.ss} @tab @code{04:31:17.01}
1071 @item DTIME @tab @code{DD HH:MM:SS.ss} @tab @code{00 04:31:17.01}
1075 A @dfn{date} is a moment in the past or the future. Internally, PSPP
1076 represents a date as the number of seconds since the @dfn{epoch},
1077 midnight, Oct. 14, 1582. The date formats translate between
1078 human-readable dates and PSPP's numeric representation of dates and
1079 times. PSPP has several date formats:
1082 @multitable {Date Format} {@code{dd-mmm-yyyy HH:MM:SS.ss}} {@code{01-OCT-1978 04:31:17.01}}
1083 @headitem Date Format @tab Template @tab Example
1084 @item DATE @tab @code{dd-mmm-yyyy} @tab @code{01-OCT-1978}
1085 @item ADATE @tab @code{mm/dd/yyyy} @tab @code{10/01/1978}
1086 @item EDATE @tab @code{dd.mm.yyyy} @tab @code{01.10.1978}
1087 @item JDATE @tab @code{yyyyjjj} @tab @code{1978274}
1088 @item SDATE @tab @code{yyyy/mm/dd} @tab @code{1978/10/01}
1089 @item QYR @tab @code{q Q yyyy} @tab @code{3 Q 1978}
1090 @item MOYR @tab @code{mmm yyyy} @tab @code{OCT 1978}
1091 @item WKYR @tab @code{ww WK yyyy} @tab @code{40 WK 1978}
1092 @item DATETIME @tab @code{dd-mmm-yyyy HH:MM:SS.ss} @tab @code{01-OCT-1978 04:31:17.01}
1096 The templates in the preceding tables describe how the time and date
1097 formats are input and output:
1101 Day of month, from 1 to 31. Always output as two digits.
1105 Month. In output, @code{mm} is output as two digits, @code{mmm} as the
1106 first three letters of an English month name (January, February,
1107 @dots{}). In input, both of these formats, plus Roman numerals, are
1111 Year. In output, DATETIME always produces a 4-digit year; other
1112 formats can produce a 2- or 4-digit year. The century assumed for
1113 2-digit years depends on the EPOCH setting (@pxref{SET EPOCH}). In
1114 output, a year outside the epoch causes the whole field to be filled
1115 with asterisks (@samp{*}).
1118 Day of year (Julian day), from 1 to 366. This is exactly three digits
1119 giving the count of days from the start of the year. January 1 is
1123 Quarter of year, from 1 to 4. Quarters start on January 1, April 1,
1124 July 1, and October 1.
1127 Week of year, from 1 to 53. Output as exactly two digits. January 1 is
1128 the first day of week 1.
1131 Count of days, which may be positive or negative. Output as at least
1135 Count of hours, which may be positive or negative. Output as at least
1139 Hour of day, from 0 to 23. Output as exactly two digits.
1142 Minute of hour, from 0 to 59. Output as exactly two digits.
1145 Seconds within minute, from 0 to 59. The integer part is output as
1146 exactly two digits. On output, seconds and fractional seconds may or
1147 may not be included, depending on field width and decimal places. On
1148 input, seconds and fractional seconds are optional. The DECIMAL setting
1149 controls the character accepted and displayed as the decimal point
1150 (@pxref{SET DECIMAL}).
1153 For output, the date and time formats use the delimiters indicated in
1154 the table. For input, date components may be separated by spaces or by
1155 one of the characters @samp{-}, @samp{/}, @samp{.}, or @samp{,}, and
1156 time components may be separated by spaces, @samp{:}, or @samp{.}. On
1157 input, the @samp{Q} separating quarter from year and the @samp{WK}
1158 separating week from year may be uppercase or lowercase, and the spaces
1159 around them are optional.
1161 On input, all time and date formats accept any amount of leading and
1162 trailing white space.
1164 The maximum width for time and date formats is 40 columns. Minimum
1165 input and output width for each of the time and date formats is shown
1169 @multitable {DATETIME} {Min. Input Width} {Min. Output Width} {4-digit year}
1170 @headitem Format @tab Min. Input Width @tab Min. Output Width @tab Option
1171 @item DATE @tab 8 @tab 9 @tab 4-digit year
1172 @item ADATE @tab 8 @tab 8 @tab 4-digit year
1173 @item EDATE @tab 8 @tab 8 @tab 4-digit year
1174 @item JDATE @tab 5 @tab 5 @tab 4-digit year
1175 @item SDATE @tab 8 @tab 8 @tab 4-digit year
1176 @item QYR @tab 4 @tab 6 @tab 4-digit year
1177 @item MOYR @tab 6 @tab 6 @tab 4-digit year
1178 @item WKYR @tab 6 @tab 8 @tab 4-digit year
1179 @item DATETIME @tab 17 @tab 17 @tab seconds
1180 @item TIME @tab 5 @tab 5 @tab seconds
1181 @item DTIME @tab 8 @tab 8 @tab seconds
1185 In the table, ``Option'' describes what increased output width enables:
1189 A field 2 columns wider than minimum will include a 4-digit year.
1190 (DATETIME format always includes a 4-digit year.)
1193 A field 3 columns wider than minimum will include seconds as well as
1194 minutes. A field 5 columns wider than minimum, or more, can also
1195 include a decimal point and fractional seconds (but no more than allowed
1196 by the format's decimal places).
1199 For the time and date formats, the default output format is the same as
1200 the input format, except that PSPP increases the field width, if
1201 necessary, to the minimum allowed for output.
1203 Time or dates narrower than the field width are right-justified within
1206 When a time or date exceeds the field width, characters are trimmed from
1207 the end until it fits. This can occur in an unusual situation, e.g.@:
1208 with a year greater than 9999 (which adds an extra digit), or for a
1209 negative value on TIME or DTIME (which adds a leading minus sign).
1211 @c What about out-of-range values?
1213 The system-missing value is output as a period at the right end of the
1216 @node Date Component Formats
1217 @subsubsection Date Component Formats
1219 The WKDAY and MONTH formats provide input and output for the names of
1220 weekdays and months, respectively.
1222 On output, these formats convert a number between 1 and 7, for WKDAY, or
1223 between 1 and 12, for MONTH, into the English name of a day or month,
1224 respectively. If the name is longer than the field, it is trimmed to
1225 fit. If the name is shorter than the field, it is padded on the right
1226 with spaces. Values outside the valid range, and the system-missing
1227 value, are output as all spaces.
1229 On input, English weekday or month names (in uppercase or lowercase) are
1230 converted back to their corresponding numbers. Weekday and month names
1231 may be abbreviated to their first 2 or 3 letters, respectively.
1233 The field width may range from 2 to 40, for WKDAY, or from 3 to 40, for
1234 MONTH. No decimal places are allowed.
1236 The default output format is the same as the input format.
1238 @node String Formats
1239 @subsubsection String Formats
1241 @cindex string formats
1242 The A and AHEX formats are the only ones that may be assigned to string
1243 variables. Neither format allows any decimal places.
1245 In A format, the entire field is treated as a string value. The field
1246 width may range from 1 to 32,767, the maximum string width. The default
1247 output format is the same as the input format.
1249 In AHEX format, the field is composed of characters in a string encoded
1250 as hex digit pairs. On output, hex digits are output in uppercase; on
1251 input, uppercase and lowercase are both accepted. The default output
1252 format is A format with half the input width.
1254 @node Scratch Variables
1255 @subsection Scratch Variables
1257 @cindex scratch variables
1258 Most of the time, variables don't retain their values between cases.
1259 Instead, either they're being read from a data file or the active file,
1260 in which case they assume the value read, or, if created with
1262 another transformation, they're initialized to the system-missing value
1263 or to blanks, depending on type.
1265 However, sometimes it's useful to have a variable that keeps its value
1266 between cases. You can do this with @cmd{LEAVE} (@pxref{LEAVE}), or you can
1267 use a @dfn{scratch variable}. Scratch variables are variables whose
1268 names begin with an octothorpe (@samp{#}).
1270 Scratch variables have the same properties as variables left with
1271 @cmd{LEAVE}: they retain their values between cases, and for the first
1272 case they are initialized to 0 or blanks. They have the additional
1273 property that they are deleted before the execution of any procedure.
1274 For this reason, scratch variables can't be used for analysis. To use
1275 a scratch variable in an analysis, use @cmd{COMPUTE} (@pxref{COMPUTE})
1276 to copy its value into an ordinary variable, then use that ordinary
1277 variable in the analysis.
1280 @section Files Used by PSPP
1282 PSPP makes use of many files each time it runs. Some of these it
1283 reads, some it writes, some it creates. Here is a table listing the
1284 most important of these files:
1287 @cindex file, command
1288 @cindex file, syntax file
1289 @cindex command file
1293 These names (synonyms) refer to the file that contains instructions
1294 that tell PSPP what to do. The syntax file's name is specified on
1295 the PSPP command line. Syntax files can also be read with
1296 @cmd{INCLUDE} (@pxref{INCLUDE}).
1301 Data files contain raw data in text or binary format. Data can also
1302 be embedded in a syntax file with @cmd{BEGIN DATA} and @cmd{END DATA}.
1304 @cindex file, output
1307 One or more output files are created by PSPP each time it is
1308 run. The output files receive the tables and charts produced by
1309 statistical procedures. The output files may be in any number of formats,
1310 depending on how PSPP is configured.
1313 @cindex file, active
1315 The active file is the ``file'' on which all PSPP procedures are
1316 performed. The active file consists of a dictionary and a set of cases.
1317 The active file is not necessarily a disk file: it is stored in memory
1321 @cindex file, system
1323 System files are binary files that store a dictionary and a set of
1324 cases. @cmd{GET} and @cmd{SAVE} read and write system files.
1326 @cindex portable file
1327 @cindex file, portable
1329 Portable files are files in a text-based format that store a dictionary
1330 and a set of cases. @cmd{IMPORT} and @cmd{EXPORT} read and write
1333 @cindex scratch file
1334 @cindex file, scratch
1336 Scratch files consist of a dictionary and cases and may be stored in
1337 memory or on disk. Most procedures that act on a system file or
1338 portable file can use a scratch file instead. The contents of scratch
1339 files persist within a single PSPP session only. @cmd{GET} and
1340 @cmd{SAVE} can be used to read and write scratch files. Scratch files
1341 are a PSPP extension.
1345 @section File Handles
1346 @cindex file handles
1348 A @dfn{file handle} is a reference to a data file, system file, portable
1349 file, or scratch file. Most often, a file handle is specified as the
1350 name of a file as a string, that is, enclosed within @samp{'} or
1353 A file name string that begins or ends with @samp{|} is treated as the
1354 name of a command to pipe data to or from. You can use this feature
1355 to read data over the network using a program such as @samp{curl}
1356 (e.g.@: @code{GET '|curl -s -S http://example.com/mydata.sav'}), to
1357 read compressed data from a file using a program such as @samp{zcat}
1358 (e.g.@: @code{GET '|zcat mydata.sav.gz'}), and for many other
1361 PSPP also supports declaring named file handles with the @cmd{FILE
1362 HANDLE} command. This command associates an identifier of your choice
1363 (the file handle's name) with a file. Later, the file handle name can
1364 be substituted for the name of the file. When PSPP syntax accesses a
1365 file multiple times, declaring a named file handle simplifies updating
1366 the syntax later to use a different file. Use of @cmd{FILE HANDLE} is
1367 also required to read data files in binary formats. @xref{FILE HANDLE},
1368 for more information.
1370 PSPP assumes that a file handle name that begins with @samp{#} refers to
1371 a scratch file, unless the name has already been declared on @cmd{FILE
1372 HANDLE} to refer to another kind of file. A scratch file is similar to
1373 a system file, except that it persists only for the duration of a given
1374 PSPP session. Most commands that read or write a system or portable
1375 file, such as @cmd{GET} and @cmd{SAVE}, also accept scratch file
1376 handles. Scratch file handles may also be declared explicitly with
1377 @cmd{FILE HANDLE}. Scratch files are a PSPP extension.
1379 In some circumstances, PSPP must distinguish whether a file handle
1380 refers to a system file or a portable file. When this is necessary to
1381 read a file, e.g.@: as an input file for @cmd{GET} or @cmd{MATCH FILES},
1382 PSPP uses the file's contents to decide. In the context of writing a
1383 file, e.g.@: as an output file for @cmd{SAVE} or @cmd{AGGREGATE}, PSPP
1384 decides based on the file's name: if it ends in @samp{.por} (with any
1385 capitalization), then PSPP writes a portable file; otherwise, PSPP
1386 writes a system file.
1388 INLINE is reserved as a file handle name. It refers to the ``data
1389 file'' embedded into the syntax file between @cmd{BEGIN DATA} and
1390 @cmd{END DATA}. @xref{BEGIN DATA}, for more information.
1392 The file to which a file handle refers may be reassigned on a later
1393 @cmd{FILE HANDLE} command if it is first closed using @cmd{CLOSE FILE
1394 HANDLE}. The @cmd{CLOSE FILE HANDLE} command is also useful to free the
1395 storage associated with a scratch file. @xref{CLOSE FILE HANDLE}, for
1399 @section Backus-Naur Form
1401 @cindex Backus-Naur Form
1402 @cindex command syntax, description of
1403 @cindex description of command syntax
1405 The syntax of some parts of the PSPP language is presented in this
1406 manual using the formalism known as @dfn{Backus-Naur Form}, or BNF. The
1407 following table describes BNF:
1413 Words in all-uppercase are PSPP keyword tokens. In BNF, these are
1414 often called @dfn{terminals}. There are some special terminals, which
1415 are written in lowercase for clarity:
1418 @cindex @code{number}
1422 @cindex @code{integer}
1423 @item @code{integer}
1426 @cindex @code{string}
1430 @cindex @code{var-name}
1431 @item @code{var-name}
1432 A single variable name.
1436 @item @code{=}, @code{/}, @code{+}, @code{-}, etc.
1437 Operators and punctuators.
1441 The end of the command. This is not necessarily an actual dot in the
1442 syntax file: @xref{Commands}, for more details.
1447 @cindex nonterminals
1448 Other words in all lowercase refer to BNF definitions, called
1449 @dfn{productions}. These productions are also known as
1450 @dfn{nonterminals}. Some nonterminals are very common, so they are
1451 defined here in English for clarity:
1454 @cindex @code{var-list}
1456 A list of one or more variable names or the keyword @code{ALL}.
1458 @cindex @code{expression}
1460 An expression. @xref{Expressions}, for details.
1464 @cindex ``is defined as''
1466 @samp{::=} means ``is defined as''. The left side of @samp{::=} gives
1467 the name of the nonterminal being defined. The right side of @samp{::=}
1468 gives the definition of that nonterminal. If the right side is empty,
1469 then one possible expansion of that nonterminal is nothing. A BNF
1470 definition is called a @dfn{production}.
1473 @cindex terminals and nonterminals, differences
1474 So, the key difference between a terminal and a nonterminal is that a
1475 terminal cannot be broken into smaller parts---in fact, every terminal
1476 is a single token (@pxref{Tokens}). On the other hand, nonterminals are
1477 composed of a (possibly empty) sequence of terminals and nonterminals.
1478 Thus, terminals indicate the deepest level of syntax description. (In
1479 parsing theory, terminals are the leaves of the parse tree; nonterminals
1483 @cindex start symbol
1484 @cindex symbol, start
1485 The first nonterminal defined in a set of productions is called the
1486 @dfn{start symbol}. The start symbol defines the entire syntax for