Add URL builder functions (#178)

* Add URL builder functions

* Update Doxygen documentation

* Add automated documentation publishing workflow

* Update documentation

* Fix with_method_tests inputs

* Simplify includes by grouping headers

Author: glynos

.github/workflows/documentation.yml

@@ -0,0 +1,67 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-deploy:
+    name: Build and Deploy Documentation
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            doxygen \
+            pandoc \
+            python3 \
+            python3-pip \
+            ninja-build
+
+      - name: Install Python documentation dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install \
+            sphinx \
+            sphinx_bootstrap_theme \
+            breathe \
+            recommonmark
+
+      - name: Install vcpkg
+        run: |
+          git clone https://github.com/Microsoft/vcpkg.git
+          ./vcpkg/bootstrap-vcpkg.sh
+
+      - name: Configure CMake
+        run: |
+          cmake \
+            -B build \
+            -G Ninja \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DCMAKE_TOOLCHAIN_FILE=${{ github.workspace }}/vcpkg/scripts/buildsystems/vcpkg.cmake \
+            .
+
+      - name: Build documentation
+        run: cmake --build build --target doc
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./build/docs/html
+          publish_branch: gh-pages
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'
+          commit_message: 'Deploy documentation from ${{ github.sha }}'

CLAUDE.md

@@ -64,10 +64,10 @@ Key build options:
 - `skyr_BUILD_TESTS` (ON): Build tests
 - `skyr_BUILD_WPT` (OFF): Build Web Platform Tests runner
 - `skyr_BUILD_BENCHMARKS` (OFF): Build performance benchmarks
-- `skyr_ENABLE_FILESYSTEM_FUNCTIONS` (ON): Enable filesystem::path conversion
-- `skyr_ENABLE_JSON_FUNCTIONS` (ON): Enable JSON serialization
 - `skyr_BUILD_WITHOUT_EXCEPTIONS` (OFF): Build without exceptions
 
+**Note**: Filesystem functions are always available (C++23 guarantees `std::filesystem`). JSON functions are automatically enabled when `nlohmann-json` is found.
+
 ## Testing
 
 ### Run All Tests

CMakeLists.txt

@@ -35,8 +35,6 @@ option(skyr_BUILD_WITHOUT_EXCEPTIONS "Build without exceptions." OFF)
 option(skyr_BUILD_WITHOUT_RTTI "Build without RTTI." OFF)
 option(skyr_USE_STATIC_CRT "Use static C Runtime library (/MT or MTd)." ON)
 option(skyr_BUILD_WITH_LLVM_LIBCXX "Instruct Clang to use LLVM's implementation of C++ standard library" OFF)
-option(skyr_ENABLE_FILESYSTEM_FUNCTIONS "Enable functions to convert URL to std::filesystem::path" ON)
-option(skyr_ENABLE_JSON_FUNCTIONS "Enable functions to convert URL components to JSON" ON)
 option(skyr_ENABLE_SANITIZERS "Enable sanitizers (address, undefined, etc.) for tests and examples" OFF)
 option(skyr_CXX_STANDARD_LIBRARY "Path to non-system C++ standard library" "")
 
@@ -51,13 +49,14 @@ if (skyr_IS_TOP_LEVEL_PROJECT)
     set(CMAKE_CXX_STANDARD_REQUIRED ON)
 endif()
 
-if (skyr_ENABLE_JSON_FUNCTIONS)
-    find_package(nlohmann_json CONFIG)
-    if (NOT nlohmann_json_FOUND)
-        message(WARNING "nlohmann_json not found. Install with: vcpkg install nlohmann-json")
-        message(WARNING "JSON functions will be disabled.")
-        set(skyr_ENABLE_JSON_FUNCTIONS OFF)
-    endif()
+# JSON functions are optional and only available if nlohmann_json is found
+find_package(nlohmann_json CONFIG)
+if (NOT nlohmann_json_FOUND)
+    message(WARNING "nlohmann_json not found. Install with: vcpkg install nlohmann-json")
+    message(WARNING "JSON functions will be disabled.")
+    set(skyr_HAS_JSON_SUPPORT OFF)
+else()
+    set(skyr_HAS_JSON_SUPPORT ON)
 endif()
 
 if (skyr_USE_STATIC_CRT AND (CMAKE_CXX_COMPILER_ID MATCHES "MSVC" OR CMAKE_CXX_SIMULATE_ID MATCHES "MSVC"))
@@ -129,11 +128,8 @@ write_basic_package_version_file(
         COMPATIBILITY SameMajorVersion
         ARCH_INDEPENDENT)
 
-set(skyr_TARGETS skyr-url)
-if (skyr_ENABLE_FILESYSTEM_FUNCTIONS)
-    list(APPEND skyr_TARGETS skyr-filesystem)
-endif()
-if (skyr_ENABLE_JSON_FUNCTIONS)
+set(skyr_TARGETS skyr-url skyr-filesystem)
+if (skyr_HAS_JSON_SUPPORT)
     list(APPEND skyr_TARGETS skyr-json)
 endif()
 
@@ -177,10 +173,10 @@ install(
         include/skyr
 )
 
-if (skyr_ENABLE_FILESYSTEM_FUNCTIONS)
-    install(DIRECTORY "${PROJECT_SOURCE_DIR}/include/skyr/filesystem" DESTINATION include/skyr)
-endif()
+# Filesystem functions are always installed (C++23 guarantees std::filesystem)
+install(DIRECTORY "${PROJECT_SOURCE_DIR}/include/skyr/filesystem" DESTINATION include/skyr)
 
-if (skyr_ENABLE_JSON_FUNCTIONS)
+# JSON functions are only installed if nlohmann_json is available
+if (skyr_HAS_JSON_SUPPORT)
     install(DIRECTORY "${PROJECT_SOURCE_DIR}/include/skyr/json" DESTINATION include/skyr)
 endif()

README.md

@@ -20,6 +20,9 @@ This library provides:
 * A ``skyr::url`` class that implements a generic URL parser,
   conforming with the [WhatWG URL specification](https://url.spec.whatwg.org/#url-class)
 * URL serialization and comparison
+* **Immutable URL transformations** with `with_*` methods for functional-style URL building
+* **URL sanitization** methods to remove credentials, fragments, and query parameters
+* **`std::format` support** with custom format specifiers for URL components
 * Percent encoding and decoding functions
 * IDNA and Punycode functions for domain name parsing
 * Unicode conversion utilities
@@ -36,7 +39,7 @@ This library provides:
 ## Using the library
 
 This project requires:
-* A **C++23 compliant compiler** (GCC 13+, Clang 16+, MSVC 2022 17.6+)
+* A **C++23 compliant compiler** (GCC 13+, Clang 19+, MSVC 2022+)
 * **No external dependencies** for core URL parsing
 
 ### ``vcpkg``
@@ -101,30 +104,25 @@ On Windows, replace the target with ``RUN_TESTS``:
 > cmake --build _build --target RUN_TESTS
 ```
 
-To install the library:
+To install the library (optional):
 
 ```bash
 > cmake --build _build --target install
 ```
 
-## Testing and installing the project
-
-### Installing with `CMake` and `Ninja`
+Or with a custom install prefix:
 
 ```bash
-> cmake .. \
+> cmake \
+    -B _build \
     -G "Ninja" \
     -DCMAKE_TOOLCHAIN_FILE=${VCPKG_ROOT}/vcpkg/scripts/buildsystems/vcpkg.cmake \
-    -DCMAKE_INSTALL_PREFIX=$PREFIX
-> ninja
-> ninja test
-> ninja install
+    -DCMAKE_INSTALL_PREFIX=/your/install/path \
+    .
+> cmake --build _build --target install
 ```
 
-Where `$PREFIX` is the location where you want to install the
-library. Depending on the location of `$PREFIX`, you may need to run
-the install command as an administrator (e.g. on Linux as `sudo`).
-
+**Note**: Depending on the install location, you may need administrator privileges (e.g., `sudo` on Linux).
 
 ## Example usage
 

cmake/skyr-url-functions.cmake

@@ -24,25 +24,5 @@ function(skyr_remove_extension file_name basename)
 endfunction()
 
 
-function(skyr_check_filesystem compile_definitions)
-    check_cxx_source_compiles("#include <filesystem>
-int main() { std::filesystem::path p{}; }" SKYR_USE_CXX17_FILESYSTEM)
-    if (SKYR_USE_CXX17_FILESYSTEM)
-        set(_compile_definitions "-DSKYR_USE_CXX17_FILESYSTEM")
-    else()
-        check_cxx_source_compiles("#include <experimental/filesystem>
-int main() { std::experimental::filesystem::path p{}; }" SKYR_USE_CXX17_EXPERIMENTAL_FILESYSTEM)
-        if (SKYR_USE_CXX17_EXPERIMENTAL_FILESYSTEM)
-            set(_compile_definitions "-DSKYR_USE_CXX17_EXPERIMENTAL_FILESYSTEM")
-            if (${CMAKE_CXX_COMPILER_ID} MATCHES GNU OR ${CMAKE_CXX_COMPILER_ID} MATCHES Clang)
-                set(_compile_definitions "${_compile_definitions} -D_LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_FILESYSTEM")
-            elseif (${CMAKE_CXX_COMPILER_ID} MATCHES MSVC)
-                set(_compile_definitions "${_compile_definitions} -D_SILENCE_EXPERIMENTAL_FILESYSTEM_DEPRECATION_WARNING")
-            endif()
-        else()
-            message(FATAL_ERROR "Filesystem operations are not supported")
-        endif()
-    endif()
-
-    set(${compile_definitions} ${_compile_definitions} PARENT_SCOPE)
-endfunction()
+# Legacy filesystem check function removed
+# C++23 guarantees std::filesystem support, so no checks are needed

cmake/targets/skyr/CMakeLists.txt

@@ -28,43 +28,36 @@ add_library(skyr::url ALIAS skyr-url)
 
 #################################################
 # skyr-filesystem
+# Always available (C++23 guarantees std::filesystem)
 #################################################
 
-if (skyr_ENABLE_FILESYSTEM_FUNCTIONS)
-    add_library(skyr-filesystem INTERFACE)
+add_library(skyr-filesystem INTERFACE)
 
-    target_compile_features(skyr-filesystem INTERFACE cxx_std_23)
+target_compile_features(skyr-filesystem INTERFACE cxx_std_23)
 
-    skyr_check_filesystem(filesystem_definitions)
-    target_compile_definitions(
-            skyr-filesystem
-            INTERFACE
-            ${filesystem_definitions}
-    )
-
-    target_link_libraries(
-            skyr-filesystem
-            INTERFACE
-            skyr-url
-    )
+target_link_libraries(
+        skyr-filesystem
+        INTERFACE
+        skyr-url
+)
 
-    target_include_directories(
-            skyr-filesystem
-            INTERFACE
-            $<INSTALL_INTERFACE:include>
-            $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
-            $<BUILD_INTERFACE:${PROJECT_BINARY_DIR}/include>
-            )
+target_include_directories(
+        skyr-filesystem
+        INTERFACE
+        $<INSTALL_INTERFACE:include>
+        $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
+        $<BUILD_INTERFACE:${PROJECT_BINARY_DIR}/include>
+)
 
-    add_library(skyr::skyr-filesystem ALIAS skyr-filesystem)
-    add_library(skyr::filesystem ALIAS skyr-filesystem)
-endif()
+add_library(skyr::skyr-filesystem ALIAS skyr-filesystem)
+add_library(skyr::filesystem ALIAS skyr-filesystem)
 
 #################################################
 # skyr-json
+# Optional - only available if nlohmann_json is found
 #################################################
 
-if (skyr_ENABLE_JSON_FUNCTIONS)
+if (skyr_HAS_JSON_SUPPORT)
     add_library(skyr-json INTERFACE)
 
     target_compile_features(skyr-json INTERFACE cxx_std_23)