variable-parser: Rewrite parse_DATA_LIST_vars().

[pspp] / doc / variables.texi

@node Variable Attributes
@chapter Manipulating variables

The variables in the active file dictionary are important.  There are
several utility functions for examining and adjusting them.

@menu
* ADD VALUE LABELS::            Add value labels to variables.
* DELETE VARIABLES::            Delete variables.
* DISPLAY::                     Display information about the active file.
* FORMATS::                     Set print and write formats.
* LEAVE::                       Don't clear variables between cases.
* MISSING VALUES::              Set missing values for variables.
* MODIFY VARS::                 Rename, reorder, and drop variables.
* MRSETS::                      Add, modify, and list multiple response sets.
* NUMERIC::                     Create new numeric variables.
* PRINT FORMATS::               Set variable print formats.
* RENAME VARIABLES::            Rename variables.
* VALUE LABELS::                Set value labels for variables.
* STRING::                      Create new string variables.
* VARIABLE ATTRIBUTE::          Set custom attributes on variables.
* VARIABLE LABELS::             Set variable labels for variables.
* VARIABLE ALIGNMENT::          Set the alignment for display.
* VARIABLE WIDTH::              Set the display width.
* VARIABLE LEVEL::              Set the measurement level.
* VECTOR::                      Declare an array of variables.
* WRITE FORMATS::               Set variable write formats.
@end menu

@node ADD VALUE LABELS
@section ADD VALUE LABELS
@vindex ADD VALUE LABELS

@display 
ADD VALUE LABELS
        /var_list value 'label' [value 'label']@dots{}
@end display

@cmd{ADD VALUE LABELS} has the same syntax and purpose as @cmd{VALUE
LABELS} (@pxref{VALUE LABELS}), but it does not clear value
labels from the variables before adding the ones specified.

@node DELETE VARIABLES
@section DELETE VARIABLES
@vindex DELETE VARIABLES

@display
DELETE VARIABLES var_list.
@end display

@cmd{DELETE VARIABLES} deletes the specified variables from the
dictionary.  It may not be used to delete all variables from the
dictionary; use @cmd{NEW FILE} to do that (@pxref{NEW FILE}).

@cmd{DELETE VARIABLES} should not used after defining transformations
and before executing a procedure.  If it is used in such a context, it
causes the data to be read.  If it is used while @cmd{TEMPORARY} is in
effect, it causes the temporary transformations to become permanent.

@node DISPLAY
@section DISPLAY
@vindex DISPLAY

@display
DISPLAY [SORTED] NAMES [[/VARIABLES=]var_list].
DISPLAY [SORTED] INDEX [[/VARIABLES=]var_list].
DISPLAY [SORTED] LABELS [[/VARIABLES=]var_list].
DISPLAY [SORTED] VARIABLES [[/VARIABLES=]var_list].
DISPLAY [SORTED] DICTIONARY [[/VARIABLES=]var_list].
DISPLAY [SORTED] SCRATCH [[/VARIABLES=]var_list].
DISPLAY [SORTED] ATTRIBUTES [[/VARIABLES=]var_list].
DISPLAY [SORTED] @@ATTRIBUTES [[/VARIABLES=]var_list].
DISPLAY [SORTED] VECTORS.
@end display

@cmd{DISPLAY} displays information about the active file.  A variety
of different forms of information can be requested.

The following keywords primarily cause information about variables to
be displayed.  With these keywords, by default information is
displayed about all variable in the active file, in the order that
variables occur in the active file dictionary.  The SORTED keyword
causes output to be sorted alphabetically by variable name.  The
VARIABLES subcommand limits output to the specified variables.

@table @asis
@item NAMES
The variables' names are displayed.

@item INDEX
The variables' names are displayed along with a value describing their
position within the active file dictionary.

@item LABELS
Variable names, positions, and variable labels are displayed.

@item VARIABLES
Variable names, positions, print and write formats, and missing values
are displayed.

@item DICTIONARY
Variable names, positions, print and write formats, missing values,
variable labels, and value labels are displayed.

@item SCRATCH
Variable names are displayed, for scratch variables only (@pxref{Scratch
Variables}).

@item ATTRIBUTES
Datafile and variable attributes are displayed, except that attributes
whose names begin with @code{@@} or @code{$@@} are omitted.

