xcover/xcover.h

Go to the documentation of this file.

/* /////////////////////////////////////////////////////////////////////////
 * File:        xcover/xcover.h
 *
 * Purpose:     Main header file for xCover, a C/C++ code coverage library.
 *
 * Created:     1st March 2008
 * Updated:     3rd January 2009
 *
 * Home:        http://xcover.org/
 *
 * Copyright (c) 2008-2009, Matthew Wilson and Synesis Software
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 * - Redistributions of source code must retain the above copyright notice,
 *   this list of conditions and the following disclaimer.
 * - Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.
 * - Neither the name(s) of Matthew Wilson and Synesis Software nor the
 *   names of any contributors may be used to endorse or promote products
 *   derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * ////////////////////////////////////////////////////////////////////// */


#ifndef XCOVER_INCL_XCOVER_H_XCOVER
#define XCOVER_INCL_XCOVER_H_XCOVER

#ifndef XCOVER_DOCUMENTATION_SKIP_SECTION
# define XCOVER_VER_XCOVER_H_XCOVER_MAJOR       1
# define XCOVER_VER_XCOVER_H_XCOVER_MINOR       1
# define XCOVER_VER_XCOVER_H_XCOVER_REVISION    2
# define XCOVER_VER_XCOVER_H_XCOVER_EDIT        5
#endif /* !XCOVER_DOCUMENTATION_SKIP_SECTION */

/* /////////////////////////////////////////////////////////////////////////
 * Version information
 */

#define XCOVER_VER_MAJOR        0
#define XCOVER_VER_MINOR        2
#define XCOVER_VER_REVISION     1

#define XCOVER_VER              0x000201ff

/* /////////////////////////////////////////////////////////////////////////
 * Includes - 1
 */

#ifndef STLSOFT_INCL_STLSOFT_H_STLSOFT
# include <stlsoft/stlsoft.h>
#endif /* !STLSOFT_INCL_STLSOFT_H_STLSOFT */

/* /////////////////////////////////////////////////////////////////////////
 * Compatibility
 */

#if _STLSOFT_VER < 0x010941ff
# error xCover requires version 1.9.65 (or later) of STLSoft; download from www.stlsoft.org
#endif /* _STLSOFT_VER */

#ifndef __COUNTER__
# error xCover can only be used with compilers that support the (non-standard) predefined pre-processor symbol __COUNTER__
#endif /* !__COUNTER__ */

#ifndef __FUNCTION__
# error xCover can only be used with compilers that support the (standard) predefined pre-processor symbol __FUNCTION__
#endif /* !__FUNCTION__ */

/* /////////////////////////////////////////////////////////////////////////
 * Includes - 2
 */

#ifdef __cplusplus
# include <stdexcept>
#endif /* __cplusplus */

#include <stdio.h>

/* /////////////////////////////////////////////////////////////////////////
 * Namespace
 */

#if defined(_STLSOFT_NO_NAMESPACE)
# define XCOVER_NO_NAMESPACE
#endif /* _STLSOFT_NO_NAMESPACE */

