CHANGELOG.md

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project
adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

#### `core` library

* A new namespace called `assert`, containing functions for implementing the `ASSERT` macro family
* In the `assert` namespace:
  * A pair of new macros called `ASSERT` and `ASSERT_NOT_NULL`, which terminate the program with a message if the assertion does not pass
  * A template function called `fail`, which implements the assertion failure mechanism
* A new namespace called `either`, containing the `Either` type for holding one of two types of value
* In the `either` namespace:
  * A tag type called `PreventSelectionForCopyAndMove` used internally
  * A pair of templates called `LHS` and `RHS` which distinguish the alternatives of an `Either`
  * A template called `Either` which can hold one of two values, which can have different types
  * A pair of functions called `make_lhs()` and `make_rhs()`, which can be used to create `LHS` and `RHS` instances to pass to an `Either`

#### `parsing` library

* In the `bits` namespace:
  * A new parser called `SizedByteSequence` which extracts a specific number of bytes from the input

#### `testing` library

* In the `expect` namespace:
  * A pair of new macros called `EXPECT_CONTAINER_EQ` and `EXPECT_CONTAINER_NE`, which check for (in)equality between two iterables

### Changed

#### General

* Turned all instances of `std::u8string`, `std::u8string_view`, `char8_t`, and `u8""` literals back into their legacy versions due to bad support
* Standardized constructor syntax (`{}` unless `()` is semantically required)

#### `parsing` library

* The `bits::ByteSequence` and `text::CharacterSequence` parsers now make a deep copy of their sequences
* The `bits::ByteSequence` parser has been renamed to `bits::ExactByteSequence`

### Deprecated

### Removed

### Fixed

* Compilation error on AppleClang: `no viable constructor or deduction guide` in `core::assert::fail()`

### Security

## [0.2.0]

Released on October 02, 2021.

### Added

#### New libraries

* `vm` library for the virtual machine implementation
* `parsing` library for parser combinators

#### `parsing` library features

* `bits` namespace containing primitives for parsing binary data
  * `FixedWidthUnsignedIntegerType` concept, which constrains to one of the `std::uintN_t` types
  * `ByteSequenceMismatch` basic error type
  * `UnexpectedEndOfInput` basic error type
  * `BitsError` composite error type
  * `BitsState` type specialized for binary data
  * `ByteSequence` parser which matches an exact sequence of bytes
  * `LittleEndianUnsignedInteger` parser template
  * `BigEndianUnsignedInteger` parser template
* `combinators` namespace containing types for combining simple parsers into more complex parsers
  * `BothMatch` error template
  * `NeitherMatch` error template
  * `OneOfError` composite error type
  * `OneOf` parser combinator, which matches exclusively one or the other of the child parsers
  * `AndThen` parser combinator, which matches one parser followed by another parser and returns both results
  * `operators` namespace containing tools for building combinator trees
    * `operator^`, which combines two parsers using the `OneOf` combinator
    * `operator&`, which combines two parsers using the `AndThen` combinator
* `result` namespace containing utility types for the outcomes of individual parsers
  * `Reject` template for holding information about a rejected parse
  * `Accept` template for holding information about an accepted parse
  * `reject` function for building a `Reject` wrapped in a `core::result::Failure`
  * `accept` function for building an `Accept` wrapped in a `core::result::Success`
* `text` namespace containing primitives for parsing UTF-8 data
  * `CharacterSequenceMismatch` basic error type
  * `TextError` composite error type
  * `TextState` type specialized for UTF-8 data
  * `CharacterSequence` parser which matches an exact sequence of characters

#### `testing` library features

* New namespace: `fixture` for types related to test fixtures
* In the `fixture` namespace:
  * `FixtureFunction` alias for the type of a fixture function
  * `FixtureVariant` template type which serves as a base class for each kind of fixture
  * `BeforeAll`, `AfterAll`, `BeforeEach`, and `AfterEach` tag types which differentiate each kind of fixture
  * The `Fixture` type itself, which abstracts over all of these details
  * In the `FixtureVariant` type:
    * A constructor accepting a `FixtureFunction`
    * A getter method called `get_name()` which returns the name of the fixture variant based on which derived class calls it
    * A method named `execute()` which runs the fixture and returns an outcome, just like a scenario
  * In the `BeforeAll`, `AfterAll`, `BeforeEach`, and `AfterEach` types:
    * A constant string field containing the name of the variant for reporting purposes
  * In the `Fixture` type:
    * A constructor which accepts a name and a fixture variant
    * A template method called `has_variant()` which checks what kind of fixture this is
    * A method called `get_variant_name()` which forwards to `get_name()` on the underlying variant
    * A getter method called `get_name()` which retrieves the fixture's name
    * A method called `execute()` which forwards to `execute()` on the underlying variant
