Skip to content

Commit f3bc62e

Browse files
GaspardKiriraGaspardKirira
committed
feat(utils): make utils independent + add primitives
- Result, ScopeGuard, String, Env, Time, UUID - Generic Validation (required/len/range/regex) - Logger context/pattern helpers - Version API
1 parent 3eaf9bc commit f3bc62e

28 files changed

Lines changed: 1054 additions & 19 deletions

‎.github/pull_request_template.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# ✅ Pull Request Template – `vixcpp/utils`
2+
3+
## 📄 Description
4+
5+
Please include a clear and concise summary of the changes in this PR,
6+
along with the motivation behind them (e.g., utility improvements, new helpers, refactoring, etc.).
7+
8+
Reference any related issues or feature requests:
9+
**Fixes** # (issue number)
10+
11+
---
12+
13+
## 🔍 Type of Change
14+
15+
Please check all that apply:
16+
17+
- [ ] 🐞 **Bug fix** (non-breaking change that fixes an issue)
18+
- [ ] ✨ **New feature** (non-breaking change that adds functionality)
19+
- [ ] 💥 **Breaking change** (modifies existing functionality or API)
20+
- [ ] 📝 **Documentation update**
21+
- [ ] ✅ **Tests / CI improvements**
22+
23+
---
24+
25+
## 🧪 How Has This Been Tested?
26+
27+
Please describe the tests you ran to verify your changes.
28+
Include steps for others to reproduce them if needed:
29+
30+
```bash
31+
# Create and enter build directory
32+
mkdir build && cd build
33+
34+
# Configure the build system
35+
cmake ..
36+
37+
# Build all targets
38+
make -j$(nproc)
39+
```
40+
41+
If unit tests were added (recommended for utility functions):
42+
43+
# Run utility tests
44+
45+
```bash
46+
./test_utils
47+
```
48+
49+
Mention what specific utility headers/functions were tested (e.g., trim(), read_file(), get_current_timestamp()).
50+
51+
✅ Checklist
52+
53+
My code follows the style guidelines of this project
54+
55+
I have reviewed my own code
56+
57+
I have added comments where needed
58+
59+
I have updated relevant documentation
60+
61+
I have added unit tests where appropriate
62+
63+
All new and existing tests pass
64+
65+
🧩 Additional Notes
66+
67+
Include any other relevant information here, such as:
68+
69+
Edge cases handled
70+
71+
Benchmark results for performance-sensitive utilities
72+
73+
Screenshots or logs for file/path utilities
74+
75+
Limitations or TODOs for future improvements

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,5 @@
3939

4040
# debug information files
4141
*.dwo
42+
build/
43+
.vscode/

‎CHANGELOG.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
Changelog – vixcpp/utils
2+
3+
All notable changes to this module will be documented in this file.
4+
The format is based on Keep a Changelog : https://keepachangelog.com/en/1.0.0/
5+
6+
and this project adheres to Semantic Versioning: https://semver.org/spec/v2.0.0.html
7+
.
8+
9+
[0.1.0] – 2025-10-07
10+
Added
11+
12+
Initial release of the utils module.
13+
14+
String utilities: trimming, splitting, case conversion, and prefix/suffix checks.
15+
16+
File utilities: read/write entire files, check for existence, create directories.
17+
18+
Path helpers: normalize paths, extract filename or extension.
19+
20+
Time helpers: timestamp formatting, current time in ISO 8601, duration helpers.
21+
22+
Cross-platform support (Linux, macOS, Windows).
23+
24+
Fully header-only, minimal dependencies.
25+
26+
Changed
27+
28+
Refactored internal string helpers from core into standalone utils module.
29+
30+
Fixed
31+
32+
Fixed inconsistent newline handling on Windows in file utilities.
33+
34+
Corrected path normalization to handle trailing slashes properly.
35+
36+
[0.0.1] – Draft
37+
38+
Created project structure for utils.
39+
40+
Set up CMake target vix_utils with interface include directory.
41+
42+
Populated initial utility headers: string.hpp, file.hpp, path.hpp, time.hpp.
43+
44+
Added example usages in examples/ for each utility group.

‎CMakeLists.txt‎

Lines changed: 28 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
# ======================================================
2-
# vix.cpp utils module CMake configuration
2+
# vix.cpp utils module CMake configuration
33
# ======================================================
44

55
cmake_minimum_required(VERSION 3.20)
6-
project(vix_utils VERSION 0.1 LANGUAGES CXX)
6+
project(vix_utils VERSION 0.2.0 LANGUAGES CXX)
77

88
# ======================================================
99
# C++ standard and options
1010
# ======================================================
1111
set(CMAKE_CXX_STANDARD 20)
1212
set(CMAKE_CXX_STANDARD_REQUIRED ON)
13-
set(CMAKE_POSITION_INDEPENDENT_CODE ON) # required for static/shared libs
13+
set(CMAKE_POSITION_INDEPENDENT_CODE ON)
1414