@itemx @@ATTRIBUTES
All datafile and variable attributes are displayed.
@end table

With the @code{VECTOR} keyword, @cmd{DISPLAY} lists all the currently
declared vectors.  If the SORTED keyword is given, the vectors are
listed in alphabetical order; otherwise, they are listed in textual
order of definition within the PSPP syntax file.

For related commands, see @ref{DISPLAY DOCUMENTS} and @ref{DISPLAY
FILE LABEL}.

@node FORMATS
@section FORMATS
@vindex FORMATS

@display
FORMATS var_list (fmt_spec).
@end display

@cmd{FORMATS} set both print and write formats for the specified
numeric variables to the specified format specification.
@xref{Input and Output Formats}.

Specify a list of variables followed by a format specification in
parentheses.  The print and write formats of the specified variables
will be changed.

Additional lists of variables and formats may be included if they are
delimited by a slash (@samp{/}).

@cmd{FORMATS} takes effect immediately.  It is not affected by
conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.

@node LEAVE
@section LEAVE
@vindex LEAVE

@display
LEAVE var_list.
@end display

@cmd{LEAVE} prevents the specified variables from being
reinitialized whenever a new case is processed.

Normally, when a data file is processed, every variable in the active
file is initialized to the system-missing value or spaces at the
beginning of processing for each case.  When a variable has been
specified on @cmd{LEAVE}, this is not the case.  Instead, that variable is
initialized to 0 (not system-missing) or spaces for the first case.
After that, it retains its value between cases.

This becomes useful for counters.  For instance, in the example below
the variable SUM maintains a running total of the values in the ITEM
variable.

@example
DATA LIST /ITEM 1-3.
COMPUTE SUM=SUM+ITEM.
PRINT /ITEM SUM.
LEAVE SUM
BEGIN DATA.
123
404
555
999
END DATA.
@end example

@noindent Partial output from this example:

@example
123   123.00
404   527.00
555  1082.00
999  2081.00
@end example

It is best to use @cmd{LEAVE} command immediately before invoking a
procedure command, because the left status of variables is reset by
certain transformations---for instance, @cmd{COMPUTE} and @cmd{IF}.
Left status is also reset by all procedure invocations.

@node MISSING VALUES
@section MISSING VALUES
@vindex MISSING VALUES

@display
MISSING VALUES var_list (missing_values).

missing_values takes one of the following forms:
        num1
        num1, num2
        num1, num2, num3
        num1 THRU num2
        num1 THRU num2, num3
        string1
        string1, string2
        string1, string2, string3
As part of a range, LO or LOWEST may take the place of num1;
HI or HIGHEST may take the place of num2.
@end display

@cmd{MISSING VALUES} sets user-missing values for numeric and string
variables.  Long string variables may have missing values, but
characters after the first 8 bytes of the missing value must be
spaces.

Specify a list of variables, followed by a list of their user-missing
values in parentheses.  Up to three discrete values may be given, or,
for numeric variables only, a range of values optionally accompanied by
a single discrete value.  Ranges may be open-ended on one end, indicated
through the use of the keyword LO or LOWEST or HI or HIGHEST.

The @cmd{MISSING VALUES} command takes effect immediately.  It is not
affected by conditional and looping constructs such as @cmd{DO IF} or
@cmd{LOOP}.

@node MODIFY VARS
@section MODIFY VARS
@vindex MODIFY VARS

@display 
MODIFY VARS
        /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (var_list)@dots{}
        /RENAME=(old_names=new_names)@dots{}
        /@{DROP,KEEP@}=var_list
        /MAP    
@end display

@cmd{MODIFY VARS} reorders, renames, and deletes variables in the
active file.

At least one subcommand must be specified, and no subcommand may be
specified more than once.  DROP and KEEP may not both be specified.

The REORDER subcommand changes the order of variables in the active
file.  Specify one or more lists of variable names in parentheses.  By
default, each list of variables is rearranged into the specified order.
To put the variables into the reverse of the specified order, put
keyword BACKWARD before the parentheses.  To put them into alphabetical
order in the dictionary, specify keyword ALPHA before the parentheses.
BACKWARD and ALPHA may also be combined.

To rename variables in the active file, specify RENAME, an equals sign
(@samp{=}), and lists of the old variable names and new variable names
separated by another equals sign within parentheses.  There must be the
same number of old and new variable names.  Each old variable is renamed to
the corresponding new variable name.  Multiple parenthesized groups of
variables may be specified.

