From 430e4c00697a3cda75a028b4b2886fc3cbab27c5 Mon Sep 17 00:00:00 2001
From: Andreas Neiser <neiser@kph.uni-mainz.de>
Date: Mon, 1 Jul 2013 23:43:14 +0200
Subject: [PATCH] Nested grouping in TrbNetSetup should be allowed, and dumping
 option added

---
 xml-db/database/TrbNetCommon.xsd | 77 +++++++++++++++++++++++---------
 xml-db/database/TrbNetEntity.xsd | 38 ----------------
 xml-db/database/TrbNetSetup.xsd  | 14 +++---
 xml-db/xml-db.pl                 | 34 +++++++++-----
 4 files changed, 87 insertions(+), 76 deletions(-)

diff --git a/xml-db/database/TrbNetCommon.xsd b/xml-db/database/TrbNetCommon.xsd
index 62c9b5f..b84458c 100644
--- a/xml-db/database/TrbNetCommon.xsd
+++ b/xml-db/database/TrbNetCommon.xsd
@@ -121,21 +121,52 @@
   </xs:element>
 
 
-  <xs:complexType name="grouptype">
-    <xs:attribute ref="name" use="required" />
-    <xs:attribute ref="address" />
-    <xs:attribute ref="size" />
-    <xs:attribute ref="purpose" />
-    <xs:attribute ref="continuous" />
-    <xs:attribute ref="mode" />
-    <xs:attribute ref="format" />
-    <xs:attribute ref="repeat" />
-  </xs:complexType>
+  <xs:element name="group">
+    <xs:complexType>
+      <xs:sequence>
+        <!-- a group does not necessarily need a description -->
+        <xs:choice minOccurs="0">
+          <xs:element   ref="description"/>
+        </xs:choice>
+        <xs:choice maxOccurs="unbounded">
+          <xs:element   ref="group"       maxOccurs="unbounded" />
+          <xs:element   ref="register"    maxOccurs="unbounded" />
+          <xs:element   ref="memory"      maxOccurs="unbounded" />
+          <xs:element   ref="fifo"        maxOccurs="unbounded" />
+        </xs:choice>
+      </xs:sequence>
+
+      <xs:attribute ref="name" use="required" />
+      <xs:attribute ref="address" />
+      <!-- size of the containing elements (more groups or
+           trbdatatypes), specified in 32bit long words
+      -->
+      <xs:attribute ref="size" />
+      <xs:attribute ref="purpose" />
+      <xs:attribute ref="continuous" />
+      <xs:attribute ref="mode" />
+      <xs:attribute ref="format" />
+      <xs:attribute ref="repeat" />
+
+    </xs:complexType>
 
-  <!-- we define this as mixed to provide values to be written (or
-       extracted from it). It will be converted to hex (or binary)
-       according to format attribute -->
-  <xs:complexType name="fieldtype" mixed="true">
+    <!-- consistency of addresses (and start, size of fields) is
+         checked more precisely programmatically -->
+    <xs:unique name="UniqueTrbDataAddressesInGroup">
+      <xs:selector xpath="register | memory | fifo" />
+      <xs:field xpath="@address" />
+    </xs:unique>
+  </xs:element>
+
+
+
+
+  <xs:element name="field">
+    
+  <!-- we define this as mixed to provide values to be written to the
+       TrbNet (or to store data extracted from TrbNet). It will be
+       converted to hex (or "binary") according to format attribute -->
+  <xs:complexType mixed="true">
     <xs:sequence>
       <!-- description can be omitted if a register or alike only contains
            one or several identical fields and the description of them can
@@ -152,7 +183,11 @@
     </xs:sequence>
 
     <xs:attribute ref="name" use="required" />
-    <!-- start is defined in TrbNetEntity as required -->
+    <!-- "start" (and "address" in basicTrbdata) should usually be
+         provided in the database, but this is verified only
+         programmatically. If it was required here, setup files
+         would become more complicated as they need to be... -->
+    <xs:attribute ref="start" />
     <xs:attribute ref="size" />
     <xs:attribute ref="purpose" />
     <xs:attribute ref="mode" />
