diff --git a/README.md b/README.md index 41f55b6..686a822 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,127 @@ section("some section") endsection() ``` +## API Reference + +### `ASSERTION_LIST_FILE` + +This variable contains the path to the included `Assertion.cmake` module. + +### `assertion_add_test` + +Adds a new test that processes the given CMake file in script mode. + +```cmake +assertion_add_test( [NAME ]) +``` + +This function adds a new test that processes the given `` in script mode. +If `NAME` is specified, it will use `` as the test name; otherwise, it +will use ``. + +Internally, the test will process the `Assertion.cmake` module in script mode +and include the given `` at the end of the module, allowing variables, +functions, and macros in the `Assertion.cmake` module to be available in the +`` without the need to include the `Assertion.cmake` module from the +``. + +### `fail` + +Throws a formatted fatal error message. + +```cmake +fail(...) +``` + +This macro throws a fatal error message formatted from the given ``. + +It formats the message by concatenating all the lines into a single message +with no separator between the lines. If one of the lines is a variable, it will +be expanded and indented by two spaces before being concatenated with the other +lines. + +### `assert` + +Asserts the given condition. + +```cmake +assert(...) +``` + +This function performs an assertion on the given ``. If the assertion +fails, it will output a formatted fatal error message with information about the +context of the asserted condition. + +Refer to the documentation of CMake's +[`if`](https://cmake.org/cmake/help/latest/command/if.html) function for more +information about supported conditions for the assertion. + +### `assert_fatal_error` + +Asserts whether a command call throws a fatal error message. + +```cmake +assert_fatal_error(CALL [...] MESSAGE ...) +``` + +This function asserts whether a function or macro named ``, called with +the specified ``, throws a fatal error message that matches the +expected ``. + +If more than one `` string is given, they are concatenated into a +single message with no separator between the strings. + +### `assert_execute_process` + +Asserts whether the given command correctly executes a process. + +```cmake +assert_execute_process( + [COMMAND] [...] + [OUTPUT ...] + [ERROR ...]) +``` + +This function asserts whether the given `` and `` +successfully execute a process. If `ERROR` is specified, it instead asserts +whether it fails to execute the process. + +If `OUTPUT` is specified, it also asserts whether the output of the executed +process matches the expected ``. If more than one `` string is +given, they are concatenated into a single output with no separator between the +strings. + +If `ERROR` is specified, it also asserts whether the error of the executed +process matches the expected ``. If more than one `` string is +given, they are concatenated into a single error with no separator between the +strings. + +### `section` + +Begins a new test section. + +```cmake +section(...) +``` + +This function begins a new test section named ``. It prints the test +section name and indents all subsequent messages by two spaces. + +If more than one `` string is given, they are concatenated into a single +name with no separator between the strings. + +Use the `endsection` function to end the test section. + +### `endsection` + +Ends the current test section. + +```cmake +endsection() +``` + +This function ends the current test section. + ## License This project is licensed under the terms of the [MIT License](./LICENSE). diff --git a/cmake/Assertion.cmake b/cmake/Assertion.cmake index 4c7f700..fc539f4 100644 --- a/cmake/Assertion.cmake +++ b/cmake/Assertion.cmake @@ -46,9 +46,9 @@ set(ASSERTION_LIST_FILE "${CMAKE_CURRENT_LIST_FILE}") # # assertion_add_test( [NAME ]) # -# This function adds a new test that will process the given `` in script +# This function adds a new test that processes the given `` in script # mode. If `NAME` is specified, it will use `` as the test name; -# otherwise, it will use `` instead. +# otherwise, it will use ``. # # Internally, the test will process this module in script mode and include the # given `` at the end of the module, allowing variables, functions, and