#ifndef XCOVER_NO_NAMESPACE
namespace xcover
{
#endif /* !XCOVER_NO_NAMESPACE */

/* /////////////////////////////////////////////////////////////////////////
 * Features
 */

#ifndef XCOVER_DOCUMENTATION_SKIP_SECTION

# ifndef XCOVER_NO_NAMESPACE
#  define XCOVER_NS_QUAL(ns, sym)           ns::sym
# else /* ? XCOVER_NO_NAMESPACE */
#  define XCOVER_NS_QUAL(ns, sym)           sym
# endif /* XCOVER_NO_NAMESPACE */

# if !defined(XCOVER_CALLCONV)
#  define XCOVER_CALLCONV
# endif /* !XCOVER_CALLCONV */

# ifndef XCOVER_CALL
#  ifdef __cplusplus
#   define XCOVER_CALL(x)                   extern "C" x
#  else /* ? __cplusplus */
#   define XCOVER_CALL(x)                   extern x
#  endif /* __cplusplus */
# endif /* !XCOVER_CALL */

#endif /* !XCOVER_DOCUMENTATION_SKIP_SECTION */

/* /////////////////////////////////////////////////////////////////////////
 * Constants & definitions
 */

/* /////////////////////////////////////////////////////////////////////////
 * Macros
 */

#define XCOVER_MARK_FILE_START()                            XCOVER_NS_QUAL(::xcover, xcover_markFileStart)(__FILE__, __LINE__, __FUNCTION__, __COUNTER__)

#define XCOVER_MARK_FILE_END()                              XCOVER_NS_QUAL(::xcover, xcover_markFileEnd)(__FILE__, __LINE__, __FUNCTION__, __COUNTER__)

#define XCOVER_MARK_LINE()                                  XCOVER_NS_QUAL(::xcover, xcover_markLine)(__FILE__, __LINE__, __FUNCTION__, __COUNTER__)

#define XCOVER_CREATE_FILE_ALIAS(aliasName)                 XCOVER_NS_QUAL(::xcover, xcover_createFileAlias)(__FILE__, __LINE__, aliasName)

#define XCOVER_ASSOCIATE_FILE_WITH_GROUP(groupName)         XCOVER_NS_QUAL(::xcover, xcover_associateFileWithGroup)(__FILE__, __LINE__, groupName)

#define XCOVER_START_GROUP_COVERAGE(groupName)              XCOVER_NS_QUAL(::xcover, xcover_startGroupCoverage)(__FILE__, __LINE__, groupName)

#define XCOVER_END_GROUP_COVERAGE(groupName)                XCOVER_NS_QUAL(::xcover, xcover_endGroupCoverage)(__FILE__, __LINE__, groupName)

#define XCOVER_REPORT_GROUP_COVERAGE(groupName, reporter)   XCOVER_NS_QUAL(::xcover, xcover_reportGroupCoverage)(__FILE__, __LINE__, groupName, reporter)

#define XCOVER_REPORT_FILE_COVERAGE(fileName, reporter)     XCOVER_NS_QUAL(::xcover, xcover_reportFileCoverage)(fileName, reporter)

#define XCOVER_REPORT_THIS_FILE_COVERAGE(reporter)          XCOVER_NS_QUAL(::xcover, xcover_reportFileCoverage)(__FILE__, reporter)

#define XCOVER_REPORT_ALIAS_COVERAGE(aliasName, reporter)   XCOVER_NS_QUAL(::xcover, xcover_reportAliasCoverage)(aliasName, reporter)

/* /////////////////////////////////////////////////////////////////////////
 * Error codes
 */

enum xcover_rc_t
{
    XCOVER_RC_SUCCESS                   =   0,

    XCOVER_RC_EXCEPTION                 =   -1001,

    XCOVER_RC_OUT_OF_MEMORY,

    XCOVER_RC_UNEXPECTED,

    XCOVER_RC_GROUP_NOT_FOUND,

    XCOVER_RC_FILE_NOT_FOUND,

    XCOVER_RC_ALIAS_NOT_FOUND,

