[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: sav files with attributes
From: |
Ben Pfaff |
Subject: |
Re: sav files with attributes |
Date: |
Thu, 04 Sep 2008 22:42:06 -0700 |
User-agent: |
Gnus/5.11 (Gnus v5.11) Emacs/22.2 (gnu/linux) |
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