Re: sav files with attributes

[Ben Pfaff]

Ben Pfaff <address@hidden> writes:

> I'm adding support for attributes to PSPP.

I wrote up system file format documentation for attributes and
user documentation for the attribute commands tonight.  (Usually
I write code before documentation, but this time I'm doing it the
other way around.)

Here is the diff.  Feedback welcome.

diff --git a/doc/dev/system-file-format.texi b/doc/dev/system-file-format.texi
index 70fa385..3e764c8 100644
--- a/doc/dev/system-file-format.texi
+++ b/doc/dev/system-file-format.texi
@@ -96,6 +96,7 @@ Each type of record is described separately below.
 * Variable Display Parameter Record::
 * Long Variable Names Record::
 * Very Long String Record::
+* Data File and Variable Attributes Records::
 * Miscellaneous Informational Records::
 * Dictionary Termination Record::
 * Data Record::
@@ -791,6 +792,85 @@ After the last tuple, there may be a single byte 00, or 
@{00, address@hidden
 The total length is @code{count} bytes.
 @end table
 
address@hidden Data File and Variable Attributes Records
address@hidden Data File and Variable Attributes Records
+
+The data file and variable attributes records represent custom
+attributes for the system file or for individual variables in the
+system file, as defined on the DATAFILE ATTRIBUTE (@pxref{DATAFILE
+ATTRIBUTE,,,pspp, PSPP Users Guide}) and VARIABLE ATTRIBUTE commands
+(@pxref{VARIABLE ATTRIBUTE,,,pspp, PSPP Users Guide}), respectively.
+
address@hidden
+/* @r{Header.} */
+int32               rec_type;
+int32               subtype;
+int32               size;
+int32               count;
+
+/* @r{Exactly @code{count} bytes of data.} */
+char                attributes[];
address@hidden example
+
address@hidden @code
address@hidden int32 rec_type;
+Record type.  Always set to 7.
+
address@hidden int32 subtype;
+Record subtype.  Always set to 17 for a data file attribute record or
+to 18 for a variable attributes record.
+
address@hidden int32 size;
+The size of each element in the @code{attributes} member. Always set to 1.
+
address@hidden int32 count;
+The total number of bytes in @code{attributes}.
+
address@hidden char attributes[];
+The attributes, in a text-based format.
+
+In record type 17, this field contains a single attribute set.  An
+attribute set is a sequence of one or more attributes concatenated
+together.  Each attribute consists of a name, which has the same
+syntax as a variable name, followed by, inside parentheses, a sequence
+of one or more values.  Each value consists of a string enclosed in
+single quotes (@code{'}) followed by a line feed (byte 0x0a).  A value
+may contain single quote characters, which are not themselves escaped
+or quoted or required to be present in pairs.  There is no apparent
+way to embed a line feed in a value.  There is no distinction between
+an attribute with a single value and an attribute array with one
+element.
+
+In record type 18, this field contains a sequence of one or more
+variable attribute sets.  If more than one variable attribute set is
+present, each one after the first is delimited from the previous by
address@hidden/}.  Each variable attribute set consists of a variable name,
+followed by @code{:}, followed by an attribute set with the same
+syntax as on record type 17.
+
+The total length is @code{count} bytes.
address@hidden table
+
address@hidden Example
+
+A system file produced with the following VARIABLE ATTRIBUTE commands
+in effect:
+
address@hidden
+VARIABLE ATTRIBUTE VARIABLES=dummy ATTRIBUTE=fred[1]('23') fred[2]('34').
+VARIABLE ATTRIBUTE VARIABLES=dummy ATTRIBUTE=bert('123').
address@hidden example
+
address@hidden
+will contain a variable attribute record with the following contents:
+
address@hidden
+00000000  07 00 00 00 12 00 00 00  01 00 00 00 22 00 00 00  |............"...|
+00000010  64 75 6d 6d 79 3a 66 72  65 64 28 27 32 33 27 0a  |dummy:fred('23'.|
+00000020  27 33 34 27 0a 29 62 65  72 74 28 27 31 32 33 27  |'34'.)bert('123'|
+00000030  0a 29                                             |.)              |
address@hidden example
+
 @node Miscellaneous Informational Records
 @section Miscellaneous Informational Records
 
diff --git a/doc/language.texi b/doc/language.texi
index 1345433..ed1123d 100644
--- a/doc/language.texi
+++ b/doc/language.texi
@@ -497,6 +497,11 @@ they are displayed.  Example: a width of 8, with 2 decimal 
places.
 @item Write format
 Similar to print format, but used by the @cmd{WRITE} command
 (@pxref{WRITE}).
+
address@hidden custom attributes
address@hidden Custom attributes
+User-defined associations between names and values.  @xref{VARIABLE
+ATTRIBUTE}.
 @end table
 
 @node System Variables
diff --git a/doc/variables.texi b/doc/variables.texi
index a66e423..c2a944e 100644
--- a/doc/variables.texi
+++ b/doc/variables.texi
@@ -6,9 +6,9 @@ several utility functions for examining and adjusting them.
 
 @menu
 * ADD VALUE LABELS::            Add value labels to variables.
+* DATAFILE ATTRIBUTE::          Set custom attributes on data files.
 * DELETE VARIABLES::            Delete variables.
-* DISPLAY::                     Display variable names & descriptions.
-* DISPLAY VECTORS::             Display a list of vectors.
+* 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.
@@ -18,6 +18,7 @@ several utility functions for examining and adjusting them.
 * 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.
@@ -39,6 +40,52 @@ ADD VALUE LABELS
 LABELS} (@pxref{VALUE LABELS}), but it does not clear value
 labels from the variables before adding the ones specified.
 
address@hidden DATAFILE ATTRIBUTE
address@hidden DATAFILE ATTRIBUTE
address@hidden DATAFILE ATTRIBUTE
+
address@hidden
+DATAFILE ATTRIBUTE
+         ATTRIBUTE=name('value') [name('value')address@hidden
+         address@hidden@b{]}('value') 
address@hidden@b{]}('value')address@hidden
+         DELETE=name address@hidden
+         address@hidden@b{]} address@hidden@address@hidden
address@hidden display
+
address@hidden ATTRIBUTE} adds, modifies, or removes user-defined
+attributes associated with the active file.  Custom data file
+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.
+
+Use the ATTRIBUTE subcommand to add or modify a custom data file
+attribute.  Specify the name of the attribute as an identifier
+(@pxref{Tokens}), followed by the desired value, in parentheses, as a
+quoted string.  Attribute names that begin with @code{$} are reserved
+for PSPP's internal use, and attribute names that begin with @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.  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 particular variables, instead of
+with the entire active file, use @cmd{VARIABLE ATTRIBUTE} instead.
+
address@hidden ATTRIBUTE} takes effect immediately.  It is not affected
+by conditional and looping structures such as @cmd{DO IF} or
address@hidden
+
 @node DELETE VARIABLES
 @section DELETE VARIABLES
 @vindex DELETE VARIABLES
