- [MATRIX DATA](commands/matrix/matrix-data.md)
- [MCONVERT](commands/matrix/mconvert.md)
- [MATRIX](commands/matrix/matrix.md)
+- [Utilities](commands/utilities/index.md)
+ - [ADD DOCUMENT](commands/utilities/add-document.md)
+ - [CACHE](commands/utilities/cache.md)
+ - [CD](commands/utilities/cd.md)
+ - [COMMENT](commands/utilities/comment.md)
+ - [DOCUMENT](commands/utilities/document.md)
+ - [DISPLAY DOCUMENTS](commands/utilities/display-documents.md)
+ - [DISPLAY FILE LABEL](commands/utilities/display-file-label.md)
+ - [DROP DOCUMENTS](commands/utilities/drop-documents.md)
+ - [ECHO](commands/utilities/echo.md)
+ - [ERASE](commands/utilities/erase.md)
+ - [EXECUTE](commands/utilities/execute.md)
+ - [FILE LABEL](commands/utilities/file-label.md)
+ - [FINISH](commands/utilities/finish.md)
+ - [HOST](commands/utilities/host.md)
+ - [INCLUDE](commands/utilities/include.md)
+ - [INSERT](commands/utilities/insert.md)
# Developer Documentation
--- /dev/null
+# ADD DOCUMENT
+
+```
+ADD DOCUMENT
+ 'line one' 'line two' ... 'last line' .
+```
+
+`ADD DOCUMENT` adds one or more lines of descriptive commentary to
+the active dataset. Documents added in this way are saved to system
+files. They can be viewed using `SYSFILE INFO` or `DISPLAY DOCUMENTS`.
+They can be removed from the active dataset with `DROP DOCUMENTS`.
+
+Each line of documentary text must be enclosed in quotation marks, and
+may not be more than 80 bytes long. See also
+[`DOCUMENT`](document.md).
+
--- /dev/null
+# CACHE
+
+```
+CACHE.
+```
+
+This command is accepted, for compatibility, but it has no effect.
+
--- /dev/null
+# CD
+
+```
+CD 'new directory' .
+```
+
+`CD` changes the current directory. The new directory becomes that
+specified by the command.
+
--- /dev/null
+# COMMENT
+
+```
+Comment commands:
+ COMMENT comment text ... .
+ *comment text ... .
+
+Comments within a line of syntax:
+ FREQUENCIES /VARIABLES=v0 v1 v2. /* All our categorical variables.
+```
+
+`COMMENT` is ignored. It is used to provide information to the
+author and other readers of the PSPP syntax file.
+
+`COMMENT` can extend over any number of lines. It ends at a dot at
+the end of a line or a blank line. The comment may contain any
+characters.
+
+PSPP also supports comments within a line of syntax, introduced with
+`/*`. These comments end at the first `*/` or at the end of the line,
+whichever comes first. A line that contains just this kind of comment
+is considered blank and ends the current command.
+
--- /dev/null
+# DISPLAY DOCUMENTS
+
+```
+DISPLAY DOCUMENTS.
+```
+
+`DISPLAY DOCUMENTS` displays the documents in the active dataset.
+Each document is preceded by a line giving the time and date that it
+was added. See also [`DOCUMENT`](document.md).
+
--- /dev/null
+# DISPLAY FILE LABEL
+
+```
+DISPLAY FILE LABEL.
+```
+
+`DISPLAY FILE LABEL` displays the file label contained in the active
+dataset, if any. See also [`FILE LABEL`](file-label.md).
+
+This command is a PSPP extension.
+
--- /dev/null
+# DOCUMENT
+
+```
+DOCUMENT DOCUMENTARY_TEXT.
+```
+
+`DOCUMENT` adds one or more lines of descriptive commentary to the
+active dataset. Documents added in this way are saved to system
+files. They can be viewed using `SYSFILE INFO` or [`DISPLAY
+DOCUMENTS`](display-documents.md). They can be removed from the
+active dataset with [`DROP DOCUMENTS`](drop-documents.md).
+
+Specify the text of the document following the `DOCUMENT` keyword. It
+is interpreted literally—any quotes or other punctuation marks are
+included in the file. You can extend the documentary text over as
+many lines as necessary, including blank lines to separate paragraphs.
+Lines are truncated at 80 bytes. Don't forget to terminate the
+command with a dot at the end of a line. See also [ADD
+DOCUMENT](add-document.md).
+
--- /dev/null
+# DROP DOCUMENTS
+
+```
+DROP DOCUMENTS.
+```
+
+`DROP DOCUMENTS` removes all documents from the active dataset. New
+documents can be added with [`DOCUMENT`](document.md).
+
+`DROP DOCUMENTS` changes only the active dataset. It does not modify
+any system files stored on disk.
+
--- /dev/null
+# ECHO
+
+```
+ECHO 'arbitrary text' .
+```
+
+Use `ECHO` to write arbitrary text to the output stream. The text
+should be enclosed in quotation marks following the normal rules for
+[string tokens](../../language/basics/tokens.md#strings).
+
--- /dev/null
+# ERASE
+
+```
+ERASE FILE "FILE_NAME".
+```
+
+`ERASE FILE` deletes a file from the local file system. The file's
+name must be quoted. This command cannot be used if the SAFER (*note
+SET::) setting is active.
+
--- /dev/null
+# EXECUTE
+
+```
+EXECUTE.
+```
+
+`EXECUTE` causes the active dataset to be read and all pending
+transformations to be executed.
+
--- /dev/null
+# FILE LABEL
+
+```
+FILE LABEL file label.
+```
+
+`FILE LABEL` provides a title for the active dataset. This title is
+saved into system files and portable files that are created during
+this PSPP run.
+
+The file label should not be quoted. If quotes are included, they are
+become part of the file label.
+
--- /dev/null
+# FINISH
+
+```
+FINISH.
+```
+
+`FINISH` terminates the current PSPP session and returns control to
+the operating system.
+
--- /dev/null
+# HOST
+
+In the syntax below, the square brackets must be included in the command
+syntax and do not indicate that that their contents are optional.
+
+```
+HOST COMMAND=['COMMAND'...]
+ TIMELIMIT=SECS.
+```
+
+`HOST` executes one or more commands, each provided as a string in
+the required `COMMAND` subcommand, in the shell of the underlying
+operating system. PSPP runs each command in a separate shell process
+and waits for it to finish before running the next one. If a command
+fails (with a nonzero exit status, or because it is killed by a signal),
+then PSPP does not run any remaining commands.
+
+PSPP provides `/dev/null` as the shell's standard input. If a
+process needs to read from stdin, redirect from a file or device, or use
+a pipe.
+
+PSPP displays the shell's standard output and standard error as PSPP
+output. Redirect to a file or `/dev/null` or another device if this is
+not desired.
+
+By default, PSPP waits as long as necessary for the series of
+commands to complete. Use the optional `TIMELIMIT` subcommand to limit
+the execution time to the specified number of seconds.
+
+PSPP built for mingw does not support all the features of `HOST`.
+
+PSPP rejects this command if the SAFER (*note SET::) setting is
+active.
+
+## Example
+
+The following example runs `rsync` to copy a file from a remote
+server to the local file `data.txt`, writing `rsync`'s own output to
+`rsync-log.txt`. PSPP displays the command's error output, if any. If
+`rsync` needs to prompt the user (e.g. to obtain a password), the
+command fails. Only if the `rsync` succeeds, PSPP then runs the
+`sha512sum` command.
+
+```
+HOST COMMAND=['rsync remote:data.txt data.txt > rsync-log.txt'
+ 'sha512sum -c data.txt.sha512sum].
+```
+
--- /dev/null
+# INCLUDE
+
+```
+INCLUDE [FILE=]'FILE_NAME' [ENCODING='ENCODING'].
+```
+
+`INCLUDE` causes the PSPP command processor to read an additional
+command file as if it were included bodily in the current command file.
+If errors are encountered in the included file, then command processing
+stops and no more commands are processed. Include files may be nested
+to any depth, up to the limit of available memory.
+
+The [`INSERT`](insert.md) command is a more flexible alternative to
+`INCLUDE`. An `INCLUDE` command acts the same as `INSERT` with
+`ERROR=STOP CD=NO SYNTAX=BATCH` specified.
+
+The optional `ENCODING` subcommand has the same meaning as with
+`INSERT`.
+
--- /dev/null
+# Utility Commands
+
+This chapter describes commands that don't fit in other categories.
+
+Most of these commands are not affected by commands like `IF` and
+`LOOP`: they take effect only once, unconditionally, at the time that
+they are encountered in the input.
--- /dev/null
+# INSERT
+
+```
+INSERT [FILE=]'FILE_NAME'
+ [CD={NO,YES}]
+ [ERROR={CONTINUE,STOP}]
+ [SYNTAX={BATCH,INTERACTIVE}]
+ [ENCODING={LOCALE, 'CHARSET_NAME'}].
+```
+
+`INSERT` is similar to [`INCLUDE`](include.md) but more flexible. It
+causes the command processor to read a file as if it were embedded in
+the current command file.
+
+If `CD=YES` is specified, then before including the file, the current
+directory becomes the directory of the included file. The default
+setting is `CD=NO`. Note that this directory remains current until it
+is changed explicitly (with the `CD` command, or a subsequent `INSERT`
+command with the `CD=YES` option). It does not revert to its original
+setting even after the included file is finished processing.
+
+If `ERROR=STOP` is specified, errors encountered in the inserted file
+causes processing to immediately cease. Otherwise processing continues
+at the next command. The default setting is `ERROR=CONTINUE`.
+
+If `SYNTAX=INTERACTIVE` is specified then the syntax contained in the
+included file must conform to [interactive syntax
+conventions](../../language/basics/syntax-variants.md). The default
+setting is `SYNTAX=BATCH`.
+
+`ENCODING` optionally specifies the character set used by the
+included file. Its argument, which is not case-sensitive, must be in
+one of the following forms:
+
+* `LOCALE`
+ The encoding used by the system locale, or as overridden by the
+ `SET` command (*note SET::). On GNU/Linux and other Unix-like
+ systems, environment variables, e.g. `LANG` or `LC_ALL`, determine
+ the system locale.
+
+* `'CHARSET_NAME'`
+ An [IANA character set
+ name](http://www.iana.org/assignments/character-sets). Some
+ examples are `ASCII` (United States), `ISO-8859-1` (western Europe),
+ `EUC-JP` (Japan), and `windows-1252` (Windows). Not all systems
+ support all character sets.
+
+* `Auto,ENCODING`
+ Automatically detects whether a syntax file is encoded in a Unicode
+ encoding such as UTF-8, UTF-16, or UTF-32. If it is not, then PSPP
+ generally assumes that the file is encoded in `ENCODING` (an IANA
+ character set name). However, if `ENCODING` is UTF-8, and the
+ syntax file is not valid UTF-8, PSPP instead assumes that the file
+ is encoded in `windows-1252`.
+
+ For best results, `ENCODING` should be an ASCII-compatible encoding
+ (the most common locale encodings are all ASCII-compatible),
+ because encodings that are not ASCII compatible cannot be
+ automatically distinguished from UTF-8.
+
+* `Auto`
+ `Auto,Locale`
+ Automatic detection, as above, with the default encoding taken from
+ the system locale or the setting on `SET LOCALE`.
+
+When `ENCODING` is not specified, the default is taken from the
+`--syntax-encoding` command option, if it was specified, and otherwise
+it is `Auto`.
+
projects / pspp / commitdiff