The DROP subcommand deletes a specified list of variables from the
active file.

The KEEP subcommand keeps the specified list of variables in the active
file.  Any unlisted variables are deleted from the active file.

MAP is currently ignored.

If either DROP or KEEP is specified, the data is read; otherwise it is
not.

@cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
(@pxref{TEMPORARY}).

@node NUMERIC
@section NUMERIC
@vindex NUMERIC

@display
NUMERIC /var_list [(fmt_spec)].
@end display

@cmd{NUMERIC} explicitly declares new numeric variables, optionally
setting their output formats.

Specify a slash (@samp{/}), followed by the names of the new numeric
variables.  If you wish to set their output formats, follow their names
by an output format specification in parentheses (@pxref{Input and Output
Formats}); otherwise, the default is F8.2.

Variables created with @cmd{NUMERIC} are initialized to the
system-missing value.

@node MRSETS
@section MRSETS
@vindex MRSETS

@display
MRSETS 
    /MDGROUP NAME=name VARIABLES=var_list VALUE=value
     [CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}]
     [@{LABEL='label',LABELSOURCE=VARLABEL@}]

    /MCGROUP NAME=name VARIABLES=var_list [LABEL='label']

    /DELETE NAME=@{[names],ALL@}

    /DISPLAY NAME=@{[names],ALL@}
@end display

@cmd{MRSETS} creates, modifies, deletes, and displays multiple
response sets.  A multiple response set is a set of variables that
represent multiple responses to a single survey question in one of the
two following ways:

@itemize @bullet
@item
A @dfn{multiple dichotomy set} is analogous to a survey question with
a set of checkboxes.  Each variable in the set is treated in a Boolean
fashion: one value (the "counted value") means that the box was
checked, and any other value means that it was not.

@item
A @dfn{multiple category set} represents a survey question where the
respondent is instructed to list up to @var{n} choices.  Each variable
represents one of the responses.
@end itemize

Any number of subcommands may be specified in any order.

The MDGROUP subcommand creates a new multiple dichotomy set or
replaces an existing multiple response set.  The NAME, VARIABLES, and
VALUE specifications are required.  The others are optional:

@itemize @bullet
@item
NAME specifies the name used in syntax for the new multiple dichotomy
set.  The name must begin with @samp{$}; it must otherwise follow the
rules for identifiers (@pxref{Tokens}).

@item
VARIABLES specifies the variables that belong to the set.  At least
two variables must be specified.  The variables must be all string or
all numeric.

@item
VALUE specifies the counted value.  If the variables are numeric, the
value must be an integer.  If the variables are strings, then the
value must be a string that is no longer than the shortest of the
variables in the set (ignoring trailing spaces).

@item
CATEGORYLABELS optionally specifies the source of the labels for each
category in the set:

@itemize @minus
@item
VARLABELS, the default, uses variable labels or, for variables without
variable labels, variable names.  PSPP warns if two variables have the
same variable label, since these categories cannot be distinguished in
output.

@item 
COUNTEDVALUES instead uses each variable's value label for the counted
value.  PSPP warns if two variables have the same value label for the
counted value or if one of the variables lacks a value label, since
such categories cannot be distinguished in output.
@end itemize

@item
LABEL optionally specifies a label for the multiple response set.  If
neither LABEL nor LABELSOURCE=VARLABEL is specified, the set is
unlabeled.

@item
LABELSOURCE=VARLABEL draws the multiple response set's label from the
first variable label among the variables in the set; if none of the
variables has a label, the name of the first variable is used.
LABELSOURCE=VARLABEL must be used with CATEGORYLABELS=COUNTEDVALUES.
It is mutually exclusive with LABEL.
@end itemize

The MCGROUP subcommand creates a new multiple category set or
replaces an existing multiple response set.  The NAME and VARIABLES
specifications are required, and LABEL is optional.  Their meanings
are as described above to MDGROUP.  PSPP warns if two variables in the
set have different value labels for a single value, since each of the
variables in the set should have the same possible categories.

The DELETE subcommand deletes multiple response groups.  A list of
groups may be named within a set of required square brackets, or ALL
may be used to delete all groups.

