# Specialized Type

The basic idea of specialized types is to provide the test generator (API Sanity Checker) with enough information to generate correct invocation of the target interface in a typical use case and check basic constraints on the return value. The issue is that, for many interfaces, correct invocation requires preparing correct environment and correct parameter values. And this in turn may require calling other interfaces. Specialized type (or "semantic type" of parameter) include information about various initialization means for various environments. Such information can be reused for multiple interfaces each time the same semantic types are used, which greatly speeds up the development. Correct values for simple types are created by generator completely automatically. When an interface has initialization means assigned for all of its parameters (and if necessary for initial environment), the generator can automatically compose a test for this interface.

Test development process consists in creating the complete collection of specialized types for the library. Testing of libraries with numerous interfaces by this methodology requires relatively small effort per test and thus is cheap enough. The efficiency is best revealed for interface sets with the number of interfaces starting from hundreds.

## C/C++ Language Extensions

Attributes of specialized type should be described on C/C++ language extended by the following instructions:

- $(type) - instruction initializing an instance of data type.

       void create_QAbstractProxyModel(QAbstractProxyModel* Obj)
       {
           Obj->setSourceModel($(QAbstractItemModel*));
       }

- $[interface] - instruction for interface call with properly initialized parameters.

       xmlListPtr create_filled_list()
       {
           xmlListPtr l=$[xmlListCreate];
           int num=100;
           xmlListPushBack(l,&num);
           return l;
       }

- $0 - an instance of the specialized type.

       /*initialize "doc" property of the associated parameter*/
       $0->doc = xmlParseMemory("<p/>",4);

- $1, $2, ... - references to 1st, 2nd and other interface parameters.

       /*initialize "next" field of the first parameter by the second parameter*/
       $1->next=$2;

       /*write first parameter to the second parameter*/
       $2.write($1);

- $obj - reference to the object that current method calls on (C++ only).

       /*call setStyle() method on the object*/
       $obj.setStyle(Qt::DotLine);

## Attributes of Specialized Type

Specialized type has the following attributes:

- name - Name of the specialized type
- data_type - Name of the associated real data type (QObject*, int, xmlChar ...) or the list of such types (one per line)
- value - Value for initialization (true, 1.0, "string")
- pre_condition/post_condition - Pre/Postcondition on associated function return value or parameter

       $0!=NULL

- init_code/final_code - Code that should be invoked before/after function call

       /*call the start() method on the associated parameter*/
       $0->start();

- global_code - Declarations of auxiliary functions and global variables, header includes

       #include <QWidgetAction>
       QWidgetAction* create_QWidgetAction()
       {
           QWidgetAction* Obj = new QWidgetAction($(QWidget*));
           Obj->setDefaultWidget($(QWidget*));
           return Obj;
       }

- libs - List of external shared objects used by this type. Corresponding external header files should be included in the global_code section
- kind - Kind of the specialized type:
  - normal - This specialized type should be manually associated with the parameters or return values of suitable interfaces
  - common_param - This specialized type will be automatically associated with the parameters of all suitable interfaces
  - common_retval - This specialized type will be automatically associated with the return values of all suitable interfaces
  - env - This kind of specialized type was introduced for setting up correct environment for the interfaces. The code of this specialized
    type will be added once at the beginning or at the end of main() function in the test for manually associated interface
  - common_env - This kind of specialized type is the same as env, but will be automatically associated with all library interfaces

## Associating with Interfaces

Specialized Types should be associated with the return values or parameters of some library interfaces. Base type of the specialized type should be the same as base type of return value or parameter. For example, specialized type with data_type=int* can be associated with any parameter that has int as the base type like int, int**, int&* and others (it is a so-called family of data types - collection of types that have the same base type).

## Writing Specialized Types

