GNU Info

(gawk.info)Assert Function

---

Next: Round Function Prev: Nextfile Function Up: General Functions

---

Enter node , (file) or (file)node

Assertions
----------

   When writing large programs, it is often useful to know that a
condition or set of conditions is true.  Before proceeding with a
particular computation, you make a statement about what you believe to
be the case.  Such a statement is known as an "assertion".  The C
language provides an `<assert.h>' header file and corresponding
`assert' macro that the programmer can use to make assertions.  If an
assertion fails, the `assert' macro arranges to print a diagnostic
message describing the condition that should have been true but was
not, and then it kills the program.  In C, using `assert' looks this:

     #include <assert.h>
     
     int myfunc(int a, double b)
     {
          assert(a <= 5 && b >= 17.1);
          ...
     }

   If the assertion fails, the program prints a message similar to this:

     prog.c:5: assertion failed: a <= 5 && b >= 17.1

   The C language makes it possible to turn the condition into a string
for use in printing the diagnostic message.  This is not possible in
`awk', so this `assert' function also requires a string version of the
condition that is being tested.  Following is the function:

     # assert --- assert that a condition is true. Otherwise exit.
     function assert(condition, string)
     {
         if (! condition) {
             printf("%s:%d: assertion failed: %s\n",
                 FILENAME, FNR, string) > "/dev/stderr"
             _assert_exit = 1
             exit 1
         }
     }
     
     END {
         if (_assert_exit)
             exit 1
     }

   The `assert' function tests the `condition' parameter. If it is
false, it prints a message to standard error, using the `string'
parameter to describe the failed condition.  It then sets the variable
`_assert_exit' to one and executes the `exit' statement.  The `exit'
statement jumps to the `END' rule. If the `END' rules finds
`_assert_exit' to be true, it then exits immediately.

   The purpose of the test in the `END' rule is to keep any other `END'
rules from running.  When an assertion fails, the program should exit
immediately.  If no assertions fail, then `_assert_exit' is still false
when the `END' rule is run normally, and the rest of the program's
`END' rules execute.  For all of this to work correctly, `assert.awk'
must be the first source file read by `awk'.  The function can be used
in a program in the following way:

     function myfunc(a, b)
     {
          assert(a <= 5 && b >= 17.1, "a <= 5 && b >= 17.1")
          ...
     }

If the assertion fails, you see a message similar to the following:

     mydata:1357: assertion failed: a <= 5 && b >= 17.1

   There is a small problem with this version of `assert'.  An `END'
rule is automatically added to the program calling `assert'.  Normally,
if a program consists of just a `BEGIN' rule, the input files and/or
standard input are not read. However, now that the program has an `END'
rule, `awk' attempts to read the input data files or standard input
(Note: Startup and Cleanup Actions.), most likely
causing the program to hang as it waits for input.

   There is a simple workaround to this: make sure the `BEGIN' rule
always ends with an `exit' statement.