The DISPLAY subcommand displays information about defined multiple
response sets.  Its syntax is the same as the DELETE subcommand.

Multiple response sets are saved to and read from system files by,
e.g., the @cmd{SAVE} and @cmd{GET} command.  Otherwise, multiple
response sets are currently used only by third party software.

@node PRINT FORMATS
@section PRINT FORMATS
@vindex PRINT FORMATS

@display
PRINT FORMATS var_list (fmt_spec).
@end display

@cmd{PRINT FORMATS} sets the print formats for the specified
numeric variables to the specified format specification.

Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
but @cmd{PRINT FORMATS} sets only print formats, not write formats.

@node RENAME VARIABLES
@section RENAME VARIABLES
@vindex RENAME VARIABLES

@display
RENAME VARIABLES (old_names=new_names)@dots{} .
@end display

@cmd{RENAME VARIABLES} changes the names of variables in the active
file.  Specify lists of the old variable names and new
variable names, separated by an equals sign (@samp{=}), within
parentheses.  There must be the same number of old and new variable
names.  Each old variable is renamed to the corresponding new variable
name.  Multiple parenthesized groups of variables may be specified.

@cmd{RENAME VARIABLES} takes effect immediately.  It does not cause the data
to be read.

@cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
(@pxref{TEMPORARY}).

@node VALUE LABELS
@section VALUE LABELS
@vindex VALUE LABELS

@display 
VALUE LABELS
        /var_list value 'label' [value 'label']@dots{}
@end display

@cmd{VALUE LABELS} allows values of numeric and short string
variables to be associated with labels.  In this way, a short value can
stand for a long value.

To set up value labels for a set of variables, specify the
variable names after a slash (@samp{/}), followed by a list of values
and their associated labels, separated by spaces.

Before @cmd{VALUE LABELS} is executed, any existing value labels
are cleared from the variables specified.  Use @cmd{ADD VALUE LABELS}
(@pxref{ADD VALUE LABELS}) to add value labels without clearing those
already present.

@node STRING
@section STRING
@vindex STRING

@display
STRING /var_list (fmt_spec).
@end display

@cmd{STRING} creates new string variables for use in
transformations.

Specify a slash (@samp{/}), followed by the names of the string
variables to create and the desired output format specification in
parentheses (@pxref{Input and Output Formats}).  Variable widths are
implicitly derived from the specified output formats.

Created variables are initialized to spaces.


@node VARIABLE ATTRIBUTE
@section VARIABLE ATTRIBUTE
@vindex VARIABLE ATTRIBUTE

@display
VARIABLE ATTRIBUTE
         VARIABLES=var_list
         ATTRIBUTE=name('value') [name('value')]@dots{}
         ATTRIBUTE=name@b{[}index@b{]}('value') [name@b{[}index@b{]}('value')]@dots{}
         DELETE=name [name]@dots{}
         DELETE=name@b{[}index@b{]} [name@b{[}index@b{]}]@dots{}
@end display

@cmd{VARIABLE ATTRIBUTE} adds, modifies, or removes user-defined
attributes associated with variables in the active file.  Custom
variable attributes are not interpreted by PSPP, but they are saved as
part of system files and may be used by other software that reads
them.

The required VARIABLES subcommand must come first.  Specify the
variables to which the following ATTRIBUTE or DELETE subcommand
should apply.

Use the ATTRIBUTE subcommand to add or modify custom variable
attributes.  Specify the name of the attribute as an identifier
(@pxref{Tokens}), followed by the desired value, in parentheses, as a
quoted string.  The specified attributes are then added or modified in
the variables specified on VARIABLES.  Attribute names that begin with
@code{$} are reserved for PSPP's internal use, and attribute names
that begin with @code{@@} or @code{$@@} are not displayed by most PSPP
commands that display other attributes.  Other attribute names are not
treated specially.

Attributes may also be organized into arrays.  To assign to an array
element, add an integer array index enclosed in square brackets
(@code{[} and @code{]}) between the attribute name and value.  Array
indexes start at 1, not 0.  An attribute array that has a single
element (number 1) is not distinguished from a non-array attribute.

Use the DELETE subcommand to delete an attribute from the variable
specified on VARIABLES.  Specify an attribute name by itself to delete
an entire attribute, including all array elements for attribute
arrays.  Specify an attribute name followed by an array index in
square brackets to delete a single element of an attribute array.  In
the latter case, all the array elements numbered higher than the
deleted element are shifted down, filling the vacated position.

