Re: sav files with attributes

[John Darrington]

On Thu, Sep 04, 2008 at 10:42:06PM -0700, Ben Pfaff wrote:
     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.)

I guess that means that the GUI will be expected to display them too :-\
     
     Here is the diff.  Feedback welcome.

Looks fine to me except that I think the section entitled
"DATAFILE ATTRIBUTE" belongs in chapter 6 instead of chapter 8.
     
     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
     
     
     _______________________________________________
     pspp-dev mailing list
     address@hidden
     http://lists.gnu.org/mailman/listinfo/pspp-dev

-- 
PGP Public key ID: 1024D/2DE827B3 
fingerprint = 8797 A26D 0854 2EAB 0285  A290 8A67 719C 2DE8 27B3
See http://pgp.mit.edu or any PGP keyserver for public key.

signature.asc
Description: Digital signature