ObjFW  Check-in [3c55b7ac50]

PROJECT_NAME = "ObjFW"
OUTPUT_DIRECTORY = docs/
INPUT = src src/exceptions src/runtime src/test
FILE_PATTERNS = *.h *.m
HTML_OUTPUT = .
HAVE_DOT = NO
GENERATE_LATEX = NO
HIDE_UNDOC_CLASSES = YES
HIDE_UNDOC_MEMBERS = YES
TYPEDEF_HIDES_STRUCT = YES

	     OF_WARN_UNUSED_RESULT=				\
	     OF_WEAK_UNAVAILABLE=				\
	     SIGHUP						\
	     SIGUSR1						\
	     SIGUSR2
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
IGNORE_PREFIX = OF OF_ OT OT_

/*
 * Unfortunately, that's the only way to make all compilers happy with the GNU
 * extensions for variadic macros that are being used here.
 */
#pragma GCC system_header

/** @file */

/**
 * @brief Asserts that the specified condition condition holds.
 *
 * @param condition The condition to check
 * @param ... An optional format string to print if the assertion failed,
 *	      followed by optional arguments
 */
#define OTAssert(condition, ...) \
	OTAssertImpl(self, _cmd, condition, @#condition, \
	    @__FILE__, __LINE__, ## __VA_ARGS__, nil)

/**
 * @brief Asserts that the specified condition is true.
 *
 * @param condition The condition to check
 * @param ... An optional format string to print if the assertion failed,
 *	      followed by optional arguments
 */
#define OTAssertTrue(condition, ...) \
	OTAssert(condition == true, ## __VA_ARGS__)

/**
 * @brief Asserts that the specified condition is false.
 *
 * @param condition The condition to check
 * @param ... An optional format string to print if the assertion failed,
 *	      followed by optional arguments
 */
#define OTAssertFalse(condition, ...) \
	OTAssert(condition == false, ## __VA_ARGS__)

/**
 * @brief Asserts that the two values are equal.
 *
 * @param a The value to check
 * @param b The expected value
 * @param ... An optional format string to print if the assertion failed,
 *	      followed by optional arguments
 */
#define OTAssertEqual(a, b, ...) OTAssert(a == b, ## __VA_ARGS__)

/**
 * @brief Asserts that the two values are not equal.
 *
 * @param a The value to check
 * @param b The value `a` should not have
 * @param ... An optional format string to print if the assertion failed,
 *	      followed by optional arguments
 */
#define OTAssertNotEqual(a, b, ...) OTAssert(a != b, ## __VA_ARGS__)

/**
 * @brief Asserts that the value is less than another value.
 *
 * @param a The value to check
 * @param b The value `a` should be less than
 * @param ... An optional format string to print if the assertion failed,
 *	      followed by optional arguments
 */
#define OTAssertLessThan(a, b, ...) OTAssert(a < b, ## __VA_ARGS__)

/**
 * @brief Asserts that the value is less than or equal to another value.
 *
 * @param a The value to check
 * @param b The value `a` should be less than or equal to
 * @param ... An optional format string to print if the assertion failed,
 *	      followed by optional arguments
 */
#define OTAssertLessThanOrEqual(a, b, ...) OTAssert(a <= b, ## __VA_ARGS__)

/**
 * @brief Asserts that the value is greater than another value.
 *
 * @param a The value to check
 * @param b The value `a` should be greater than
 * @param ... An optional format string to print if the assertion failed,
 *	      followed by optional arguments
 */
#define OTAssertGreaterThan(a, b, ...) OTAssert(a > b, ## __VA_ARGS__)

/**
 * @brief Asserts that the value is greater than or equal to another value.
 *
 * @param a The value to check
 * @param b The value `a` should be greater than or equal to
 * @param ... An optional format string to print if the assertion failed,
 *	      followed by optional arguments
 */
#define OTAssertGreaterThanOrEqual(a, b, ...) OTAssert(a >= b, ## __VA_ARGS__)

/**
 * @brief Asserts that the two objects are equal.
 *
 * @param a The object to check
 * @param b The object `a` is expected to be equal to
 * @param ... An optional format string to print if the assertion failed,
 *	      followed by optional arguments
 */
#define OTAssertEqualObjects(a, b, ...) OTAssert([a isEqual: b], ## __VA_ARGS__)

/**
 * @brief Asserts that the two objects are not equal.
 *
 * @param a The object to check
 * @param b The object `a` is expected to be not equal to
 * @param ... An optional format string to print if the assertion failed,
 *	      followed by optional arguments
 */
#define OTAssertNotEqualObjects(a, b, ...) \
	OTAssert(![a isEqual: b], ## __VA_ARGS__)

/**
 * @brief Asserts that the specified object is `nil`.
 *
 * @param object The object to should be `nil`
 * @param ... An optional format string to print if the assertion failed,
 *	      followed by optional arguments
 */
#define OTAssertNil(object, ...) OTAssert(object == nil, ## __VA_ARGS__)

/**
 * @brief Asserts that the specified object is not `nil`.
 *
 * @param object The object to should not be `nil`
 * @param ... An optional format string to print if the assertion failed,
 *	      followed by optional arguments
 */
#define OTAssertNotNil(object, ...) OTAssert(object != nil, ## __VA_ARGS__)

/**
 * @brief Asserts that the specified expression throws an exception.
 *
 * @param expression The expression that should throw
 * @param ... An optional format string to print if the assertion failed,
 *	      followed by optional arguments
 */
#define OTAssertThrows(expression, ...)				\
	{							\
		bool OTThrown = false;				\
		@try {						\
			expression;				\
		} @catch (id e) {				\
			OTThrown = true;			\
		}						\
		OTAssert(OTThrown, ## __VA_ARGS__);		\
	}

/**
 * @brief Asserts that the specified expression throws a specific exception.
 *
 * @param expression The expression that should throw
 * @param exception The exception the expression should throw (as just the
 *		    class name, without quotes)
 * @param ... An optional format string to print if the assertion failed,
 *	      followed by optional arguments
 */
#define OTAssertThrowsSpecific(expression, exception, ...)	\
	{							\
		bool OTThrown = false;				\
		@try {						\
			expression;				\
		} @catch (exception *e) {			\
			OTThrown = true;			\
		}						\
		OTAssert(OTThrown, ## __VA_ARGS__);		\
	}

/**
 * @brief Skips the current test, making it neither fail nor succeeed.
 *
 * @param ... An optional format string to print why the test was skipped,
 *	      followed by optional arguments
 */
#define OTSkip(...) \
	OTSkipImpl(self, _cmd, @__FILE__, __LINE__, ## __VA_ARGS__, nil)

#ifdef __cplusplus
extern "C" {
#endif
extern void OTAssertImpl(id testCase, SEL test, bool condition, OFString *check,
    OFString *file, size_t line, ...);
extern void OTSkipImpl(id testCase, SEL test, OFString *file, size_t line, ...);
#ifdef __cplusplus
}
#endif

# import "ObjFW.h"
#else
# import <ObjFW/ObjFW.h>
#endif

OF_ASSUME_NONNULL_BEGIN

/**
 * @brief A dictionary that enumerates keys and objects in the same order they
 *	  were specified during initialization.
 *
 * @warning This class is only for testing! It is slow and only to be used to
 *	    test extensions of OFDictionary, for example serializations such as
 *	    JSON, where it is desirable to compare to an expected output.
 */
@interface OTOrderedDictionary: OFDictionary
{
	OFArray *_keys;
	OFArray *_objects;
}
@end

OF_ASSUME_NONNULL_END

# import "ObjFW.h"
#else
# import <ObjFW/ObjFW.h>
#endif

OF_ASSUME_NONNULL_BEGIN

/**
 * @brief A class meant for subclassing to create a test case, consisting of
 *	  one or more tests.
 *
 * All methods with the prefix `test` that take no arguments of all classes
 * that subclass this class are automatically executed by ObjFWTest.
 */
@interface OTTestCase: OFObject
#ifdef OF_HAVE_CLASS_PROPERTIES
@property (class, readonly, nullable, nonatomic)
    OFArray OF_GENERIC(OFPair OF_GENERIC(OFString *, id) *) *summary;
#endif

/**
 * @brief Returns a summary for the test case that should be printed once all
 *	  tests in all test cases were run.
 *
 * This is mostly useful to print something at the end of all tests that needs
 * manual verification.
 */
+ (nullable OFArray OF_GENERIC(OFPair OF_GENERIC(OFString *, id) *) *)summary;

/**
 * @brief Set up method that is run before every test in the test case.
 */
- (void)setUp;

/**
 * @brief Tear down method that is run after every test in the test case.
 */
- (void)tearDown;
@end

OF_ASSUME_NONNULL_END