From cccb40bd7c26feb645de985bf14a2c0fbb8ad552 Mon Sep 17 00:00:00 2001 From: John Darrington Date: Fri, 18 Oct 2013 12:02:04 +0200 Subject: [PATCH 3/4] Documentation: Moved %size documentation out of Chapter 18 into Chapter 7 --- doc/recutils.texi | 135 ++++++++++++++++++++++++++++------------------------- 1 file changed, 72 insertions(+), 63 deletions(-) diff --git a/doc/recutils.texi b/doc/recutils.texi index 89de161..9681621 100644 --- a/doc/recutils.texi +++ b/doc/recutils.texi @@ -86,34 +86,34 @@ This manual documents version @value{VERSION} of the GNU recutils. @menu The Basics -* Introduction:: Introducing recutils. -* The Rec Format:: Writing recfiles. +* Introduction:: Introducing recutils. +* The Rec Format:: Writing recfiles. Using the Recutils -* Querying Recfiles:: Extracting data from recfiles. -* Editing Records:: Inserting and deleting records. -* Editing Fields:: Inserting, modifying and deleting fields. +* Querying Recfiles:: Extracting data from recfiles. +* Editing Records:: Inserting and deleting records. +* Editing Fields:: Inserting, modifying and deleting fields. Data Integrity -* Field Types:: Restrictions on the values of fields. -* Field Restrictions:: Requiring or forbidding specific fields. -* Checking Recfiles:: Making sure the data is ok. +* Field Types:: Restrictions on the values of fields. +* Constraints on Record Sets:: Requiring or forbidding specific fields. +* Checking Recfiles:: Making sure the data is ok. Advanced Topics -* Remote Descriptors:: Implementing distributed databases. -* Grouping and Aggregates:: Statistics. +* Remote Descriptors:: Implementing distributed databases. +* Grouping and Aggregates:: Statistics. * Queries which Join Records:: Crossing record of different types. -* Auto-Generated Fields:: Counters and time-stamps. -* Encryption:: Storing sensitive information. -* Generating Reports:: Formatted output with templates. -* Interoperability:: Importing and exporting to other formats. -* Bash Builtins:: Boosting the recutils in the shell. +* Auto-Generated Fields:: Counters and time-stamps. +* Encryption:: Storing sensitive information. +* Generating Reports:: Formatted output with templates. +* Interoperability:: Importing and exporting to other formats. +* Bash Builtins:: Boosting the recutils in the shell. Reference Material -* Invoking the Utilities:: Exhaustive list of command line arguments. -* Special Fields:: Syntax of all the supported special fields. -* Regular Expressions:: Flavor of regexps supported in recutils. -* Date input formats:: Specifying dates and times. +* Invoking the Utilities:: Exhaustive list of command line arguments. +* Special Fields:: Syntax of all the supported special fields. +* Regular Expressions:: Flavor of regexps supported in recutils. +* Date input formats:: Specifying dates and times. * GNU Free Documentation License:: Distribution terms for this document. @@ -171,11 +171,12 @@ Field Types * Date and Time Types:: Dates and times. * Other Field Types:: Emails, fields, UUIDs, @dots{} -Field Restrictions +Constraints on Record Sets * Mandatory Fields:: Requiring the presence of fields. * Prohibited Fields:: Forbidding the presence of fields. * Keys and Unique Fields:: Fields characterizing records. +* Size Constraints:: Limiting the size of a record set. * Arbitrary Constraints:: Constraints records must comply with. Checking Recfiles @@ -2789,8 +2790,8 @@ to be stored in fields of type @code{Maintainer_t} are of whatever type defined for the primary key of the @code{Hacker} record set. Why this is useful is discussed later. @xref{Queries which Join Records}. address@hidden Field Restrictions address@hidden Field Restrictions address@hidden Constraints on Record Sets address@hidden Constraints on Record Sets The records in a recfile are by default not restricted to any particular structure @@ -2809,6 +2810,7 @@ structure of the records. * Mandatory Fields:: Requiring the presence of fields. * Prohibited Fields:: Forbidding the presence of fields. * Keys and Unique Fields:: Fields characterizing records. +* Size Constraints:: Constraints on the number of records in a set. * Arbitrary Constraints:: Constraints records must comply with. @end menu @@ -3013,12 +3015,57 @@ Later, you will learn how primary keys can be used to link one record set to another using primary keys together with foreign keys. @xref{Queries which Join Records}. address@hidden Size Constraints address@hidden Size Constraints + address@hidden @code{%size} address@hidden size, record size address@hidden record size +Sometimes it is desireable to place constraints on entire records. +This can be done with the @code{%size} special field which is used to limit the +number of records in a record set. Its usage is: + address@hidden +%size: address@hidden @var{number} address@hidden example + address@hidden +If no operator is specified then @var{number} is interpreted as the +exact number of records of this type. The number can be any integer +literal, including hexadecimal and octal constants. For example: + address@hidden +%rec: Day +%size: 7 +%type: Name enum ++ Monday Tuesday Wednesday Thursday Friday ++ Saturday Sunday +%doc: There should be exactly 7 days. address@hidden example + address@hidden operators +The optional @var{relational_operator} shall be one of @code{<}, address@hidden<=}, @code{>} and @code{>address@hidden For example: + address@hidden +%rec: Item +%key: Id +%size: <= 100 +%doc: We have at most 100 different articles. address@hidden example + +It is valid to specify a size of @code{0}, meaning that no records of +this type shall exist in the file. + +Only one @code{%size} field shall appear in a record descriptor. + + @node Arbitrary Constraints @section Arbitrary Constraints @cindex @code{%constraint} @cindex restricting values of fields -Occasionally @code{%mandatory} and @code{%prohibit} are just not flexible enough. +Occasionally @code{%mandatory}, @code{%prohibit} and @code{%size} are just not flexible enough. We might, for instance, want to ensure that @emph{if} a field is present, then it must have a certain relationship to other fields. Or we might want to stipulate that only under certain conditions, a record contains @@ -3131,7 +3178,7 @@ default operation. However @command{recfix} checks more than the syntactical integrity of the recfile. If also checks certain semantics and that the data is self consistent. To do this, it uses the special fields of the record, some of which were introduced -in above (@pxref{Field Restrictions}). +in above (@pxref{Constraints on Record Sets}). It is a good idea to use the special fields to stipulate the ``enterprise rules'' of the data. @@ -5400,45 +5447,7 @@ XXX @node %size @section %size address@hidden @code{%size} address@hidden size, record size address@hidden record size -The @code{%size} special field is used to define constraints in the -number of records stored in a record set. Its usage is: - address@hidden -%size: address@hidden @var{number} address@hidden example - address@hidden -If no operator is specified then @var{number} is interpreted as the -exact number of records of this type. The number can be any integer -literal, including hexadecimal and octal constants. For example: - address@hidden -%rec: Day -%size: 7 -%type: Name enum -+ Monday Tuesday Wednesday Thursday Friday -+ Saturday Sunday -%doc: There should be exactly 7 days. address@hidden example - address@hidden operators -The optional @var{relational_operator} shall be one of @code{<}, address@hidden<=}, @code{>} and @code{>address@hidden For example: - address@hidden -%rec: Item -%key: Id -%size: <= 100 -%doc: We have at most 100 different articles. address@hidden example - -It is valid to specify a size of @code{0}, meaning that no records of -this type shall exist in the file. - -This field shall appear only once in a record descriptor. +XXX @node %constraint @section %constraint -- 1.7.10.4