    XCOVER_RC_ALIAS_ALREADY_USED,
};

#ifndef XCOVER_NO_NAMESPACE
typedef xcover_rc_t             rc_t;
#endif /* !XCOVER_NO_NAMESPACE */
#ifndef __cplusplus
typedef enum xcover_rc_t        xcover_rc_t;
#endif /* !__cplusplus */

/* /////////////////////////////////////////////////////////////////////////
 * Typedefs
 */

struct xcover_coverItem_t
{
    char const* groupName;          
    char const* fileName;           
    int         markIndex;          
    int         priorMarkLine;      
    int         posteriorMarkLine;  
};
#ifndef XCOVER_NO_NAMESPACE
typedef xcover_coverItem_t          coverItem_t;
#endif /* !XCOVER_NO_NAMESPACE */
#ifndef __cplusplus
typedef struct xcover_coverItem_t   xcover_coverItem_t;
#endif /* !__cplusplus */

struct xcover_reporter_t;
#ifndef XCOVER_NO_NAMESPACE
typedef xcover_reporter_t           reporter_t;
#endif /* !XCOVER_NO_NAMESPACE */
#ifndef __cplusplus
typedef struct xcover_reporter_t    xcover_reporter_t;
#endif /* __cplusplus */

#include <xcover/internal/reporter.h>

/* /////////////////////////////////////////////////////////////////////////
 * API functions
 */

XCOVER_CALL(xcover_rc_t) xcover_init(void);

XCOVER_CALL(void) xcover_uninit(void);

XCOVER_CALL(xcover_rc_t) xcover_createFileAlias(char const* fileName, int line, char const* aliasName);

XCOVER_CALL(xcover_rc_t) xcover_associateFileWithGroup(char const* fileName, int line, char const* groupName);

XCOVER_CALL(xcover_rc_t) xcover_markFileStart(char const* fileName, int line, char const* function, int counter);

XCOVER_CALL(xcover_rc_t) xcover_markFileEnd(char const* fileName, int line, char const* function, int counter);

XCOVER_CALL(xcover_rc_t) xcover_markLine(char const* fileName, int line, char const* function, int counter);

XCOVER_CALL(xcover_rc_t) xcover_startGroupCoverage(char const* fileName, int line, char const* groupName);

XCOVER_CALL(xcover_rc_t) xcover_endGroupCoverage(char const* fileName, int line, char const* groupName);

XCOVER_CALL(xcover_rc_t) xcover_reportGroupCoverage(char const* fileName, int line, char const* groupName, xcover_reporter_t* reporter);

XCOVER_CALL(xcover_rc_t) xcover_reportFileCoverage(char const* fileName, xcover_reporter_t* reporter);

XCOVER_CALL(xcover_rc_t) xcover_reportAliasCoverage(char const* aliasName, xcover_reporter_t* reporter);

/* /////////////////////////////////////////////////////////////////////////
 * C++-only functionality
 */

#if defined(__cplusplus)

# ifndef XCOVER_DOCUMENTATION_SKIP_SECTION
#  define XCOVER_DEFINE_FILE_STARTER()  static XCOVER_NS_QUAL(::xcover, xcover_SchwarzMarker) xcover_file_starter(XCOVER_NS_QUAL(::xcover, xcover_markFileStart), __FILE__, __LINE__, __COUNTER__)
#  define XCOVER_DEFINE_FILE_ENDER()    static XCOVER_NS_QUAL(::xcover, xcover_SchwarzMarker) xcover_file_ender(XCOVER_NS_QUAL(::xcover, xcover_markFileEnd), __FILE__, __LINE__, __COUNTER__)

class xcover_SchwarzMarker
{
public:
    xcover_SchwarzMarker(int (XCOVER_CALLCONV* pfn)(char const*, int, char const*, int), char const* fileName, int line, int counter)
    {
        (*pfn)(fileName, line, __FUNCTION__, counter);
    }
};

# endif /* !XCOVER_DOCUMENTATION_SKIP_SECTION */


# if !defined(XCOVER_NO_AUTO_INIT) || \
     defined(XCOVER_FORCE_AUTO_INIT)

class xcover_initialiser
{
public: 
    typedef xcover_initialiser  class_type;

public: 
    xcover_initialiser()
    {
        if(xcover_init() < 0)
        {
            throw std::runtime_error("could not initialise the xCover library");
        }
    }
    ~xcover_initialiser()
    {
        xcover_uninit();
    }
private:
    xcover_initialiser(class_type const&);
    class_type& operator =(class_type const&);
};

namespace
{
    static xcover_initialiser   xc_init;

} /* anonymous namespace */

#endif /* !XCOVER_NO_AUTO_INIT || XCOVER_FORCE_AUTO_INIT */
#endif /* __cplusplus */

/* /////////////////////////////////////////////////////////////////////////
 * Helper functions
 */

/* /////////////////////////////////////////////////////////////////////////
 * API functions for C++
 */

/* /////////////////////////////////////////////////////////////////////////
 * Core Functions
 */

#ifndef XCOVER_NO_NAMESPACE

inline xcover_rc_t init()
{
    return xcover_init();
}

inline void uninit()
{
    xcover_uninit();
}

#endif /* !XCOVER_NO_NAMESPACE */

/* /////////////////////////////////////////////////////////////////////////
 * Namespace
 */

#ifndef XCOVER_NO_NAMESPACE
} /* namespace xcover */
#endif /* !XCOVER_NO_NAMESPACE */

/* ////////////////////////////////////////////////////////////////////// */

#endif /* !XCOVER_INCL_XCOVER_H_XCOVER */

/* ////////////////////////////////////////////////////////////////////// */

xCover Library documentation © Matthew Wilson and Synesis Software Pty Ltd, 2008-2009