Documented OOP changes and external class skeleton generator (bug 563718)

Signed-off-by: Botond Baranyi <botond.baranyi@ericsson.com>
Change-Id: Ib1a4d939895f7c989ce2db786dde04ab98ec933f

usrguide/apiguide/3-external_classes.adoc

@@ -2,17 +2,19 @@
 :table-number: 0
 :toc:
 
-There is currently no {cpp} skeleton generator for external classes, so any external classes have to be implemented manually.
+TITAN allows the declaration of external classes in TTCN-3 code, which the user can (and has to) implement in {cpp}.
+To help with the implementation, the TTCN-3 compiler can generate external class skeletons with the command line option `-t`.
 
-External class implementation must abide by the following rules:
+These skeletons contain declarations and empty definitions for the constructors and methods of all external classes declared in TTCN-3 code. 
 
-* The file name, where the external class is declared, must be the name of the external class followed by `.hh`. Please note that the name mapping rules described in <<6-mapping_ttcn3_data_types_to_c++_constructs.adoc#mapping-of-names-and-identifiers, Mapping of Names and Identifiers>> also apply to the class and file name. The implementations of class methods can be in any {cpp} source file that is linked to the executable test suite.
-* The new `.hh` file must include the generated header file of the TTCN-3 module containing the external class declaration.
-* The include to the new `.hh` file is already in the desired namespace in the generated {cpp} code, so no further namespaces are needed around the external class declaration.
-* The external class must inherit the built-in {cpp} class `OBJECT` (`object` in TTCN-3).
-* The C++ equivalents of all functions in the TTCN-3 external function declaration must be virtual.
-* The class must also have a virtual destructor (even if it is empty).
-* For more information about function parameters and return values of class types see <<6-mapping_ttcn3_data_types_to_c++_constructs.adoc#object-references, Object References>>.
+Clarifications about the skeletons and implementation tips:
+
+* One header (`.hh`) and one source file (`.cc`) is generated for each external class. The base names of these files (i.e. their names before the extensions) are equal to the names of their external class in TTCN-3. Please note that the name mapping rules described in <<6-mapping_ttcn3_data_types_to_c++_constructs.adoc#mapping-of-names-and-identifiers, Mapping of Names and Identifiers>> also apply to the file names.
+* Both the generated header and source file can be extended with additional members and methods, however these new members and methods will not be visible in TTCN-3.
+* The compiler will not regenerate the external class skeletons, if they already exist. Not even if the external class declaration in TTCN-3 changes. The compiler option `-f` (in addition to `-t`) can be used to force the regeneration of external class skeletons, however this will also overwrite any user code added to the previous skeletons.
+* The generated source file contains empty function definitions for methods declared in TTCN-3 (plus an empty default constructor, if no constructor was declared). It also contains a minimal implementation of the `log` function, which can be extended to display more information about the object while logging. The header file also contains a static inline function called `class_name`, which is used in error messages.
+* The generated destructor automatically contains a try-catch block, to ensure that no exceptions are thrown from the destructor. All user code must be written inside the try-catch block.
+* For more information about how to handle references of class types see <<6-mapping_ttcn3_data_types_to_c++_constructs.adoc#object-references, Object References>>.
 
 == Example
 
@@ -20,34 +22,45 @@ Example.ttcn:
 [source]
 ----
 type external class ExternalClass {
-  public external function f_ext(in integer x) return charstring;
-  external function f_ext2(inout OtherClass p);
+  create(integer x);
+  public function f_ext1(in integer x, out octetstring y);
+  function f_ext2(inout template charstring p) return boolean;  
 }
 ----
 
 ExternalClass.hh:
 [source]
 ----
-#include "Example.hh"
+// This external class skeleton header file was generated by the
+// TTCN-3 Compiler of the TTCN-3 Test Executor version 7/CAX 105 7730 R2A
+// for ebotbar (ebotbar@u2004VB) on Wed Nov 18 15:25:06 2020
+
+// Copyright (c) 2000-2020 Ericsson Telecom AB
 
-#ifndef EXTERNALCLASS_HH
-#define EXTERNALCLASS_HH
+// You may modify this file. Add your attributes and prototypes of your
+// member functions here.
 
-// NOTE: no namespace specification needed, since the 'include' command is
-// already in the desired namespace!
+#ifndef ExternalClass_HH
+#define ExternalClass_HH
 
 class ExternalClass : public OBJECT {
 public:
-  virtual CHARSTRING f__ext(const INTEGER& x);
-  
+static const char* class_name() { return "ExternalClass"; }
+
+public:
+virtual void f__ext1(const INTEGER& x, OCTETSTRING& y);
+
 protected:
-  virtual void f__ext2(OBJECT_REF<OtherClass>& p);
-  
+virtual BOOLEAN f__ext2(CHARSTRING_template& p);
+
 public:
-  virtual ~ExternalClass() { }
+ExternalClass(const INTEGER& x);
 
-// additional members and methods
+public:
+virtual ~ExternalClass();
 
+public:
+virtual void log() const;
 };
 
 #endif
@@ -56,21 +69,55 @@ public:
 ExternalClass.cc:
 [source]
 ----
