0024722: Move functionality of WOK command wgendoc to OCCT tool gendoc
[occt.git] / dox / dev_guides / cdl / cdl.md
1  Component Definition Language (CDL)  {#occt_dev_guides__cdl}
2 ==============================
3
4 @tableofcontents
5
6 @section occt_cdl_0 DEPRECATION WARNING
7
8 Please note that CDL is considered as obsolete and is to be removed in one of future releases of OCCT.
9
10 @section occt_cdl_1 CDL and Application Architecture
11
12 CDL is the component  definition language of the Open CASCADE Technology (**OCCT**) programming  platform. Some components, which CDL allows you to create, are specific to OCCT  application architecture. These and other components, which you can define  using CDL include the following: 
13
14   * Class (including enumeration,  exception)
15   * Package
16   * Schema
17   * Executable
18   * Client.
19   
20 A **class** is the  fundamental software component in object-oriented development. Because of a  very large number of resources used in large-scale applications, the **class** itself  is too small to be used as a basic management unit. 
21
22 So, while the class is  the basic data component defined in CDL, this language also provides a way to  group classes, **enumerations**, and **exceptions** together – the **package**.  A package groups together a number of classes, which have semantic links. For  example, a geometry package would contain Point, Line, and Circle classes. A  package can also contain enumerations, exceptions, and package methods. In  practice, a class name is prefixed with the name of its package e.g.  *Geom_Circle*. 
23
24 Using the services  described in the **packages**, you can construct an **executable**. You  can also group together services provided by **packages**.  
25
26 To save data in a file,  you need to define persistent classes. Then, you group these classes in a  schema, which provides the necessary read/write tools. 
27
28
29 @image html /dev_guides/cdl/images/cdl_image003.png "Building  an Open CASCADE Technology application" 
30 @image latex /dev_guides/cdl/images/cdl_image003.png "Building  an Open CASCADE Technology application" 
31     
32 @section occt_cdl_2 Introduction to  CDL
33 @subsection occt_cdl_2_1  Purposes of the Language
34
35 You can use CDL to **define** **data** in the Open CASCADE Technology environment. CDL allows you to define  various kinds of data types supporting the application architecture and  development methodology, which you envision. CDL is neither an analysis  formalism (e.g. Booch methodology) nor a data manipulation language (e.g. C++). 
36
37 You use CDL in the **design** **phase** of a development process to define a set of software components which  best model the concepts stated in the application specification. 
38
39 @image html /dev_guides/cdl/images/cdl_image004.png "The Development Process" 
40 @image latex /dev_guides/cdl/images/cdl_image004.png "The Development Process" 
41
42
43 From a structural point  of view, CDL is an object-oriented language. It is centered on the notion of  the **class** - a data type, which represents an elementary concept. CDL  offers various means of organizing classes, mostly under the fundamental form  of **packages**. A package contains a set of classes, which share some  semantic relationship. This greatly simplifies your task of managing individual  classes when confronted with a very large number of them. 
44
45 Once you have defined  the classes and packages using CDL, you can implement their **methods** -  i.e., their functionality - in one of the data manipulation languages supported  by the OCCT environment (currently C++). 
46
47 Even though you can describe classes directly in C++  and save them as header files (.hxx), to do so would forfeit all the advantages  of using CDL. These are: 
48
49   * Precise, complete, and  easy-to-read description of the software components.
50   * Creation of a link with the  database; object persistence forms part of the predefined environment of the  language.
51   * Multi-language access to the  services of an application engine – a specific architectural form created using  the CDL tools, which serves as the motor of an application.
52   
53 @subsection occt_cdl_2_2   Overview of CDL
54
55 CDL is an object-oriented  language. In other words, it structures a system around data types rather than  around the actions carried out on them. In this context, an **object** is an  **instance** of a data type, and its definition determines how you can use  it. Each data type is implemented by one or more classes, which make up the  basic elements of the system. 
56
57 @subsubsection occt_cdl_2_2_1    Classes
58
59 A class is an  implementation of a **data type**. It defines its **behavior** and its **representation**. 
60
61 The behavior of a class  is its programming interface - the services offered by its **methods**. The  representation of a class is its data structure - the **fields**, which  store its data. 
62
63 Every object is an **instance** of its class. For example, the object *p* of the data type *Point* is  an instance of the class *Point*. 
64
65 The class Point could be  defined as in the example below: 
66
67 @code
68 class Point from  GeomPack
69     ---Purpose: represents a point in 3D space.
70    is
71     Create returns Point;
72 fields
73     x, y, z : Real;
74 end Point; 
75 @endcode
76
77 The definition of this class comprises two sections: 
78
79   * one starting with the  keywords **is**
80   * one starting with the keyword  **fields**.
81
82 The first section  contains a list of methods available to the clients of the class. The second  section defines the way in which instances are represented. Once this class has  been compiled you could **instantiate** its data type in a C++ test program  as in the example below: 
83
84
85
86 @code
87 GeomPack_Point p;
88 @endcode
89
90
91 @subsubsection occt_cdl_2_2_2     Categories of Types
92
93 You declare the  variables of a **data manipulation language** as being of certain data  types. These fall into two categories: 
94
95   * Data types manipulated by  handle (or reference)
96   * Data types manipulated by  value
97   
98     @image html /dev_guides/cdl/images/cdl_image005.png "Manipulation of data types" 
99     @image latex /dev_guides/cdl/images/cdl_image005.png  "Manipulation of data types" 
100
101 As seen above, you  implement data types using classes. However, classes not only define their data  representation and methods available for their instances, but they also define  how the instances will be manipulated: 
102   * A data type manipulated by  value contains the instance itself.
103   * A data type manipulated by  handle contains a reference to the instance.
104
105 The most obvious  examples of data types manipulated by value are the predefined **primitive  types**: Boolean, Character, Integer, Real... 
106
107 A variable of a data  type manipulated by handle, which is not attached to an object, is said to be **null**.  To reference an object, you need to instantiate the class with one of its  constructors. This is done in C++ as in the following syntax: 
108
109 ~~~~~
110 Handle(myClass) m = new myClass;
111 ~~~~~
112
113
114 @subsubsection occt_cdl_2_2_3     Persistence
115
116 An object is called **persistent** if it can be permanently stored. In other words, you can use the object  again at a later date, both in the application, which created it, and in  another application. 
117
118 In order to make an  object persistent, you need to declare it in CDL as inheriting from the **Persistent**  class, or to have one of its parent classes inheriting from the *Persistent* class. 
119
120 Note that the classes  inheriting from the *Persistent* class are handled by reference. 
121
122 **Example** 
123 ~~~~~
124 class Watch inherits Persistent
125 ~~~~~
126
127 In this example,  building the application, you add the *Watch* class to the corresponding schema  of data types. 
128 If, running the  application, you instantiate an object of the *Watch* class, you have the  possibility of storing it in a file. 
129 You cannot store objects  instantiated from classes, which inherit from the *Storable* class.  However, you can store them as fields of an object, which inherits from  *Persistent*. 
130
131 Note that the objects  inheriting from Storable are handled by value. 
132
133 **Example** 
134 ~~~~~
135 If 
136 class WatchSpring  inherits Storable 
137 //then this could be  stored as a field of a Watch 
138 //object: 
139 class Watch inherits  Persistent 
140 is...... 
141 fields 
142 name :  ConstructorName; 
143 powersource :  WatchSpring; 
144 end; 
145 ~~~~~
146
147 @subsubsection occt_cdl_2_2_4    Packages
148
149 In large-scale long-term  development the task of marshalling potentially thousands of classes is likely  to quickly prove unmanageable. CDL introduces the notion of **package** of  classes containing a set of classes, which have some semantic or syntactic  relationship. For example, all classes representing a particular set of  electronic components might make up a package called Diode. 
150
151 As the package name  prefixes the class name when implementing such class (in C++ for example),  classes belonging to different packages can have the same name. For example,  two packages, one dealing with finance and the other dealing with aircraft  maneuvers, might both contain a class called *Bank*, without any possibility of  confusion. 
152
153 **Example** 
154 ~~~~~
155 Finance_Bank 
156 Attitude_Bank 
157 ~~~~~
158
159
160 @subsubsection occt_cdl_2_2_5     Inheritance
161
162 The purpose of  inheritance is to reduce development workload. The inheritance mechanisms allow  you to declare a new class as already containing the characteristics of an  existing class. This new class can then be rapidly specialized for a task at  hand. This eliminates the necessity of developing each component “from  scratch”. 
163
164 For example, having  already developed a class *BankAccount*, you can quickly specialize new classes -  *SavingsAccount, LongTermDepositAccount, MoneyMarketAccount,  RevolvingCreditAccount*, etc.. 
165
166 As a consequence, when  two or more classes inherit from a parent (or ancestor) class, all these  classes surely inherit the behavior of their parent (or ancestor). For example,  if the parent class *BankAccount* contains the method *Print* that tells it to  print itself out, then all its descendent classes offer the same service. 
167
168 One way of ensuring the  use of inheritance is to declare classes at the top of a hierarchy as being **deferred**.  In such classes, the inherited methods are not implemented. This forces you to  create a new class used to redefine the methods. In this way, you guarantee a  certain minimum common behavior among descendent classes. 
169
170 **Example** 
171 ~~~~~
172 deferred class BankAccount inherits Persistent 
173 is 
174 ....... 
175 fields 
176 name :  AccountHolderName; 
177 balance : CreditBalance; 
178 end; 
179 ~~~~~
180
181 @subsubsection occt_cdl_2_2_6     Genericity
182
183 You will often wish to  model a certain type of behavior as a class. For example, you will need a list  modeled as a class. 
184
185 In order to be able to  list different objects, the class *List* must be able to accept different  data types as parameters. This is where genericity comes in: you first declare  a list declared as the generic class *List*, willing to accept any data  type (or only a particular set of acceptable data types). Then, when you want  to make a list of a certain type of object, you instantiate the class *List* with  the appropriate data type. 
186
187 **Example** 
188
189 ~~~~~
190 generic class NewList (Item) 
191 inherits OldList 
192 is 
193 ..... 
194 end ; 
195 ~~~~~
196
197 Items may be of any  type, an Integer or a Real for example. 
198
199 When defining the  package, add the following line: 
200 **Example** 
201 ~~~~~
202 class NewListOfInteger instantiates 
203 NewList (Integer); 
204 ~~~~~
205
206 @subsubsection occt_cdl_2_2_7     Exceptions
207
208 The behavior of any  object is implemented by methods, which you define in its class declaration.  The definition of these methods includes not only their signature (their  programming interface) but also their domain of validity. 
209
210 In CDL, this domain is  expressed by **exceptions**. Exceptions are raised under various error  conditions. This mechanism is a safeguard of software quality. 
211
212 @subsubsection occt_cdl_2_2_8     Completeness
213
214 You use CDL to define  data types. Such definitions are not considered complete unless they contain  the required amount of structured commentary. 
215
216 The compiler does not  enforce this required degree of completeness, so it is the responsibility of  the developer to ensure that all CDL codes are properly annotated. 
217
218 Completeness is regarded  as an essential component of long-term viability of a software component. 
219
220
221 @subsection occt_cdl_2_3   Lexical Conventions
222 @subsubsection occt_cdl_2_3_1    Syntax  notation
223
224 In this manual, CDL  declarations are described using a simple variant of the Backus-Naur formalism.  Note the following: 
225
226   * Italicized words, which may  also be hyphenated, denote syntactical categories, for example *declaration-of-a-non-generic-class* ;
227   * Keywords appear in bold type: **class** ;
228   * Brackets enclose optional  elements: 
229 ~~~~~
230   identifier [from package-name] 
231 ~~~~~
232   * Curly braces enclose repeated  elements. The element may appear zero or many times: 
233 ~~~~~  
234   integer ::=  digit{digit} 
235 ~~~~~
236   * Vertical bars separate  alternatives:
237 ~~~~~
238 passing-method ::=  <b>[in] | out | in out </b> 
239 ~~~~~
240   * Two apostrophes enclose a  character or a string of characters, which must appear:
241 ~~~~~
242 exponent ::=  ’E’[’+’]integer | ’E-’ integer 
243 ~~~~~
244 **NOTE** To introduce the ideas progressively, the  examples presented in this manual may be incomplete, and thus not compilable by  the CDL compiler. 
245
246
247 @subsubsection occt_cdl_2_3_2    Lexical  elements
248
249 A CDL source is composed  of text from one or more compiled units. The text of each compiled unit is a  string of separate lexical elements: **identifiers**, **keywords**, **constants**,  and **separators**. The separators (blank spaces, end of line, format  characters) are ignored by the CDL compiler, but these are often necessary for  separating identifiers, keywords, and constants. 
250
251
252 @subsubsection occt_cdl_2_3_3     Comments
253
254 With CDL, you cannot use  the expression of all useful information about a development unit. In  particular, certain information is more easily expressed in natural language.  You can add such information to the CDL description of a data type. 
255
256 Rubrics and free  comments are to be differentiated: 
257
258 **Free comments** are preceded by the characters “--” (two  hyphens), and they terminate at the end of the line in which they appear. 
259 **Example** 
260 ~~~~~
261 --This is a comment 
262 ~~~~~
263
264 Unlike rubrics, free  comments can appear before or after any lexical element. The first written  character of the comment itself *must not* be a hyphen. If a hyphen is  necessary make sure it is preceded by a blank. 
265 **Example** 
266 ~~~~~
267 -- -List item 
268 ~~~~~
269 **Rubrics** are various types of comments attached to CDL components.  A rubric is a comment made up of three hyphens, name of the rubric (without any  intermediary space) and then a colon and a space. It is terminated by the  beginning of the following rubric, or by the end of the commentary. 
270
271 **Example** 
272 ~~~~~
273 ---Purpose:This is an example of a 
274 --rubric composed of a 
275 --comment which extends to 
276 --four lines. 
277 ~~~~~
278
279 The different categories  of rubrics and the form of their content do not depend on the Component  Description Language, but on the tool for which it is intended.  
280
281 The use of commentary is  generally governed by the internal programming standards of an enterprise. You  are encouraged to use various well-defined rubrics, such as Purpose, Warning,  Example, References, Keywords, etc. 
282
283 These rubrics can be  attached to: 
284
285   * Packages
286   * Classes
287   * Methods
288   * Schemas
289   * Executables
290   * Clients
291
292 @subsubsection occt_cdl_2_3_4     Identifiers
293
294 An identifier is an  arbitrary chain of characters, either letters or digits, but it must begin with  a letter. 
295
296 The underscore “_” is  considered to be a letter as long as it doesn’t appear at the beginning or the  end of an identifier. 
297
298 Capital and small  letters are not equivalent (i.e. AB, Ab, aB, ab are four different  identifiers). 
299
300
301 @subsubsection occt_cdl_2_3_5     Keywords
302
303 The following is a list  of keywords. 
304
305 * alias 
306 * any                    
307 * as                     
308 * asynchronous 
309 * class                     
310 * client                 
311 * deferred            
312 * end 
313 * enumeration           
314 * exception           
315 * executable        
316 * external 
317 * fields                     
318 * friends               
319 * from                 
320 * generic 
321 * immutable              
322 * imported            
323 * inherits              
324 * instantiates 
325 * is                          
326 * library                
327 * like                   
328 * me 
329 * mutable                 
330 * myclass             
331 * out                   
332 * package 
333 * pointer                   
334 * primitive             
335 * private              
336 * protected 
337 * raises                    
338 * redefined           
339 * returns              
340 * schema 
341 * static                     
342 * to                      
343 * uses                 
344 * virtual 
345
346 In a CDL file, the  following characters are used as punctuation: 
347 ; : , = ( ) [ ] ‘ “ 
348
349 @subsubsection occt_cdl_2_3_6     Constants
350
351 There are three  categories of constants: 
352
353   * Numeric
354   * Literal
355   * Named
356
357 #### Numeric Constants
358
359 There are two types of  numeric constants: integer and real. 
360
361 An **integer** constant  consists of a string of digits, which may or may not be preceded by a sign.  Integer constants express whole numbers. 
362
363 **Examples** 
364 ~~~~~
365 1995         0            -273         +78 
366 ~~~~~
367 A **real** constant  may or may not be preceded by a sign, and consists of an integral part followed  by a decimal point and a fractional part (either one or both parts may be null,  but both parts must always be present). It may also be followed by the letter E  to indicate that the following figures represent the exponent (also optionally  signed). 
368
369 **Examples** 
370 ~~~~~
371 5.0        0.0           -0.8E+3          5.67E-12 
372 ~~~~~
373 #### Literal Constants
374
375 Literal constants  include individual characters and strings of characters. 
376
377 An **individual  character** constant is a single printable character enclosed by two  apostrophes. (See the definition of the class Character in the Standard  Package). 
378
379 **Examples** 
380 ~~~~~
381  ‘B’       ‘y’      ‘&amp;’      ‘*’      ‘’’ ‘‘ 
382 ~~~~~
383 A **string** constant  is composed of printable characters enclosed by quotation marks. 
384
385 **Examples** 
386 ~~~~~
387 ’’G’’     ’’jjjj’’      ’’This is a character string, isn’t it?’’ 
388 ~~~~~
389 The **quotation mark** can  itself appear within a character string as long as it is preceded by a  backslash. 
390
391 **Examples** 
392 ~~~~~
393 ’’This film was  originally called \’’Gone with the Tide\’’.’’ 
394 ~~~~~
395
396 #### Named Constants
397
398 Named constants are  sub-divided into two categories: Booleans and enumerations. 
399
400 **Booleans** can be of two types: True or False. 
401
402 An **enumeration** constant  is an identifier, which appears in the description of an enumeration. 
403
404 @section occt_cdl_3 Software  Components
405
406 @subsection occt_cdl_3_1   Predefined Resources
407 @subsubsection occt_cdl_3_1_1     Primitive types
408
409 Primitive types are  predefined in the language and they are **manipulated by value**. 
410
411 Four of these primitives  are known to the schema of the database because they inherit from the class **Storable**.  In other words, they can be used in the implementation of persistent objects,  either when contained in entities declared within the methods of the object, or  when they form part of the internal representation of the object. 
412
413 The primitives inheriting  from **Storable** are the following: 
414
415 * **Boolean** Is used to represent logical data. It has only  two values: *True* and *False*. 
416 * **Byte** 8-bit number. 
417 * **Character** Designates any ASCII character. 
418 * **ExtCharacter** Is an extended character. 
419 * **Integer** Is an integer number. 
420 * **Real** Denotes a real number (i.e. one with a whole and  a fractional part, either of which may be null). 
421 * **ShortReal** Real with a smaller choice of values and memory  size. 
422
423 There are also  non-storable primitives. They are: 
424
425 * **CString** Is used for literal constants. 
426 * **ExtString** Is an extended string. 
427 * **Address** Represents a byte address of undetermined size. 
428
429 The services offered by  each of these types are described in the Standard Package. 
430
431
432 @subsubsection occt_cdl_3_1_2     Manipulating types by reference (by handle)
433
434 Two types are  manipulated by handle: 
435
436   * Types defined using classes  inheriting from the **Persistent** class are storable in a file.
437   * Types defined using classes  inheriting from the **Transient** class.
438   
439 These types are not storable as such in a file. 
440
441 @image html /dev_guides/cdl/images/cdl_image006.png "Manipulation of a data type by reference"
442 @image latex /dev_guides/cdl/images/cdl_image006.png "Manipulation of a data type by reference"
443
444
445 @subsubsection occt_cdl_3_1_3     Manipulating types by value
446
447 Types, which are  manipulated by value, behave in a more direct fashion than those manipulated by  handle. As a consequence, they can be expected to perform operations faster,  but they cannot be stored independently in a file. 
448
449 You can store types  known to the schema (i.e. either primitives or inheriting from Storable) and  manipulated by value inside a persistent object as part of the representation.  This is the only way for you to store objects “manipulated by value” in a file. 
450
451 @image html /dev_guides/cdl/images/cdl_image007.png "Manipulation of a data type by value" 
452 @image latex /dev_guides/cdl/images/cdl_image007.png "Manipulation of a data type by value" 
453
454 Three types are  manipulated by value: 
455
456   * Primitive types
457   * Enumerated types
458   * Types defined by classes not  inheriting from Persistent or Transient, whether directly or not
459
460 @subsubsection occt_cdl_3_1_4   Summary  of properties
461
462
463 Here is a summary of how various data types are handled and their  storability:
464  
465 | | Manipulated by handle | Manipulated by value |
466 | :---- | :---- | :---- |
467 | storable | Persistent | Primitive, Storable (storable if nested in a persistent class) |
468 | temporary | Transient | Other | 
469
470
471
472
473 @subsection occt_cdl_3_2   Classes
474
475 @subsubsection occt_cdl_3_2_1    Class  declaration
476
477 The class is the main  system for creating data types under CDL. By analyzing any CDL-based software,  you find that classes are the modular units that make up packages. When you  describe a new class, you introduce a new data type. 
478
479 Whatever the category of  the described type (manipulated by value, Storable or not, manipulated by  handle, Persistent or not) the structure of the class definition remains the  same. The syntax below illustrates it: 
480
481 ~~~~~
482 -- declaration-of-a-simple-class ::= 
483 class class-name from package-name 
484 [uses data-type {  ’,’ data-type } ] 
485 [raises  exception-name { ’,’ exception-name} ] 
486 is class-definition 
487 end [ class-name ]  ’;’ 
488 data-type ::=  enumeration-name | class-name | 
489 exception-name | primitive-type 
490 package-name ::=  identifier 
491 class-name ::=  identifier 
492 class-definition ::= 
493 [{member-method}] 
494 [declaration-of-fields] 
495 [declaration-of-friends] 
496 ~~~~~
497 Class name becomes a new  data type, which you can use inside its own definition. Other types appearing  in the definition must either be primitive types, previously declared classes,  exceptions, or enumerations. 
498
499 Apart from the types  defined in the Standard Package, which are **implicitly visible** everywhere,  you need to declare the data types after the keyword **uses**. This concerns  both the class behavior and its internal representation. 
500
501 **Exceptions** are declared after the word **raises**. 
502
503 **Example** 
504 ~~~~~
505 class Line from  GeomPack 
506 usesPoint,  Direction, Transformation 
507 raisesNullDirection,  IdenticalPoints 
508 is-- class  definition follows here 
509 -- using Point,  Direction and 
510 -- Transformation  objects,and the 
511 -- NullDirection and  Identical- 
512 -- -Points  exceptions. 
513 end Line; 
514 ~~~~~
515
516 The elements, which make  up the definition of a class, are divided into four parts: 
517   * the behavior
518   * the invariants
519   * the internal representation
520   * the friend methods and friend  classes.
521
522     @image html /dev_guides/cdl/images/cdl_image009.png "Contents of a class"
523     @image latex /dev_guides/cdl/images/cdl_image009.png "Contents of a class"
524
525 @subsubsection occt_cdl_3_2_2     Categories of classes
526
527 Classes fall into three categories: 
528   * Ordinary classes
529   * Deferred classes
530   * Generic classes
531
532 #### Deferred classes
533
534 The principal  characteristic of a **deferred class** is that you cannot instantiate it.  Its purpose is to provide a given behavior shared by a hierarchy of  classes and dependent on the implementation of the descendents. This allows guaranteeing a certain base of inherited behavior common to all classes based on a particular deferred class. Deferred classes are declared as in the  following syntax: 
535
536 ~~~~~
537 -- declaration-of-a-deferred-class ::= deferred class  class-name 
538 [inherits class-name  {’,’ class-name}] 
539 [uses data-type {’,’  data-type}] 
540 [raises exception-name  {’,’ exception-name}] 
541         is class-definition 
542         end [class-name]’;’ 
543 ~~~~~
544 Please, note that a deferred class does not have to contain a  constructor
545
546 <h4>Generic classes</h4>
547
548 The principal  characteristic of a **generic class** is that it offers a set of  functional behavior to manipulate other data types. To instantiate  a generic class you need to pass a data type in argument. Generic classes are  declared as in the following syntax: 
549
550 ~~~~~
551 -- declaration-of-a-generic-class ::= [deferred] generic  class class-name ’(’generic-type {’,’generic-type}’)’ 
552 [inheritsclass-name {’,’ class-name}] 
553 [usesdata-type {’,’  data-type}] 
554 [raisesexception-name  {’,’ exception-name}] 
555 [{[visibility]  declaration-of-a-class}] 
556         is class-definition 
557         end [class-name]’;’ 
558 generic-type ::=  identifier as type-constraint 
559 identifier ::=  letter{[underscore]alphanumeric} 
560 type-constraint ::= any | class-name [’(’data-type {’,’ data-type}’)’] 
561 ~~~~~
562
563
564 @subsection occt_cdl_3_3   Packages
565
566 @subsubsection occt_cdl_3_3_1    Package  declaration
567
568 **Packages** are  used to group   classes, which have some logical coherence. For example, the  Standard Package groups together all the predefined resources of the language.  In its simplest form, a package contains the declaration of all data types,  which it introduces. You may also use a package to offer public methods and  hide its internal classes by declaring them private. 
569
570 **Example** 
571
572 ~~~~~
573 -- package-declaration ::= package package-name 
574         [uses package-name {’,’ package-name}] 
575         is package-definition 
576         end [package-name]’;’ 
577 -- package-name ::= identifier 
578 -- package-definition ::= 
579         [{type-declaration}] 
580         [{package-method}] 
581 -- type-declaration ::= 
582         [private] declaration-of-an-enumeration |       [private] declaration-of-a-class |      declaration-of-an-exception 
583 -- package-method ::= identifier [simple-formal-part][returned-type -declaration] 
584 [error-declaration] 
585 [is private]’;’ 
586 ~~~~~
587
588 The data types described  in a package *may* include one or more of the following data types: 
589   * Enumerations
590   * Object classes
591   * Exceptions
592   * Pointers to other object  classes.
593
594 Inside a package, two  data types *cannot* have the same name. 
595
596 You declare data types  before using them in the definition of other data types. 
597
598 When two classes are **mutually  recursive**, one of the two must be first declared in an incomplete  fashion. 
599
600 Grouped behind the  keyword **uses** are the names of all the packages containing definitions of  classes of which the newly introduced data types are clients. 
601
602 The methods you declare  in a package do not belong to any particular class. **Package methods** must carry a name different from the data types contained in the package. Like  any other method, they can be overloaded. With the exception of the keyword **me** and the visibility (a package method can *only* be either public or  private) package methods are described in the same way as **instance methods**. 
603
604 @image html /dev_guides/cdl/images/cdl_image010.png "Contents of a package" 
605 @image latex /dev_guides/cdl/images/cdl_image010.png "Contents of a package" 
606
607
608 The example of the package below includes some of the basic data structures: 
609
610 ~~~~~
611 package Collection 
612         uses 
613         Standard 
614         is 
615 exception NoSuchObject inherits Failure; 
616 exception NoMoreObject inherits Failure; 
617 generic class SingleList; 
618 generic class Set; 
619 end Collection; 
620 ~~~~~
621
622 Note that the class *Set* is declared after the declarations of the *NoSuchObject* and *NoMoreObject*  exceptions and the *SingleList* class of which Set is a client. In the same way, the classes *Failure*, *Persistent*, and the exception *NoSuchObject* are defined before they are used. They are  defined in the *Standard* package, which appears after the keyword **uses**. 
623
624 @subsubsection occt_cdl_3_3_2    Name space
625
626 The **name space** or  **scope** of a class extends from the beginning of its declaration up to the  end of the package in which it appears. 
627
628 Sometimes, two classes,  which come from separate packages, are both visible to a third package and  carry the same name. For example, there might be two different classes both  called “Window” in a screen generator package and in an architectural package.  As a client of a data type, you can find yourself in the position of having to  remove the ambiguity over the origin of this type; you do this by means of the  keyword **from**.
629  
630
631 ~~~~~
632 -- class-name ::= identifier [from package-name] 
633 -- exception-name ::= identifier [from package-name] 
634 -- enumeration-name ::= identifier [from package-name] 
635 ~~~~~
636
637 You can use the keyword **from** everywhere the name of a class, exception, or enumeration appears. As a  consequence, as a client of the class “Window” you could write wherever  necessary: 
638
639 ~~~~~
640 Window from ScreenGenerator 
641 -- or 
642 Window from ArchitecturalFeatures 
643 ~~~~~
644
645 **Note** that within the description of a package the keyword **from** must be used when referencing any data type  that is not defined in this package.
646
647 Here is a further  example: 
648
649 ~~~~~
650 class Line from Geom 
651 uses 
652         Point from Geom2d, 
653         Point from Geom3d 
654 is 
655         -- class definition  using Point from AppropriatePackage wherever Point  appears 
656 end; 
657 ~~~~~
658
659 @subsubsection occt_cdl_3_3_3     Declaration of classes
660
661 You cannot describe a  package in one single file. You need to describe it in different units and send  them separately to the CDL compiler. Each compilation unit can contain the  declaration of a class or of a package. When you describe a class in a unit  different than that, which describes its package, you need to specify which  package the class belongs to. You do this using the keyword **from**. 
662
663 If the **from** clause  appears in the **uses** clause of the package, it does not need to be  repeated elsewhere. 
664
665 The following example  takes the package “Collection” which was presented above, but this time it is  divided into three compilation units. 
666
667 ~~~~~
668 -- First compilation unit, the package “Collection” : 
669 package Collection 
670         uses 
671         Standard 
672         is 
673 exception  NoMoreObject inherits Failure from Standard; 
674 exception NoSuchObject inherits Failure from Standard; 
675 generic class SingleList; 
676 generic class Set, Node, Iterator; 
677 end Collection; 
678 -- Second compilation unit, the class “SingleList” : 
679 generic class SingleList from Collection (Item as 
680 Storable) 
681         inherits 
682                 Persistent from Standard 
683                 raises 
684                 NoSuchObject from  Collection 
685                 is 
686                 -- definition of the  SingleList class 
687         end SingleList; 
688 -- Third compilation unit, the class “Set” : 
689 generic class Set from Collection (Item as Storable) 
690         inherits 
691                 Persistent from Standard; 
692         raises 
693                 NoSuchObject from Collection, 
694                 NoMoreObject from  Collection 
695                 private class Node  instantiates SingleList 
696                 from Collection  (Item); 
697  end Set; 
698 ~~~~~
699
700 NOTE 
701 It is not explicitly stated that the *Node* class  belongs to the *Collection* package. In fact any nested class necessarily  belongs to the package of the class, which encompasses it. 
702
703 Note that a package can  hide certain classes (just as it can hide methods) by declaring them **private**.  To make a class private, you prefix its description with the keyword **private**.  In the example of the *Collection* package, the *SingleList* class serves only  to implement the *Set* class. It is recommended to make it private. You write  this as in the following syntax: 
704
705
706 **Example** 
707 ~~~~~
708 package Collection 
709         uses 
710         Standard 
711         is 
712 generic class Set,  Node, Iterator; 
713 private generic class SingleList; 
714 exception NoMoreObject inherits Failure from Standard; 
715 end Collection; 
716 ~~~~~
717
718
719
720 @subsection occt_cdl_3_4   Other Data Types
721
722 The other data types are: 
723   * Enumerations
724   * Imports
725   * Aliases
726   * Exceptions
727   * Pointers
728
729 @subsubsection occt_cdl_3_4_1     Enumerations
730
731 The **enumerated types** are  the second type, which is manipulated by value. Unlike the primitive types they  are extensible because they are defined by the user under the form of  enumerations. An enumeration is an ordered sequence of named whole constant  values called enumeration constants. 
732
733 **Example** 
734 ~~~~~
735 declaration-of-an-enumeration ::= 
736 enumeration enumeration-name 
737 is identifier {’,’ identifier} 
738 [end [enumeration-name]]’;’ 
739 enumeration-name ::= identifier 
740 ~~~~~
741 The declaration of an  enumeration creates an enumerated type. An object of this type can successively  take the value of any one of the constants cited in the list. 
742
743 **Example** 
744 ~~~~~
745 enumeration MagnitudeSign is Negative, Null, Positive; 
746 ~~~~~
747
748 Inside a package, two  enumeration constants cannot have the same name, even if they belong to  different enumerated types.
749  
750 **Example** 
751 ~~~~~
752 enumeration Cars is 
753         Honda, 
754         Ford, 
755         Volkswagen, 
756         Renault 
757 end; 
758 enumeration AmericanPresidents is 
759         Nixon, 
760         Reagan, 
761         Ford, -- Error: ‘Ford’ already defined 
762         Carter 
763 end; 
764 ~~~~~
765
766 @subsubsection occt_cdl_3_4_2    Imports
767
768 An **imported type** is  one of which which has not been defined in CDL. It is up to the supplier of  this data type to ensure compatibility with the CDL language by providing  services which allow CDL to recognize the imported data type. 
769
770 The CDL syntax for  declaring an imported type is: 
771 ~~~~~
772 declaration-of-an-imported-type::=[private] imported  typename ; 
773 ~~~~~
774
775 Let us try to define an imported type:
776
777 * In the *MyPack.cdl* file, you declare the imported type:
778 ~~~~~ 
779 package MyPack 
780         .... 
781         imported MyImport; 
782         .... 
783         end Mypack; 
784 ~~~~~   
785 * In the *MyPack_MyImport.hxx* file, you write the following C++ code: 
786 ~~~~~
787 #ifndef _MyPack_MyImport_HeaderFile 
788 #define _MyPack_MyImport_HeaderFile 
789 #include Standard_Type.hxx 
790 typedef unsigned long MyPack_MyImport; 
791 extern const Handle(Standard_Type)&amp; TYPE 
792 (MyPack_MyImport); 
793 ~~~~~
794 * In the *MyPack_MyImport.cxx* file, you write the following C++ code: 
795 ~~~~~
796 #ifndef _MyPack_MyImport_HeaderFile 
797 #include MyPack_MyImport.hxx 
798 #endif 
799 const Handle(Standard_Type)&amp; TYPE (MyPack_MyImport) 
800
801         static Handle(Standard_Type) _aType = 
802                 new Standard_Type  (“MyPack_MyImport”,sizeof 
803                 (MyPack_MyImport)) 
804                  return _aType; 
805         } 
806 ~~~~~
807
808 Then, add the names of  these two files <i>(MyPack_MyImport.hxx, MyPack_MyImport.cxx)</i> to a file called  FILES in the src subdirectory of the package. If the file does not exist you  must create it. 
809
810
811 @subsubsection occt_cdl_3_4_3    Aliases
812
813 An **alias** is an  extra name for a type, which is already known. It is declared as in the  following syntax: 
814
815 ~~~~~
816 declaration-of-an-alias::= [private] alias type1 is type2  [from apackage] ; 
817 ~~~~~
818
819 **Example** 
820 ~~~~~
821 alias Mass is Real; 
822 ---Purpose: 
823 -- Defined as a quantity of matter. 
824 -- Gives rise to the  inertial and 
825 -- gravitational  properties of a body. 
826 -- It is measured in  kilograms. 
827 ~~~~~
828
829 Having defined *Mass* as  a type of *Real*, you can use either *Mass* or *Real* to type an  argument when defining a method. 
830
831
832 @subsubsection occt_cdl_3_4_4     Exceptions
833
834 In the model recommended  by CDL, the principal characteristic of errors is that they are treated in a  different place from the place where they appear. In other words, the methods  recovering and those raising a given exception are written independently from  each other. 
835
836 Subsequently this poses  the problem of communication between the two programs. The principle adopted  consists in viewing the exception as both a class and an object. The exception  class (by means of one of its instances) is used to take control of an  exception, which has been raised. 
837
838 Consequently, error conditions  are defined by means of **classes of exceptions**. Exception classes are  arranged hierarchically so as to be able to recover them in groups. They are  all descendents of a single root class called *Failure*, and it is at the level  of this class that the behavior linked to the raising of exceptions is  implemented. 
839 ~~~~~
840 declaration-of-an-exception ::=exception exception-name inherits exception-name 
841 ~~~~~
842
843 All exceptions share identical behavior, that of the  class *Failure*. Here are some examples of exception classes: 
844 ~~~~~
845 exception NumericError inherits Failure; 
846 exception Overflow inherits NumericError; 
847 exception Underflow inherits NumericError; 
848 ~~~~~
849
850 The use of exceptions as  a means to interrupt the normal execution of one program and then take control  of another one depends on the programming language used to implement the  methods. See the following chapter <a href="#occt_cdl_4">“Defining the Software Components”</a>  on page 32. 
851
852
853 @subsection occt_cdl_3_5   Schemas
854
855 The purpose of a **schema** is to list persistent data types, which will be stored in files by the  application. A schema groups together persistent packages. A persistent package  is one, which contains at least one persistent class. 
856
857 ~~~~~
858 declaration-of-a-schema ::= 
859 schema SchemaName 
860 is 
861 {package PackageName;} 
862 {class ClassName;} 
863 end;
864 ~~~~~
865  
866 For example 
867 ~~~~~
868 schema Bicycle 
869 ---Purpose: Defines the Bicycle schema. 
870 is 
871 package  FrameComponents; 
872 package WheelComponents; 
873 end; 
874 ~~~~~
875
876
877 **Note** that it is  unnecessary to specify all the dependencies of the packages. It is sufficient  to specify the highest level ones. The others on which they depend are  automatically supplied. 
878
879 @subsection occt_cdl_3_6   Executables
880
881 The purpose of an **executable** is to make an executable program without a front-end. It can be used to  test more than one package at a time. An executable is written in a .cdl file  as a set of packages. 
882 **Example** 
883 ~~~~~
884 definition-of-an-executable ::= 
885         executable ExecutableName 
886         is 
887
888 executable ExecutablePart 
889         [uses  [Identifier as external] 
890         [{’,’  Identifier as external}] 
891         [UnitName as  library] 
892         [{’,’  UnitName as library}] 
893         is 
894         {FileName  [as C++|c|fortran|object];} 
895         end; 
896         } 
897 end; 
898 ~~~~~
899
900 **Example** 
901 ~~~~~
902 executable MyExecUnit 
903         ---Purpose: 
904         -- Describes the  executable MyExecUnit 
905         is 
906         executable myexec 
907         -- the binary file 
908         uses 
909         Tcl_Lib as external 
910         is 
911         myexec; 
912         -- the C++ file 
913         end; 
914         -- several binaries can be specified in one .cdl file. 
915         executable myex2 
916         is 
917         myex2; 
918 end; 
919 end; 
920 ~~~~~
921
922 @section occt_cdl_4 Defining the Software Components
923
924 @subsection occt_cdl_4_1   Behavior
925
926 The behavior of an  object class is defined by a list of **methods**, which are either **functions** or **procedures**. Functions return an object, whereas procedures only  communicate by passing arguments. In both cases, when the transmitted object is  an instance manipulated by a handle, its identifier is passed. There are three  categories of methods: 
927
928 * **Object constructor** Creates an instance of the described class. A  class will have one or more object constructors with various arguments or none. 
929 * **Instance method** Operates on the instance which owns it. 
930 * **Class method** Does not work on individual instances, only on the class itself. 
931
932 @subsubsection occt_cdl_4_11    Object  Constructors
933
934 A constructor is a  function, which allows the **creation of instances** of the class it  describes. 
935
936 ~~~~~
937 constructor-declaration ::= 
938 Create [ simple-formal-part ] declaration-ofconstructed-type 
939 [ exception-declarations ] 
940 simple-formal-part ::= 
941 ’(’  initialization-parameter {’;’ initialization parameter}’)’ 
942 initialization-parameter ::= 
943 identifier {’,’ identifier} ’:’ parameter-access  datatype 
944 [ ’=’ initial-value ] 
945 parameter-access ::= 
946 mutable | [ immutable ] 
947 initial_value ::= 
948 numeric-constant | literal-constant | named-constant 
949 declaration-of-constructed-type ::= 
950 returns [ mutable ] class-name 
951 ~~~~~
952
953 The name of the  constructors is fixed: “Create”. The object returned by a constructor is  always of the type of the described class. If that type is manipulated by a  handle, you *must* declare it as **mutable**, in which case the content  of the instance it references is accessible for further modification. 
954
955 For example, the  constructor of the class “Point” 
956 ~~~~~
957 Create (X, Y, Z : Real) 
958 returns mutable  Point; 
959 ~~~~~
960
961 With the exception of  the types predefined by the language, all types of initialization parameters *must* appear in the **uses** clause of the class of which the constructor is a  member. 
962
963 When an initialization  parameter is of a type which is manipulated by a handle, an access right *must* be associated with it so as to express if the internal representation of  the referenced object is modifiable (**mutable**) or not (**immutable**).  The default option is **immutable**. Let, for example, take the constructor of the  persistent class “Line”. 
964
965 ~~~~~
966 Create (P : mutable Point; D : mutable Direction) 
967 returns mutable  Line; 
968 ~~~~~
969
970 In the above example “P”  and “D” must be mutable because the constructor stores them in the internal  representation of the created line, which is mutable itself. An alternative  would be to accept immutable initialization parameters and then copy them into  the constructor in a mutable form. 
971
972 The parameters of a  native type can have a default value: this is expressed by assigning a constant  of the same type to the parameter concerned. Parameters, which have a default  value, may not be present when the call to the constructor is made, in which  case they take the value specified in the declaration. For this reason, they  must all be grouped at the end of the list. Let, for example, take the constructor of the  persistent class “Vector”. 
973
974 ~~~~~
975 Create (D : mutable Direction; M : Real = 1.0) 
976 returns mutable  Vector; 
977 ~~~~~
978
979 A class can have many  constructors (in this case, you say they are **overloaded**) provided that  they differ in their syntax and that the presence of parameters having default  values does not create ambiguities. 
980
981 The restrictions on  their use are expressed by a list of **exceptions** against which each  constructor is protected. 
982
983 Each class must have at  least one constructor to be able to create objects of its type. 
984
985 @subsubsection occt_cdl_4_1_2     Instance Methods
986
987 An instance method is a  function or procedure, which applies to any instance of the class, which  describes it. 
988
989 **Example** 
990 ~~~~~
991 declaration-of-an-instance-method ::= identifier formal-part-of-instance-method 
992 [  declaration-of-returned-type ] 
993 [  exception-declaration ] 
994 formal-part-of-instance-method  ::=  ’(’ me [’:’  passing-mode parameter-access ] {’;’ parameter}’)’ 
995 parameter ::= identifier {’,’  identifier} ’:’ passing-mode 
996 parameter-access 
997 data-type [ ’=’ initial-value ] 
998 passing-mode ::= [ in ] | out | in  out 
999 parameter-access ::= mutable |  [immutable] 
1000 declaration-of-returned-type  ::= returns  return-access data-type 
1001 return-access ::= mutable |[ immutable  ]| any 
1002 ~~~~~
1003
1004 The name **me** denotes  the object to which the method is applied: you call this the “principal object”  of the method. The passing mode expresses whether the direct content of the  principal object or a parameter is either: 
1005
1006   * read
1007   * created and returned
1008   * read then updated and  returned by the method.
1009
1010 Remember that the direct  content of an argument of a type which is manipulated by value contains the  internal representation of the object itself. Thus, when the argument is of  this type, **out** and **in out** mean that the content of the object will  undergo a modification. When the method is a function (as is the case for  constructors), all the arguments must be **in** (read). This is the default  mode. 
1011
1012 In case of an argument  of a type manipulated by a handle, the direct content being an object identifier,  the passing mode addresses itself to the handle, and no longer to the internal  representation of the object, the modification of which is controlled by the  access right. An argument of this type declared **mutable** may see its  internal representation modified. If declared **immutable**, it is  protected. When a parameter is both **in out** and **mutable**, the  identifiers passed and returned denote two distinct modifiable objects. 
1013
1014 When the returned object  is manipulated by a handle it can be declared modifiable or not, or  indeterminate (**any**). To return an object with an indeterminate access  right means that the method transmits the identifier without changing its state  and that the method has no right to alter the access right. This functionality  is particularly useful in the case of collections; temporarily storing an  object in a structure and unable to modify its state. 
1015
1016 With the exception of  the types predefined by the language, all types of parameters and returned  objects, whether manipulated by a handle or by value, *must* appear in the  **uses** clause of the class of which the method is a member. 
1017 As is the case for  constructors, some parameters can have a default value, provided that they are  of primitive or enumerated type. They are passed in the **in** mode, and  they are found at the end of the list of arguments. 
1018
1019 Overloading of instance  methods and use of exceptions and post-conditions is allowed and respects the  same rules than constructors. 
1020
1021 Note the overloading of  “Coord” in the following example of instance methods associated with the  persistent class “Point”: 
1022
1023 ~~~~~
1024 Coord (me; X, Y, Z : out Real); 
1025 ---Purpose: returns the coordinates of me 
1026
1027 Coord (me; i : Integer) returns Real; 
1028 ---Purpose: returns the abscissa (i=1), the 
1029 -- ordinate (i=2) or the value (i=3) of  me 
1030
1031 SetCoord (me : mutable; X, Y, Z : Real); 
1032 ---Purpose: modifies the coordinates of me 
1033
1034 Distance (me; P : Point) returns Real 
1035 ---Purpose: returns the distance to a point 
1036 ~~~~~
1037
1038 In all these cases, **me** is implicitly an object of type *Point*. Only “SetCoord” is able to modify  the internal representation of a point. 
1039
1040 @subsubsection occt_cdl_4_1_3    Class  Methods
1041
1042 A class method is a  function or procedure relative to the class it describes, but does not apply to  a particular instance of the class. 
1043
1044 ~~~~~
1045 declaration-of-a-class-method ::= identifier formal-part-of-class-method 
1046 [ declaration-of-returned-type ] 
1047 [ exception-declaration ] 
1048 formal-part-of-class-method ::= ’(’ myclass {’;’ parameter}’)’ 
1049 ~~~~~
1050
1051 The first parameter **myclass** indicates that the method does not apply to a previously created instance,  but to the class itself. The rest of the syntax is identical to that of the  instance methods. In particular, access rights (**mutable**, **immutable**,  **any**) and the argument passing mode (**in**, **out**, **in out**)  must remain unchanged. With the exception of the types predefined by the  language, all types of parameters must appear in the **uses** clause of the  class of which the method is a member. Overloading of class methods and the use  of exceptions and post-conditions is allowed, and it follows the same rules as  for constructors and instance methods. 
1052
1053 Examples of class  methods associated with the class “Real”: 
1054
1055 ~~~~~
1056 First (myclass) returns Real; 
1057 ---Purpose: returns lower limit of reals 
1058
1059 Last (myclass) returns Real; 
1060 ---Purpose: returns upper limit of reals 
1061 ~~~~~
1062
1063 @subsubsection occt_cdl_4_1_4    Package  Methods
1064
1065 Package methods are  methods which are members of a package. They are frequently used for library or  application initialization, or for offering an application programming  interface to the sources to the package. They are sometimes methods used for  development purposes but which are not made available to final end-users of the  package. 
1066
1067 ~~~~~
1068 package-method ::= identifier  [simple-formal-part][returned-type-declaration] 
1069 [exception-declaration] 
1070 [is private]’;’ 
1071 ~~~~~
1072
1073 @subsubsection occt_cdl_4_1_5     Sensitivity to Overloading
1074
1075 When there is more than  one method of a class, several methods share the same name but have different  syntax, you say the method is overloaded. 
1076
1077 In order that the  methods can be considered distinct, they must differ either in the number of  parameters, or one of their parameters must be of a different type. In  particular, you *cannot* overload a method if you merely modify it as  follows: 
1078
1079   * The type of the returned  object when the method behaves as a function
1080   * The name or the mode of  passing a parameter (**in**, **out**, or **in out**) 
1081   * The mutability of passed  objects (**mutable**, **immutable**, **any**) 
1082   * Default value of a parameter.
1083   
1084 @subsection occt_cdl_4_2   Internal Representation
1085
1086 Each object contains its  own state in a private space in the memory. This state consists of a set of **fields**, which include or reference other objects. 
1087
1088 **Example** 
1089 ~~~~~
1090 declaration-of-the-internal-representation-of-a-class ::= fields field {field} 
1091 field ::= identifier {’,’ identifier} ’:’ data-type [’[’integer {’,’integer}’]’]’;’ 
1092 ~~~~~
1093
1094 A copy of all the  defined fields exists locally in each instance of the class. This group of  fields will be initialized by the class constructors when the object is  instantiated. 
1095
1096 Fields *must not* have  the same name as any method of the class in which they appear. When the field  type is followed by a list of integer constants between square brackets, the  data will take the form of a multi-dimensional array containing objects of this  type. 
1097
1098 The following example  shows two equivalent ways of describing three fields of the “Real” type: 
1099
1100 **Example** 
1101 ~~~~~
1102 fields 
1103 x, y, z: Real; 
1104 coord: Real[3]; 
1105 ~~~~~
1106
1107
1108 Depending on their type,  Object fields have one of the two forms. When the field is of the “manipulated  by handle” type, it corresponds to an identifier. In this case, the contents of  the object can be shared by other objects or by a handle in a program. When the  field is of a “manipulated by value” type, it contains the value of the object.  In this case you say the object is **embedded**. 
1109
1110 @subsection occt_cdl_4_3   Exceptions
1111   
1112 Exceptions describe  exceptional situations, which can arise during the execution of a method. With  the raising of an exception, the normal course of program execution is  interrupted. The actions carried out in response to this situation are called   treatment of exception. 
1113 ~~~~~
1114 exception-treatment ::= raises exception-name  {’,’ exception-name} 
1115 ~~~~~
1116 Each exception name  corresponds to a class of exceptions previously defined as being susceptible to  being raised by the method under which it appears. Exception classes must all  appear in the **raises** clause of the class of which the method is a member.  The class of exceptions is analogous to the class of objects described in this  manual. 
1117
1118 Take for example the  method which returns the x, y, or z coordinate of a point. 
1119
1120 ~~~~~
1121 Coord (me; i : Integer) returns Real 
1122 ---Purpose: 
1123 -- Returns the abscissa (i=1) 
1124 -- the ordinate (i=2) 
1125 -- or the value (i=3) 
1126 -- of me. 
1127 raises OutOfRange; 
1128 -- if i is not equal to 1, 2, or 3. 
1129 ~~~~~
1130
1131
1132 Instance methods are  likely to raise certain exceptions called **systematic exceptions** which do  not have to appear. They are: 
1133
1134 * *NullObject* - raised when the principal object does not exist. 
1135 * *ImmutableObject* - raised when a method tries to modify an immutable  principal object. 
1136 * *TypeMismatch* - raised if an argument typed by association is of  an unsuitable type. 
1137
1138 These exceptions are described  in the Standard Package (System Toolkits). 
1139
1140
1141 @subsection occt_cdl_4_4   Inheritance
1142
1143 @subsubsection occt_cdl_4_4_1     Overview
1144
1145 The notion of  inheritance comes from a development strategy according to which you begin by  modeling data in the most general fashion. Then you specialize it more and more  so as to correspond to more and more precise cases. 
1146
1147 For example, to develop  a basic geometry, you can first of all consider the group of geometric objects,  and then differentiate the points, vectors, and curves. You can specialize the  latter into conic sections, and then decompose them into circles, ellipses, and  hyperbolas. Then, the class of conics is considered as a sub-class of curves,  and a super-class of circles. 
1148
1149 A sub-class has at least  the behavior of its super-classes. Thus, a circle could be viewed as a conic, a  curve, or even as a geometric object. In each case, the applicable methods  belong to the level where you view the class. In this case, you say that the  sub-class inherits the behavior from its super-classes. 
1150
1151
1152 **Example** 
1153 ~~~~~
1154 declaration-of-a-sub-class ::= class class-name 
1155 inherits class-name 
1156 [uses data-type {’,’ data-type}] 
1157 [raises exception-name {’,’ exception-name}] 
1158 is class-definition 
1159 end [class-name]’;’ 
1160 ~~~~~
1161
1162 A class cannot inherit  one of its descendent classes; nor can it inherit a native type. All the  classes of a system can be described in a non-cyclic diagram called the **inheritance  graph**. 
1163
1164 The definition of a  sub-class is identical to that of a simple class. Note that a super-class must  not appear in the **uses** clause of the sub-class, even if it appears  in the definition of the sub-class. The behavior of a sub-class includes as a  minimum all  instance methods and protected methods of its super-classes. 
1165
1166 **Note** that constructors and class methods are never  inherited. 
1167
1168 @subsubsection occt_cdl_4_4_2     Redefining methods
1169
1170 Certain inherited  methods can be redefined. 
1171
1172 **Example** 
1173
1174 ~~~~~
1175 declaration-of-a-redefined-method ::= identifier formal-part-of-instance-method [returnedtype- declaration] 
1176 [declaration-of-exceptions] 
1177 is redefined [visibility]’;’ 
1178 ~~~~~
1179
1180 A redefined method must conform  to the syntax described in the super-class where it appears. The exceptions  contained in the super-class can be renewed, and others may be added as long as  they inherit from an ancestor class. 
1181
1182 The redefined attribute  can be applied neither to a constructor, nor to a class method, since neither  of them can be inherited. If the redefined method is private or protected, the  visibility must be exactly repeated in the redefinition. For further details on  visibility, refer to <a href="#occt_cdl_4_6"> Visibility </a> section. 
1183
1184
1185 **Example** 
1186 ~~~~~
1187 SquareDistance (me; P : Point) returns Real 
1188 is redefined private; 
1189 ~~~~~
1190
1191 With regards to the  internal representation, all fields defined in the super-classes are, by  default, inherited, but they can also be redefined. 
1192
1193 @subsubsection occt_cdl_4_4_3 Non-redefinable methods
1194
1195 Instance methods, which  are declared virtual are redefinable in descendent classes, and you can force  this redefinition by making a method **deferred**. For more details, see the  next section.
1196  
1197 **Example** 
1198
1199 ~~~~~
1200 declaration-of-a-non-redefinable-method ::= identifier formal-part-of-instance-method [returnedtype- declaration] 
1201 [declaration-of-exceptions] 
1202  is virtual [visibility]’;’ 
1203 ~~~~~
1204
1205 All methods are static  by default. To enable redefinition in all the child classes, add **is virtual** when declaring the method. 
1206
1207 You must also be able to  forbid redefinition. A redefinable method can become non-redefinable if you  declare: **is redefined static**. 
1208
1209
1210 @subsubsection occt_cdl_4_4_4 Deferred Classes and Methods
1211
1212 The presence of certain  classes in the inheritance graph can be justified purely by their ability to  force certain behavior on other classes, in other words, to make other classes  provide various services. 
1213
1214 The CDL language allows  you to describe a class, which introduces methods without implementing them, so  as to force its descendent classes to define them. These are called **deferred  classes**; the non-implemented methods are also termed **deferred methods**. 
1215
1216
1217 **Example** 
1218 ~~~~~
1219 declaration-of-a-deferred-class ::= deferred class class-name 
1220 [inherits class-name [uses data-type {’,’ data-type}] 
1221 [raises exception-name {’,’ exception-name}] 
1222 is class-definition 
1223 end [class-name]’;’ 
1224 declaration-of-a-deferred-method ::= identifier formal-part-of-instance-method [returnedtype- declaration] 
1225 [declaration-of-exceptions] 
1226 is deferred [visibility]’;’ 
1227 ~~~~~
1228
1229 Only instance methods  can be deferred. 
1230
1231 It is sufficient for a class to contain one deferred  method for it to be a deferred class. It can contain any number of deferred  methods (or none). 
1232
1233 A deferred class may  still have an internal representation but one or more **non-protected** constructors  would be necessary to initialize them. The constructors must be visible in the  sub-classes. 
1234
1235 The constructors of a  deferred class are called **Initialize** (not **Create**). They are **protected** by default, and do not return any object. You cannot create an object of a  deferred class type. 
1236 For example, consider  the class *Point*, and its declaration as deferred. 
1237
1238 **Example** 
1239 ~~~~~
1240 deferred class Point inherits Geometry is 
1241 Initialize; 
1242 ---Purpose: Initializes the point. 
1243 Coord (me; X, Y, Z : out Real) 
1244 ---Purpose: Returns the coordinates 
1245 is deferred; 
1246 SetCoord (me : mutable; X, Y, Z : Real) 
1247 ---Purpose: Modifies the coordinates 
1248 is deferred; 
1249 Distance (me; P : Point) returns Real; 
1250 ---Purpose: Returns the distance from the point P 
1251 end Point; 
1252 ~~~~~
1253
1254 Notice that the function  *Distance* is not deferred. Although this class contains no representation,  this method is programmable by calling *Coord*. 
1255
1256 In a sub-class of a  deferred class, all deferred methods, which have been inherited, must be  implemented, then redeclared (the attribute **redefined** is useless for  this purpose), unless the sub-class is itself deferred. 
1257
1258 A non-deferred method  can be redefined as a deferred one, in which case it will be declared as  follows: **is redefined deferred**. 
1259
1260 The notion of deferred  class is very useful. The advantage of introducing it, as was previously shown  in the deferred class *Point*, is that the corresponding resources will be  available even before being implemented. Later, you can add different  representations to Point (for example, spherical or Cartesian coordinates)  without having to modify client programs. 
1261
1262 Thanks to the  possibility of redefining methods, this approach does not have any negative  impact on performance: a method implemented at the level of a deferred class  can be reprogrammed in one of its sub-classes while taking into account the  data representation. 
1263
1264 @subsubsection occt_cdl_4_4_5     Declaration by Association
1265
1266 At the heart of a class  hierarchy, object identifiers are compatible in the ascendant sense. Since the  *Conic* class is descended from the *Curve* class, an identifier of type *Curve* can  reference an object of type *Conic* (remember that the behavior of *Curve* is  applicable to *Conic*). In other words, you can assign a reference to a *Conic* to an identifier of type *Curve*, but not vice versa. 
1267
1268 For example, once the  classes have been compiled you could write a C++ test program in which you  instantiate a Conic but reference it with a handle to a Curve: 
1269 ~~~~~
1270 Handle(Curve) c = new Conic 
1271 ~~~~~
1272 This same rule applies  to parameters of methods; that is to say, you can call a method with  identifiers corresponding to a sub-type of that specified in its declaration.  To illustrate this, let us go back to the “Distance” method of the “Point” class: 
1273
1274 ~~~~~
1275 Distance (me; P : point) returns Real; 
1276 ~~~~~
1277 Conforming to the rule  of type compatibility, you could make a call to the method “Distance” with  reference to an object from a class descended from “Point”. Consequently, if  “SphericPoint” is a sub-class of “Point” and therefore inherits this method, it  will be possible to calculate the distance between two “SphericPoint”, or  between a “SphericPoint” and a “Point”, without having to redefine the method. 
1278
1279 On the other hand,  sometimes you may want to force two parameters to be exactly of the same type,  and thus not apply the rule of type compatibility. To do this, you need to  associate the type of the concerned parameters in the method declaration. 
1280
1281 ~~~~~
1282 association-typing ::= like associated-parameter 
1283 associated-parameter ::= me | identifier 
1284 ~~~~~
1285
1286 Note that identifier is the name of a parameter, which appears first in the formal part of the declaration of the method.
1287
1288
1289 You can use this  technique, which consists in declaring by association, to declare a method that  will exchange the content of two objects, or a method, which copies another  object: 
1290
1291 ~~~~~
1292 Swap (me : mutable; With : mutable like me); 
1293 DeepCopy (me) returns mutable like me; 
1294 ~~~~~
1295
1296 Make sure not to  write the Swap method as in the syntax below: 
1297
1298
1299 ~~~~~
1300 Swap (me : mutable; With : mutable Point); 
1301 ~~~~~
1302
1303 In this case **me** may  be a CartesianPoint or a SphericalPoint, while *With* can only be a Point. 
1304
1305 @subsubsection occt_cdl_4_4_6     Redefinition of Fields
1306
1307 The creation of a  hierarchy of classes should be viewed as a means to specialize their behavior,  (e.g. a circle is more specialized than a conic section). The more you  specialize the object classes, the more it is justified to call into question  the inherited fields in order to obtain greater optimization. So, in the  description of the internal representation of a sub-class, it is possible not  to inherit all of the fields of the super-classes. You then say the fields have  been redefined. 
1308
1309 ~~~~~
1310 redefinition-of-the-representation-of-a-class ::= redefined redefinition-of-a-field {’,’ redefinition-of-a- 
1311 field}’,’ 
1312 redefinition-of-a-field ::= [field-name] from [class] class-name 
1313 ~~~~~
1314
1315 Redefinition of fields  can only be done in classes manipulated by a handle. 
1316
1317 This declaration appears  at the beginning of the definition of the internal representation of the  sub-class, which breaks the field inheritance. The non-inherited fields are all  those which come from the class specified behind the rubric **from**. 
1318
1319
1320 @subsection occt_cdl_4_5   Genericity
1321
1322 @subsubsection occt_cdl_4_5_1     Overview
1323
1324 Inheritance is a  powerful mechanism for extending a system, but it does not always allow you to  avoid code duplication, particularly in the case where two classes differ only  in the type of objects they manipulate (you certainly encounter this phenomenon  in all basic structures). In such cases, it is convenient to send arbitrary  parameters representing types to a class. Such a class is called a **generic  class**. Its parameters are the generic types of the class. 
1325
1326 Generic classes are  implemented in two steps. You first declare the generic class to establish the  model, and then instantiate this class by giving information about the generic  types. 
1327
1328 @subsubsection occt_cdl_4_5_2     Declaration of a Generic Class
1329
1330 The syntax is as  follows: 
1331
1332 ~~~~~
1333 declaration-of-a-generic-class ::= [deferred] generic class class-name  ’(’generic-type {’,’generic-type}’)’ 
1334 [inherits class-name 
1335 [uses data-type {’,’ data-type}] 
1336 [raises exception-name {’,’ exception-name}] 
1337         is class-definition 
1338         end [class-name]’;’ 
1339 generic-type ::= identifier as type-constraint 
1340 type-constraint ::= any | class-name [’(’data-type {’,’data-type}’)’] 
1341 ~~~~~
1342
1343 The names of generic  types become new types, which are usable in the definition of a class, both in  its behavior (methods) and its representation (fields). The generic type is  only visible inside the generic class introducing it. As a result, it is  possible to have another generic class using the same generic type within the  same package. 
1344
1345 When you specify the  type constraint under the form of a class name, you impose a minimum set of  behavior on the manipulated object.  
1346
1347 This shows that the  generic type has as a minimum the services defined in the class. This can be  any kind of a previously defined class, including another generic class, in  which case you state exactly with what types they are instantiated. 
1348
1349 When the generic type is  constrained by the attribute **any**, the generic class is intended to be  used for any type at all, and thus corresponds to classes whether manipulated  by a handle or by value. 
1350
1351 No class can inherit  from a generic class. 
1352
1353 A generic class can be a  deferred class. A generic class can also accept a deferred class as its  argument. In both these cases any class instantiated from it will also be  deferred. The resulting class can then be inherited by another class. 
1354
1355 Below is a partial  example of a generic class: a persistent singly linked list.
1356  
1357 ~~~~~
1358 generic class SingleList (Item as Storable) 
1359         inherits Persistent 
1360         raises NoSuchObject 
1361         is 
1362         Create returns mutable SingleList; 
1363     ---Purpose: Creates an empty list 
1364         IsEmpty (me) returns  Boolean; 
1365                 ---Purpose: Returns true if the list me is  empty 
1366         SwapTail (me :  mutable; S : in out mutable 
1367         SingleList) 
1368                 ---Purpose: Exchanges the tail of list me  with S 
1369         -- Exception  NoSuchObject raised when me is empty 
1370         raises NoSuchObject; 
1371            Value (me) returns Item 
1372            ---Purpose: Returns first element of the list  me 
1373         -- Exception NoSuchObject  raised when me is empty 
1374         raises NoSuchObject; 
1375            Tail (me) returns mutable SingleList 
1376         ---Purpose: Returns  the tail of the list me 
1377         -- Exception  NoSuchObject raised when me is empty 
1378         raises NoSuchObject; 
1379            fields 
1380                 Data : Item; 
1381            Next : SingleList; 
1382            end SingleList; 
1383 ~~~~~      
1384
1385 Even though no object of  the type “SingleList” IS created, the class contains a constructor. This class  constitutes a model, which will be recopied at instantiation time to create a  new class which will generate objects. The constructor will then be required. 
1386
1387 **Example** 
1388 ~~~~~
1389 generic class Sequence(Item as any, Node as 
1390 SingleList(Item)) 
1391 inherits Object 
1392 . . . 
1393 end Sequence 
1394 ~~~~~
1395
1396 In the above example,  there are two generic types: *Item* and *Node*. The first imposes no restriction.  The second must at least have available the services of the class *SingleList* instantiated with the type with which *Sequence* will itself be instantiated. 
1397
1398 In the incomplete  declaration of a generic class, the keyword **generic** must appear. 
1399
1400 **Example** 
1401 ~~~~~
1402 generic class SingleList; 
1403 generic class Sequence; 
1404 ~~~~~
1405
1406 @subsubsection occt_cdl_4_5_3     Instantiation of a Generic Class
1407
1408 The syntax is as  follows: 
1409
1410 ~~~~~
1411 instantiation-of-a-generic-class ::= [deferred] class  class-name 
1412      instantiates class-name ’(’data-type {’,’ data-type}’);’ 
1413 ~~~~~
1414
1415 Instantiation is said to  be **static**. In other words, it must take place before any use can be made  of the type of the instantiated class. Each data type is associated term by  term with those declared at the definition of the generic class. These latter  ones, when they are not of the type **any**, restrict instantiation to those  classes, which have a behavior at least equal to that of the class specified in  the type constraint, including constructors. Note that this is not guaranteed  by inheritance itself. 
1416
1417 For example, let’s  instantiate the class *Sequence* for the type *Point*: 
1418
1419 ~~~~~
1420 class SingleListOfPoint instantiates SingleList(Point); 
1421 class Sequence instantiates 
1422         Sequence(Point,SingleListOfPoint); 
1423 ~~~~~
1424
1425 The instantiation of a  generic deferred class is a deferred class (the **deferred** attribute must  be present during instantiation). An instantiated class cannot be declared in  an incomplete fashion. 
1426
1427 @subsubsection occt_cdl_4_5_4    Nested  Generic Classes
1428
1429 It often happens that  many classes are linked by a common generic type. This is the case when a base  structure provides an iterator, for example, in the class *Graph*. A graph is  made up of arcs, which join together the nodes, which reference objects of any  type. This type is generic both for the graph and for the node. In this  context, it is necessary to make sure that the group of linked generic classes  is indeed instantiated for the same type of object. So as to group the  instantiation, CDL allows the declaration of certain classes to be nested. 
1430
1431 **Example** 
1432
1433 ~~~~~
1434 declaration-of-a-generic-class ::=  [deferred] generic class class-name  ’(’generic-type{’,’generic-type}’)’ 
1435    [inherits class-name {’,’ class-name}] 
1436    [uses data-type {’,’ data-type}] 
1437    [raises exception-name {’,’ exception-name}] 
1438    [{[visibility] class-declaration}] 
1439    is class-definition 
1440 end [class-name]’;’ 
1441    class-declaration ::= incomplete-declaration-of-a-class | declaration-of-a-non-generic-class | instantiation-of-a-generic-class 
1442 ~~~~~
1443
1444 **Nested classes**, even though they are described as non-generic  classes, are generic by construction, being inside the class of which they are  a part. As a consequence, the generic types introduced by the **encompassing  class** can be used in the definition of the nested class. This is true even  if the generic type is only used in a nested class. The generic types still must appear as an argument of the encompassing class. All other types used by a  nested class must appear in its **uses** or **raises** clauses,  just as if it were an independent class. 
1445
1446 Nested classes are, by  default, **public**. In other words, they can be used by the clients of the  encompassing class. On the other hand, when one of the nested classes is  declared **private** or **protected**, this class must not appear  in any of the public methods of the other classes. It cannot be used in a  protected field because then it could be used in a sub-class, which implies it  would not be private. 
1447
1448 The following example  shows how to write the Set class with its iterator. 
1449
1450 ~~~~~
1451 generic class Set (Item as Storable) 
1452         inherits Persistent 
1453         private class Node  instantiates SingleList (Item); 
1454         class Iterator 
1455                    uses Set, Node 
1456                    raises  NoSuchObject, NoMoreObject 
1457                    is 
1458                    Create (S : Set)  returns mutable Iterator; 
1459                 ---Purpose: Creates  an iterator on the group S 
1460                    More (me) returns  Boolean; 
1461                 ---Purpose: Returns  true if there are still elements 
1462                    -- to explore 
1463                    Next (me) raises  NoMoreObject; 
1464                 ---Purpose: Passes  to the following element 
1465                    Value (me)  returns any Item raises NoSuchObject; 
1466                 ---Purpose: Returns  the current element 
1467                    fields 
1468                    Current : Node; 
1469                 end Iterator; 
1470                 is 
1471                    Create returns  mutable Set; 
1472                 ---Purpose: Creates  an empty group 
1473                    IsEmpty (me)  returns Boolean; 
1474                 ---Purpose: Returns  true if the group is empty 
1475                    Add (me :  mutable; T : Item); 
1476                 ---Purpose: Adds an  item to the group me 
1477                    Remove (me :  mutable; T : item) raises 
1478                 NoSuchObject; 
1479                 ---Purpose: Removes  an item from the group me 
1480                    etc. 
1481                    fields 
1482                    Head : Node; 
1483         end Set; 
1484 ~~~~~
1485
1486 Note that in their  fields, both “Set” and “Iterator” are clients of another class, “Node”. This  last can be effectively declared **private** for it only appears in fields  which are themselves private. 
1487
1488 The instantiation of a  generic class containing nested classes remains unchanged. The same declaration  is used to instantiate the encompassing class and the nested classes. These  latter will have their name suffixed by the name supplied at instantiation,  separated by “Of”. For example, you instantiate the class “Set” described above  for the type “Point” as follows: 
1489
1490 ~~~~~
1491 class SetOfPoint instantiates Set(Point); 
1492 ~~~~~
1493 In doing so, you  implicitly describe the classes “NodeOfSetOfPoint” and “IteratorOfSetOfPoint”,  which are respectively the result of the concatenation of “Node” and “Iterator”  with “Of” then “SetOfPoint”. 
1494
1495 Note that in the  incomplete declaration of an encompassing class, all the names of the nested  classes *must* appear behind that of the encompassing class. 
1496
1497 ~~~~~
1498 incomplete-declaration-of-a-generic-class ::= [deferred] generic class-name {’,’  class-name}; 
1499 ~~~~~
1500
1501 For example, an incomplete declaration of the above  class “Set” would be as in the example below: 
1502
1503 ~~~~~
1504 generic class Set, Node, Iterator; 
1505 ~~~~~
1506
1507 Only the encompassing  class can be deferred. In the above example only the class “Set” can be  deferred. 
1508
1509
1510
1511 @subsection occt_cdl_4_6   Visibility
1512
1513 @subsubsection occt_cdl_4_6_1     Overview
1514
1515 A field, method, class,  or package method is only available for use if it is **visible**. 
1516 Each of these components  has a default visibility, which can be explicitly modified during class or  package declaration. The three possible states of visibility are: 
1517   * Public
1518   * Private
1519   * Protected
1520
1521 @subsubsection occt_cdl_4_6_2     Visibility of Fields
1522
1523 A field is **private**.  It can never be public - this would destroy the whole concept of data  encapsulation. The attribute **private** is redundant when it is applied to  a field. This means that a field is only visible to methods within its own  class. 
1524 A field can be declared **protected**, which means that it becomes visible in subclasses of its own class. Its  contents can be modified by methods in subclasses. 
1525
1526 ~~~~~
1527 field ::= identifier {’,’ identifier} ’:’ data-type 
1528 [’[’integer{’,’integer}’]’] 
1529 [is protected]’;’ 
1530 ~~~~~
1531
1532 **Example** 
1533
1534 ~~~~~
1535 fields 
1536    Phi, Delta, Gamma : AngularMomenta [3] 
1537    is protected ; 
1538 ~~~~~
1539
1540 @subsubsection occt_cdl_4_6_3     Visibility of Methods
1541
1542 Methods act on fields.  Only methods belonging to a class can act on the fields of the class; this  stems from the principle of object encapsulation. Methods can be characterized  in three ways: by default, methods are **public**. Methods can be declared **private** or **protected** to restrict their usage. 
1543
1544 * **Public** methods are the default and generally the most common. They describe the behavior of a class or a package, and they are  callable by any part of a program. 
1545 * **Private** methods  exist only for the internal structuring of their  class or their package. Private class methods can only be called by methods  belonging to the same class. Private package methods can only be called by all  methods belonging to the same package and its classes. 
1546 * **Protected**  methods are private methods, which are also callable from  the interior of descendent classes.  
1547
1548 If you want to restrict  the usage of a method, you associate with it a visibility as follows : 
1549 ~~~~~
1550 -- declaration-of-the-visibility ::= is visibility 
1551 visibility ::= private | protected 
1552 ~~~~~
1553
1554 The declaration of the  visibility of a method appears at the end of its definition, before the final  semi-colon. The attribute **private** indicates that the method will only be  visible to the behavior of the class of which the method is a member; **protected** will propagate the visibility among the sub-classes of this class. 
1555
1556 For example, add to the  class “Line” an internal method allowing the calculation of the perpendicular  distance to the power of two, from the line to a point. 
1557
1558 ~~~~~
1559 SquareDistance (me; P : Point) returns Real 
1560 is private;
1561 ~~~~~
1562
1563 @subsubsection occt_cdl_4_6_4     Visibility of Classes, Exceptions and Enumerations
1564
1565 The visibility of a  class is the facility to be able to use this class in the definition of another  class. The visibility of a class extends from the beginning of its declaration  up to the end of the package in which it appears. You have seen that the  keyword **uses** allows extension of this visibility to other packages. 
1566
1567 As was explained in the  section on “<a href="#occt_cdl_3_3_2">Name Space</a>”, any ambiguity, which arises from having two classes  with the same name coming from different packages, is dealt with by the use of  the keyword **from**. 
1568
1569 A class declared **private** is only available within its own package. 
1570
1571 @subsubsection occt_cdl_4_6_5    Friend  Classes and Methods
1572
1573 In certain cases,  methods need to have direct access to the private or protected parts of classes  of which they are clients. Such a method is called a **friend** of the  class, which is accessed. For example, you declare a method to be a friend when  a service can only be obtained via the use of another non-descendent class, or  perhaps when this will help to improve performance. 
1574
1575 Classes can also be  declared friends of other classes. In this case all the methods of the friend  class will have access to the fields and methods of the host class. The right  is **not reciprocal**. 
1576
1577 Friend classes or  methods are declared inside the class, which reveals its private and protected  data or methods to them. This helps in managing the continuing evolution of a  class, helping to recognize and to avoid the creation of side effects. 
1578
1579 **Example** 
1580 ~~~~~
1581 declaration-of-friends ::= friends friend {’,’friend} 
1582    friend ::=    identifier from [class] class-name  [formal-part] | 
1583 -- Defining the Software Components 67 
1584 identifier from [package] package-name  [formal-part] | class] class-name 
1585    formal-part ::= simple-formal-part | formal-part-of-instance-method | formal-part-of-class-method 
1586 ~~~~~
1587
1588 The formal part must be present if the method contains one; thus this can be overloaded without  necessarily propagating the friend relationship among its homonyms. The keyword  **class** allows you to avoid certain ambiguities. For example, it removes  any confusion between “method M from class C” and “method M from package P”. 
1589
1590 As an example, take a  method, which calculates the perpendicular distance between a line and a point.  Suppose this method needs to access the fields of the point. In the class  “Point” you would write: 
1591
1592 ~~~~~
1593 friends Distance from Line (me; P : Point) 
1594 ~~~~~
1595
1596 A method can be a friend  to many classes. The class to which the method belongs does not need to  appear in the **uses** clause of other classes of which it is a friend. 
1597
1598 When the methods of a class are all friends  of another class, you can establish the friendship at the level of the class. 
1599
1600
1601 | | Public | Private | Protected |
1602 | :---- | :---- | :---- | :----- |
1603 | Field | Does not exist | **Default** - Visible to methods in its own class and in friend classes | Visible to methods in its own class, sub-classes and friend classes |
1604 | Method | **Default** - Callable anywhere | Callable by methods in its own class and in friend classes | Callable by methods in its own class, sub-classes and friend classes | 
1605 | Class | **Default**  - Visible everywhere with the use of **from** rubric | Visible to classes in its own package | Does not exist | 
1606 | Package method | **Default** - Callable everywhere with the use of **from** rubric | Visible to classes in its own package | Does not exist | 
1607 | Nested Class | **Default** -  Visible to the clients of the encompassing class | Visible to the encompassing class and other classes nested in the encompassing class | Does not exist | 
1608
1609
1610 @section occt_cdl_5 Appendix A. Syntax  Summary
1611
1612
1613 This summary of the CDL  syntax will aid in the comprehension of the language, but does *not* constitute  an exact definition thereof. In particular, the grammar described here accepts  a super-set of CDL constructors semantically validated. 
1614
1615 (1) capital ::= ’A’ | ’B’ | ’C’ | ’D’ | ’E’ | ’F’ | ’G’ | ’H’ | ’I’ | ’J’ | ’K’ | ’L’ | ’M’ | ’N’ | 
1616 ’O’ | ’P’ | ’Q’ | ’R’ | ’S’ | ’T’ | ’U’ | ’V’ | ’W’ | ’X’ | ’Y’ | ’Z’ 
1617
1618 (2) non-capital ::= ’a’ | ’b’ | ’c’ | ’d’ | ’e’ | ’f’ | ’g’ | ’h’ | ’i’ | ’j’ | ’k’ | ’l’ | ’m’ | ’n’ | 
1619 ’o’ | ’p’ | ’q’ | ’r’ | ’s’ | ’t’ | ’u’ | ’v’ | ’w’ | ’x’ | ’y’ | ’z’ 
1620
1621 (3) digit ::= ’0’ | ’1’ | ’2’ | ’3’ | ’4’ | ’5’ | ’6’ | ’7’ | ’8’ | ’9’ 
1622
1623 (4) underscore ::= ’_’ 
1624
1625 (5) special character  ::= ’ ’ | ’!’ | ’”’ | ’#’ | ’$’ | ’%’ | ’&amp;’ | ’’’ | ’(’ | ’)’ | ’*’ | ’+’ | ’,’ | ’-’ | ’.’ | ’/’ | ’:’ | ’;’ | ’’ | ’=’ | ’’ | ’?’ | ’@’ | ’[’ | ’\’ | ’]’ | ’^’ | ’‘’ | ’{’ | ’|’ | ’}’ | ’~’ 
1626
1627 (6) printable  character::= capitals | non-capitals | digits | underscore | special characters 
1628
1629 (7) letter ::= capital |  non-capital 
1630
1631 (8) alphanumeric ::= letter | digit 
1632
1633 (9) identifier ::= letter{[underscore]alphanumeric} 
1634
1635 (10) integer ::= digit{digit} 
1636
1637 (11) exponent ::= ’E’[’+’]integer |  ’E-’integer 
1638
1639 (12) numeric-constant  ::= [’+’]integer ’.’ integer[exponent] | ’-’integer ’.’ integer[exponent] 
1640
1641
1642 (13) literal-constant  ::= ’’’printable character’’’ | ’~’{printable 
1643 character}’~’ 
1644
1645 (14) package-name ::= identifier 
1646
1647 (15) enumeration-name  ::= identifier [**from** package-name] 
1648
1649 (16) class-name ::= identifier [**from** package-name] 
1650
1651 (17) exception-name ::= identifier [**from** package-name] 
1652
1653 (18) constructor-name  ::= ’Create’ |  ’Initialize’ 
1654
1655 (19) primitive-type ::= ’Boolean’ |  ’Character’ | ’Integer’ | ’Real’ 
1656
1657 (20) data-type ::= enumeration-name | class-name | exception-name | primitive-type 
1658
1659 (21) passed-type ::= data-type | **like me** | **like** identifier 
1660
1661 (22) passing-mode ::= [**in**] | **out** | **in out** 
1662
1663 (23) parameter-access ::= **mutable** | [**immutable**] 
1664
1665 (23A) return-access ::= **mutable** | [**immutable**]| **any** 
1666
1667 (24) value ::= numeric-constant | literal-constant | identifier 
1668
1669 (25) parameter ::= identifier {’,’ identifier} ’:’ passing-mode access-right passed-type [’=’ value] 
1670
1671 (26) simple-formal-part  ::= ’(’parameter {’;’  parameter}’)’ 
1672
1673 (27)  formal-part-of-instance-method ::= ’(’ **me** [’:’ passing-mode access-right] {’;’ parameter}’)’ 
1674
1675 (28)  formal-part-of-class-method ::= ’(’ **myclass** {’;’ parameter}’)’ 
1676
1677 (29) visibility ::= **private** | **protected** 
1678
1679 (30) redefinition ::= **static** | **deferred** 
1680
1681 (31) definition-level ::= redefinition | **redefined** [redefinition] 
1682
1683 (32)  declaration-of-constructed-type ::= **returns** [**mutable**] class-name 
1684
1685 (33)  declaration-of-returned-type ::= **returns** return-access  passed-type 
1686
1687 (34)  declaration-of-errors ::= **raises** exception-name {’,’  exception-name} 
1688
1689 (35)  declaration-of-visibility ::= **is** visibility 
1690
1691 (36)  declaration-of-attributes-of-instance-method ::= **is** visibility | **is** definition-of-level [visibility] 
1692
1693 (37) constructor ::= constructor-name [simple-formal-part] 
1694 [declaration-of-constructed-type] 
1695 [declaration-of-errors] 
1696 [declaration-of-visibility]’;’ 
1697
1698 (38) instance-method ::= identifier formal-part-of-instance-method 
1699 [declaration of returned type] 
1700 [declaration-of-errors] 
1701 [declaration-of-attributes-of-instancemethod]’;’ 
1702
1703 (39) class-method ::= identifier formal-part-of-the-class-method 
1704 [declaration of returned type] 
1705 [declaration-of-errors] 
1706 [declaration-of-visibility]’;’ 
1707
1708 (40) package-method ::= identifier [simple-formal-part] 
1709 [declaration-of-returned-type] 
1710 [declaration-of-errors] 
1711 [**is private**]’;’ 
1712
1713 (41) member-method ::= constructor |  instance-method | class-method 
1714
1715 (42) formal-part ::= simple-formal-part | formal-part-of-instance-method| formal-part-of-class-method 
1716
1717 (43) friend ::= identifier **from** [**class**] class-name  [formal-part] 
1718 | identifier **from** [**package**] package-name [formal-part] | 
1719 [**class**] class-name 
1720
1721 (44) field ::= identifier {’,’ identifier} ’:’ data-type 
1722 [’[’integer {’,’ integer}’]’] 
1723 [**is protected**]’;’ 
1724
1725 45)  redefinition-of-field ::= [field-name] **from** [**class**] class-name 
1726
1727 (46)  declaration-of-fields ::= **fields** [**redefined** redefinition-of-field  {’,’ redefinition-of-field}’;’] 
1728 field {field} 
1729
1730 (47)  declaration-of-an-alias::= [**private**] **alias** class-name1 **is** class-name2  [**from** package-name] 
1731
1732 (48)  declaration-of-friends ::= **friends** friend {’,’ friend} 
1733
1734 (49) class-definition  ::= [{member-method}] 
1735 [declaration-of-fields] 
1736 [declaration-of-friends] 
1737
1738 (50)  declaration-of-an-exception ::= **exception** exception-name **inherits** exception-name 
1739
1740 (51) declaration-of-an-enumeration  ::= **enumeration** enumeration-name 
1741 **is** identifier {’,’  identifier} 
1742 [**end** [enumeration-name]]’;’ 
1743
1744 (52)  incomplete-declaration-of-a-non-generic-class ::= 
1745 [**deferred**] **class** class-name’;’ 
1746
1747 (53)  incomplete-declaration-of-a-generic-class ::= 
1748 [**deferred**] **generic class** class-name {’,’ class-name}’;’ 
1749
1750 (54)  declaration-of-a-non-generic-class ::= 
1751 [**deferred**] **class** class-name 
1752 [**inherits** class-name 
1753 [**uses** data-type {’,’ data-type}] 
1754 [**raises** exception-name {’,’ exception-name}] 
1755 **is** definition-of-a-class 
1756 **end** [class-name]’;’ 
1757
1758 (55) type-constraint ::= **any** | class-name  [’(’data-type {’,’ data-type}’)’] 
1759
1760 (56) generic-type ::= identifier **as** type-constraint 
1761
1762 (57) declaration-of-a-generic-class ::=
1763 [**deferred**] **generic class** class-name ’(’generic-type
1764 {’,’ generic-type}’)’
1765 [**inherits** class-name
1766 [**uses** data-type {’,’ data-type}]
1767 [**raises** exception-name {’,’ exception-name}]
1768 [{[visibility] declaration-of-a-class}]
1769 **is** class-definition
1770 **end** [class-name]’;’
1771
1772 (58) instantiation-of-a-generic-class::=
1773 [**deferred**] **class** class-name
1774 **instantiates** class-name ’(’data-type
1775 {’,’ data-type}’);’
1776
1777 (59) declaration-of-a-class::=
1778 incomplete-declaration-of-a-non-generic-class
1779 |
1780 incomplete-declaration-of-a-generic-class |
1781 declaration-of-a-non-generic-class |
1782 declaration-of-a-generic-class |
1783 instantiation-of-a-generic-class
1784
1785 (60) type-declaration ::=
1786 [private] declaration-of-an-enumeration | [**private**] class-declaration | declaration-of-an-exception
1787
1788 (61) package-definition ::=
1789 [{type-declaration}]
1790 [{package-method}]
1791
1792 (62) package-declaration ::= **package** package-name
1793 [**uses** package-name {’,’ package-name}]
1794   **is** package-definition
1795 **end** [package-name]’;’
1796
1797 (63) executable-declaration ::=
1798              **executable** executable-name
1799                             **is**
1800             {
1801              **executable** executable-part
1802 [**uses** [identifier **as external**]
1803      [{’,’ identifier **as external**}]
1804      [unit-name **as library**]
1805      [{’,’ unit-name **as library**}]
1806                             **is**
1807                      {file-name [as C++|c|fortran|object];}
1808                                **end** ’;’
1809                  }
1810                 **end** ’;’
1811
1812 (64) schema-declaration ::=
1813  **schema** schema-name
1814   **is**
1815 [{**package** package-name ’;’ }]
1816 [{**class** class-name ’;’ }]
1817 **end** ’;’
1818
1819
1820
1821
1822
1823 @section occt_cdl_6 Appendix B Comparison of CDL and C++ 
1824
1825 ## Syntax for Data Types manipulated by Handle and by Value in CDL
1826
1827 |  | Handle | Value |
1828 | :---- | :---- | :---- | 
1829 | Permanent | Persistent | Storable |
1830 | Temporary | Transient | Any |
1831 | Reading | Immutable | In |
1832 | Writing | Mutable | Out |
1833 | Read/Write | Mutable | In out | 
1834 | Return | Not specified : any | Without copy: --C++ return const& |
1835
1836 ## Syntax for Data Types manipulated by Handle and by Value in C++
1837
1838 | | Handle | Value |
1839 | :---- | :---- | :--- |
1840 | C++ Declaration | Handle(PGeom_Point) p1; | gp_Pnt p2; |
1841 | C++ Constructor | p1 = newPGeom_Point(p2); | p2(0.,0.,0.); |
1842 | C++ Method | x=p1 -> XCoord(); | x=p2.XCoord(); |
1843
1844
1845  
1846