@@ -167,10 +202,7 @@
     <!-- if PERL evaluates this field to true,
          an error is indicated by this field -->
     <xs:attribute ref="errorflag" />
-  </xs:complexType>
-
-
-  <xs:element name="field" type="fieldtype">
+      </xs:complexType>
     <xs:unique name="UniqueEnumItems">
       <xs:selector xpath="enumItem" />
       <xs:field xpath="@value" />
@@ -178,9 +210,12 @@
   </xs:element>
 
   <xs:complexType name="basicTrbData">
-
     <xs:attribute ref="name" use="required" />
-    <!-- start is defined in TrbNetEntity as required attribute -->
+    <!-- "address" (and "start" in fieldtype) should usually be provided in
+         the database, but this is verified only programmatically. If
+         it was required here, setup files would become more
+         complicated as they need to be... -->
+    <xs:attribute ref="address" />
     <xs:attribute ref="mode" />
     <xs:attribute ref="purpose" />
   </xs:complexType>
diff --git a/xml-db/database/TrbNetEntity.xsd b/xml-db/database/TrbNetEntity.xsd
index 0162560..3e41c8f 100644
--- a/xml-db/database/TrbNetEntity.xsd
+++ b/xml-db/database/TrbNetEntity.xsd
@@ -21,17 +21,6 @@
               <xs:element ref="field" />
             </xs:choice>
           </xs:sequence>
-          <xs:attribute ref="address" use="required"/>
-        </xs:extension>
-      </xs:complexContent>
-    </xs:complexType>
-  </xs:redefine>
-
-  <xs:redefine schemaLocation="TrbNetCommon.xsd">
-    <xs:complexType name="fieldtype">
-      <xs:complexContent>
-        <xs:extension base="fieldtype">
-          <xs:attribute ref="start" use="required"/>
         </xs:extension>
       </xs:complexContent>
     </xs:complexType>
@@ -82,32 +71,5 @@
   </xs:element>
 
 
-  <xs:element name="group">
-    <xs:complexType>
-      <xs:complexContent>
-        <xs:extension base="grouptype">
-          <xs:sequence>
-            <!-- a group does not necessarily need a description -->
-            <xs:choice minOccurs="0">
-              <xs:element   ref="description"/>
-            </xs:choice>
-            <xs:choice maxOccurs="unbounded">
-              <xs:element   ref="group"       maxOccurs="unbounded" />
-              <xs:element   ref="register"    maxOccurs="unbounded" />
-              <xs:element   ref="memory"      maxOccurs="unbounded" />
-              <xs:element   ref="fifo"        maxOccurs="unbounded" />
-            </xs:choice>
-          </xs:sequence>
-
-        </xs:extension>
-      </xs:complexContent>
-    </xs:complexType>
 
-    <!-- consistency of addresses (and start, size of fields) is
-         checked more precisely programmatically -->
-    <xs:unique name="UniqueTrbDataAddressesInGroup">
-      <xs:selector xpath="register | memory | fifo" />
-      <xs:field xpath="@address" />
-    </xs:unique>
-  </xs:element>
 </xs:schema>
diff --git a/xml-db/database/TrbNetSetup.xsd b/xml-db/database/TrbNetSetup.xsd
index 4a1cda3..b2503ee 100644
--- a/xml-db/database/TrbNetSetup.xsd
+++ b/xml-db/database/TrbNetSetup.xsd
@@ -6,7 +6,8 @@
     <xs:complexType>
       <xs:sequence>
         <!-- must contain either a uid map to setup the network
-             initially, or a trb directive -->
+             initially, or a trb directive. otherwise it's useless :)
+             -->
         <xs:choice>
           <xs:element   ref="uidMap"/>
           <xs:element   ref="trb"/>
@@ -34,15 +35,16 @@
 
   <xs:complexType name="trbitemtype">
     <!-- the entity may contain similar elements as the TrbNetEntity
