Merge pull request #622 from nexusformat/choice_element_619

add choice element to NXDL Schema
nexusformat · May 14, 2018 · 693599a · 693599a
2 parents 9b1e2d7 + ebf42b8
commit 693599a
Show file tree

Hide file tree

Showing 4 changed files with 120 additions and 6 deletions.
diff --git a/manual/source/defs_intro.rst b/manual/source/defs_intro.rst
@@ -6,11 +6,23 @@ Introduction to NeXus definitions
 ..
 	.. image:: img/NeXus.png
 
-While the design principles of NeXus are explained in the :ref:`UserManual`, this Reference Documentation specifies all allowed :ref:`base classes <base.class.definitions>` and all standardized :ref:`application definitions <application.definitions>`. Furthermore, it also contains :ref:`contributed definitions <contributed.definitions>` of new bases classes or application definitions that are currently under review.
+While the design principles of NeXus are explained in the 
+:ref:`UserManual`, this Reference Documentation specifies 
+all allowed :ref:`base classes <base.class.definitions>` 
+and all standardized :ref:`application definitions <application.definitions>`. 
+Furthermore, it also contains 
+:ref:`contributed definitions <contributed.definitions>` 
+of new bases classes or application definitions that 
+are currently under review.
 
-Base class definitions and application definitions have basically the same structure, but different semantics: Base class definitions define the *complete* set of 
-terms that *might* be used in an instance of that class.  Application definitions 
-define the *minimum* set of terms that *must* be used in an instance of that class.  
+Base class definitions and application definitions have basically 
+the same structure, but different semantics: 
+
+* Base class definitions define the *complete* set of 
+  terms that *might* be used in an instance of that class.  
+
+* Application definitions 
+  define the *minimum* set of terms that *must* be used in an instance of that class.  
 
 Base classes and application definitions are specified using a domain-specific XML scheme, the :ref:`NXDL`.
 