@@ -61,15 +108,28 @@ effect, it causes the temporary transformations to become 
permanent.
 @vindex DISPLAY
 
 @display
-DISPLAY @{NAMES,INDEX,LABELS,VARIABLES,DICTIONARY,address@hidden
-        [SORTED] [var_list]
+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.
+DISPLAY DOCUMENTS.
+DISPLAY FILE LABEL.
 @end display
 
address@hidden displays requested information on variables.  Variables can
-optionally be sorted alphabetically.  The entire dictionary or just
-specified variables can be described.
address@hidden displays information about the active file.  A variety
+of different forms of information can be requested.
 
-One of the following keywords can be present:
+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
@@ -91,23 +151,29 @@ Variable names, positions, print and write formats, 
missing values,
 variable labels, and value labels are displayed.
 
 @item SCRATCH
-Varible names are displayed, for scratch variables only (@pxref{Scratch
+Variable names are displayed, for scratch variables only (@pxref{Scratch
 Variables}).
address@hidden table
 
-If SORTED is specified, then the variables are displayed in ascending
-order based on their names; otherwise, they are displayed in the order
-that they occur in the active file dictionary.
address@hidden ATTRIBUTES
+Datafile and variable attributes are displayed, except that attributes
+whose names begin with @code{@@} are omitted.
 
address@hidden DISPLAY VECTORS
address@hidden DISPLAY VECTORS
address@hidden DISPLAY VECTORS
address@hidden @@ATTRIBUTES
+All datafile and variable attributes are displayed.
address@hidden table
 
address@hidden
-DISPLAY VECTORS.
address@hidden display
+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.
+
+With the @code{DOCUMENTS} keyword, @cmd{DISPLAY} shows all the
+documents that have been added to the active file (using the
address@hidden or @cmd{ADD DOCUMENT} commands).
 
address@hidden VECTORS} lists all the currently declared vectors.
+With @code{FILE LABEL}, @cmd{DISPLAY} shows the label that has been
+assigned to the active file (using the @cmd{FILE LABEL} command), if
+any.
 
 @node FORMATS
 @section FORMATS
@@ -357,6 +423,60 @@ implicitly derived from the specified output formats.
 Created variables are initialized to spaces.
 
 
address@hidden VARIABLE ATTRIBUTE
address@hidden VARIABLE ATTRIBUTE
address@hidden VARIABLE ATTRIBUTE
+
address@hidden
+VARIABLE ATTRIBUTE
+         VARIABLES=var_list
+         ATTRIBUTE=name('value') [name('value')address@hidden
+         address@hidden@b{]}('value') 
address@hidden@b{]}('value')address@hidden
+         DELETE=name address@hidden
+         address@hidden@b{]} address@hidden@address@hidden
address@hidden display
+
address@hidden 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
address@hidden are reserved for PSPP's internal use, and attribute names
+that begin with @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} instead.
+
address@hidden ATTRIBUTE} takes effect immediately.  It is not affected
+by conditional and looping structures such as @cmd{DO IF} or
address@hidden
+
 @node VARIABLE LABELS
 @section VARIABLE LABELS
 @vindex VARIABLE LABELS

-- 
Ben Pfaff 
http://benpfaff.org