- [MATCH FILES](commands/combining/match-files.md)
- [UPDATE](commands/combining/update.md)
- [Manipulating Variables](commands/variables/index.md)
+ - [ADD VALUE LABELS](commands/variables/add-value-labels.md)
+ - [DELETE VARIABLES](commands/variables/delete-variables.md)
- [DISPLAY](commands/variables/display.md)
+ - [FORMATS](commands/variables/formats.md)
+ - [LEAVE](commands/variables/leave.md)
+ - [MISSING VALUES](commands/variables/missing-values.md)
+ - [MRSETS](commands/variables/mrsets.md)
+ - [NUMERIC](commands/variables/numeric.md)
+ - [PRINT FORMATS](commands/variables/print-formats.md)
+ - [RENAME VARIABLES](commands/variables/rename-variables.md)
+ - [SORT VARIABLES](commands/variables/sort-variables.md)
+ - [STRING](commands/variables/string.md)
+ - [VALUE LABELS](commands/variables/value-labels.md)
+ - [VARIABLE ALIGNMENT](commands/variables/variable-alignment.md)
+ - [VARIABLE ATTRIBUTE](commands/variables/variable-attribute.md)
+ - [VARIABLE LABELS](commands/variables/variable-labels.md)
+ - [VARIABLE LEVEL](commands/variables/variable-level.md)
+ - [VARIABLE ROLE](commands/variables/variable-role.md)
+ - [VARIABLE WIDTH](commands/variables/variable-width.md)
+ - [VECTOR](commands/variables/vector.md)
+ - [WRITE FORMATS](commands/variables/write-formats.md)
# Developer Documentation
--- /dev/null
+# ADD VALUE LABELS
+
+`ADD VALUE LABELS` has the same syntax and purpose as [`VALUE
+LABELS`](value-labels.md), but it does not clear value labels from the
+variables before adding the ones specified.
+
+```
+ADD VALUE LABELS
+ /VAR_LIST VALUE 'LABEL' [VALUE 'LABEL']...
+```
--- /dev/null
+# DELETE VARIABLES
+
+`DELETE VARIABLES` deletes the specified variables from the dictionary.
+
+```
+DELETE VARIABLES VAR_LIST.
+```
+
+`DELETE VARIABLES` should not be used after defining transformations
+but before executing a procedure. If it is anyhow, it causes the data
+to be read. If it is used while `TEMPORARY` is in effect, it causes
+the temporary transformations to become permanent.
+
+`DELETE VARIABLES` may not be used to delete all variables from the
+dictionary; use [`NEW FILE`](../../commands/data-io/new-file.html)
+instead.
+
--- /dev/null
+# FORMATS
+
+```
+FORMATS VAR_LIST (FMT_SPEC) [VAR_LIST (FMT_SPEC)]....
+```
+
+`FORMATS` set both print and write formats for the specified variables
+to the specified [output
+format](../../language/datasets/formats/index.md).
+
+Specify a list of variables followed by a format specification in
+parentheses. The print and write formats of the specified variables
+will be changed. All of the variables listed together must have the
+same type and, for string variables, the same width.
+
+Additional lists of variables and formats may be included following
+the first one.
+
+`FORMATS` takes effect immediately. It is not affected by conditional
+and looping structures such as `DO IF` or `LOOP`.
+
--- /dev/null
+# LEAVE
+
+`LEAVE` prevents the specified variables from being reinitialized
+whenever a new case is processed.
+
+```
+LEAVE VAR_LIST.
+```
+
+Normally, when a data file is processed, every variable in the active
+dataset is initialized to the system-missing value or spaces at the
+beginning of processing for each case. When a variable has been
+specified on `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.
+
+```
+DATA LIST /ITEM 1-3.
+COMPUTE SUM=SUM+ITEM.
+PRINT /ITEM SUM.
+LEAVE SUM
+BEGIN DATA.
+123
+404
+555
+999
+END DATA.
+```
+
+Partial output from this example:
+
+```
+123 123.00
+404 527.00
+555 1082.00
+999 2081.00
+```
+
+It is best to use `LEAVE` command immediately before invoking a
+procedure command, because the left status of variables is reset by
+certain transformations—for instance, `COMPUTE` and `IF`. Left status
+is also reset by all procedure invocations.
+
--- /dev/null
+# MISSING VALUES
+
+In many situations, the data available for analysis is incomplete, so
+that a placeholder must be used to indicate that the value is unknown.
+One way that missing values are represented, for numeric data, is the
+["system-missing value"](../../language/basics/missing-values.html).
+Another, more flexible way is through "user-missing values" which are
+determined on a per variable basis.
+
+The `MISSING VALUES` command sets user-missing values for variables.
+
+```
+MISSING VALUES VAR_LIST (MISSING_VALUES).
+
+where 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.
+```
+
+`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 `MISSING VALUES` command takes effect immediately. It is not
+affected by conditional and looping constructs such as `DO IF` or
+`LOOP`.
+
--- /dev/null
+# MRSETS
+
+`MRSETS` creates, modifies, deletes, and displays multiple response
+sets. A multiple response set is a set of variables that represent
+multiple responses to a survey question.
+
+Multiple responses are represented in one of the two following ways:
+
+- A "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.
+
+- A "multiple category set" represents a survey question where the
+ respondent is instructed to list up to N choices. Each variable
+ represents one of the responses.
+
+```
+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}
+```
+
+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:
+
+- `NAME` specifies the name used in syntax for the new multiple
+ dichotomy set. The name must begin with `$`; it must otherwise
+ follow the rules for [identifiers](../../language/basics/tokens.md).
+
+- `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.
+
+- `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).
+
+- `CATEGORYLABELS` optionally specifies the source of the labels for
+ each category in the set:
+
+ − `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.
+
+ − `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.
+
+- `LABEL` optionally specifies a label for the multiple response set.
+ If neither `LABEL` nor `LABELSOURCE=VARLABEL` is specified, the set
+ is unlabeled.
+
+- `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`.
+
+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 in `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 `SAVE` and `GET` command. Otherwise, multiple response sets
+are currently used only by third party software.
+
--- /dev/null
+# NUMERIC
+
+`NUMERIC` explicitly declares new numeric variables, optionally setting
+their output formats.
+
+```
+NUMERIC VAR_LIST [(FMT_SPEC)] [/VAR_LIST [(FMT_SPEC)]]...
+```
+
+ Specify the names of the new numeric variables as `VAR_LIST`. If
+you wish to set the variables' output formats, follow their names by
+an [output format](../../language/datasets/formats/index.html) in
+parentheses; otherwise, the default is `F8.2`.
+
+ Variables created with `NUMERIC` are initialized to the
+system-missing value.
+
--- /dev/null
+# PRINT FORMATS
+
+```
+PRINT FORMATS VAR_LIST (FMT_SPEC) [VAR_LIST (FMT_SPEC)]....
+```
+
+`PRINT FORMATS` sets the print formats for the specified variables to
+the specified format specification.
+
+It has the same syntax as [`FORMATS`](formats.md), but `PRINT FORMATS`
+sets only print formats, not write formats.
+
--- /dev/null
+# RENAME VARIABLES
+
+`RENAME VARIABLES` changes the names of variables in the active dataset.
+
+```
+RENAME VARIABLES (OLD_NAMES=NEW_NAMES)... .
+```
+
+Specify lists of the old variable names and new variable names,
+separated by an 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. When the old and
+new variable names contain only a single variable name, the
+parentheses are optional.
+
+`RENAME VARIABLES` takes effect immediately. It does not cause the
+data to be read.
+
+`RENAME VARIABLES` may not be specified following `TEMPORARY` (*note
+TEMPORARY::).
+
--- /dev/null
+# SORT VARIABLES
+
+`SORT VARIABLES` reorders the variables in the active dataset's
+dictionary according to a chosen sort key.
+
+```
+SORT VARIABLES [BY]
+ (NAME | TYPE | FORMAT | LABEL | VALUES | MISSING | MEASURE
+ | ROLE | COLUMNS | ALIGNMENT | ATTRIBUTE NAME)
+ [(D)].
+```
+
+The main specification is one of the following identifiers, which
+determines how the variables are sorted:
+
+* `NAME`
+ Sorts the variables according to their names, in a case-insensitive
+ fashion. However, when variable names differ only in a number at
+ the end, they are sorted numerically. For example, `VAR5` is
+ sorted before `VAR400` even though `4` precedes `5`.
+
+* `TYPE`
+ Sorts numeric variables before string variables, and shorter string
+ variables before longer ones.
+
+* `FORMAT`
+ Groups variables by print format; within a format, sorts narrower
+ formats before wider ones; with the same format and width, sorts
+ fewer decimal places before more decimal places. See [`PRINT
+ FORMATS`](print-formats.md).
+
+* `LABEL`
+ Sorts variables without a variable label before those with one.
+ See [VARIABLE LABELS](variable-labels.md).
+
+* `VALUES`
+ Sorts variables without value labels before those with some. See
+ [VALUE LABELS](value-labels.md).
+
+* `MISSING`
+ Sorts variables without missing values before those with some. See
+ [MISSING VALUES](missing-values.md).
+
+* `MEASURE`
+ Sorts nominal variables first, followed by ordinal variables,
+ followed by scale variables. See [VARIABLE
+ LEVEL](variable-level.md).
+
+* `ROLE`
+ Groups variables according to their role. See [VARIABLE
+ ROLE](variable-role.md).
+
+* `COLUMNS`
+ Sorts variables in ascending display width. See [VARIABLE
+ WIDTH](variable-width.md).
+
+* `ALIGNMENT`
+ Sorts variables according to their alignment, first left-aligned,
+ then right-aligned, then centered. See [VARIABLE
+ ALIGNMENT](variable-alignment.md).
+
+* `ATTRIBUTE NAME`
+ Sorts variables according to the first value of their `NAME`
+ attribute. Variables without attributes are sorted first. See
+ [VARIABLE ATTRIBUTE](variable-attribute.md).
+
+Only one sort criterion can be specified. The sort is "stable," so to
+sort on multiple criteria one may perform multiple sorts. For
+example, the following will sort primarily based on alignment, with
+variables that have the same alignment ordered based on display width:
+
+```
+SORT VARIABLES BY COLUMNS.
+SORT VARIABLES BY ALIGNMENT.
+```
+
+
+Specify `(D)` to reverse the sort order.
+
--- /dev/null
+# STRING
+
+`STRING` creates new string variables.
+
+```
+STRING VAR_LIST (FMT_SPEC) [/VAR_LIST (FMT_SPEC)] [...].
+```
+
+Specify a list of names for the variable you want to create, followed
+by the desired [output
+format](../../language/datasets/formats/index.html) in parentheses.
+Variable widths are implicitly derived from the specified output
+formats. The created variables will be initialized to spaces.
+
+If you want to create several variables with distinct output formats,
+you can either use two or more separate `STRING` commands, or you can
+specify further variable list and format specification pairs, each
+separated from the previous by a slash (`/`).
+
+The following example is one way to create three string variables; Two
+of the variables have format `A24` and the other `A80`:
+
+```
+STRING firstname lastname (A24) / address (A80).
+```
+
+Here is another way to achieve the same result:
+
+```
+STRING firstname lastname (A24).
+STRING address (A80).
+```
+
+... and here is yet another way:
+
+```
+STRING firstname (A24).
+STRING lastname (A24).
+STRING address (A80).
+```
--- /dev/null
+# VALUE LABELS
+
+The values of a variable can be associated with explanatory text
+strings. In this way, a short value can stand for a longer, more
+descriptive label.
+
+Both numeric and string variables can be given labels. For string
+variables, the values are case-sensitive, so that, for example, a
+capitalized value and its lowercase variant would have to be labeled
+separately if both are present in the data.
+
+```
+VALUE LABELS
+ /VAR_LIST VALUE 'LABEL' [VALUE 'LABEL']...
+```
+
+`VALUE LABELS` allows values of variables to be associated with
+labels.
+
+To set up value labels for one or more variables, specify the variable
+names after a slash (`/`), followed by a list of values and their
+associated labels, separated by spaces.
+
+Value labels in output are normally broken into lines automatically.
+Put `\n` in a label string to force a line break at that point. The
+label may still be broken into lines at additional points.
+
+Before `VALUE LABELS` is executed, any existing value labels are
+cleared from the variables specified. Use [`ADD VALUE
+LABELS`](add-value-labels.md) to add value labels without clearing
+those already present.
+
--- /dev/null
+# VARIABLE ALIGNMENT
+
+`VARIABLE ALIGNMENT` sets the alignment of variables for display
+editing purposes. It does not affect the display of variables in PSPP
+output.
+
+```
+VARIABLE ALIGNMENT
+ VAR_LIST ( LEFT | RIGHT | CENTER )
+ [ /VAR_LIST ( LEFT | RIGHT | CENTER ) ]
+ .
+ .
+ .
+ [ /VAR_LIST ( LEFT | RIGHT | CENTER ) ]
+
+```
--- /dev/null
+# VARIABLE ATTRIBUTE
+
+`VARIABLE ATTRIBUTE` adds, modifies, or removes user-defined attributes
+associated with variables in the active dataset. 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.
+
+```
+VARIABLE ATTRIBUTE
+ VARIABLES=VAR_LIST
+ ATTRIBUTE=NAME('VALUE') [NAME('VALUE')]...
+ ATTRIBUTE=NAME[INDEX]('VALUE') [NAME[INDEX]('VALUE')]...
+ DELETE=NAME [NAME]...
+ DELETE=NAME[INDEX] [NAME[INDEX]]...
+```
+
+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](../../language/basics/tokens.md), 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 `$` are reserved for PSPP's internal
+use, and attribute names that begin with `@` or `$@` 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 (`[`
+and `]`) 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 dataset, instead
+of with particular variables, use [`DATAFILE
+ATTRIBUTE`](../commands/data-io/datafile-attribute.md) instead.
+
+`VARIABLE ATTRIBUTE` takes effect immediately. It is not affected by
+conditional and looping structures such as `DO IF` or `LOOP`.
+
--- /dev/null
+# VARIABLE LABELS
+
+Each variable can have a "label" to supplement its name. Whereas a
+variable name is a concise, easy-to-type mnemonic for the variable, a
+label may be longer and more descriptive.
+
+```
+VARIABLE LABELS
+ VARIABLE 'LABEL'
+ [VARIABLE 'LABEL']...
+```
+
+`VARIABLE LABELS` associates explanatory names with variables. This
+name, called a "variable label", is displayed by statistical
+procedures.
+
+Specify each variable followed by its label as a quoted string.
+Variable-label pairs may be separated by an optional slash `/`.
+
+If a listed variable already has a label, the new one replaces it.
+Specifying an empty string as the label, e.g. `''`, removes a label.
+
--- /dev/null
+# VARIABLE LEVEL
+
+```
+VARIABLE LEVEL variables ({SCALE | NOMINAL | ORDINAL})...
+```
+
+`VARIABLE LEVEL` sets the [measurement
+level](../../language/datasets/variables.md) of the listed variables.
+
--- /dev/null
+# VARIABLE ROLE
+
+```
+VARIABLE ROLE
+ /ROLE VAR_LIST
+ [/ROLE VAR_LIST]...
+```
+
+`VARIABLE ROLE` sets the intended role of a variable for use in dialog
+boxes in graphical user interfaces. Each `ROLE` specifies one of the
+following roles for the variables that follow it:
+
+* `INPUT`
+ An input variable, such as an independent variable.
+
+* `TARGET`
+ An output variable, such as an dependent variable.
+
+* `BOTH`
+ A variable used for input and output.
+
+* `NONE`
+ No role assigned. (This is a variable's default role.)
+
+* `PARTITION`
+ Used to break the data into groups for testing.
+
+* `SPLIT`
+ No meaning except for certain third party software. (This role's
+ meaning is unrelated to `SPLIT FILE`.)
+
+The PSPPIRE GUI does not yet use variable roles.
--- /dev/null
+# VARIABLE WIDTH
+
+```
+VARIABLE WIDTH
+ VAR_LIST (width)
+ [ /VAR_LIST (width) ]
+ .
+ .
+ .
+ [ /VAR_LIST (width) ]
+```
+
+`VARIABLE WIDTH` sets the column width of variables for display
+editing purposes. It does not affect the display of variables in the
+PSPP output.
+
--- /dev/null
+# VECTOR
+
+```
+Two possible syntaxes:
+ VECTOR VEC_NAME=VAR_LIST.
+ VECTOR VEC_NAME_LIST(COUNT [FORMAT]).
+```
+
+`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 (`=`) and the variables to
+put in the vector. The variables must be all numeric or all string,
+and string variables must 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
+create variables named `VEC1` through `VEC<count>`. By default, the
+new variables are numeric with 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. With a string format
+such as `A8`, the variables will be string variables; with a numeric
+format, they will be numeric. Variable names including the suffixes
+may not exceed 64 characters in length, and none of the variables may
+exist prior to `VECTOR`.
+
+Vectors created with `VECTOR` disappear after any procedure or
+procedure-like command is executed. The variables contained in the
+vectors remain, unless they are [scratch
+variables](../../language/datasets/scratch-variables.md).
+
+Variables within a vector may be referenced in expressions using
+`vector(index)` syntax.
+
--- /dev/null
+# WRITE FORMATS
+
+```
+WRITE FORMATS VAR_LIST (FMT_SPEC) [VAR_LIST (FMT_SPEC)]....
+```
+
+`WRITE FORMATS` sets the write formats for the specified variables to
+the specified format specification. It has the same syntax as
+[`FORMATS`](formats.md), but `WRITE FORMATS` sets only write formats,
+not print formats.
+
projects / pspp / commitdiff