To associate custom attributes with the entire active file, instead of
with particular variables, use @cmd{DATAFILE ATTRIBUTE} (@pxref{DATAFILE ATTRIBUTE}) instead.

@cmd{VARIABLE ATTRIBUTE} takes effect immediately.  It is not affected
by conditional and looping structures such as @cmd{DO IF} or
@cmd{LOOP}.

@node VARIABLE LABELS
@section VARIABLE LABELS
@vindex VARIABLE LABELS

@display
VARIABLE LABELS
        var_list 'var_label' 
        [ /var_list 'var_label']
        .
        .
        .
        [ /var_list 'var_label']
@end display

@cmd{VARIABLE LABELS} associates explanatory names
with variables.  This name, called a @dfn{variable label}, is displayed by
statistical procedures.

To assign a variable label to a group of variables, specify a 
list of variable names and the variable label as a string.
To assign different labels to different variables in the same command, 
precede the subsequent variable list with a slash (@samp{/}).


@node VARIABLE ALIGNMENT
@comment  node-name,  next,  previous,  u
@section VARIABLE ALIGNMENT
@vindex VARIABLE ALIGNMENT

@display
VARIABLE ALIGNMENT
        var_list ( LEFT | RIGHT | CENTER )
        [ /var_list ( LEFT | RIGHT | CENTER ) ]
        .
        .
        .
        [ /var_list ( LEFT | RIGHT | CENTER ) ]
@end display

@cmd{VARIABLE ALIGNMENT} sets the alignment of variables for display editing 
purposes.   This only has effect for third party software.  It does not affect 
the display of variables in the PSPP output.




@node VARIABLE WIDTH
@comment  node-name,  next,  previous,  up
@section VARIABLE WIDTH
@vindex VARIABLE WIDTH
@display
VARIABLE WIDTH
        var_list (width)
        [ /var_list (width) ] 
        .
        .
        .
        [ /var_list (width) ] 
@end display

@cmd{VARIABLE WIDTH} sets the column width of variables for display editing
purposes.   This only affects third party software.  It does not affect 
the display of variables in the PSPP output.


@node VARIABLE LEVEL
@comment  node-name,  next,  previous,  up
@section VARIABLE LEVEL
@vindex VARIABLE LEVEL
@display
VARIABLE LEVEL
        var_list ( SCALE | NOMINAL | ORDINAL )
        [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
        .
        .
        .
        [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
@end display

@cmd{VARIABLE LEVEL} sets the measurement level of  variables.
Currently, this has no effect except for certain third party software.


@node VECTOR
@section VECTOR
@vindex VECTOR

@display
Two possible syntaxes:
        VECTOR vec_name=var_list.
        VECTOR vec_name_list(count [format]).
@end display

@cmd{VECTOR} allows a group of variables to be accessed as if they
were consecutive members of an array with a vector(index) notation.

To make a vector out of a set of existing variables, specify a name
for the vector followed by an equals sign (@samp{=}) and the variables
to put in the vector.  All the variables in the vector must be the same
type.  String variables in a vector must all have the same width.

To make a vector and create variables at the same time, specify one or
more vector names followed by a count in parentheses.  This will cause
variables named @code{@var{vec}1} through @code{@var{vec}@var{count}}
to be created as numeric variables.  By default, the new variables
have print and write format F8.2, but an alternate format may be
specified inside the parentheses before or after the count and
separated from it by white space or a comma.  Variable names including
numeric suffixes may not exceed 64 characters in length, and none of
the variables may exist prior to @cmd{VECTOR}.

Vectors created with @cmd{VECTOR} disappear after any procedure or
procedure-like command is executed.  The variables contained in the
vectors remain, unless they are scratch variables (@pxref{Scratch
Variables}).

Variables within a vector may be referenced in expressions using
@code{vector(index)} syntax.

@node WRITE FORMATS
@section WRITE FORMATS
@vindex WRITE FORMATS

@display
WRITE FORMATS var_list (fmt_spec).
@end display

@cmd{WRITE FORMATS} sets the write formats for the specified numeric
variables
to the specified format specification.  Its syntax is identical to
that of FORMATS (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
write formats, not print formats.