Union: Difference between revisions
No edit summary |
No edit summary |
||
| (3 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
The FACE 3 Technical Standard introduced the ability to document union templates – in PHENOM, these are represented by union [[View|Views]]. | |||
== Union Creation == | |||
Unions cannot be created independently, but rather existing View elements can be converted to be unions. On its [[Data Model Details|Details]] page, a toggle labeled 'Union' is used to change the view element between a union and non-union structure. | |||
Not all views can be changed to be a union type, and so the toggle may be disabled for some view elements in the model. Which views may be transformed into unions is governed by FACE standard rules. | |||
[[File:View_Page_Union_Toggle.png|800px|border|PHENOM views can be converted to unions via a toggle on the Details page.]] | |||
=== Non-Composite (Nesting) Views as Unions === | === Non-Composite (Nesting) Views as Unions === | ||
For a non-composite view to be converted to a union, three FACE structural requirements must be fulfilled. | For a non-composite view to be converted to a union, three FACE structural requirements must be fulfilled. | ||
First: a union cannot be a “top level” type, but must rather be defined as a sub-type, nested inside the definition of another structure. In a FACE model, this will appear as a template structure that is not housed in its own template node, but is rather defined as a sub-structure in the specification of another template node. In PHENOM, this is represented as a view that is referenced as the type of another view's field - this is what is referred to as "nested attribute". In this case, the field in question should also be marked as "Private", indicating that the nested view is defined in a scope internal to the view in which it is nested. | |||
[[File:Private Union Nesting.png|800px|border|The private nesting of a union view within a top level view.]] | |||
[[File:Union | |||
Second: to become a union, a view must have at least one [[View Attribute|attribute]] or field that references an [[Enumerations|enumeration]] as its platform type. In a FACE model, this enumerated field will be selected by the query related to the union template to serve as the discriminant over which the union is switched. In PHENOM, when a user toggles a view to be a union, a drop-down appears next to the switch allowing the selection of the discriminant. This drop-down lists all of the current view's enumeration attributes. | |||
[[File:View Switch Selection.png|800px|border|Selection of an enumeration-based view attribute as a union discriminant.]] | |||
Third: to be eligible for conversion to a union, all of the projections in the view must project the same element. In a FACE model, this is the same rule that applies to all non-composite templates. In PHENOM, this requirement can be satisfied by ensuring that the first element of each attribute's projection path is the same for the selected view. | |||
[[File:Union Projection Uniformity.png|800px|The projected characteristic uniformity among view attributes required of union types.]] | |||
If the union toggle on a given view's page is disabled, it is likely because one of the above requirements is not fulfilled. | |||
=== Assigning Case Literals to Union Fields === | |||
Once the discriminant of a view has been selected, the attributes of the view can be assigned to the different union cases. Each case is represented by at least one of the literals associated with the discriminant attribute's platform type enumeration. While more than one of the literals can indicate a single case, a given literal can only be associated with at most one case. Only one attribute is allowed to occupy any given case. The view attribute acting as the union's discriminant can also occupy one of the cases. | |||
By expanding a view attribute, a drop-down listing the discriminant enumeration's literals can be used to add literals to that attribute's case. Once selected, the literals of a given attribute's case are shown above the attribute rolename. | |||
[[File:Union Case Selection.png|800px|border|The drop-down listing the discriminant field's enumeration type's literals can be used to select case literals applied to a given field's case. Once selected, they will appear above the relevant field's rolename.]] | |||
=== Composite Views as Unions === | === Composite Views as Unions === | ||
Composite FACE templates can also be indicated as unions. Mirroring that, in | Composite FACE templates can also be indicated as unions. Mirroring that, in PHENOM, composite views can also be switched to be unions. | ||
Composite unions don't require any additional specifications, such as the indication of an enumeration-based discriminant. Instead, each composition is considered a member of a single case labeled with an integer value corresponding to the compositions index in the composite. | Composite unions don't require any additional specifications, such as the indication of an enumeration-based discriminant. Instead, each composition is considered a member of a single case labeled with an integer value corresponding to the compositions index in the composite. | ||
== Union View Export to FACE 3 Queries and Templates == | == Union View Export to FACE 3 Queries and Templates == | ||
Upon exporting a model to the FACE 3 format, PHENOM automatically converts any union views to their appropriate FACE query and template representations. | |||
Upon exporting a model to the FACE 3 format, | |||
The template representing any union view is prefixed with the `union` FACE keyword. The discriminant field selected for the view is used as the parameter of the union's switch statement. The view attributes' case literal assignments are converted to case groups in the union template. The union template as a whole is related to a query that reflects the semantics indicated in the view attributes' | The template representing any union view is prefixed with the `union` FACE keyword. The discriminant field selected for the view is used as the parameter of the union's switch statement. The view attributes' case literal assignments are converted to case groups in the union template. The union template as a whole is related to a query that reflects the semantics indicated in the view attributes' PHENOM path. | ||
The query and template generated for a given view can be previewed on the view's Details page by expanding the 'Query and Template Preview' section under the attributes listing. | The query and template generated for a given view can be previewed on the view's Details page by expanding the 'Query and Template Preview' section under the attributes listing. | ||
[[File:Union Query Template Preview.png|800px|border|A view of PHENOM's query and template preview for a union view.]] | |||
== Union Structure Code Representation == | == Union Structure Code Representation == | ||
Latest revision as of 10:30, 7 February 2024
The FACE 3 Technical Standard introduced the ability to document union templates – in PHENOM, these are represented by union Views.
Union Creation
Unions cannot be created independently, but rather existing View elements can be converted to be unions. On its Details page, a toggle labeled 'Union' is used to change the view element between a union and non-union structure.
Not all views can be changed to be a union type, and so the toggle may be disabled for some view elements in the model. Which views may be transformed into unions is governed by FACE standard rules.
Non-Composite (Nesting) Views as Unions
For a non-composite view to be converted to a union, three FACE structural requirements must be fulfilled.
First: a union cannot be a “top level” type, but must rather be defined as a sub-type, nested inside the definition of another structure. In a FACE model, this will appear as a template structure that is not housed in its own template node, but is rather defined as a sub-structure in the specification of another template node. In PHENOM, this is represented as a view that is referenced as the type of another view's field - this is what is referred to as "nested attribute". In this case, the field in question should also be marked as "Private", indicating that the nested view is defined in a scope internal to the view in which it is nested.
Second: to become a union, a view must have at least one attribute or field that references an enumeration as its platform type. In a FACE model, this enumerated field will be selected by the query related to the union template to serve as the discriminant over which the union is switched. In PHENOM, when a user toggles a view to be a union, a drop-down appears next to the switch allowing the selection of the discriminant. This drop-down lists all of the current view's enumeration attributes.
Third: to be eligible for conversion to a union, all of the projections in the view must project the same element. In a FACE model, this is the same rule that applies to all non-composite templates. In PHENOM, this requirement can be satisfied by ensuring that the first element of each attribute's projection path is the same for the selected view.
If the union toggle on a given view's page is disabled, it is likely because one of the above requirements is not fulfilled.
Assigning Case Literals to Union Fields
Once the discriminant of a view has been selected, the attributes of the view can be assigned to the different union cases. Each case is represented by at least one of the literals associated with the discriminant attribute's platform type enumeration. While more than one of the literals can indicate a single case, a given literal can only be associated with at most one case. Only one attribute is allowed to occupy any given case. The view attribute acting as the union's discriminant can also occupy one of the cases.
By expanding a view attribute, a drop-down listing the discriminant enumeration's literals can be used to add literals to that attribute's case. Once selected, the literals of a given attribute's case are shown above the attribute rolename.
Composite Views as Unions
Composite FACE templates can also be indicated as unions. Mirroring that, in PHENOM, composite views can also be switched to be unions.
Composite unions don't require any additional specifications, such as the indication of an enumeration-based discriminant. Instead, each composition is considered a member of a single case labeled with an integer value corresponding to the compositions index in the composite.
Union View Export to FACE 3 Queries and Templates
Upon exporting a model to the FACE 3 format, PHENOM automatically converts any union views to their appropriate FACE query and template representations.
The template representing any union view is prefixed with the `union` FACE keyword. The discriminant field selected for the view is used as the parameter of the union's switch statement. The view attributes' case literal assignments are converted to case groups in the union template. The union template as a whole is related to a query that reflects the semantics indicated in the view attributes' PHENOM path.
The query and template generated for a given view can be previewed on the view's Details page by expanding the 'Query and Template Preview' section under the attributes listing.
Union Structure Code Representation
Though interpreted as unions in IDL, the FACE standard dictates C struct and C++/Java class representations of these structures.
Please refer to the FACE Technical Standard documents for details on implementing union type structures in code.