Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bw-hro/tempdir
TempDir is a lightweight C++17 library designed to provide an easy-to-use solution for managing temporary directories and files.
https://github.com/bw-hro/tempdir
cpp17 directory filesystem header-only porable temporary
Last synced: 20 days ago
JSON representation
TempDir is a lightweight C++17 library designed to provide an easy-to-use solution for managing temporary directories and files.
- Host: GitHub
- URL: https://github.com/bw-hro/tempdir
- Owner: bw-hro
- License: other
- Created: 2024-11-21T04:46:59.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2024-11-28T07:52:26.000Z (25 days ago)
- Last Synced: 2024-11-28T08:30:40.464Z (25 days ago)
- Topics: cpp17, directory, filesystem, header-only, porable, temporary
- Language: C++
- Homepage: https://bw-hro.github.io/TempDir/
- Size: 68.4 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# TempDir: Simplified Temporary Directory for C++
[](https://github.com/bw-hro/TempDir/actions/workflows/ubuntu.yml)
[](https://github.com/bw-hro/TempDir/actions/workflows/windows.yml)
[](https://github.com/bw-hro/TempDir/actions/workflows/macos.yml)
[](https://bw-hro.github.io/TempDir/coverage-report)
[](https://raw.githubusercontent.com/bw-hro/TempDir/main/LICENSE.txt)
[](https://github.com/bw-hro/TempDir/releases)
[](https://vcpkg.link/ports/bw-tempdir)
**TempDir** is a lightweight C++17 library designed to provide an easy-to-use solution for managing temporary directories and files, particularly in unit testing scenarios (e.g., with [Catch2](https://github.com/catchorg/Catch2)). Inspired by JUnit's [`@TempDir`](https://junit.org/junit5/docs/current/api/org.junit.jupiter.api/org/junit/jupiter/api/io/TempDir.html) annoation in the Java ecosystem, **TempDir** simplifies the creation, cleanup, and management of temporary directories in your C++ projects.
The library is implemented as a **single-header file**, making integration easy and comes without additional dependencies. The project is licensed under the **MIT License**.
## Features
- **Automatic cleanup**: Configurable cleanup policies to manage temporary directories' lifecycle.
- **Easy integration**: A single-header implementation that can be directly included in your project.
- **Unit test focus**: Perfect for use in testing frameworks like Catch2
- **Modern C++ support**: Written in C++17 for robust and efficient performance.
## Installation
Simply copy the [`tempdir.hpp`](https://github.com/bw-hro/TempDir/releases/latest/download/tempdir.hpp) file into your project and include it in your source files:
```cpp
#include
```
You can also use the *vcpkg* port `bw-tempdir`
```sh
vcpkg install bw-tempdir
```
or add dependency to *vpkg.json* manifest file
```json
{
"name": "your-project",
"version-string": "1.0.0",
"dependencies": [
"bw-tempdir",
...
]
}
```
## Example Usage
### Creating and Managing a Temporary Directory
```cpp
#include
#include
#include
#include
using namespace bw::tempdir;
int main()
{
try
{
TempDir temp_dir; // Creates a temporary directory in the system's temp folder.
// Access the directory path
std::cout << "Temporary directory created at: " << temp_dir.path() << std::endl;
// Perform operations in the temp directory
auto test_file = temp_dir.path() / "example.txt";
std::ofstream(test_file) << "Hello, TempDir!";
std::cout << "Created file: " << test_file << std::endl;
// Directory is automatically cleaned up based on the cleanup policy
// when temp_dir goes out of scope.
}
catch (const TempDirException& ex)
{
std::cerr << "An error occurred: " << ex.what() << std::endl;
}
return 0;
}
```
Please do also check [examples directory](/examples/) for more examples.
### Using TempDir in Catch2 Unit Tests
```cpp
#include
#include
#include
#include
using namespace bw::tempdir;
namespace fs = std::filesystem;
TEST_CASE("TempDir usage in unit tests")
{
TempDir temp_dir;
REQUIRE(fs::exists(temp_dir.path())); // Temp directory should exist.
auto test_file = temp_dir.path() / "test.txt";
std::ofstream(test_file) << "Unit test data";
REQUIRE(fs::exists(test_file)); // File should be created.
}
// temp_dir out of scope, created temp directory will be removed
```
## Cleanup Policies
The `TempDir` class offers configurable cleanup policies:
- **`Cleanup::always`**: Always clean up the directory when `TempDir` goes out of scope.
- **`Cleanup::on_success`**: Clean up only if no exceptions were thrown.
- **`Cleanup::never`**: Keep the directory and its contents.
You can set the cleanup policy in the constructor:
```cpp
TempDir temp_dir(Cleanup::on_success);
```
## Logging
Disabled by default `TempDir` supports customizable logging by allowing you to provide a logging function in the `Config` object:
```cpp
// print to std::cout
TempDir temp_dir(Config().enable_logging());
// TempDir create '/tmp/temp_dir_1732162084442_37189'
// TempDir remove '/tmp/temp_dir_1732162084442_37189'
// forward to custom logger
TempDir temp_dir(Config().enable_logging([](auto& msg) {
spdlog::info(msg);
}));
```
## License
**TempDir** is licensed under the MIT License. See [LICENSE](LICENSE.txt) for details.
## Contributing
Contributions are welcome! If you encounter a bug, have a feature request, or would like to contribute code, feel free to open an issue or submit a pull request.