1 // Copyright (C) 2007-2008 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.
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
22 #include "DDS_Dictionary.h"
24 #include "DDS_KeyWords.h"
26 #include <LDOMString.hxx>
27 #include <LDOMParser.hxx>
29 #include <UnitsAPI.hxx>
31 #include <TColStd_SequenceOfInteger.hxx>
32 #include <TColStd_SequenceOfAsciiString.hxx>
33 #include <TColStd_SequenceOfExtendedString.hxx>
35 #include <NCollection_Map.hxx>
37 #include <Standard_Failure.hxx>
38 #include <Standard_ErrorHandler.hxx>
40 IMPLEMENT_STANDARD_HANDLE(DDS_Dictionary, MMgt_TShared)
41 IMPLEMENT_STANDARD_RTTIEXT(DDS_Dictionary, MMgt_TShared)
45 \brief This class provides an information about used datums,
46 reading them from XML file.
48 There is the only instance of the class DDS_Dictionary in the application
49 which can be retrieved by method Get().
51 Datum is a set of parameters describing a phisical characteristic.
52 These parameters are loaded from the XML file which has the following format:
56 <COMPONENT COMPONENT_NAME="component_name">
58 <UNIT_SYSTEM UNIT_SYSTEM_NAME="[system_internal_name]" UNIT_SYSTEM_LABEL="[system_label]">
59 <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]">
64 <DATUM DATUM_UNITS="[base_system_internal_name]" DATUM_FORMAT="[sprintf_format_specification]"
65 DATUM_ID="[datum_id]" DATUM_LABEL="[datum_label]" DATUM_REQUIRED="[requred_value]"
66 DATUM_FILTER="[string_regular_expression]">
68 <VALUE_DESCR VD_DEFV="[default_value]" VD_MAXV="[max_value]" VD_MINV="[min_value]" VD_TYPE="[value_type]"/>
69 <VALUE_LIST_REF VLR_LIST="[referenced_list_id]"/>
72 <SHORT_D>[brief_desription_text]</SHORT_D>
73 <LONG_D>[full_description_text]</LONG_D>
76 <OPTION OPTION_NAME="[option_name_1]">[option_value_1]</OPTION>
77 <OPTION OPTION_NAME="[option_name_2]">[option_value_2]</OPTION>
79 <OPTION OPTION_NAME="[option_name_n]">[option_value_n]</OPTION>
85 <VALUE_LIST VALUE_LIST_ID="[list_id]" VALUE_LIST_NAME="[list_name]">
86 <VALUE_LIST_VALUE VALUE_LIST_VALUEID="[list_element_id]" VALUE_LIST_VALUEICON="[list_element_icon_file]">[list_element_name]</VALUE_LIST_VALUE>
87 <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>
99 In above description of the datum XML file format internal keys are used as XML tags
100 and attributes names. Real XML keywords are defined by DDS_KeyWords class.
102 XML file should have one main tag named "dictionary" (key "D_URI"). This tag
103 should contain one or several components.
104 Component is an independent set of datums and units systems.
105 Components are defined by XML tag named "component" (key "COMPONENT") with
106 attribute "name" (key COMPONENT_NAME).
107 Component name is used as component identifier and should be unique.
109 Component tag can contain:
111 - Tag "unit_systems" (key UNIT_SYSTEMS) defines a set of used units systems.
112 At least one unit system named SI ("System International") should exist.
113 If this system does not exist, it will be created automatically.
114 Each units system is defined by XML tag "unit system" (key UNIT_SYSTEM) under
115 the tag "unit_systems" with attributes "name" (key UNIT_SYSTEM_NAME)
116 and "label" (key UNIT_SYSTEM_LABEL). Name is an identifier of the units system and
117 label is its human readable description.
119 - One or several tags "datum" (key DATUM). For this tag the following attributes
121 -# Identifier (key DATUM_ID) specifies the unique id string for the datum.
122 -# Label (key DATUM_LABEL) specifies human readable name of the datum.
123 -# Measure units (key DATUM_UNITS) for the given units system. Attribute name
124 defines a name of units system and a keyword got from DDS_KeyWords by key DATUM_UNITS.
125 For example, for "SI" units system and default keyword the attribute name is "SIunits".
126 This attribute should be specified for each declared units system.
127 Value of this attribute should be a string describing measure units.
128 For possible designations for measure units and their multiple prefixes
129 please refer to the UnitsAPI package of the OpenCascade library
130 (files Units.dat and Lexi_Expr.dat). Measure units are used for numerical
131 values conversion from one units system to another one.
132 -# Format (key DATUM_FORMAT) specifies the format string which will be used
133 during initial formatting of the value. This string should be specified
135 -# Filter (key DATUM_FILTER) specifies the regualr expression. The value (string)
136 entered by the user will be checked up to match to this regular expression
137 (if it defined). Non matched strings will be rejected.
138 -# Required value (key DATUM_REQUIRED). If this attributed si defined and its value
139 is \c true then user can't leave an input non-filled - parameter must be explicitly
140 entered by the user).
142 - One or several tags "list definition" (key VALUE_LIST). Each such tag defines
143 the list of items for enumerable data. Attribute "list id" (key VALUE_LIST_ID)
144 specifies the identifier string for the list and attribute "list name"
145 (key VALUE_LIST_NAME) defines a list name string. Each list item is described
146 by tag "list value" (key VALUE_LIST_VALUE) under the tag "list definition".
147 Each this tag contains item string text and have the following attributes:
148 -# "list item id" (key VALUE_LIST_VALUEID) - integer numerical identifier for
150 -# "list item icon" (key VALUE_LIST_VALUEICON) - icon file name for the item
152 Tag "datum" can have child subtags "description" and "options".
154 - Tag "description" (key DESCR) contains two sub tags:
155 -# "short description" (key SHORT_D) specifies a brief datum description text
156 -# "long description" (key LONG_D) specifies a detailed description text
158 - Tag "options" (key OPTIONS) contains one or more sub tags "option" (key OPTION).
159 Each of these XML elements should contain text option value and attribute
160 "name" (key OPTION_NAME) which specifies option name.
162 Each tag "datum" defines most common parameters of phisical characteristic.
163 These parameters are placed in two groups:
164 -# Domain parameters under the tag "domain" (key DY_DOMAIN). This tag can
165 contain value description tag (key VALUE_DESCR) for descrete data which is
166 described by following parameters:
167 - default value (key VD_DEFV)
168 - maximum value (key VD_MAXV)
169 - minimum value (key VD_MINV)
170 - type of value (key VD_TYPE), possible values are String, Integer, Float, List
171 -# list reference tag (key VALUE_LIST_REF) for enumerable data described by
172 "list reference" attribute (key VLR_LIST) which references to the list
173 (see "list definition" tag) by list id.
175 Below is an example of the XML file using default keywords.
178 <datadictionary version="1.0">
179 <component name="My Component">
181 <!-- specify two unit systems -->
184 <system name="SI" label="System international">
185 <system name="AS" label="Anglo - sacson system">
188 <!-- specify datum -->
189 <!-- units of measure for SI - meters (m), for AS - inches (in) -->
190 <datum SIunits="m" ASunits="in" format="%.25f" id="X" label="X coordinate" required="">
192 <!-- default value not specified -->
193 <valueDescr default="" max="999999999.999" min="0.000" type="Float"/>
196 <shortDescr>X coordinate for object</shortDescr>
197 <longDescr>X multiplier of object coordinates. Describe position of object in direction of X axis</longDescr>
201 <datum SIunits="m" ASunits="in" format="%.25f" id="Y" label="Y coordinate" required="">
203 <valueDescr default="" max="999999999.999" min="0.000" type="Float"/>
206 <shortDescr>Y coordinate for object</shortDescr>
207 <longDescr>Y multiplier of object coordinates. Describe position of object in direction of Y axis</longDescr>
211 <!-- datum for object name with filter which not allow to input more that 8 letters,
212 numbers or unerscores with first letter only -->
213 <datum format="%.8us" id="ObjectName" label="Name" required="yes"
214 filter="^([A-Z]+)([A-Z,0-9,_]*)$">
216 <!-- limits and default not specified, type is string -->
217 <valueDescr default="" max="" min="" type="String" />
220 <!-- long description not specified -->
221 <shortDescr>Name of object</shortDescr>
226 <!-- datum for enumeration of side -->
227 <datum format="" id="Side" label="Side" required="">
229 <!-- default list item is item with id 0 -->
230 <valueDescr default="0" type="List"/>
231 <!-- list reference on list named "side_list" -->
232 <listRef list="side_list"/>
235 <shortDescr>Side of object</shortDescr>
239 <!-- list definition for enumeration of side -->
240 <valueList listid="side_list" name="Side">
241 <value id="1">left</value>
242 <value id="2">right</value>
243 <value id="3">top</value>
244 <value id="4">bottom</value>
245 <value id="0">undefined</value>
256 Create an instance of the dictionary. Can not be used directly.
257 Use Get() method instead.
259 DDS_Dictionary::DDS_Dictionary()
265 \brief Copy constructor (put in private section to prevent object copying).
267 DDS_Dictionary::DDS_Dictionary( const DDS_Dictionary& )
272 \brief Assignment operator (put in private section to prevent object copying).
274 void DDS_Dictionary::operator=( const DDS_Dictionary& )
279 \brief Get the names of defined units systems from all components.
280 \param theSystems returning sequence of units systems names.
282 void DDS_Dictionary::GetUnitSystems( TColStd_SequenceOfAsciiString& theSystems ) const
286 NCollection_Map<TCollection_AsciiString> aMap;
287 for ( Standard_Integer i = 1; i <= myGroupMap.Extent(); i++ )
289 TColStd_SequenceOfAsciiString theSeq;
290 myGroupMap.FindFromIndex( i )->GetUnitSystems( theSeq );
291 for ( Standard_Integer s = 1; s <= theSeq.Length(); s++ )
293 if ( aMap.Contains( theSeq.Value( s ) ) )
296 theSystems.Append( theSeq.Value( s ) );
297 aMap.Add( theSeq.Value( s ) );
304 \brief Get the names of defined units systems from the specified component
307 If component is not found, empty list is returned.
309 \param theSystems returning sequence of units systems names.
310 \param theComponent component name
312 void DDS_Dictionary::GetUnitSystems( TColStd_SequenceOfAsciiString& theSystems,
313 const TCollection_AsciiString& theComponent ) const
316 if ( myGroupMap.Contains( theComponent ) )
317 myGroupMap.FindFromKey( theComponent )->GetUnitSystems( theSystems );
321 \brief Get the label of the units system \a theSystem.
323 Searches the given units system in all components. If units system is not found
324 in any component, empty string is returned.
326 \param theSystem units system
327 \return units system label
329 TCollection_ExtendedString DDS_Dictionary::GetUnitSystemLabel( const TCollection_AsciiString& theSystem ) const
331 TCollection_ExtendedString aLabel;
332 for ( Standard_Integer i = 1; i <= myGroupMap.Extent() && !aLabel.Length(); i++ )
333 aLabel = myGroupMap.FindFromIndex( i )->GetUnitSystemLabel( theSystem );
338 \brief Get the label of the units system \a theSystem from the
339 component \a theComponent.
341 Searches the specified units system in the specified component only.
342 If units system is not found, empty string is returned.
344 \param theSystem units system
345 \param theComponent component name
346 \return units system label
348 TCollection_ExtendedString DDS_Dictionary::GetUnitSystemLabel( const TCollection_AsciiString& theSystem,
349 const TCollection_AsciiString& theComponent ) const
351 TCollection_ExtendedString aLabel;
352 if ( myGroupMap.Contains( theComponent ) )
353 aLabel = myGroupMap.FindFromKey( theComponent )->GetUnitSystemLabel( theSystem );
358 \brief Get the name of active units system from the first found component.
360 If at least one component exists, then its active units system name
361 is returned. Otherwise, empty string is returned.
363 \return active units system name
365 TCollection_AsciiString DDS_Dictionary::GetActiveUnitSystem() const
367 TCollection_AsciiString aSystem;
368 if ( myGroupMap.Extent() )
369 aSystem = myGroupMap.FindFromIndex( 1 )->GetActiveUnitSystem();
374 \brief Get the name of active units system from the component \a theComponent.
376 If this component exists, its active units system name is returned.
377 Otherwise, empty string is returned.
379 \param theComponent component name
380 \return active units system name
382 TCollection_AsciiString DDS_Dictionary::GetActiveUnitSystem( const TCollection_AsciiString& theComponent ) const
384 TCollection_AsciiString aSystem;
385 if ( myGroupMap.Contains( theComponent ) )
386 aSystem = myGroupMap.FindFromKey( theComponent )->GetActiveUnitSystem();
391 \brief Set the active units system.
393 This units system will be activated in each existing component,
394 if it component has this units system.
396 \param theSystem units system to be made active
398 void DDS_Dictionary::SetActiveUnitSystem( const TCollection_AsciiString& theSystem )
400 for ( Standard_Integer i = 1; i <= myGroupMap.Extent(); i++ )
401 myGroupMap.FindFromIndex( i )->SetActiveUnitSystem( theSystem );
405 \brief Set the active units system for the component \a theComponent.
407 If specified units system doesn't exist in the component, nothing happens.
409 \param theSystem units system to be made active
410 \param theComponent component name
412 void DDS_Dictionary::SetActiveUnitSystem( const TCollection_AsciiString& theSystem,
413 const TCollection_AsciiString& theComponent )
415 if ( myGroupMap.Contains( theComponent ) )
416 myGroupMap.FindFromKey( theComponent )->SetActiveUnitSystem( theSystem );
420 \brief Get the only instance of the data dictionary.
421 \return the only instance of the data dictionary
423 Handle_DDS_Dictionary DDS_Dictionary::Get()
425 static Handle(DDS_Dictionary) sDictionary;
427 if ( sDictionary.IsNull() )
428 sDictionary = new DDS_Dictionary();
434 \brief Load datum definitions in the dictionary from the XML file
436 \param theFileName XML file name
437 \return \c true if loading is succeded or \c false otherwise.
439 Standard_Boolean DDS_Dictionary::Load( const TCollection_AsciiString theFileName )
441 static NCollection_Map<TCollection_AsciiString> _LoadMap;
443 if ( _LoadMap.Contains( theFileName ) )
444 return Standard_True;
446 Handle(DDS_Dictionary) aDic = Get();
448 return Standard_False;
451 if ( aParser.parse( theFileName.ToCString() ) )
452 return Standard_False;
454 LDOM_Document aDoc = aParser.getDocument();
455 LDOM_Element aDocElement = aDoc.getDocumentElement();
456 for ( LDOM_Element aComponentElem = aDocElement.GetChildByTagName( KeyWord( "COMPONENT" ) );
457 !aComponentElem.isNull(); aComponentElem = aComponentElem.GetSiblingByTagName() )
458 aDic->FillDataMap( aComponentElem, 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 theComponentData component XML node
528 \param theDocElement document XML node
530 void DDS_Dictionary::FillDataMap( const LDOM_Element& theComponentData, const LDOM_Element& theDocElement )
532 TCollection_AsciiString aCompName = theComponentData.getAttribute( KeyWord( "COMPONENT_NAME" ) );
533 if ( !myGroupMap.Contains( aCompName ) )
534 myGroupMap.Add( aCompName, new DDS_DicGroup( aCompName ) );
535 Handle(DDS_DicGroup) aDicGroup = myGroupMap.FindFromKey( aCompName );
536 aDicGroup->FillDataMap( theComponentData, theDocElement );
537 myGroupMap.Add( aCompName, aDicGroup );
541 \brief Convert numeric value \a theValue from specified measure units
542 \a theUnits to "SI" measure units (mm for Length, radians for Angles, etc).
543 \param theValue value being converted
544 \param theUnits measure units
545 \return converted value
547 Standard_Real DDS_Dictionary::ToSI( const Standard_Real theValue, const Standard_CString theUnits )
549 Standard_Real aRetValue = theValue;
550 if ( theUnits && *theUnits && strcmp( theUnits, "%" ) )
553 #if (OCC_VERSION_MAJOR << 16 | OCC_VERSION_MINOR << 8 | OCC_VERSION_MAINTENANCE) > 0x060100
556 aRetValue = UnitsAPI::AnyToSI( theValue, theUnits );
558 catch( Standard_Failure ) {
561 else if ( theUnits && *theUnits )
562 aRetValue = theValue / 100.0;
568 \brief Convert numeric value \a theValue to specified measure units
569 \a theUnits from "SI" measure units (mm for Length, radians for Angles, etc).
570 \param theValue value being converted
571 \param theUnits measure units
572 \return converted value
574 Standard_Real DDS_Dictionary::FromSI( const Standard_Real theValue, const Standard_CString theUnits )
576 Standard_Real aRetValue = theValue;
577 if ( theUnits && *theUnits && strcmp( theUnits, "%" ) )
580 #if (OCC_VERSION_MAJOR << 16 | OCC_VERSION_MINOR << 8 | OCC_VERSION_MAINTENANCE) > 0x060100
583 aRetValue = UnitsAPI::AnyFromSI( theValue, theUnits );
585 catch( Standard_Failure ) {
588 else if ( theUnits && *theUnits )
589 aRetValue = theValue * 100.0;
595 \brief Fill given string container \a seq with keys belonging to group with name \a theComponent
596 \param theComponent name of group whose keys should be stored in the container
597 \param seq returned string container with keys belonging to group; it is not cleared before filling
599 void DDS_Dictionary::GetKeys( const TCollection_AsciiString& theComponent, TColStd_SequenceOfAsciiString& seq ) const
601 Handle( DDS_DicGroup ) aDicGroup;
602 if( myGroupMap.Contains( theComponent ) )
603 aDicGroup = myGroupMap.FindFromKey( theComponent );
605 if( !aDicGroup.IsNull() )
606 aDicGroup->GetKeys( seq );