-         element, but without a complex grouping mechanism. This is
-         why we defined some sparse elements in TrbNetCommon.xsd,
-         which are extended/redefined in TrbNetEntity.xsd -->
+         element. They usually modify the "default" structure in an
+         entity and are programmtically merged. Note that the pedantic
+         grouping structure as in the database is not required here.
+         This works because we require unique "name" attributes. -->
     <xs:choice minOccurs="0" maxOccurs="unbounded">
-      <xs:element name="group" type="grouptype" />
+      <xs:element ref="group" />
       <xs:element ref="register" />
       <xs:element ref="memory" />
       <xs:element ref="fifo" />
-      <xs:element name="field" type="fieldtype" />
+      <xs:element ref="field" />
     </xs:choice>
     <xs:attribute name="ref" type="nametype" use="required" />
     <xs:attribute name="address" type="addresstype" />
diff --git a/xml-db/xml-db.pl b/xml-db/xml-db.pl
index 631f986..8ccf036 100755
--- a/xml-db/xml-db.pl
+++ b/xml-db/xml-db.pl
@@ -20,6 +20,7 @@ my $help = 0;
 my $verbose = 0;
 my $warnings = 1;
 my $db_dir = "$RealBin/database";
+my $dump_database = 0;
 
 Getopt::Long::Configure(qw(gnu_getopt));
 GetOptions(
@@ -27,7 +28,8 @@ GetOptions(
            'man' => \$man,
            'verbose|v+' => \$verbose,
            'warnings|w!' => \$warnings,
-           'db-dir=s' => \$db_dir
+           'db-dir=s' => \$db_dir,
+           'dump' => \$dump_database
           ) or pod2usage(2);
 pod2usage(1) if $help;
 pod2usage(-exitval => 0, -verbose => 2) if $man;
@@ -41,15 +43,19 @@ if ($verbose) {
 
 # jump to subroutine which handles the job,
 # depending on the options
-&Main;
+
+if($dump_database) {
+  &DumpDatabase;
+}
+else {
+  &Main;
+}
 
 sub Main {
   # load the unmerged database and the provided files
-  my ($db,$files) = &LoadDBAndFiles;
+  my ($db,$files) = &LoadDBAndFiles(@ARGV);
+
 
-  DumpDatabase($db);
-  exit;
-  
   my $merged = {};
 
   foreach my $item (@$files) {
@@ -160,10 +166,14 @@ sub PrintMessage($$) {
 }
 
 sub DumpDatabase($) {
-  my $db = shift;
-  foreach my $file (keys %$db) {
-    print "Dumping $file...\n";
-    DumpDocument($db->{$file}->{'Doc'});
+  # we ignore all files on cmd line
+  my ($db, undef) = &LoadDBAndFiles;
+  my %entities = map { $_ => 1 } @ARGV;
+  my $num = scalar keys %entities;
+  foreach my $entity (keys %$db) {
+    next if $num>0 and not exists $entities{$entity};
+    print "Dumping Entity <$entity>:\n" if $num>1;
+    DumpDocument($db->{$entity}->{'Doc'});
   }
 }
 
@@ -242,7 +252,7 @@ sub LoadDBAndFiles {
   # now, back in the normal working directoy, load and
   # validate the provided files
   my $files = [];
-  for (@ARGV) {
+  for (@_) {
     my $doc = $parser->parse_file($_);
     ValidateXML($doc, $schemas);
     push(@$files, [$_, $doc]);
@@ -275,6 +285,7 @@ xml-db.pl - Manipulate the TrbNet descriptively using XML
 =head1 SYNOPSIS
 
 xml-db.pl [options] [xml file(s)]
+xml-db.pl --dump [entity names]
 
  Options:
    -h, --help     brief help message
@@ -284,6 +295,7 @@ xml-db.pl [options] [xml file(s)]
    -g, --generate generate config xml file (smart guessing from TrbNet)
    -s, --save     save all config fields from TrbNet in xml file
    -l, --restore  load config fields into TrbNet from xml file
+   --dump         dump the database as tree, restricted to given entity names
 
 =head1 OPTIONS
 
-- 
2.43.0