Specialized Type has XML-like structure (you can skip any section if it is not needed):

     <spec_type>

         <kind>
             <!-- Kind of the specialized type.
                  Select it from the following list:
                    normal
                    common_param
                    common_retval
                    env
                    common_env -->
         </kind>

         <data_type>
             <!-- Name of the corresponding real data type, one per line.
                  You can specify several data types if kind is 'common_param'
                  or 'common_retval', one per line.
                  This section is not used if kind is 'env' or 'common_env' -->
         </data_type>

         <value>
             <!-- Value for initialization (true, 1.0, \"string\", ...) -->
         </value>

         <pre_condition>
             <!-- Precondition on associated function parameter.
                    Example: $0!=NULL -->
         </pre_condition>

         <post_condition>
             <!-- Postcondition on associated function return value or parameter.
                    Example: $0!=NULL && $obj.style()==Qt::DotLine -->
         </post_condition>

         <init_code>
             <!-- Code that should be invoked before function call.
                    Example: $0->start(); -->
         </init_code>

         <final_code>
             <!-- Code that should be invoked after function call
                    Example: $0->end(); -->
         </final_code>

         <global_code>
             <!-- Declarations of auxiliary functions and global variables, header includes -->
         </global_code>

         <associating>
             <interfaces>
                 <!-- List of interfaces (mangled/symbol names in C++)
                      that will be associated with the specialized type, one per line -->
             </interfaces>

             <except>
                 <!-- List of interfaces (mangled/symbol names in C++)
                      that will not be associated with the specialized type, one per line.
                      This section is used if kind is 'common_env', 'common_param' or 'common_return' -->
             </except>

             <links>
                 <!-- Associations with the return value, parameters or/and object, one per line:
                        param1
                        param2
                         ...
                        object
                        retval -->
             </links>

             <param_name>
                 <!-- Associations with the parameters by name, one per line:
                        param_name1
                        param_name2
                        param_name3
                         ...
                             -->
             </param_name>
         </associating>

         <associating>
             <!-- Other associations -->
         </associating>

         <name>
             <!-- Name of the specialized type -->
         </name>

         <libs>
             <!-- External shared objects, one per line.
                  If spectype contains call of the functions from
                  some external shared objects then these objects
                  should be listed here. Corresponding external
                  header files should be included in global_code -->
         </libs>

     </spec_type>

## Writing Collection of Specialized Types

You can unite several specialized types into collection(s):

     <collection>

         <spec_type>
             <!-- Specialized Type №1 -->
         </spec_type>

         <spec_type>
             <!-- Specialized Type №2 -->
         </spec_type>

            ...

     </collection>

     <collection>
         <!-- Other Collection -->
     </collection>

The file containing collection(s) of specialized types can be provided to the -specialized-types (-st) option:
`api-sanity-checker -specialized-types SPECTYPES.xml -gen -build -run`

## Using Test Data

Test data (special files needed by tests) should be created in some directory before generating tests. Path to that directory should be provided to -test-data (-td) option:
`api-sanity-checker -test-data DIR -specialized-types SPECTYPES.xml -gen -build -run`

For accessing test data files in the attributes of specialized types you should use TEST_DATA_PATH("file") construction. Test generator will copy specified file to the local "testdata/" directory and replace TEST_DATA_PATH("file") with the "testdata/file" in the generated code.

       QSound* create_QSound()
       {
           QSound* Obj = new QSound(TEST_DATA_PATH("SoundFile.wav"), NULL);
           Obj->setLoops(5);
           return Obj;
       }

## Examples

- Setting up environment for all interfaces and correct initialization for parameters of type GObject* in the ATK library:

     <spec_type>
         <kind>
             common_env
         </kind>

         <init_code>
             g_type_init();
         </init_code>
     </spec_type>

     <spec_type>
         <kind>
             common_param
         </kind>

         <data_type>
             GObject*
         </data_type>

         <value>
             g_object_new (G_TYPE_OBJECT, NULL)
         </value>

         <global_code>
             #include <glib.h>
         </global_code>
     </spec_type>

- Correct initialization for all parameters of type xmlListPtr in the libxml2 library:

     <spec_type>
         <kind>
             common_param
         </kind>

         <data_type>
             xmlListPtr
         </data_type>

         <value>
             create_filled_list()
         </value>

         <constraint>
             $0!=NULL
         </constraint>

         <global_code>
             xmlListPtr create_filled_list()
             {
                 xmlListPtr l = $[xmlListCreate];
                 int num = 100;
                 xmlListPushBack(l, &num);
                 return l;
             }
         </global_code>
     </spec_type>

- Correct initialization for the 1st parameter of interface xmlListAppend(xmlListPtr l, void* data) from libxml2 library:

     <spec_type>
         <kind>
             normal
         </kind>

         <data_type>
             xmlListPtr
         </data_type>

         <value>
             create_filled_list()
         </value>

         <global_code>
             xmlListPtr create_filled_list()
             {
                 xmlListPtr l = $[xmlListCreate];
                 int num = 100;
                 xmlListPushBack(l, &num);
                 return l;
             }
         </global_code>

         <associating>
             <interfaces>
                 xmlListAppend
             </interfaces>

             <links>
                 param1
             </links>
         </associating>
     </spec_type>

- Setting up environment for all interfaces from the QtCore library:

     <spec_type>
         <kind>
             common_env
         </kind>

         <global_code>
             #include<QApplication>
             #include<QTimer>
         </global_code>

         <init_code>
             #ifdef Q_WS_X11
               bool useGUI = getenv( "DISPLAY" ) != 0;
             #else
               bool useGUI = TRUE;
             #endif
             QApplication* app = new QApplication(argc, argv, useGUI);
         </init_code>

         <final_code>
             QTimer::singleShot(100, app, SLOT(quit()));
             app->exec();
         </final_code>
     </spec_type>

- Setting up environment for all interfaces from the Gtk+ library:

     <spec_type>
         <kind>
             common_env
         </kind>

         <init_code>
             gtk_init(&argc, &argv);
         </init_code>

         <final_code>
            gtk_timeout_add(100, &main_loop_quit, NULL);
            gtk_main();
         </final_code>

         <global_code>
             #include <gtk.h>
             gboolean main_loop_quit(gpointer data)
             {
                 gtk_main_quit();
                 return FALSE;
             }
         </global_code>

         <associating>
             <except>
                 gtk_init
                 gtk_init_check
                 gtk_parse_args
                 gdk_init
                 gdk_init_check
                 gdk_parse_args
                 gtk_test_init
             </except>
         </associating>
     </spec_type>

- Using test data for initializing all parameters of type xmlTextReaderPtr in the libxml2 library:

     <spec_type>
         <kind>
             common_param
         </kind>

         <data_type>
             xmlTextReaderPtr
         </data_type>

         <value>
             create_reader()
         </value>

         <global_code>
             xmlTextReaderPtr create_reader(int n)
             {
                 xmlTextReaderPtr reader = xmlReaderForFile(TEST_DATA_PATH("file.xml"), NULL, 0);
                 int i;
                 for(i=0; i<n; i+=1)
                 {
                     xmlTextReaderRead(reader);
                 }
                 return reader;
             }
         </global_code>
     </spec_type>

- Checking the return value of interface xmlLinkGetData(xmlLinkPtr lk) from the libxml2 library:

     <spec_type>
         <kind>
             normal
         </kind>

         <data_type>
             void*
         </data_type>

         <constraint>
             $0!=NULL
         </constraint>

         <associating>
             <interfaces>
                 xmlLinkGetData
             </interfaces>

             <links>
                 retval
             </links>
         </associating>
     </spec_type>