1515
# ======================================================
1616
# Build types and warnings
@@ -21,7 +21,7 @@ endif()
2121

2222
set(GLOBAL_CXX_FLAGS "-Wall -Wextra -Wshadow -Weffc++")
2323
set(CMAKE_CXX_FLAGS_RELEASE "${GLOBAL_CXX_FLAGS} -O2 -DNDEBUG")
24-
set(CMAKE_CXX_FLAGS_DEBUG "${GLOBAL_CXX_FLAGS} -g -fsanitize=address -fsanitize=undefined -D_GLIBCXX_DEBUG")
24+
set(CMAKE_CXX_FLAGS_DEBUG "${GLOBAL_CXX_FLAGS} -g -fsanitize=address -fsanitize=undefined -D_GLIBCXX_DEBUG")
2525

2626
message(STATUS "Build type: ${CMAKE_BUILD_TYPE}")
2727
message(STATUS "CXX flags: ${CMAKE_CXX_FLAGS}")
@@ -34,9 +34,10 @@ file(GLOB_RECURSE UTILS_SOURCES
3434
)
3535

3636
# ======================================================
37-
# Create static library 'utils'
37+
# Create static library 'utils' (+ alias Vix::utils)
3838
# ======================================================
3939
add_library(utils STATIC ${UTILS_SOURCES})
40+
add_library(Vix::utils ALIAS utils)
4041

