Programming Language Support
----------------------------

While HWUT is designed to support any programming language that is able to
produce an application that can be executed from the command line and print
something on the standard output, HWUT comes with some specific support for
several programming languages. This section outlines auxiliaries that may
facilitate the implementation of test applications. 

All language specific support is located in the directory
'$HWUT_PATH/support/X' where 'X' is the name of the specific programming
language.

Choices
.......

HWUT's interaction with the test applications is based on command 
line arguments. HWUT provides a means to check them elegantly
using the macro ``hwut_choice``. By means of this macro the 
following code fragment

  .. code-block:: c

    int main(int argc, char** argv)
    {
        uint8_t*  test_string = 0x0;

        if( argc > 1 )
            if( strcmp(argv[1], "--hwut-info") == 0 ) {
                printf("My String Function Test\n");
                printf("CHOICES: 7bit, 8bit, 16bit, 32bit");
                return 0;
            }
            elif( strcmp(argv[1], "7bit") == 0 ) {
                test_string = create_7bit_encoded_example();
            }
            elif( strcmp(argv[1], "8bit") == 0 ) {
                test_string = create_8bit_encoded_example();
            }
            elif( strcmp(argv[1], "16bit") == 0 ) {
                test_string = create_16bit_encoded_example();
            }
            elif( strcmp(argv[1], "32bit") == 0 ) {
                test_string = create_32bit_encoded_example();
            }
        }
        /* test on 'test_string' */
        ...
    }

can be transformed into

  .. code-block:: c

    #include "hwut_unit.h"

    int main(int argc, char** argv)
    {
        uint8_t*  test_string = 0x0;

        hwut_info("My String Function Test;\n"
                  "CHOICES: 7bit, 8bit, 16bit, 32bit;");
        hwut_choice("7bit",  test_string = create_7bit_encoded_example()  );
        hwut_choice("8bit",  test_string = create_8bit_encoded_example()  );
        hwut_choice("16bit", test_string = create_16bit_encoded_example() );
        hwut_choice("32bit", test_string = create_32bit_encoded_example() );

        /* test on 'test_string' */
        ...
    }

which is at the same time shorter and more readable. The formal syntax of
the ``hwut_choice`` macro is 

   .. c:macro:: hwut_choice(CHOICE, STATEMENT)

      where ``CHOICE`` is the string against which command line argument '1' 
      is checked. ``STATEMENT`` is the statement to be executed if the first
      argument is equal to ``CHOICE``.

and the formal syntax of the ``hwut_info`` macro is 

   .. c:macro:: hwut_info(MESSAGE)

      where ``MESSAGE`` is the string to be reported as a response to the 
      command line argument ``--hwut-info``.

NUnit-Like Testing
..................

At the time of this writing there is a pre-dominant tool for unit testing
called 'NUnit'. With this tool tests are based on function calls like
``Assert.AreEqual(This, That)``. This is manytimes very inconvenient
when doing larger tests on system behavior. For 'real' unit tests that
are restricted to single function calls and what they return such tests
may be appropriate. HWUT provides a very simple means to support such tests
by the ``hwut_verify_verbose`` macro in 'C/C++'. It can be accessed by including

  .. code-block:: c

      #include <hwut_unit.h>

This macro allows to check for
expressions of any complexity in the syntax of C itself. For example:

  .. code-block:: c
     
      hwut_verify_verbose( 1 + 1 == 2 );
      hwut_verify_verbose( 1 + 1 == 3 );

results in the output::

      test-hwut_unit.c:      [OK] 1 + 1 == 2
      test-hwut_unit.c:24: [FAIL] 1 + 1 == 3

Note, that the line number is only output when the test fails. This prevents
that HWUT's plain comparison fails when only the position of tests changes
inside the file. If it is desired to print out a comment along with the 
test, then the macro ``hwut_verify_verbose`` may be used, e.g.

  .. code-block:: c
     
     hwut_verify_verbose("----------------------------\n" 
                  "One plus one is two, or not?\n"
                  1 + 1 == 2);

which results in::

     One plus one is two, or not?
     ----------------------------
     test-hwut_unit.c:      [OK] 1 + 1 == 2
     
If it is only required to print out errors, then the silent version ``

  .. code-block:: c
     
     hwut_verify( 1 + 1 == 2 );
     hwut_verify( 1 + 1 == 3 );
     hwut_averify("------------------------------------\n"           
                         "Silent: One plus one is two, or not?"
                         1 + 1 == 2);
                         
     hwut_averify("-------------------------------------------\n"
                         "Silent: One plus one is not three, or what?"
                         1 + 1 == 3);

results in the following output, where obviously the successful tests 
are not printed anymore::

     test-hwut_unit.c:24: [FAIL] 1 + 1 == 3
     -----------------------------------
     One plus one is not three, or what?
     test-hwut_unit.c:    [FAIL] 1 + 1 == 3
     
The formal specification of the macros for NUnit like testing is

   .. cmacro:: hwut_verify_verbose(CONDITION)

      Tests for ``CONDITION`` to me met. Dependent on the result it
      prints an OK message or a FAIL message on the screen. If it 
      fails, the place where the failure occured is printed on the 
      screen.

   .. cmacro:: hwut_verify(CONDITION)

      acts like ``hwut_verify_verbose`` but prints only in case of failure.


   .. cmacro:: hwut_verify_verbose(ANNOTATION, CONDITION)
   
      which is the 'annotated' version of ``hwut_verify_verbose`` that prints 
      the message ``ANNOTATION`` before the condition is checked.


   .. cmacro:: hwut_averify(ANNOTATION, CONDITION)

      acts like ``hwut_verify_verbose`` but prints only in case of failure.

The explicit test for equal, not equal, greater than, etc. becomes redundant
since with the ``hwut_verify_verbose`` macros all kinds of expressions can be tested. 
The complexity of its conditions is only restricted by the restrictions of 
the C-language.