@@ -168,3 +180,49 @@ attribute         [#minOccurs]_   1
     for NXDL *application definitions* and  *contributed definitions*, ``minOccurs=1`` is the default.
     In all cases, the ``minOccurs`` attribute in the NXDL file will override the default
     for that element (group, field, attribute, or link).
+
+.. index:: !choice
+
+Choice
+======
+
+The ``choice`` element allows one to create a group with a defined name 
+that is one specific NXDL base class from a defined list of possibilities
+
+In some cases when creating an application definition, more than one 
+choice of base class might be used to define a particular subgroup.  
+For this particular situation, the ``choice`` was added to the NeXus 
+NXDL Schema. 
+
+In this example fragment of an NXDL application definition, 
+the ``pixel_shape`` could be represented by *either* 
+``NXoff_geometry`` or ``NXcylindrical_geometry``.
+
+
+.. code-block:: xml
+    :linenos:
+
+	<choice name="pixel_shape">
+	  <group type="NXoff_geometry">
+	    <doc>
+	      Shape description of each pixel. Use only if all pixels in the detector
+	      are of uniform shape.
+	    </doc>
+	  </group>
+	  <group type="NXcylindrical_geometry">
+	    <doc>
+	      Shape description of each pixel. Use only if all pixels in the detector
+	      are of uniform shape and require being described by cylinders.
+	    </doc>
+	  </group>
+	</choice>
+
+
+The ``@name`` attribute of the ``choice`` element specifies the name that
+will appear in the HDF5 data file using one of the groups listed within the choice.
+Thus, it is not necessary to specify the name in each group.  (At some point, 
+the NXDL Schema may be modified to enforce this rule.)
+
+A ``choice`` element may be used wherever a ``group`` element
+is used.  It **must** have at least two groups listed (otherwise, it would
+not be useful).
diff --git a/manual/source/introduction.rst b/manual/source/introduction.rst
@@ -195,7 +195,10 @@ Important Classes
 -----------------
 
 Here are some of the important classes found in nearly all NeXus files. A
-complete list can be found in the :ref:`Design` chapter.
+complete list can be found in the :ref:`Design-NeXusClasses` chapter.
+A complete list of *all* NeXus classes may be found in
+the :ref:`all.class.definitions` chapter.
+
 
 .. note:: ``NXentry``
           is the only class required in a valid NeXus data file.

diff --git a/nxdl.xsd b/nxdl.xsd
@@ -367,6 +367,41 @@
 
 	<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
+	<xs:complexType name="choiceType">
+		<xs:annotation>
+			<xs:documentation>
+				A ``choice`` element is used when a named group might take one
+				of several possible NeXus base classes.  Logically, it must
+				have at least two group children.
+			</xs:documentation>
+		</xs:annotation>
+		<xs:sequence>
+		  <xs:element name="group" type="nx:groupType" minOccurs="2" maxOccurs="unbounded">
+		  	<xs:annotation>
+		  		<xs:documentation>
+		  			NeXus base class that could be used here.
+		  			The group will take the ``@name`` attribute 
+		  			defined by the parent ``choice`` element
+		  			so do not specify the ``@name`` attribute of
+		  			the group here.
+		  		</xs:documentation>
+		  		<!-- TODO: How to enforce the name rule in the schema? -->
+		  	</xs:annotation>
+		  </xs:element>
+		</xs:sequence>
+		<xs:attribute name="name" use="required" type="nx:validItemName">
+			<xs:annotation>
+				<xs:documentation>
+					The name to be applied to the selected child group.  
+					None of the child groups should define a 
+					``@name`` attribute.
+				</xs:documentation>
+			</xs:annotation>
+		</xs:attribute>
+	</xs:complexType>
+
+	<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
 	<xs:complexType name="groupType">
 		<xs:annotation>
 			<xs:documentation>
@@ -474,6 +509,14 @@
 					</xs:documentation>
 				</xs:annotation>
 			</xs:element>
+			<xs:element name="choice" type="nx:choiceType" minOccurs="0" maxOccurs="unbounded">
+				<xs:annotation>
+					<xs:documentation>
+						Use a ``choice`` if a named group could be either
+						of a defined list of base classes.
+					</xs:documentation>
+				</xs:annotation>
+			</xs:element>
 			<xs:element name="group" type="nx:groupType" minOccurs="0" maxOccurs="unbounded">
 				<xs:annotation>
 					<xs:documentation>

diff --git a/utils/nxdl_desc2rst.py b/utils/nxdl_desc2rst.py
@@ -84,6 +84,15 @@
 :ref:`NXDL.data.type.fieldType`
                 ''',
 
+                'choice': '''
+A ``choice`` element is used when a named group might take one
+of several possible NeXus base classes.  Logically, it must
+have at least two group children.
+
+For more details, see: 
+:ref:`NXDL.data.type.choiceType`
+                ''',
+
                 'group': '''
 A ``group`` element can *only* be a child of a 
 ``definition`` or ``group`` element.
@@ -323,7 +332,7 @@ def applyTemplates(ns, parent, path, indentLevel, handler=generalHandler):
     for node in parent.xpath(path, namespaces=ns):
         name = node.get('name') or node.get('ref') or node.get('value')
         if name is not None:
-            if name in ('nx:groupGroup'):
+            if name in ('nx:groupGroup',):
                 print(">"*45, name)
             if name in db:
                 raise "Duplicate name found: " + name
@@ -438,6 +447,7 @@ def main(tree, ns):
                  "/xs:schema/xs:complexType[@name='docType']",
                  "/xs:schema/xs:complexType[@name='enumerationType']",
                  "/xs:schema/xs:complexType[@name='fieldType']",
+                 "/xs:schema/xs:complexType[@name='choiceType']",
                  "/xs:schema/xs:complexType[@name='groupType']",
                  "/xs:schema/xs:complexType[@name='linkType']",
                  "/xs:schema/xs:complexType[@name='symbolsType']",