4142
target_include_directories(utils
4243
PUBLIC
@@ -47,7 +48,8 @@ target_include_directories(utils
4748
# Dependencies
4849
# ======================================================
4950
find_package(spdlog REQUIRED)
50-
target_link_libraries(utils PRIVATE spdlog::spdlog)
51+
# Logger.hpp inclut des headers spdlog
52+
target_link_libraries(utils PUBLIC spdlog::spdlog)
5153

5254
# ======================================================
5355
# Export target for other projects
@@ -56,6 +58,7 @@ set_target_properties(utils PROPERTIES
5658
EXPORT_NAME utils
5759
VERSION ${PROJECT_VERSION}
5860
SOVERSION 0
61+
OUTPUT_NAME vix_utils
5962
)
6063

6164
# ======================================================
@@ -79,4 +82,23 @@ export(EXPORT vix_utilsTargets
7982
NAMESPACE Vix::
8083
)
8184

85+
# ======================================================
86+
# Examples (optional)
87+
# ======================================================
88+
option(VIX_UTILS_BUILD_EXAMPLES "Build examples for vix_utils" ON)
89+
90+
if (VIX_UTILS_BUILD_EXAMPLES)
91+
add_executable(utils_log_demo examples/log_demo.cpp)
92+
target_link_libraries(utils_log_demo PRIVATE Vix::utils)
93+
target_include_directories(utils_log_demo PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include)
94+
95+
add_executable(utils_validation_demo examples/validation_demo.cpp)
96+
target_link_libraries(utils_validation_demo PRIVATE Vix::utils)
97+
target_include_directories(utils_validation_demo PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include)
98+
99+
add_executable(utils_env_time_uuid examples/env_time_uuid.cpp)
100+
target_link_libraries(utils_env_time_uuid PRIVATE Vix::utils)
101+
target_include_directories(utils_env_time_uuid PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include)
102+
endif()
103+
82104
message(STATUS "Utils library configured with ${UTILS_SOURCES}")

‎CONTRIBUTING.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# ✅ Pull Request Template – `vixcpp/utils`
2+
3+
## 📄 Description
4+
5+
Please include a clear and concise summary of the changes in this PR,
6+
along with the motivation behind them (e.g., utility improvements, new helpers, refactoring, etc.).
7+
8+
Reference any related issues or feature requests:
9+
**Fixes** # (issue number)
10+
11+
---
12+
13+
## 🔍 Type of Change
14+
15+
Please check all that apply:
16+
17+
- [ ] 🐞 **Bug fix** (non-breaking change that fixes an issue)
18+
- [ ] ✨ **New feature** (non-breaking change that adds functionality)
19+
- [ ] 💥 **Breaking change** (modifies existing functionality or API)
20+
- [ ] 📝 **Documentation update**
21+
- [ ] ✅ **Tests / CI improvements**
22+
23+
---
24+
25+
## 🧪 How Has This Been Tested?
26+
27+
Please describe the tests you ran to verify your changes.
28+
Include steps for others to reproduce them if needed:
29+
30+
```bash
31+
# Create and enter build directory
32+
mkdir build && cd build
33+
34+
# Configure the build system
35+
cmake ..
36+
37+
# Build all targets
38+
make -j$(nproc)
39+
```
40+
41+
If unit tests were added (recommended for utility functions):
42+
43+
# Run utility tests
44+
45+
```bash
46+
./test_utils
47+
```
48+
49+
Mention what specific utility headers/functions were tested (e.g., trim(), read_file(), get_current_timestamp()).
50+
51+
✅ Checklist
52+
53+
My code follows the style guidelines of this project
54+
55+
I have reviewed my own code
56+
57+
I have added comments where needed
58+
59+
I have updated relevant documentation
60+
61+
I have added unit tests where appropriate
62+
63+
All new and existing tests pass
64+
65+
🧩 Additional Notes
66+
67+
Include any other relevant information here, such as:
68+
69+
Edge cases handled
70+
71+
Benchmark results for performance-sensitive utilities
72+
73+
Screenshots or logs for file/path utilities
74+
75+
Limitations or TODOs for future improvements

‎Makefile‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
VERSION ?= v0.1.0
2+
BRANCH_DEV = dev
3+
BRANCH_MAIN = main
4+
5+
.PHONY: help release commit push merge tag test changelog
6+
7+
help:
8+
@echo "Available commands:"
9+
@echo " make commit - Add and commit all files (on $(BRANCH_DEV) branch)"
10+
@echo " make push - Push the $(BRANCH_DEV) branch"
11+
@echo " make merge - Merge $(BRANCH_DEV) into $(BRANCH_MAIN)"
12+
@echo " make tag VERSION=vX.Y.Z - Create and push a Git tag (default: $(VERSION))"
13+
@echo " make release VERSION=vX.Y.Z - Full release: changelog + commit + push + merge + tag"
14+
@echo " make test - Compile and run tests"
15+
@echo " make changelog - Update CHANGELOG.md using script"
16+
17+
commit:
18+
git checkout $(BRANCH_DEV)
19+
@if [ -n "$$(git status --porcelain)" ]; then \
20+
echo "📝 Committing changes..."; \
21+
git add .; \
22+
git commit -m "chore(release): prepare $(VERSION)"; \
23+
else \
24+
echo "✅ Nothing to commit."; \
25+
fi
26+
27+
push:
28+
git push origin $(BRANCH_DEV)
29+
30+
merge:
31+
git checkout $(BRANCH_MAIN)
32+
git merge --no-ff --no-edit $(BRANCH_DEV)
33+
git push origin $(BRANCH_MAIN)
34+
35+
tag:
36+
@if git rev-parse $(VERSION) >/dev/null 2>&1; then \
37+
echo "❌ Tag $(VERSION) already exists."; \
38+
exit 1; \
39+
else \
40+
echo "🏷️ Creating annotated tag $(VERSION)..."; \
41+
git tag -a $(VERSION) -m "Release version $(VERSION)"; \
42+
git push origin $(VERSION); \
43+
fi
44+
45+
release:
46+
make changelog
47+
make commit
48+
make push
49+
make merge
50+
make tag VERSION=$(VERSION)
51+
52+
test:
53+
cd build && ctest --output-on-failure
54+
55+
changelog:
56+
bash scripts/update_changelog.sh

‎examples/env_time_uuid.cpp‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
#include <vix/utils/Env.hpp>
2+
#include <vix/utils/Time.hpp>
3+
#include <vix/utils/UUID.hpp>
4+
#include <iostream>
5+
6+
using namespace Vix::utils;
7+
8+
int main()
9+
{
10+
std::cout << "APP_ENV=" << env_or("APP_ENV", "dev") << "\n";
11+
std::cout << "iso8601_now=" << iso8601_now() << "\n";
12+
std::cout << "uuid4=" << uuid4() << "\n";
13+
std::cout << "now_ms=" << now_ms() << "\n";
14+
return 0;
15+
}

‎examples/log_demo.cpp‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
#include <vix/utils/Logger.hpp>
2+
#include <vix/utils/UUID.hpp>
3+
#include <vix/utils/Env.hpp>
4+
5+
using Vix::Logger;
6+
using namespace Vix::utils;
7+
8+
int main()
9+
{
10+
auto &log = Logger::getInstance();
11+
log.setLevel(Logger::Level::INFO);
12+
log.setPattern("[%Y-%m-%d %T.%e] [%^%l%$] %v");
13+
14+
Logger::Context cx;
15+
cx.request_id = uuid4();
16+
cx.module = "log_demo";
17+
cx.fields["service"] = "utils";
18+
log.setContext(cx);
19+
20+
log.log(Logger::Level::INFO, "Hello from utils/log_demo");
21+
log.logf(Logger::Level::INFO, "Boot args", "port", 8080, "env", env_or("APP_ENV", "dev"));
22+
log.log(Logger::Level::WARN, "This is a warning");
23+
// log.throwError("Demo error"); // décommente pour tester
24+
return 0;
25+
}

0 commit comments

Comments
 (0)