* In the `suite` namespace:
  * Four new macros which define fixtures in the same way as scenarios: `BEFORE_ALL`, `AFTER_ALL`, `BEFORE_EACH`, and `AFTER_EACH`
  * A new type called `FixtureRegistrar` which is used by the new macros to add fixtures to the suite
  * In the `FixtureRegistrar` type:
    * A constructor that forwards to `add_fixture()` on the suite
  * In the `Suite` singleton:
    * A method called `add_fixture()` which registers a new fixture in the suite
* In `reporter::Reporter`, `abstract_reporter::AbstractReporter`, and `console_reporter::ConsoleReporter`:
  * Two new methods called `handle_fixture_start()` and `handle_fixture_end()` which are called before and after each fixture
  * Another new method called `set_show_fixtures()` which toggles how much information is reported about fixtures
* In the `expect` namespace:
  * A new template function called `fail_comparison()`, which is exactly like `fail()` but formats its output specifically as a comparison failure

### Changed

#### Build system

* Upgrade the C++ version to C++20
* Renamed the `test` library to `testing` to better fit with other library names (specifically `parsing`)

#### `testing` library features

* Print a special message when there are no tests in a test suite
* Tests can now accept a `--show-fixtures` argument on the command line which causes the reporter to print more information about which fixtures run and when
* The `SCENARIO` macro and `ScenarioRegistrar` type have been moved to the `suite` namespace
* The console reporter will now display a count of total fixture invocations in the suite summary
* All reporters now require a third argument, `fixture_count`, to the `handle_suite_end()` method
* The `EXPECT` family of macros now print much more detailed information when a test fails
* In the `expect` namespace:
  * The `fail` function now takes more arguments and has been made into a template based on the type of value being `EXPECT`ed

### Fixed

#### `parsing` library

* Compilation `cast truncates constant value` warning on MSVC

#### `testing` library

* Disallow copying and moving the Suite singleton
* Incorrect include guard symbols
* Compilation warning on AppleClang: `[[nodiscard]]` on a function returning `void`

#### Build system

* Give a nice message from CMake instead of weird errors when trying to build for non-64-bit systems

## [0.1.0]

Released on September 04, 2021.

### Added

#### New libraries

* `core` library for fundamental types and functions used by everything else
* `test` library for testing infrastructure
* `unix` library for wrapping Unix-like APIs
* `windows` library for wrapping Windows APIs

#### `core` library features

* `core::constant_error` namespace, containing a `ConstantError` template for errors with a constant message
* `core::error_chain` namespace, containing the `ErrorChain` class for building complex error types
* `core::none` namespace, containing the `None` type to use as a placeholder
* `core::resource_warden` namespace, containing a class template for cleaning up raw resources on scope exit
* `core::result` namespace, containing facilities for operations that can fail

#### `test` library features

* `test::abstract_reporter` namespace, containing the `AbstractReporter` interface
* `test::cli` namespace, containing a function `execute()` that can be called from `main()`
* `test::console_reporter` namespace, containing a reporter that writes to stdout
* `test::expect` namespace, containing macros to express test assertions
* `test::outcome` namespace, containing types representing scenario outcomes
* `test::reporter` namespace, containing factories for specific reporters and also a wrapper type
* `test::scenario` namespace, containing the `Scenario` type for representing a single test scenario
* `test::suite` namespace, containing the `Suite` singleton used to hold all of the tests in a suite

#### `unix` library features

* `unix::errno_error` namespace, containing utilities for working with `errno`
* `unix::fs` namespace, containing wrappers for filesystem APIs on Unix-like systems

#### `windows` library features

* `windows::fs` namespace, containing wrappers for filesystem APIs on Windows
* `windows::transcoding` namespace, containing functions for transcoding UTF8 with UTF16 for Windows APIs
* `windows::windows_error` namespace, containing functions and a type for reading and formatting Windows errors

#### Build system features

* `AddCrucibleExecutable` module, which provides a wrapper for `add_executable()`
* `AddCrucibleLibrary` module, which provides a wrapper for `add_library()`
* `AddCrucibleTest` module, which provides a wrapper for `add_test()`
* `EnableCompilerWarnings` module, which provides a function that enables common compiler warning flags
* `EnableRuntimeSanitizers` module, which provides a function that enables ASAN, TSAN, and UBSAN based on options
* Write all final build outputs (executables and libraries) to `${PROJECT_BINARY_DIR}/artifacts`
* Automatically export all symbols from all libraries when building Windows DLLs

#### Repository features

* Build dependencies in the README
* Build instructions in the README
* Test instructions in the README
* Attribution in the README

[Unreleased]: https://gitlab.com/bravelytyped/crucible
[0.2.0]: https://gitlab.com/bravelytyped/crucible/-/tree/v0.2.0
[0.1.0]: https://gitlab.com/bravelytyped/crucible/-/tree/v0.1.0