+// This external class skeleton source file was generated by the
+// TTCN-3 Compiler of the TTCN-3 Test Executor version 7/CAX 105 7730 R2A
+// for ebotbar (ebotbar@u2004VB) on Wed Nov 18 15:25:06 2020
+
+// Copyright (c) 2000-2020 Ericsson Telecom AB
+
+// You may modify this file. Complete the bodies of empty functions and
+// add your member functions here.
+
+#include <TTCN3.hh>
+
+namespace oop {
+
 #include "ExternalClass.hh"
 
-namespace Example {
+void ExternalClass::f__ext1(const INTEGER& x, OCTETSTRING& y)
+{
+
+}
 
-CHARSTRING ExternalClass::f__ext(const INTEGER& x)
+BOOLEAN ExternalClass::f__ext2(CHARSTRING_template& p)
 {
-  // method implementation
+
 }
 
-void ExternalClass::f__ext2(OBJECT_REF<OtherClass>& p)
+ExternalClass::ExternalClass(const INTEGER& x)
+: OBJECT()
 {
-  // method implementation
+
 }
 
+ExternalClass::~ExternalClass()
+{
+try {
+
+} catch (...) {
+fprintf(stderr, "Unhandled exception or dynamic test case error in destructor of class `ExternalClass'");
+exit(EXIT_FAILURE);
 }
+}
+
+void ExternalClass::log() const
+{
+TTCN_Logger::log_event_str("ExternalClass: { ");
+TTCN_Logger::log_event_str(" }");
+}
+
+
+} /* end of namespace */
 ----
 
-NOTE: If external class methods are implemented in a different {cpp} file, than the mentioned new `.hh` file (such as `ExternalClass.cc` in this case), then they need to be placed in the TTCN-3 module's namespace.
+NOTE: The generated constructor automatically contains an empty base-constructor call. This is fine if the base-constructor has no parameters (e.g. it has a default constructor). If the base-constructor has at least one parameter, then appropriate parameter values need to be added to the base-constructor call, otherwise it won't compile.

usrguide/referenceguide/4-ttcn3_language_extensions.adoc

@@ -9056,9 +9056,28 @@ TITAN supports the object-oriented programming features described in chapter 5 o
 * Class members of `port` and `port array` types are not allowed.
 * Class member `templates` cannot have parameters.
 * Exceptions are not currently supported.
-* The `select class` statement is not currently supported.
-* The `of`-operator (Dynamic Class Discrimination) is not currently supported.
-* The casting of classes (`=>` operator) is not currently supported.
+* The members and methods of the resulting object from a casting operation (i.e. `=>` operation) cannot be accessed directly, the casting result needs to be saved into a variable first.
+
+Example:
+[source]
+----
+type class Node {
+  var integer data;
+  var Node next;
+  public function get_data() return integer { return data; }
+  public function get_next() return Node { return next; }
+}
+
+...
+
+var object v_obj := Node.create(3, null);
+
+var integer v_int := (v_obj => Node).get_data(); // error
+
+var Node v_node := v_obj => Node;
+var integer v_int2 := v_node.get_data(); // OK
+----
+
 * Unhandled dynamic test case errors inside the destructor of a class cause the program to terminate (due to C++ limitations).
 * The `with` attributes of class members and methods are currently ignored.
 * Members of `timer` and `timer array` types cannot be initialized in the constructor, and the default constructor doesn't add a formal parameter for the initialization of these members.
@@ -9133,7 +9152,8 @@ only variables and function parameters are valid `out` actual parameters.
 * External classes and external methods in classes cannot be abstract.
 * A definition in the subclass can only have the same name as a definition in one of the superclasses, if both are methods (incl. external or abstract), and both have the same prototype (i.e. identical return type, identical formal parameter names, types and direction).
 * Internal classes can define external methods, even if they are not derived from an external class.
-* There are no restrictions to visibility of members or methods (i.e. members can be public and overriding methods can have any visibility, regardless of the overriden method's visibility).
+* Class members cannot be public, as per the standard. However there are no restrictions to the visibility of methods (i.e. overriding methods can have any visibility, regardless of the overriden method's visibility).
+* Constructors of external classes must not have a statement block or a super-constructor call.
 
 
 == Default alternatives of union types

usrguide/referenceguide/ReferenceGuide.adoc

 ---
 Author: Jenő Balaskó
 Version: 7.2.0
-Date: 2020-10-30
+Date: 2020-11-27
 
 ---
 = Programmers' Technical Reference Guide for the TITAN TTCN-3 Toolset
 :author: Jenő Balaskó
 :revnumber:7.2.0
-:revdate: 2020-10-30
+:revdate: 2020-11-27
 :title-logo-image: images/titan_logo.png
 :sectnums:
 :doctype: book

usrguide/userguide/UserGuide.adoc

 ---
 Author: Jenő Balaskó
 Version: 7.2.0
-Date: 2020-10-30
+Date: 2020-11-27
 
 ---
 = User Guide for TITAN TTCN-3 Test Executor
 :author: Jenő Balaskó
 :revnumber: 7.2.0
-:revdate: 2020-10-30
+:revdate: 2020-11-27
 :title-logo-image: images/titan_logo.png
 :sectnums:
 :doctype: book