1 // Copyright (C) 2007-2020 CEA/DEN, EDF R&D, OPEN CASCADE
3 // Copyright (C) 2003-2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN,
4 // CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS
6 // This library is free software; you can redistribute it and/or
7 // modify it under the terms of the GNU Lesser General Public
8 // License as published by the Free Software Foundation; either
9 // version 2.1 of the License, or (at your option) any later version.
11 // This library is distributed in the hope that it will be useful,
12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 // Lesser General Public License for more details.
16 // You should have received a copy of the GNU Lesser General Public
17 // License along with this library; if not, write to the Free Software
18 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20 // See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
23 #include "DDS_Dictionary.h"
25 #include "DDS_KeyWords.h"
27 #include <LDOMString.hxx>
28 #include <LDOMParser.hxx>
30 #include <UnitsAPI.hxx>
32 #include <TColStd_SequenceOfInteger.hxx>
33 #include <TColStd_SequenceOfAsciiString.hxx>
34 #include <TColStd_SequenceOfExtendedString.hxx>
36 #include <NCollection_Map.hxx>
38 #include <Standard_Failure.hxx>
39 #include <Standard_ErrorHandler.hxx>
41 IMPLEMENT_STANDARD_RTTIEXT(DDS_Dictionary, Standard_Transient)
43 Handle(DDS_Dictionary) DDS_Dictionary::myDictionary = Handle(DDS_Dictionary)();
47 \brief This class provides an information about used datums,
48 reading them from XML file.
50 There is the only instance of the class DDS_Dictionary in the application
51 which can be retrieved by method Get().
53 Datum is a set of parameters describing a phisical characteristic.
54 These parameters are loaded from the XML file which has the following format:
58 <COMPONENT COMPONENT_NAME="component_name">
60 <UNIT_SYSTEM UNIT_SYSTEM_NAME="[system_internal_name]" UNIT_SYSTEM_LABEL="[system_label]">
61 <UNIT_SYSTEM UNIT_SYSTEM_NAME="[system_internal_name]" UNIT_SYSTEM_LABEL="[system_label]">
63 <UNIT_SYSTEM UNIT_SYSTEM_NAME="[system_internal_name]" UNIT_SYSTEM_LABEL="[system_label]">
66 <DATUM DATUM_UNITS="[base_system_internal_name]" DATUM_FORMAT="[sprintf_format_specification]"
67 DATUM_ID="[datum_id]" DATUM_LABEL="[datum_label]" DATUM_REQUIRED="[requred_value]"
68 DATUM_FILTER="[string_regular_expression]">
70 <VALUE_DESCR VD_DEFV="[default_value]" VD_MAXV="[max_value]" VD_MINV="[min_value]" VD_TYPE="[value_type]"/>
71 <VALUE_LIST_REF VLR_LIST="[referenced_list_id]"/>
74 <SHORT_D>[brief_desription_text]</SHORT_D>
75 <LONG_D>[full_description_text]</LONG_D>
78 <OPTION OPTION_NAME="[option_name_1]">[option_value_1]</OPTION>
79 <OPTION OPTION_NAME="[option_name_2]">[option_value_2]</OPTION>
81 <OPTION OPTION_NAME="[option_name_n]">[option_value_n]</OPTION>
87 <VALUE_LIST VALUE_LIST_ID="[list_id]" VALUE_LIST_NAME="[list_name]">
88 <VALUE_LIST_VALUE VALUE_LIST_VALUEID="[list_element_id]" VALUE_LIST_VALUEICON="[list_element_icon_file]">[list_element_name]</VALUE_LIST_VALUE>
89 <VALUE_LIST_VALUE VALUE_LIST_VALUEID="[list_element_id]" VALUE_LIST_VALUEICON="[list_element_icon_file]">[list_element_name]</VALUE_LIST_VALUE>
91 <VALUE_LIST_VALUE VALUE_LIST_VALUEID="[list_element_id]" VALUE_LIST_VALUEICON="[list_element_icon_file]">[list_element_name]</VALUE_LIST_VALUE>
101 In above description of the datum XML file format internal keys are used as XML tags
102 and attributes names. Real XML keywords are defined by DDS_KeyWords class.
104 XML file should have one main tag named "dictionary" (key "D_URI"). This tag
105 should contain one or several components.
106 Component is an independent set of datums and units systems.
107 Components are defined by XML tag named "component" (key "COMPONENT") with
108 attribute "name" (key COMPONENT_NAME).
109 Component name is used as component identifier and should be unique.
111 Component tag can contain:
113 - Tag "unit_systems" (key UNIT_SYSTEMS) defines a set of used units systems.
114 At least one unit system named SI ("System International") should exist.
115 If this system does not exist, it will be created automatically.
116 Each units system is defined by XML tag "unit system" (key UNIT_SYSTEM) under
117 the tag "unit_systems" with attributes "name" (key UNIT_SYSTEM_NAME)
118 and "label" (key UNIT_SYSTEM_LABEL). Name is an identifier of the units system and
119 label is its human readable description.
121 - One or several tags "datum" (key DATUM). For this tag the following attributes
123 -# Identifier (key DATUM_ID) specifies the unique id string for the datum.
124 -# Label (key DATUM_LABEL) specifies human readable name of the datum.
125 -# Measure units (key DATUM_UNITS) for the given units system. Attribute name
126 defines a name of units system and a keyword got from DDS_KeyWords by key DATUM_UNITS.
127 For example, for "SI" units system and default keyword the attribute name is "SIunits".
128 This attribute should be specified for each declared units system.
129 Value of this attribute should be a string describing measure units.
130 For possible designations for measure units and their multiple prefixes
131 please refer to the UnitsAPI package of the OpenCascade library
132 (files Units.dat and Lexi_Expr.dat). Measure units are used for numerical
133 values conversion from one units system to another one.
134 -# Format (key DATUM_FORMAT) specifies the format string which will be used
135 during initial formatting of the value. This string should be specified
137 -# Filter (key DATUM_FILTER) specifies the regualr expression. The value (string)
138 entered by the user will be checked up to match to this regular expression
139 (if it defined). Non matched strings will be rejected.
140 -# Required value (key DATUM_REQUIRED). If this attributed si defined and its value
141 is \c true then user can't leave an input non-filled - parameter must be explicitly
142 entered by the user).
144 - One or several tags "list definition" (key VALUE_LIST). Each such tag defines
145 the list of items for enumerable data. Attribute "list id" (key VALUE_LIST_ID)
146 specifies the identifier string for the list and attribute "list name"
147 (key VALUE_LIST_NAME) defines a list name string. Each list item is described
148 by tag "list value" (key VALUE_LIST_VALUE) under the tag "list definition".
149 Each this tag contains item string text and have the following attributes:
150 -# "list item id" (key VALUE_LIST_VALUEID) - integer numerical identifier for
152 -# "list item icon" (key VALUE_LIST_VALUEICON) - icon file name for the item
154 Tag "datum" can have child subtags "description" and "options".
156 - Tag "description" (key DESCR) contains two sub tags:
157 -# "short description" (key SHORT_D) specifies a brief datum description text
158 -# "long description" (key LONG_D) specifies a detailed description text
160 - Tag "options" (key OPTIONS) contains one or more sub tags "option" (key OPTION).
161 Each of these XML elements should contain text option value and attribute
162 "name" (key OPTION_NAME) which specifies option name.
164 Each tag "datum" defines most common parameters of phisical characteristic.
165 These parameters are placed in two groups:
166 -# Domain parameters under the tag "domain" (key DY_DOMAIN). This tag can
167 contain value description tag (key VALUE_DESCR) for descrete data which is
168 described by following parameters:
169 - default value (key VD_DEFV)
170 - maximum value (key VD_MAXV)
171 - minimum value (key VD_MINV)
172 - type of value (key VD_TYPE), possible values are String, Integer, Float, List
173 -# list reference tag (key VALUE_LIST_REF) for enumerable data described by
174 "list reference" attribute (key VLR_LIST) which references to the list
175 (see "list definition" tag) by list id.
177 Below is an example of the XML file using default keywords.
180 <datadictionary version="1.0">
181 <component name="My Component">
183 <!-- specify two unit systems -->
186 <system name="SI" label="System international">
187 <system name="AS" label="Anglo - sacson system">
190 <!-- specify datum -->
191 <!-- units of measure for SI - meters (m), for AS - inches (in) -->
192 <datum SIunits="m" ASunits="in" format="%.25f" id="X" label="X coordinate" required="">
194 <!-- default value not specified -->
195 <valueDescr default="" max="999999999.999" min="0.000" type="Float"/>
198 <shortDescr>X coordinate for object</shortDescr>
199 <longDescr>X multiplier of object coordinates. Describe position of object in direction of X axis</longDescr>
203 <datum SIunits="m" ASunits="in" format="%.25f" id="Y" label="Y coordinate" required="">
205 <valueDescr default="" max="999999999.999" min="0.000" type="Float"/>
208 <shortDescr>Y coordinate for object</shortDescr>
209 <longDescr>Y multiplier of object coordinates. Describe position of object in direction of Y axis</longDescr>
213 <!-- datum for object name with filter which not allow to input more that 8 letters,
214 numbers or unerscores with first letter only -->
215 <datum format="%.8us" id="ObjectName" label="Name" required="yes"
216 filter="^([A-Z]+)([A-Z,0-9,_]*)$">
218 <!-- limits and default not specified, type is string -->
219 <valueDescr default="" max="" min="" type="String" />
222 <!-- long description not specified -->
223 <shortDescr>Name of object</shortDescr>
228 <!-- datum for enumeration of side -->
229 <datum format="" id="Side" label="Side" required="">
231 <!-- default list item is item with id 0 -->
232 <valueDescr default="0" type="List"/>
233 <!-- list reference on list named "side_list" -->
234 <listRef list="side_list"/>
237 <shortDescr>Side of object</shortDescr>
241 <!-- list definition for enumeration of side -->
242 <valueList listid="side_list" name="Side">
243 <value id="1">left</value>
244 <value id="2">right</value>
245 <value id="3">top</value>
246 <value id="4">bottom</value>
247 <value id="0">undefined</value>
258 Create an instance of the dictionary. Can not be used directly.
259 Use Get() method instead.
261 DDS_Dictionary::DDS_Dictionary()
262 : Standard_Transient()
267 \brief Copy constructor (put in private section to prevent object copying).
269 DDS_Dictionary::DDS_Dictionary( const DDS_Dictionary& )
270 : Standard_Transient()
275 \brief Assignment operator (put in private section to prevent object copying).
277 void DDS_Dictionary::operator=( const DDS_Dictionary& )
282 \brief Get the names of defined units systems from all components.
283 \param theSystems returning sequence of units systems names.
285 void DDS_Dictionary::GetUnitSystems( TColStd_SequenceOfAsciiString& theSystems ) const
289 NCollection_Map<TCollection_AsciiString> aMap;
290 for ( Standard_Integer i = 1; i <= myGroupMap.Extent(); i++ )
292 TColStd_SequenceOfAsciiString theSeq;
293 myGroupMap.FindFromIndex( i )->GetUnitSystems( theSeq );
294 for ( Standard_Integer s = 1; s <= theSeq.Length(); s++ )
296 if ( aMap.Contains( theSeq.Value( s ) ) )
299 theSystems.Append( theSeq.Value( s ) );
300 aMap.Add( theSeq.Value( s ) );
307 \brief Get the names of defined units systems from the specified component
310 If component is not found, empty list is returned.
312 \param theSystems returning sequence of units systems names.
313 \param theComponent component name
315 void DDS_Dictionary::GetUnitSystems( TColStd_SequenceOfAsciiString& theSystems,
316 const TCollection_AsciiString& theComponent ) const
319 if ( myGroupMap.Contains( theComponent ) )
320 myGroupMap.FindFromKey( theComponent )->GetUnitSystems( theSystems );
324 \brief Get the label of the units system \a theSystem.
326 Searches the given units system in all components. If units system is not found
327 in any component, empty string is returned.
329 \param theSystem units system
330 \return units system label
332 TCollection_ExtendedString DDS_Dictionary::GetUnitSystemLabel( const TCollection_AsciiString& theSystem ) const
334 TCollection_ExtendedString aLabel;
335 for ( Standard_Integer i = 1; i <= myGroupMap.Extent() && !aLabel.Length(); i++ )
336 aLabel = myGroupMap.FindFromIndex( i )->GetUnitSystemLabel( theSystem );
341 \brief Get the label of the units system \a theSystem from the
342 component \a theComponent.
344 Searches the specified units system in the specified component only.
345 If units system is not found, empty string is returned.
347 \param theSystem units system
348 \param theComponent component name
349 \return units system label
351 TCollection_ExtendedString DDS_Dictionary::GetUnitSystemLabel( const TCollection_AsciiString& theSystem,
352 const TCollection_AsciiString& theComponent ) const
354 TCollection_ExtendedString aLabel;
355 if ( myGroupMap.Contains( theComponent ) )
356 aLabel = myGroupMap.FindFromKey( theComponent )->GetUnitSystemLabel( theSystem );
361 \brief Get the name of active units system from the first found component.
363 If at least one component exists, then its active units system name
364 is returned. Otherwise, empty string is returned.
366 \return active units system name
368 TCollection_AsciiString DDS_Dictionary::GetActiveUnitSystem() const
370 TCollection_AsciiString aSystem;
371 if ( myGroupMap.Extent() )
372 aSystem = myGroupMap.FindFromIndex( 1 )->GetActiveUnitSystem();
377 \brief Get the name of active units system from the component \a theComponent.
379 If this component exists, its active units system name is returned.
380 Otherwise, empty string is returned.
382 \param theComponent component name
383 \return active units system name
385 TCollection_AsciiString DDS_Dictionary::GetActiveUnitSystem( const TCollection_AsciiString& theComponent ) const
387 TCollection_AsciiString aSystem;
388 if ( myGroupMap.Contains( theComponent ) )
389 aSystem = myGroupMap.FindFromKey( theComponent )->GetActiveUnitSystem();
394 \brief Set the active units system.
396 This units system will be activated in each existing component,
397 if it component has this units system.
399 \param theSystem units system to be made active
401 void DDS_Dictionary::SetActiveUnitSystem( const TCollection_AsciiString& theSystem )
403 for ( Standard_Integer i = 1; i <= myGroupMap.Extent(); i++ )
404 myGroupMap.FindFromIndex( i )->SetActiveUnitSystem( theSystem );
408 \brief Set the active units system for the component \a theComponent.
410 If specified units system doesn't exist in the component, nothing happens.
412 \param theSystem units system to be made active
413 \param theComponent component name
415 void DDS_Dictionary::SetActiveUnitSystem( const TCollection_AsciiString& theSystem,
416 const TCollection_AsciiString& theComponent )
418 if ( myGroupMap.Contains( theComponent ) )
419 myGroupMap.FindFromKey( theComponent )->SetActiveUnitSystem( theSystem );
423 \brief Get the only instance of the data dictionary.
424 \return the only instance of the data dictionary
426 Handle(DDS_Dictionary) DDS_Dictionary::Get()
428 if ( myDictionary.IsNull() )
429 myDictionary = new DDS_Dictionary();
435 \brief Load datum definitions in the dictionary from the XML file
437 \param theFileName XML file name
438 \return \c true if loading is succeded or \c false otherwise.
440 Standard_Boolean DDS_Dictionary::Load( const TCollection_AsciiString theFileName )
442 static NCollection_Map<TCollection_AsciiString> _LoadMap;
444 if ( _LoadMap.Contains( theFileName ) )
445 return Standard_True;
447 Handle(DDS_Dictionary) aDic = Get();
449 return Standard_False;
452 if ( aParser.parse( theFileName.ToCString() ) )
453 return Standard_False;
455 LDOM_Document aDoc = aParser.getDocument();
456 LDOM_Element aDocElement = aDoc.getDocumentElement();
457 if ( !aDocElement.isNull() )
458 aDic->FillDataMap( aDocElement );
460 _LoadMap.Add( theFileName );
462 return Standard_True;
466 \brief Get XML keyword as LDOMString by specified \a key.
468 If key doesn't exist, empty string is returned.
469 This function is provided for convenience.
471 \param key keyword name
472 \return keyword value
474 LDOMString DDS_Dictionary::KeyWord( const TCollection_AsciiString& key )
477 Handle(DDS_KeyWords) aKeyWords = DDS_KeyWords::Get();
478 if ( !aKeyWords.IsNull() )
480 TCollection_AsciiString aStr = aKeyWords->GetKeyWord( key );
482 keyWord = LDOMString( aStr.ToCString() );
488 \brief Get the data dictionary item by specified identifier \a theID
489 from the component \a theComponent.
491 If the component or item is not found, null handle is returned.
492 \param theID data dictionary item ID
493 \param theComponent component name
494 \return handle to the data dictionary item
496 Handle(DDS_DicItem) DDS_Dictionary::GetDicItem( const TCollection_AsciiString& theID,
497 const TCollection_AsciiString& theComponent ) const
499 Handle(DDS_DicItem) aDicItem;
500 Handle(DDS_DicGroup) aDicGroup;
501 if ( myGroupMap.Contains( theComponent ) )
502 aDicGroup = myGroupMap.FindFromKey( theComponent );
503 if ( !aDicGroup.IsNull() )
504 aDicItem = aDicGroup->GetDicItem( theID );
509 \brief Get the data dictionary item by specified identifier \a theID.
511 Function searches the item in all components. If item is not found
512 in all components, null handle is returned.
514 \param theID data dictionary item ID
515 \return handle to the data dictionary item
517 Handle(DDS_DicItem) DDS_Dictionary::GetDicItem( const TCollection_AsciiString& theID ) const
519 Handle(DDS_DicItem) aDicItem;
520 for ( Standard_Integer i = 1; i <= myGroupMap.Extent() && aDicItem.IsNull(); i++ )
521 aDicItem = myGroupMap.FindFromIndex( i )->GetDicItem( theID );
526 \brief Fill the internal data structures from the XML node.
527 \param theDocElement document XML node
529 void DDS_Dictionary::FillDataMap( const LDOM_Element& theDocElement )
531 for ( LDOM_Element aComponentElem = theDocElement.GetChildByTagName( KeyWord( "COMPONENT" ) );
532 !aComponentElem.isNull(); aComponentElem = aComponentElem.GetSiblingByTagName() )
534 TCollection_AsciiString aCompName = aComponentElem.getAttribute( KeyWord( "COMPONENT_NAME" ) );
535 if ( !myGroupMap.Contains( aCompName ) )
536 myGroupMap.Add( aCompName, CreateGroup( aCompName ) );
537 Handle(DDS_DicGroup) aDicGroup = myGroupMap.FindFromKey( aCompName );
538 aDicGroup->FillDataMap( aComponentElem, theDocElement );
539 myGroupMap.Add( aCompName, aDicGroup );
544 \brief Convert numeric value \a theValue from specified measure units
545 \a theUnits to "SI" measure units (mm for Length, radians for Angles, etc).
546 \param theValue value being converted
547 \param theUnits measure units
548 \return converted value
550 Standard_Real DDS_Dictionary::ToSI( const Standard_Real theValue, const Standard_CString theUnits )
552 Standard_Real aRetValue = theValue;
553 if ( theUnits && *theUnits && strcmp( theUnits, "%" ) )
557 aRetValue = UnitsAPI::AnyToSI( theValue, theUnits );
559 catch( Standard_Failure& ) {
562 else if ( theUnits && *theUnits )
563 aRetValue = theValue / 100.0;
569 \brief Convert numeric value \a theValue to specified measure units
570 \a theUnits from "SI" measure units (mm for Length, radians for Angles, etc).
571 \param theValue value being converted
572 \param theUnits measure units
573 \return converted value
575 Standard_Real DDS_Dictionary::FromSI( const Standard_Real theValue, const Standard_CString theUnits )
577 Standard_Real aRetValue = theValue;
578 if ( theUnits && *theUnits && strcmp( theUnits, "%" ) )
582 aRetValue = UnitsAPI::AnyFromSI( theValue, theUnits );
584 catch( Standard_Failure& ) {
587 else if ( theUnits && *theUnits )
588 aRetValue = theValue * 100.0;
594 \brief Fill given string container \a seq with keys belonging to group with name \a theComponent
595 \param theComponent name of group whose keys should be stored in the container
596 \param seq returned string container with keys belonging to group; it is not cleared before filling
598 void DDS_Dictionary::GetKeys( const TCollection_AsciiString& theComponent, TColStd_SequenceOfAsciiString& seq ) const
600 Handle( DDS_DicGroup ) aDicGroup;
601 if( myGroupMap.Contains( theComponent ) )
602 aDicGroup = myGroupMap.FindFromKey( theComponent );
604 if( !aDicGroup.IsNull() )
605 aDicGroup->GetKeys( seq );
609 \brief Create instance of a dictionary group. This method can
610 be used for customization data dictionary by specific
612 \return New dictionary group instance.
614 Handle(DDS_DicGroup) DDS_Dictionary::CreateGroup( const TCollection_AsciiString& theCompName ) const
616 return new DDS_DicGroup( theCompName );
620 \brief Set instance of dictionary. This method might be used in descendant classes to initialize
621 custom dictionary and replace the default implementation.
622 This method overrides static handle on dictionary that is available
625 void DDS_Dictionary::SetDictionary( const Handle(DDS_Dictionary)& theDict )
627 myDictionary = theDict;